runtime

package
v1.0.5 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package runtime defines the execution seam (backlog AO-014, spec §6.2).

core depends only on these interfaces; the concrete executors live in the exec module (exec/native spawns real CLIs, exec/fake powers unit tests) and are wired in by cmd/fort. This is the only path from core to execution.

Index

Constants

View Source 
const (
	AuthorityChatSubscriptionIsolatedV1    AuthorityMode = "chat_subscription_isolated_v1"
	PolicyCodexSubscriptionChatV1                        = "codex-subscription-chat-v1"
	RuntimeContractCodexSubscriptionExecV1               = "codex_subscription_exec_v1"
	AdapterCodexSubscription                             = "model.chat.text-only.codex-subscription"

	ReasoningEffortMedium       ReasoningEffort = "medium"
	ReasoningContextCurrentTurn                 = "current_turn"
	AccountTypeChatGPT                          = "chatgpt"
	ThreadModeEphemeral                         = "ephemeral"
	SandboxModeReadOnly                         = "readOnly"
	ApprovalPolicyNever                         = "never"
	WorkdirModeEmptyPerTarget                   = "empty_per_target"
	ToolsModeNone                               = "none"
	ResourcePolicyDenyAndFail                   = "deny_and_fail"
	UnknownProviderIdentity                     = "unknown"
	UsageSourceCodexExecJSONL                   = "codex_exec_jsonl"

	ErrorChatPolicyUnavailable  = "chat_policy_unavailable"
	ErrorChatAuthorityViolation = "chat_authority_violation"
	ErrorProviderResultUnknown  = "provider_result_unknown"
	ErrorProviderFailed         = "provider_failed"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentSourceInventory added in v1.0.4 

type AgentSourceInventory interface {
	Inventory(context.Context, AgentSourceInventoryRequest) (AgentSourceInventorySnapshot, error)
}

AgentSourceInventory discovers source-qualified framework identities and their readiness evidence. It intentionally has no execution, enrollment, or binding method; those remain separate explicit Fort commands.

type AgentSourceInventoryRequest added in v1.0.4 

type AgentSourceInventoryRequest struct {
	ExecutionSourceID string `json:"execution_source_id"`
}

type AgentSourceInventorySnapshot added in v1.0.4 

type AgentSourceInventorySnapshot struct {
	ExecutionSource conversation.ExecutionSource `json:"execution_source"`
	Agents          []SourceAgentInventory       `json:"agents"`
	ObservedAt      time.Time                    `json:"observed_at"`
}

func (AgentSourceInventorySnapshot) Validate added in v1.0.4 

func (snapshot AgentSourceInventorySnapshot) Validate() error

type AuthorityMode added in v1.0.4 

type AuthorityMode string

type EventType 

type EventType string

EventType enumerates normalized run events streamed from any runtime. 

const (
	EventStarted EventType = "started" // process spawned
	EventStdout  EventType = "stdout"  // raw stdout line
	EventStderr  EventType = "stderr"  // raw stderr line
	EventMessage EventType = "message" // normalized assistant/output message
	EventExited  EventType = "exited"  // process exited (Code set)
	EventError   EventType = "error"   // runtime-level error (Data set)
	// EventTool: the agent invoked a tool (spec 030). Data is a compact JSON
	// object {"name":..., "summary":...}.
	EventTool EventType = "tool"
	// EventSubagent: the agent spawned a sub-task (spec 030; claude's Task
	// tool). Data is {"description":..., "agent":...}.
	EventSubagent EventType = "subagent"
)

type HandoffEmitter added in v1.0.4 

type HandoffEmitter interface {
	EmitHandoff(context.Context, HandoffEmitterRequest) (StructuredHandoffEmission, error)
}

HandoffEmitter is the only adapter seam allowed to translate one provider-native structured tool/action into Agent-initiated Handoff intent. It has no method for parsing prose or dispatching work; persistence and authority intersection remain Fort commands outside the adapter.

type HandoffEmitterRequest added in v1.0.4 

type HandoffEmitterRequest struct {
	AdapterID                string `json:"adapter_id"`
	AdapterRevision          string `json:"adapter_revision"`
	InvocationID             string `json:"invocation_id"`
	AccountID                string `json:"account_id"`
	SourceAgentID            string `json:"source_agent_id"`
	SourceBehaviorRevisionID string `json:"source_behavior_revision_id"`
	SourceBindingRevisionID  string `json:"source_binding_revision_id"`
	StructuredPayload        []byte `json:"structured_payload"`
}

func (HandoffEmitterRequest) Validate added in v1.0.4 

func (request HandoffEmitterRequest) Validate() error

type ProviderUsage added in v1.0.4 

type ProviderUsage struct {
	InputTokens       int64 `json:"input_tokens"`
	CachedInputTokens int64 `json:"cached_input_tokens"`
	OutputTokens      int64 `json:"output_tokens"`
	ReasoningTokens   int64 `json:"reasoning_tokens"`
}

type ReasoningEffort added in v1.0.4 

type ReasoningEffort string

type ResponseMetadata added in v1.0.4 

type ResponseMetadata struct {
	ProviderThreadID                string        `json:"provider_thread_id"`
	RequestedModel                  string        `json:"requested_model"`
	ResolvedModel                   string        `json:"resolved_model"`
	SelectedAdapterID               string        `json:"selected_adapter_id"`
	SelectedAdapterRevision         string        `json:"selected_adapter_revision"`
	SelectedCodexVersion            string        `json:"selected_codex_version"`
	SelectedCodexExecutableRevision string        `json:"selected_codex_executable_revision"`
	SelectedCodexSchemaRevision     string        `json:"selected_codex_schema_revision"`
	ObservedAdapterID               string        `json:"observed_adapter_id"`
	ObservedAdapterRevision         string        `json:"observed_adapter_revision"`
	ObservedCodexVersion            string        `json:"observed_codex_version"`
	ObservedCodexExecutableRevision string        `json:"observed_codex_executable_revision"`
	ObservedCodexSchemaRevision     string        `json:"observed_codex_schema_revision"`
	TerminalStatus                  string        `json:"terminal_status"`
	UsageSource                     string        `json:"usage_source"`
	Usage                           ProviderUsage `json:"usage"`
}

func (ResponseMetadata) Validate added in v1.0.4 

func (m ResponseMetadata) Validate() error

type RoutineAuthority added in v1.0.4 

type RoutineAuthority interface {
	InspectSourceRoutine(context.Context, RoutineAuthorityInspectionRequest) (SourceRoutineAuthorityEvidence, error)
	FenceSourceRoutine(context.Context, RoutineAuthorityFenceRequest) (SourceRoutineFenceReceipt, error)
}

RoutineAuthority can inspect and fence a framework-native schedule before a Fort Routine import. Deliberately, it exposes no enqueue or execution method.

type RoutineAuthorityFenceRequest added in v1.0.4 

type RoutineAuthorityFenceRequest struct {
	Inspection  SourceRoutineAuthorityEvidence `json:"inspection"`
	RequestedAt time.Time                      `json:"requested_at"`
}

func (RoutineAuthorityFenceRequest) Validate added in v1.0.4 

func (request RoutineAuthorityFenceRequest) Validate() error

type RoutineAuthorityInspectionRequest added in v1.0.4 

type RoutineAuthorityInspectionRequest struct {
	AccountID             string `json:"account_id"`
	ExecutionSourceID     string `json:"execution_source_id"`
	SourceAgentID         string `json:"source_agent_id"`
	OpaqueSourceRoutineID string `json:"opaque_source_routine_id"`
}

type Run 

type Run interface {
	ID() string
	// Stream returns the event channel; it is closed when the run terminates.
	Stream() <-chan RunEvent
	// Signal injects input into a running interactive task (HITL).
	Signal(input string) error
	// Cancel terminates the run.
	Cancel() error
	// Status returns the current status.
	Status() Status
	// Wait blocks until the run terminates and returns the terminal status.
	Wait() Status
}

Run is a handle to a dispatched invocation: stream (events), status, and signal (stdin injection for human-in-the-loop) + cancel.

type RunEvent 

type RunEvent struct {
	RunID     string            `json:"run_id"`
	Type      EventType         `json:"type"`
	Time      time.Time         `json:"time"`
	Data      string            `json:"data,omitempty"`
	Code      int               `json:"code,omitempty"` // exit code for EventExited
	ErrorCode string            `json:"error_code,omitempty"`
	Response  *ResponseMetadata `json:"response,omitempty"`
}

RunEvent is one normalized event in a run's stream.

type RunSpec 

type RunSpec struct {
	RunID   string   // caller-assigned id, echoed back on the Run
	Profile string   `json:"-"` // exact Fort-owned profile; subscription authority crosses it through the conditional wire contract
	Agent   string   // provider key: claude | codex | openclaw | hermes
	Model   string   // optional provider-specific model override; empty uses provider default
	Prompt  string   // the task body handed to the CLI
	Workdir string   // scoped working directory
	Env     []string // additional KEY=VALUE pairs
	// Machine is the resolved target host (spec 022). Empty means "here": the
	// local runtime handles it. A non-local name routes the spec to that
	// machine's runtime (exec/cluster). Providers ignore this field.
	Machine string

	// Authority and RuntimeContract are empty together for legacy execution.
	// Primary Channel turns carry the one closed subscription authority below.
	Authority              AuthorityMode   `json:"authority,omitempty"`
	RuntimeContract        string          `json:"runtime_contract,omitempty"`
	TextOnlyPolicy         *TextOnlyPolicy `json:"text_only_policy,omitempty"`
	ExpectedPolicyRevision string          `json:"-"`
}

RunSpec describes one agent invocation.

func (RunSpec) MarshalJSON added in v1.0.4 

func (s RunSpec) MarshalJSON() ([]byte, error)

MarshalJSON preserves the long-standing legacy execution wire while adding the profile required to validate the closed subscription authority. A control-plane profile never becomes a new legacy/native execution input.

func (*RunSpec) UnmarshalJSON added in v1.0.4 

func (s *RunSpec) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects a profile on empty legacy authority instead of silently accepting a wire shape that this version would never emit.

func (RunSpec) ValidateAuthority added in v1.0.4 

func (s RunSpec) ValidateAuthority() error

type Runtime 

type Runtime interface {
	// Dispatch launches spec and returns a Run handle. The returned Run begins
	// streaming immediately; the caller drains Stream() and/or calls Wait().
	Dispatch(ctx context.Context, spec RunSpec) (Run, error)
	// Name identifies the runtime implementation (for diagnostics).
	Name() string
}

Runtime spawns agent invocations. Implementations must be safe for concurrent Dispatch calls.

type SourceAgentInventory added in v1.0.4 

type SourceAgentInventory struct {
	SourceAgent  conversation.SourceAgent `json:"source_agent"`
	Capabilities []string                 `json:"capabilities"`
	Readiness    SourceAgentReadiness     `json:"readiness"`
}

type SourceAgentReadiness added in v1.0.4 

type SourceAgentReadiness struct {
	Ready            bool     `json:"ready"`
	ContractID       string   `json:"contract_id"`
	ContractRevision string   `json:"contract_revision"`
	Evidence         []string `json:"evidence"`
}

type SourceRoutineAuthorityEvidence added in v1.0.4 

type SourceRoutineAuthorityEvidence struct {
	AccountID             string    `json:"account_id"`
	ExecutionSourceID     string    `json:"execution_source_id"`
	SourceAgentID         string    `json:"source_agent_id"`
	OpaqueSourceRoutineID string    `json:"opaque_source_routine_id"`
	ProjectionRevision    int       `json:"projection_revision"`
	Enabled               bool      `json:"enabled"`
	LastOccurrence        time.Time `json:"last_occurrence"`
	NextOccurrence        time.Time `json:"next_occurrence"`
	ObservedAt            time.Time `json:"observed_at"`
}

func (SourceRoutineAuthorityEvidence) ValidateFor added in v1.0.4 

func (evidence SourceRoutineAuthorityEvidence) ValidateFor(request RoutineAuthorityInspectionRequest) error

type SourceRoutineFenceReceipt added in v1.0.4 

type SourceRoutineFenceReceipt struct {
	AccountID             string    `json:"account_id"`
	ExecutionSourceID     string    `json:"execution_source_id"`
	OpaqueSourceRoutineID string    `json:"opaque_source_routine_id"`
	ProjectionRevision    int       `json:"projection_revision"`
	FenceReceiptID        string    `json:"fence_receipt_id"`
	SourceDisabledAt      time.Time `json:"source_disabled_at"`
	LastOccurrence        time.Time `json:"last_occurrence"`
	NextOccurrence        time.Time `json:"next_occurrence"`
}

func (SourceRoutineFenceReceipt) ValidateFor added in v1.0.4 

func (receipt SourceRoutineFenceReceipt) ValidateFor(evidence SourceRoutineAuthorityEvidence) error

type State 

type State string

State is a run's lifecycle state. 

const (
	StateRunning   State = "running"
	StateSucceeded State = "succeeded"
	StateFailed    State = "failed"
	StateCanceled  State = "canceled"
)

type Status 

type Status struct {
	State    State  `json:"state"`
	ExitCode int    `json:"exit_code"`
	Err      string `json:"err,omitempty"`
}

Status is a run's terminal-or-current status.

func (Status) Terminal 

func (s Status) Terminal() bool

Terminal reports whether the run has finished.

type StructuredHandoffEmission added in v1.0.4 

type StructuredHandoffEmission struct {
	AdapterID                string    `json:"adapter_id"`
	AdapterRevision          string    `json:"adapter_revision"`
	InvocationID             string    `json:"invocation_id"`
	AccountID                string    `json:"account_id"`
	SourceAgentID            string    `json:"source_agent_id"`
	SourceBehaviorRevisionID string    `json:"source_behavior_revision_id"`
	SourceBindingRevisionID  string    `json:"source_binding_revision_id"`
	RecipientAgentID         string    `json:"recipient_agent_id"`
	ContextRecordIDs         []string  `json:"context_record_ids"`
	RequestedResult          string    `json:"requested_result"`
	ReplyToMessageID         string    `json:"reply_to_message_id,omitempty"`
	RequestedAuthority       []string  `json:"requested_authority"`
	EmittedAt                time.Time `json:"emitted_at"`
}

StructuredHandoffEmission is adapter-validated intent only. Recipient revisions, output Conversation, delegation grant, policy intersection, target, lease, and lifecycle evidence are resolved and persisted by Fort.

func (StructuredHandoffEmission) ValidateFor added in v1.0.4 

func (emission StructuredHandoffEmission) ValidateFor(request HandoffEmitterRequest) error

type TextOnlyPolicy added in v1.0.4 

type TextOnlyPolicy struct {
	PolicyID                        string          `json:"policy_id"`
	PolicyRevision                  string          `json:"policy_revision"`
	Model                           string          `json:"model"`
	ReasoningEffort                 ReasoningEffort `json:"reasoning_effort"`
	ReasoningContext                string          `json:"reasoning_context"`
	RequestTimeoutMillis            int             `json:"request_timeout_millis"`
	DeveloperInstructionRevision    string          `json:"developer_instruction_revision"`
	AccountType                     string          `json:"account_type"`
	AccountPlan                     string          `json:"account_plan"`
	SelectedAdapterID               string          `json:"selected_adapter_id"`
	SelectedAdapterRevision         string          `json:"selected_adapter_revision"`
	SelectedCodexVersion            string          `json:"selected_codex_version"`
	SelectedCodexExecutableRevision string          `json:"selected_codex_executable_revision"`
	SelectedCodexSchemaRevision     string          `json:"selected_codex_schema_revision"`
	ThreadMode                      string          `json:"thread_mode"`
	SandboxMode                     string          `json:"sandbox_mode"`
	ApprovalPolicy                  string          `json:"approval_policy"`
	WorkdirMode                     string          `json:"workdir_mode"`
	DynamicToolsMode                string          `json:"dynamic_tools_mode"`
	MCPMode                         string          `json:"mcp_mode"`
	CommandPolicy                   string          `json:"command_policy"`
	FileReadPolicy                  string          `json:"file_read_policy"`
	IsolationRevision               string          `json:"isolation_revision"`
}

TextOnlyPolicy is the complete wire-visible subscription execution policy. Authentication material and process-private executable paths never enter it.

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.