agent

type Composition ¶

type Composition struct {
	Definition workflowcompile.ResolvedDefinition `json:"definition"`
	Launch     graph.Node                         `json:"launch"`
	Wait       *graph.Node                        `json:"wait,omitempty"`
	Edges      []graph.Edge                       `json:"edges,omitempty"`
}

Composition is the deterministic expansion of agent_launch. Definition is resolved child-workflow material owned by the adapter package. Launch and optional Wait are parent graph nodes; Edges contains the wait's data edge.

Without Wait, Launch retains the authored node identity and exposes the ordinary call@v1 run-id, status, events-ref, cancellation, and outputs-ref handle fields. With Wait, Wait retains the authored identity and exposes the ordinary wait_for@v1 payload, resume, and timed_out fields; payload is the schema-bound object containing the agent handle, status, and result. The source expander must preserve these distinct downstream contracts.

func Compose(request CompositionRequest) (Composition, error)

type CompositionRequest ¶

type CompositionRequest struct {
	NodeID      string                  `json:"node_id"`
	DisplayName string                  `json:"display_name,omitempty"`
	Config      graph.Config            `json:"config"`
	ParentClose graph.ParentClosePolicy `json:"parent_close"`
	Timeout     *graph.TimeoutPolicy    `json:"timeout,omitempty"`
	Retry       *graph.RetryPolicy      `json:"retry,omitempty"`
	Wait        *WaitPolicy             `json:"wait,omitempty"`
	// InputBindings are ordinary parent call bindings. Compose declares a
	// matching generated-child input and forwards each value to agent_session.
	InputBindings map[string]graph.Binding `json:"input_bindings,omitempty"`
	Source        *graph.SourceRef         `json:"source,omitempty"`
}

CompositionRequest describes one graph-native agent_launch declaration. Config is the agent_session config embedded in the generated child. Timeout and Retry apply to that external operation, while ParentClose applies to the ordinary call child-run link.

type Kind ¶

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

Kind implements agent_session@v1 as an ordinary recoverable external operation. agent_launch composition places this kind in a child workflow.

func New(options Options) (*Kind, error)

func Register(registry stepkind.Registry, options Options) (*Kind, error)

func (k *Kind) Cancel(ctx context.Context, ref stepkind.ExternalOperationRef) error

func (k *Kind) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)

func (k *Kind) Heartbeat(ctx context.Context, ref stepkind.ExternalOperationRef) error

func (k *Kind) Observe(ctx context.Context, ref stepkind.ExternalOperationRef) (stepkind.Observation, error)

func (*Kind) Spec() stepkind.StepKindSpec

func (*Kind) ValidateConfig(_ context.Context, input graph.Config) []diagnostic.Diagnostic

type LaunchOutcome ¶

type LaunchOutcome string

LaunchOutcome distinguishes a new host launch from an exact replay.

const (
	LaunchApplied  LaunchOutcome = "applied"
	LaunchReplayed LaunchOutcome = "replayed"
)

type LaunchRequest ¶

type LaunchRequest struct {
	Identity       LogicalIdentity `json:"identity"`
	Substrate      string          `json:"substrate"`
	LaunchID       string          `json:"launch_id"`
	LogicalAgentID string          `json:"logical_agent_id"`
	Prompt         string          `json:"prompt,omitempty"`
	Correlation    string          `json:"correlation"`
	Inputs         values.ValueSet `json:"inputs"`
	IdempotencyKey string          `json:"idempotency_key"`
}

LaunchRequest is the immutable extraction-safe launch envelope. Inputs stay typed; resolved credentials and provider-specific session/team data must not enter this contract. IdempotencyKey identifies the same logical launch across attempts and process recovery.

func (r LaunchRequest) Digest() (string, error)

func (r LaunchRequest) Validate() error

type LaunchResult ¶

type LaunchResult struct {
	Outcome LaunchOutcome `json:"outcome"`
	Ref     SessionRef    `json:"ref"`
	Handle  SessionHandle `json:"handle"`
}

LaunchResult binds one exact request digest to its durable session ref and safe workflow handle.

func (r LaunchResult) Validate(request LaunchRequest) error

type LogicalIdentity ¶

type LogicalIdentity struct {
	RunID     string `json:"run_id"`
	NodeID    string `json:"node_id"`
	Iteration string `json:"iteration,omitempty"`
}

LogicalIdentity excludes attempt number so ambiguous retries of the same expanded child node use one launch identity.

func (i LogicalIdentity) Validate() error

type Options ¶

type Options struct{ Host SessionHost }

Options supplies the host boundary for agent_session@v1.

type SessionFailure ¶

type SessionFailure struct {
	Code      string
	Message   string
	Retryable bool
	Cause     error
}

SessionFailure contains only safe-to-persist failure metadata. Cause stays process-local and is never formatted by the adapter.

type SessionHandle ¶

type SessionHandle struct {
	SessionID   string `json:"session_id"`
	SessionURI  string `json:"session_uri,omitempty"`
	Mailbox     string `json:"mailbox,omitempty"`
	Substrate   string `json:"substrate"`
	Correlation string `json:"correlation"`
}

SessionHandle is the typed safe handle exposed to workflow consumers. URIs must not carry userinfo, query parameters, fragments, or credentials.

func (h SessionHandle) Validate() error

type SessionHost ¶

type SessionHost interface {
	LaunchSession(context.Context, LaunchRequest) (LaunchResult, error)
	ObserveSession(context.Context, SessionRef) (SessionObservation, error)
	HeartbeatSession(context.Context, SessionRef) error
	CancelSession(context.Context, SessionRef) error
}

SessionHost is the complete app-owned boundary for durable agent sessions. LaunchSession must be concurrency-safe and exact-replay safe by IdempotencyKey, returning ErrLaunchConflict for a changed request. The other methods must locate work solely from SessionRef so runtime recovery after a process restart never depends on process-local adapter state. Hosts may use Prompt and Inputs only at the immediate launch boundary; durable host state stores the request digest and non-secret references, never raw prompt, resolved credentials, or typed input payloads.

type SessionHostFuncs ¶

type SessionHostFuncs struct {
	Launch    func(context.Context, LaunchRequest) (LaunchResult, error)
	Observe   func(context.Context, SessionRef) (SessionObservation, error)
	Heartbeat func(context.Context, SessionRef) error
	Cancel    func(context.Context, SessionRef) error
}

SessionHostFuncs adapts functions to SessionHost for hosts and tests.

func (f SessionHostFuncs) CancelSession(ctx context.Context, ref SessionRef) error

func (f SessionHostFuncs) HeartbeatSession(ctx context.Context, ref SessionRef) error

func (f SessionHostFuncs) LaunchSession(ctx context.Context, request LaunchRequest) (LaunchResult, error)

func (f SessionHostFuncs) ObserveSession(ctx context.Context, ref SessionRef) (SessionObservation, error)

type SessionObservation ¶

type SessionObservation struct {
	State    SessionState
	Handle   SessionHandle
	Result   *values.Value
	Progress map[string]string
	Failure  *SessionFailure
}

SessionObservation is returned by the injected host. Result is an exact typed value; the adapter applies a private/run minimum classification before returning it to runtime persistence.

type SessionRef ¶

type SessionRef struct {
	ID            string `json:"id"`
	Substrate     string `json:"substrate"`
	Correlation   string `json:"correlation"`
	RequestDigest string `json:"request_digest"`
}

SessionRef is the minimum durable, non-secret reference required to observe, heartbeat, or cancel an agent session after restart.

func (r SessionRef) Validate() error

type SessionState ¶

type SessionState string

SessionState is the host-observed terminal or pending session state.

const (
	SessionPending   SessionState = "pending"
	SessionSucceeded SessionState = "succeeded"
	SessionFailed    SessionState = "failed"
	SessionCanceled  SessionState = "canceled"
)

type SourceExpander ¶

type SourceExpander struct{}

SourceExpander lowers agent_launch into the ordinary call/wait composition implemented by this package. It is stateless and concurrency-safe.

func (SourceExpander) ExpandNode(request workflowcompile.NodeExpansionRequest) (workflowcompile.NodeExpansion, bool, []diagnostic.Diagnostic)

func (SourceExpander) Name() string

type WaitPolicy ¶

type WaitPolicy struct {
	Timeout graph.Duration `json:"timeout"`
}

WaitPolicy enables agent_launch wait sugar. Timeout is the canonical child-run wait deadline; it does not turn timeout into a successful result.