rctx

package
v0.3.30 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 18, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package rctx holds the runtime-context protocol: readers and writers for every value carried on context.Context during execution (session, envelope, route, metadata, workspace key, outbound emit), plus outbound payload encoding. It depends only on the root agentkit package; all runtime layers may depend on it.

Index

Constants

View Source 
const (
	MetadataSessionScope   = "sessionScope"
	MetadataConversationID = "conversationId"
	MetadataTurnCount      = "turnCount"
)
View Source 
const DefaultCLISessionID = agentkit.SessionID("cli:default")

DefaultCLISessionID is the stable CLI session id used when no /new happened.

Variables

This section is empty.

Functions

func ActiveEntryKey 

func ActiveEntryKey(route agentkit.RouteRef, policy RoutePolicy, userID string) agentkit.SessionID

ActiveEntryKey returns the stable key for /new active-session mapping.

func ActiveEntryKeyFromContext 

func ActiveEntryKeyFromContext(ctx context.Context) agentkit.SessionID

ActiveEntryKeyFromContext derives the stable /new active-session mapping key from the turn route. Conversation may already be resolved to a child session.

func ActiveSessionEntryKey 

func ActiveSessionEntryKey(platform string, delivery agentkit.SessionID, scope agentkit.SessionScope, userID string) agentkit.SessionID

ActiveSessionEntryKey returns the stable session-store key used for /new active-session mapping.

func AgentIDFromContext 

func AgentIDFromContext(ctx context.Context) agentkit.AgentID

AgentIDFromContext reports the agent executing the current turn.

func ApplyEnvelopeToContext 

func ApplyEnvelopeToContext(ctx context.Context, env agentkit.TurnEnvelope) context.Context

ApplyEnvelopeToContext stores the turn envelope on ctx.

func ApplyScope 

func ApplyScope(delivery agentkit.SessionID, scope agentkit.SessionScope, userID string) agentkit.SessionID

ApplyScope derives the effective session id used for Loop locking, history, and permission pending.

func BuildDeliverySessionID 

func BuildDeliverySessionID(platform, channel, thread, user string) agentkit.SessionID

BuildDeliverySessionID is the canonical finest-grain id platforms should emit.

func BuildSessionRoute 

func BuildSessionRoute(in agentkit.SessionRouteInput) agentkit.RouteRef

BuildSessionRoute builds a session-kind RouteRef from structured fields.

func ChannelKeyMatches 

func ChannelKeyMatches(jobChannelKey, contextChannelKey string) bool

ChannelKeyMatches reports whether a job belongs to the given channel key.

func ChildConversationID 

func ChildConversationID(parentConversation, agentName string, seq int64) string

ChildConversationID returns a subagent conversation id under a parent.

func ContextWithDeliveryRoute 

func ContextWithDeliveryRoute(ctx context.Context, platform string, delivery agentkit.SessionID) context.Context

ContextWithDeliveryRoute attaches a minimal session-kind delivery route to ctx.

func ContextWithOutboundEmit 

func ContextWithOutboundEmit(ctx context.Context, emit agentkit.OutboundEmit) context.Context

ContextWithOutboundEmit attaches the per-turn outbound hook to ctx.

func ConversationFromContext 

func ConversationFromContext(ctx context.Context) string

ConversationFromContext reports the history/lock key for the current turn.

func ConversationFromEvent 

func ConversationFromEvent(event agentkit.MessageEvent) agentkit.SessionID

ConversationFromEvent returns the conversation key for Loop locking and history.

func ConversationFromLoopRequest 

func ConversationFromLoopRequest(req agentkit.LoopRequest) agentkit.SessionID

ConversationFromLoopRequest returns the conversation key for a queued turn.

func DecodeSessionRoute 

func DecodeSessionRoute(route agentkit.RouteRef) (agentkit.SessionRouteTarget, bool)

DecodeSessionRoute decodes a session-kind RouteRef into SessionRouteTarget.

func DeliveryFromEnvelope 

func DeliveryFromEnvelope(env agentkit.TurnEnvelope) agentkit.SessionID

DeliveryFromEnvelope returns the outbound delivery id from a turn envelope.

func DeliveryRouteFromContext 

func DeliveryRouteFromContext(ctx context.Context) agentkit.SessionID

DeliveryRouteFromContext returns the platform delivery target from the turn envelope.

func DeliveryWithUser 

func DeliveryWithUser(delivery agentkit.SessionID, userID string) agentkit.SessionID

DeliveryWithUser returns a delivery SessionID with the :u: segment set or replaced.

func EnvelopeFromContext 

func EnvelopeFromContext(ctx context.Context) agentkit.TurnEnvelope

EnvelopeFromContext returns the current turn envelope, or zero when unset.

func InboundDeliveryID 

func InboundDeliveryID(event agentkit.MessageEvent) agentkit.SessionID

InboundDeliveryID returns the platform delivery target from an inbound message.

func MarshalOutboundData 

func MarshalOutboundData(v any) json.RawMessage

MarshalOutboundData JSON-encodes an outbound event payload.

func MergeEnvelopeMetadata 

func MergeEnvelopeMetadata(env agentkit.TurnEnvelope, extra map[string]any) agentkit.TurnEnvelope

MergeEnvelopeMetadata copies extra metadata onto env.

func MetadataFromContext 

func MetadataFromContext(ctx context.Context) map[string]any

MetadataFromContext returns platform metadata for the current turn.

func MetadataString 

func MetadataString(env agentkit.TurnEnvelope, key string) string

MetadataString returns a trimmed metadata string when present.

func NewCLISessionID 

func NewCLISessionID() agentkit.SessionID

NewCLISessionID returns a fresh opaque CLI session id.

func NewConversationID 

func NewConversationID(current string) string

NewConversationID returns a fresh conversation id for /new.

func NewSessionID 

func NewSessionID(base agentkit.SessionID) agentkit.SessionID

NewSessionID returns a fresh logical session id derived from the current stable session key. CLI keeps its historic cli:<timestamp> format.

func OutboundEmitFromContext 

func OutboundEmitFromContext(ctx context.Context) agentkit.OutboundEmit

OutboundEmitFromContext returns the per-turn outbound hook, if any.

func OutboundFromEnvelope 

func OutboundFromEnvelope(env agentkit.TurnEnvelope, typ agentkit.EventType, data []byte) agentkit.OutboundEvent

OutboundFromEnvelope builds an outbound event from envelope routing context.

func OutboundRouteID 

func OutboundRouteID(event agentkit.OutboundEvent) agentkit.SessionID

OutboundRouteID returns the platform routing target for an outbound event.

func ParseScope 

func ParseScope(raw string) agentkit.SessionScope

ParseScope normalizes runner config. Unknown values fall back to channel scope.

func PlatformFromContext 

func PlatformFromContext(ctx context.Context) string

PlatformFromContext reports the platform id for the current turn.

func RegisterPlatformPolicy 

func RegisterPlatformPolicy(platform string, policy PlatformSessionPolicy)

RegisterPlatformPolicy registers or overrides routing policy for a platform id.

func ResolveEnvelope 

func ResolveEnvelope(event agentkit.MessageEvent, policy RoutePolicy) agentkit.TurnEnvelope

ResolveEnvelope builds a TurnEnvelope from an inbound MessageEvent and policy.

func RouteRefFromContext 

func RouteRefFromContext(ctx context.Context) agentkit.RouteRef

RouteRefFromContext returns the outbound route from the turn envelope.

func RouteReplyTo 

func RouteReplyTo(route agentkit.RouteRef) string

RouteReplyTo returns the ephemeral reply anchor for this turn, if any.

func RouteSessionID 

func RouteSessionID(route agentkit.RouteRef) (agentkit.SessionID, bool)

RouteSessionID decodes a session-kind RouteRef into a delivery SessionID.

func SanitizeDirSegment 

func SanitizeDirSegment(key string) string

SanitizeDirSegment maps an arbitrary string to a single safe path segment.

func SessionFromContext 

func SessionFromContext(ctx context.Context) (agentkit.Session, bool)

SessionFromContext returns the open session when the agent set it for tools.

func SessionIDFromContext 

func SessionIDFromContext(ctx context.Context) agentkit.SessionID

SessionIDFromContext reports the history/lock key for the current turn.

func SessionRoute 

func SessionRoute(platform, deliveryID string) agentkit.RouteRef

SessionRoute builds a minimal session-kind route from a delivery id string.

func SessionRouteFromDelivery 

func SessionRouteFromDelivery(platform string, delivery agentkit.SessionID, replyTo string) agentkit.RouteRef

SessionRouteFromDelivery builds a session route from a delivery SessionID.

func SessionScopeFromContext 

func SessionScopeFromContext(ctx context.Context) agentkit.SessionScope

SessionScopeFromContext reads the runner/platform session scope from envelope metadata.

func SlackSessionID 

func SlackSessionID(channelID, threadTS string) agentkit.SessionID

SlackSessionID builds a stable session key from Slack channel and optional thread timestamp. Use threadTS from event.ThreadTimeStamp; for top-level channel messages pass "".

func SlackSessionIDForScope 

func SlackSessionIDForScope(scope agentkit.SessionScope, channelID, threadTS, userID string) agentkit.SessionID

SlackSessionIDForScope builds the effective session id for Slack components. Prefer ApplyScope(BuildDeliverySessionID(...), scope, userID) in new code; this helper remains for tests and direct agent invocations.

func SyncMessageEvent 

func SyncMessageEvent(event agentkit.MessageEvent, env agentkit.TurnEnvelope) agentkit.MessageEvent

SyncMessageEvent copies resolved envelope fields onto an inbound message.

func UserIDFromContext 

func UserIDFromContext(ctx context.Context) string

UserIDFromContext reports the end-user id for the current turn.

func WithAgentID 

func WithAgentID(ctx context.Context, agentID agentkit.AgentID) context.Context

WithAgentID returns ctx with an updated envelope agent id.

func WithContextMetadata 

func WithContextMetadata(ctx context.Context, extra map[string]any) context.Context

WithContextMetadata merges metadata onto the turn envelope.

func WithConversation 

func WithConversation(ctx context.Context, conversation string) context.Context

WithConversation returns ctx with an updated envelope conversation.

func WithMetadataScope 

func WithMetadataScope(env agentkit.TurnEnvelope, scope agentkit.SessionScope) agentkit.TurnEnvelope

WithMetadataScope stamps session scope onto envelope metadata for /new entry-key resolution.

func WithRoute 

func WithRoute(ctx context.Context, route agentkit.RouteRef) context.Context

WithRoute returns ctx with an updated envelope route.

func WithSession 

func WithSession(ctx context.Context, s agentkit.Session) context.Context

WithSession attaches the turn's open session for tool handlers (e.g. delegate).

func WithWorkspace 

func WithWorkspace(ctx context.Context, workspace string) context.Context

WithWorkspace returns ctx with an updated envelope workspace.

func WithWorkspaceService 

func WithWorkspaceService(ctx context.Context, ws workspace.Service) context.Context

WithWorkspaceService attaches the workspace resolver used for session spill files.

func WorkspaceDirName 

func WorkspaceDirName(key string) string

WorkspaceDirName maps a workspace key to a single safe path segment.

func WorkspaceFromContext 

func WorkspaceFromContext(ctx context.Context) string

WorkspaceFromContext reports the tenant workspace key for the current turn. Runner should set TurnEnvelope.Workspace explicitly; fallback derivation logs a warning.

func WorkspaceKey 

func WorkspaceKey(sessionID string) string

WorkspaceKey derives the workspace isolation key from an opaque SessionID. Routable IM-style ids collapse to platform:channel; non-routable ids keep platform plus the first segment after the platform prefix.

func WorkspaceKeyFromLocalDir 

func WorkspaceKeyFromLocalDir(dirName string, omitPlatform bool) string

WorkspaceKeyFromLocalDir maps a tenant directory name under localBase back to a workspace key. This mirrors WorkspaceLocalDirName for the common platform_channel layout.

func WorkspaceLocalDirName 

func WorkspaceLocalDirName(key string, omitPlatform bool) string

WorkspaceLocalDirName maps a workspace key to a single safe path segment under localBase. When omitPlatform is true, only the first routing segment is used.

func WorkspaceServiceFromContext 

func WorkspaceServiceFromContext(ctx context.Context) workspace.Service

WorkspaceServiceFromContext returns the workspace service for spill I/O, if set.

Types

type ActiveEntryMode 

type ActiveEntryMode string

ActiveEntryMode selects which key active-session mapping uses. 

const (
	ActiveEntryEffective ActiveEntryMode = "effective"
	ActiveEntryDelivery  ActiveEntryMode = "delivery"
)

type AsyncEmitter 

type AsyncEmitter struct {
	// contains filtered or unexported fields
}

AsyncEmitter wraps an OutboundEmit so calls return immediately while events are delivered in arrival order by a single goroutine. This keeps async subagent outbound (e.g. ACP SessionUpdate) from blocking the child agent runtime on platform I/O, while preserving event order for progress cards. Close must be called when the emitter is no longer needed to retire the goroutine; events still queued are best-effort drained.

func NewAsyncEmitter 

func NewAsyncEmitter(inner agentkit.OutboundEmit) *AsyncEmitter

NewAsyncEmitter returns an emitter that serializes events through a single goroutine. Returns nil when inner is nil so callers can assign directly.

func (*AsyncEmitter) Close 

func (e *AsyncEmitter) Close()

Close drains the queue and retires the goroutine. Safe to call once.

func (*AsyncEmitter) CloseWithTimeout 

func (e *AsyncEmitter) CloseWithTimeout(d time.Duration) bool

CloseWithTimeout drains the queue like Close but gives up waiting after d. It returns true if the loop retired within d, false if it is still draining (the loop goroutine keeps running best-effort and retires once the queue is empty). Use this on paths where blocking forever on platform I/O would stall a more important step (e.g. async subagent follow-up delivery): the progress card is best-effort UI and must not block the follow-up turn.

func (*AsyncEmitter) Emit 

func (e *AsyncEmitter) Emit(_ context.Context, event agentkit.OutboundEvent) error

Emit is the OutboundEmit entry point. It never blocks on platform I/O; when the queue is full the event is dropped with a warning rather than stalling the caller or growing without bound.

type DeliveryParts 

type DeliveryParts struct {
	Platform string
	Channel  string
	Thread   string
	User     string
	Routable bool
}

DeliveryParts holds parsed segments of a platform delivery SessionID.

func ParseDelivery 

func ParseDelivery(id agentkit.SessionID, fallbackUser string) DeliveryParts

ParseDelivery splits a delivery SessionID into routing segments.

type PlatformSessionPolicy 

type PlatformSessionPolicy struct {
	ActiveEntryMode ActiveEntryMode
}

PlatformSessionPolicy holds per-platform routing overrides applied on top of runner defaults.

func PlatformSessionPolicyFor 

func PlatformSessionPolicyFor(platform string) PlatformSessionPolicy

PlatformSessionPolicyFor returns overrides for a platform, or zero when unset.

type RoutePolicy 

type RoutePolicy struct {
	ConversationScope agentkit.SessionScope
	ActiveEntryMode   ActiveEntryMode
}

RoutePolicy configures how inbound routes map to conversation and workspace.

func DefaultRoutePolicy 

func DefaultRoutePolicy(conversationScope agentkit.SessionScope) RoutePolicy

DefaultRoutePolicy is runner's default: channel conversation and workspace.

func RoutePolicyForPlatform 

func RoutePolicyForPlatform(platform string, base RoutePolicy) RoutePolicy

RoutePolicyForPlatform merges runner defaults with platform-specific overrides.

type RouteTarget 

type RouteTarget struct {
	DeliveryID  agentkit.SessionID
	ChannelID   string
	ThreadID    string
	ReplyTo     string
	ScopeUserID string
}

RouteTarget is the decoded delivery target for a session-kind route.

func RouteTargetFromRoute 

func RouteTargetFromRoute(route agentkit.RouteRef) (RouteTarget, bool)

RouteTargetFromRoute decodes structured delivery fields from a session route.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.