Documentation
¶
Overview ¶
Package runtime assembles and owns a deployment, its event routing, and transport-neutral sessions.
Index ¶
- Variables
- func PatternAgentLifecycle() event.Pattern
- func SubjectAgentRegistered(id string) event.Subject
- func SubjectAgentRemoved(id string) event.Subject
- type AgentLifecycleEvent
- type AgentRegistry
- func (r *AgentRegistry) Agent(id string) (*agent.Agent, bool)
- func (r *AgentRegistry) AgentNames() []string
- func (r *AgentRegistry) Close() error
- func (r *AgentRegistry) Delete(id string) (*agent.Agent, bool)
- func (r *AgentRegistry) Instance(id string) (*agent.Agent, bool)
- func (r *AgentRegistry) Put(id string, instance *agent.Agent) error
- type Builder
- type Config
- type DynamicCatalogConfig
- type HostFactoryDecorator
- type RegisterAgentOption
- type Runtime
- func (r *Runtime) Agent(name string) (*agent.Agent, bool)
- func (r *Runtime) AgentNames() []string
- func (r *Runtime) Attach(ctx context.Context, pattern event.Pattern, sink event.Sink, ...) (func(), error)
- func (r *Runtime) Close() error
- func (r *Runtime) RegisterAgent(ctx context.Context, name string, def agent.Definition, ...) (*agent.Agent, error)
- func (r *Runtime) Sessions() *session.Manager
- func (r *Runtime) UnregisterAgent(ctx context.Context, name string, opts ...UnregisterAgentOption) error
- type SessionConfig
- type UnregisterAgentOption
Constants ¶
This section is empty.
Variables ¶
var ErrBuilderUsed = errdefs.Conflictf("runtime Builder has already been used")
ErrBuilderUsed reports an attempted registration or Build after a Builder's single construction attempt has started.
Functions ¶
func PatternAgentLifecycle ¶ added in v0.1.11
PatternAgentLifecycle matches every runtime agent lifecycle event.
func SubjectAgentRegistered ¶ added in v0.1.11
SubjectAgentRegistered returns the subject for a successful dynamic registration:
runtime.agent.<id>.registered
func SubjectAgentRemoved ¶ added in v0.1.11
SubjectAgentRemoved returns the subject for a successful dynamic removal:
runtime.agent.<id>.removed
Types ¶
type AgentLifecycleEvent ¶ added in v0.1.11
type AgentLifecycleEvent struct {
AgentID string `json:"agent_id"`
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
}
AgentLifecycleEvent is the payload of runtime.agent.* lifecycle events. It intentionally carries only identity and card summary, so the envelope stays small.
type AgentRegistry ¶ added in v0.1.11
type AgentRegistry struct {
// contains filtered or unexported fields
}
AgentRegistry is the runtime-live, concurrency-safe agent view. Dynamically registered agents live in its own map; statically deployed agents are served as a read-only fallback from the deployment result. It implements session.InstanceResolver, so the session manager resolves both kinds through one seam.
func (*AgentRegistry) Agent ¶ added in v0.1.11
func (r *AgentRegistry) Agent(id string) (*agent.Agent, bool)
Agent resolves a dynamically registered agent first, then falls back to the deployment snapshot.
func (*AgentRegistry) AgentNames ¶ added in v0.1.11
func (r *AgentRegistry) AgentNames() []string
AgentNames returns the sorted union of dynamically registered and deployed agent names.
func (*AgentRegistry) Close ¶ added in v0.1.11
func (r *AgentRegistry) Close() error
Close closes every dynamically registered agent. Deployed agents are owned (and closed) by deploy.Result, so they are left untouched.
func (*AgentRegistry) Delete ¶ added in v0.1.11
func (r *AgentRegistry) Delete(id string) (*agent.Agent, bool)
Delete removes and returns a dynamically registered agent. Deployed agents are not affected and return ok=false.
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder transactionally assembles one Runtime over a resource registry. It is single-use.
func NewBuilder ¶
NewBuilder creates a Runtime builder over a resource registry. The registry must already hold every resource factory the document references (event bus, checkpoint store, tool assemblies, engines, hooks, ...).
func (*Builder) Build ¶
Build constructs one fully started Runtime. A Builder may be used for exactly one Build attempt.
func (*Builder) WithHostFactory ¶
func (b *Builder) WithHostFactory(decorator HostFactoryDecorator) error
WithHostFactory installs a decorator over the runtime's base host factory. It is rejected when nil or after Build starts.
type Config ¶
type Config struct {
// EventBus names the deployment resource providing event.Bus.
EventBus string
// CheckpointStore names the deployment resource providing
// agent.CheckpointStore; empty keeps checkpoints as a host no-op.
CheckpointStore string
// Sessions configures the runtime-owned session manager.
Sessions SessionConfig
DynamicCatalog *DynamicCatalogConfig
}
Config is the strictly decoded deploy.Document.Runtime subtree.
type DynamicCatalogConfig ¶
DynamicCatalogConfig maps agent IDs to tool.Assembly resource names; the reserved "default" key is the fallback for agents without an explicit entry. The injection policy itself lives in each tool.Assembly's dynamic settings — the runtime only wires the assembly and creates per-session views.
type HostFactoryDecorator ¶
type HostFactoryDecorator func(session.HostFactory) (session.HostFactory, error)
HostFactoryDecorator wraps the runtime's built-in base host factory. The decorator receives the base factory (event publishing, interrupts, ask-user, checkpointing) and MUST delegate anything it does not override back to it — the canonical shape is agent.HostFuncs{Inner: base, ...}.
type RegisterAgentOption ¶ added in v0.1.11
type RegisterAgentOption func(*registerOptions) error
RegisterAgentOption configures one dynamic agent registration.
func WithToolAssembly ¶ added in v0.1.11
func WithToolAssembly(resourceName string) RegisterAgentOption
WithToolAssembly names a built tool.Assembly resource used as the new agent's dynamic catalog entry. It requires the deployment to have a dynamic_catalog section.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime owns the complete application object graph built by Builder.
func (*Runtime) Agent ¶ added in v0.1.11
Agent resolves an agent by name from the live view (dynamically registered first, then the deployment snapshot).
func (*Runtime) AgentNames ¶ added in v0.1.11
AgentNames returns the sorted union of deployed and dynamically registered agent names.
func (*Runtime) Attach ¶ added in v0.1.5
func (r *Runtime) Attach( ctx context.Context, pattern event.Pattern, sink event.Sink, opts ...event.AttachOption, ) (func(), error)
Attach subscribes pattern on the runtime's borrowed event router and delivers matching envelopes to sink until the returned stop function is called, ctx is cancelled, the subscription ends, or the sink returns an error (which detaches that attachment). It is the runtime-level entry point for consumers that want run events without resolving the deployment document's event_bus resource themselves — for example UI sinks subscribing to prompt lifecycle events:
detach, err := app.Attach(ctx, session.PatternPromptRequested(), sink) defer detach()
The router is owned by the Runtime: Attach fails with NotAvailable after Close, and every attachment is torn down when the Runtime closes. External attachments inherit the bus default backpressure (DropNewest), so a slow consumer drops envelopes instead of blocking the run pipeline; pass event.WithAttachBackpressure to opt into a different policy for a specific subscription.
func (*Runtime) Close ¶
Close stops new session work, waits for active turns, and releases all owned objects. Concurrent callers wait for and receive the same aggregate result.
func (*Runtime) RegisterAgent ¶ added in v0.1.11
func (r *Runtime) RegisterAgent( ctx context.Context, name string, def agent.Definition, opts ...RegisterAgentOption, ) (*agent.Agent, error)
RegisterAgent assembles and registers a new agent at runtime: the Definition is run through the same assembly path as deployment (deploy.BindAgent), then the agent becomes resolvable by the session manager. The name must not collide with an existing dynamic agent or a deployed agent (both are Conflict).
RegisterAgent is serialized with UnregisterAgent and Close. After Close it fails with NotAvailable.
func (*Runtime) UnregisterAgent ¶ added in v0.1.11
func (r *Runtime) UnregisterAgent( ctx context.Context, name string, opts ...UnregisterAgentOption, ) error
UnregisterAgent removes a dynamically registered agent: new session activity is blocked, live sessions are drained (active turns are allowed to finish, bounded by ctx or WithRemoveTimeout), and the agent's engine and hooks are closed. Unknown names are an idempotent no-op; deployed (static) agents cannot be removed at runtime.
type SessionConfig ¶
type SessionConfig struct {
IdleTimeout time.Duration
SinkBuffer int
SpeculativeBufferEvents int
SpeculativeBufferBytes int
DeliveryConcurrency int
MaxSessions int
Resume bool
}
SessionConfig configures the runtime-owned session manager.
type UnregisterAgentOption ¶ added in v0.1.11
type UnregisterAgentOption func(*removeOptions) error
UnregisterAgentOption configures one dynamic agent removal.
func WithRemoveTimeout ¶ added in v0.1.11
func WithRemoveTimeout(d time.Duration) UnregisterAgentOption
WithRemoveTimeout bounds how long UnregisterAgent waits for active turns to finish before giving up. On timeout the agent is left in place (registration intact, sessions intact) and the call is retryable.
Source Files
Directories