agent

package
v0.36.0 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2026 License: MIT Imports: 8 Imported by: 0

README

agent/ — multi-provider agent-runner contract

This package defines the provider-agnostic types every agent provider implementation and the runner orchestrator depend on. It is the foundation block of the v0.5.0 multi-provider agent-runner subsystem.

What lives here

File Purpose
doc.go Package overview + the 9-capability matrix
types.go Enums, struct types: ProviderName, Capability, Capabilities, SandboxLevel, EffortLevel, MCPServerConfig, PermissionConfig, CodeIntelEnforcement, Spec, CostData, Result, BackstopReport, QualityReport, plus the IsSupported capability gate
provider.go Provider interface (5 methods: Name, Capabilities, Spawn, Resume, Shutdown)
handle.go Handle interface (4 methods: SessionID, Events, Inject, Stop)
event.go Event sealed-interface + 8 variant structs + MarshalEvent / UnmarshalEvent polymorphic JSON helpers
errors.go Sentinel errors: ErrUnsupported, ErrNoProvider, ErrSessionNotFound, ErrSpawnFailed, ErrProviderUnavailable

What does NOT live here

  • Provider implementations (provider/claude, provider/codex, provider/stub) — they import this package.
  • The runner orchestration loop — runner/ imports this package.
  • HTTP clients, process spawning, filesystem I/O, MCP-stdio bridging, worktree management, prompt rendering, result posting.

This package is pure types + interfaces. No business logic, no I/O, no dependencies beyond the Go standard library and log/slog.

Relationship to the legacy TypeScript surface

This package is the verbatim Go translation of the legacy TS contract at:

../agentfactory/packages/core/src/providers/types.ts

JSON tags on every struct use camelCase to match the TS wire format verbatim. Readers of QueuedWork.resolvedProfile JSON across the fleet (daemon, platform-side workflow nodes, rensei-tui) depend on this.

Public package boundary

This package is exported at the top level of the module (github.com/RenseiAI/donmai/agent). Downstream consumers including rensei-tui import it directly without depending on the rest of donmai. F.1.1 §1 ratifies this boundary. Do not move or rename without an ADR.

The 9 capabilities

A provider declares a Capabilities struct describing which optional behaviors it supports. The runner gates on these flags via IsSupported(caps, capability) rather than try-catching unsupported operations. The 9 named capabilities (each maps 1:1 to a flag on Capabilities):

Capability constant Capabilities field Meaning
CapMessageInjection SupportsMessageInjection Handle.Inject can deliver mid-session user messages
CapSessionResume SupportsSessionResume Provider.Resume can continue a prior session
CapToolPlugins SupportsToolPlugins Provider accepts MCP stdio tool plugins (af_linear, af_code)
CapBaseInstructions NeedsBaseInstructions Provider consumes Spec.BaseInstructions
CapPermissionConfig NeedsPermissionConfig Provider consumes Spec.PermissionConfig
CapCodeIntelEnforcement SupportsCodeIntelligenceEnforcement Provider supports the Grep/Glob → af_code redirect
CapSubagentEvents EmitsSubagentEvents Provider emits Anthropic-style subagent (Task) events
CapReasoningEffort SupportsReasoningEffort Provider honors Spec.Effort (low/medium/high/xhigh)
CapToolPermissionFormatClaude ToolPermissionFormat == "claude" Provider uses Claude's Bash(prefix:glob) tool-permission grammar
v0.5.0 provider matrix (per F.1.1 §3 and locked coordinator decisions)
Provider Inject Resume ToolPlugins BaseInstr PermConfig CodeIntel Subagent Effort PermFmt
claude false true true false false false true true claude
codex false true true true true false false true codex
stub configurable per-test configurable per-test

The bolded claude flags reflect the v0.5.0 CLI shell-out approach: the Claude CLI does not expose mid-session injection in JSON-stream mode, and the runtime canUseTool callback is not yet exposed by the CLI either. Both flip to true in F.5 if/when a wrapper sidecar lands.

Sealed Event variants

The Event interface is sealed: it requires both Kind() EventKind and an unexported isAgentEvent() marker. External packages cannot satisfy the interface, which keeps the discriminated union closed to the 8 variants defined in event.go:

InitEvent → SystemEvent* → (AssistantTextEvent | ToolUseEvent | ToolResultEvent | ToolProgressEvent)* → (ResultEvent | ErrorEvent)

To decode an Event polymorphically from JSON (e.g. the events.jsonl file the runner persists per session), use:

ev, err := agent.UnmarshalEvent(jsonBytes)

UnmarshalEvent reads a "kind" discriminator field and dispatches to the matching variant struct. Use MarshalEvent to encode in the same shape; the wire format is {"kind": "<EventKind>", ...variant fields...}.

Wire-format compatibility rule

If you change a wire shape (add/remove/rename a JSON field, change a JSON tag, add an enum value), you must update the F.1.1 design doc in the same change:

../runs/2026-05-01-wave-6-fleet-iteration/F1.1-runner-contract.md

The doc is the contract source-of-truth — keeping it single-sourced prevents drift between implementations.

Testing

go test -race ./agent/...

Tests cover:

  • JSON round-trip for Spec, Capabilities, Result (verifies camelCase tags + omitempty behavior).
  • Round-trip for every Event variant + MarshalEvent / UnmarshalEvent polymorphic dispatch + error paths.
  • IsSupported capability gate (table-driven over all 9 capabilities).
  • Sentinel errors are distinct (no accidental aliasing).
  • Provider and Handle interfaces are implementable from outside the package (compile-time check via a no-op type).

Documentation

Overview

Package agent declares the provider-agnostic contract for the donmai multi-provider agent-runner subsystem.

This package is the verbatim Go translation of the legacy TypeScript type contract at: 

../agentfactory/packages/core/src/providers/types.ts

It defines the types every provider implementation (claude, codex, stub, future spring-ai/a2a/gemini/ollama/opencode/jules/amp) and the runner orchestrator depend on. The package is pure types + interfaces with zero behavior, no I/O, no business logic, and no dependencies beyond the Go standard library and log/slog.

Public Package

This package is exported at the top level of the module: 

github.com/RenseiAI/donmai/agent

It is importable by downstream consumers including rensei-tui without requiring an donmai dependency cascade. F.1.1 §1 ratifies this boundary.

Wire Format Compatibility

JSON tags use camelCase to match the legacy TS shape verbatim. The JSON shape is consumed by readers of QueuedWork.resolvedProfile across the fleet. If you change a wire shape (add/remove/rename a JSON field), update the F.1.1 design doc at: 

../runs/2026-05-01-wave-6-fleet-iteration/F1.1-runner-contract.md

in the same change so the contract stays single-sourced.

The Nine Capabilities

Providers declare a Capabilities struct describing which optional features they support. The runner gates behavior off these flags rather than try-catching unsupported operations. The named capability constants (CapMessageInjection, CapSessionResume, ...) align 1:1 with the Capabilities struct fields and are used with IsSupported() helper.

Sealed Event Variants

The Event interface uses the sealed-interface variant pattern: each of the 8 event variants (InitEvent, SystemEvent, AssistantTextEvent, ToolUseEvent, ToolResultEvent, ToolProgressEvent, ResultEvent, ErrorEvent) implements both Kind() EventKind and the unexported isAgentEvent() marker. New variants must be added to this package — external packages cannot satisfy the interface, which keeps the discriminated union closed. For polymorphic JSON decoding use UnmarshalEvent.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnsupported is returned when a provider is asked to perform a
	// capability it does not advertise (e.g. Handle.Inject on a
	// provider with SupportsMessageInjection=false, or Provider.Resume
	// on a provider with SupportsSessionResume=false).
	ErrUnsupported = errors.New("agent: capability not supported by provider")

	// ErrNoProvider is returned when the runner cannot resolve a
	// Provider for a requested ProviderName (e.g. an org's profile
	// names a provider not registered with the running binary).
	ErrNoProvider = errors.New("agent: no provider registered for name")

	// ErrSessionNotFound is returned by Provider.Resume when the
	// requested session id is unknown or has already terminated.
	ErrSessionNotFound = errors.New("agent: session id not found")

	// ErrSpawnFailed is returned by Provider.Spawn when the provider
	// could not start the session (CLI missing, app-server
	// unreachable, etc.). Wrap with fmt.Errorf for context.
	ErrSpawnFailed = errors.New("agent: spawn failed")

	// ErrProviderUnavailable is returned by provider constructors
	// (provider.New) when the provider's runtime dependency is missing
	// or not reachable (e.g. `claude` binary not on PATH, codex
	// app-server failed to start). It is a probe-time error distinct
	// from ErrSpawnFailed which is per-session.
	ErrProviderUnavailable = errors.New("agent: provider runtime unavailable")
)

Sentinel errors returned by Provider and Handle implementations.

Callers wrap these with fmt.Errorf("context: %w", err) and check with errors.Is. Per F.1.1 §2 these are the contract-level errors; provider-specific errors live in the provider subpackage.

Functions

func IsSupported 

func IsSupported(caps Capabilities, c Capability) bool

IsSupported reports whether a Capabilities matrix has the named Capability flag set. This is the runner's preferred gate over reading individual fields, because it keeps gating expressions consistent across providers.

func MarshalEvent 

func MarshalEvent(e Event) ([]byte, error)

MarshalEvent encodes an Event to JSON, embedding the discriminant "kind" field so the value can be round-tripped through UnmarshalEvent.

The wire shape is: 

{"kind": "<EventKind>", ...variant fields...}

Variant fields are flattened onto the outer object. Use MarshalEvent when persisting events to JSONL / streaming over HTTP; the JSONL shape is what runner/ writes to <worktree>/.agent/events.jsonl per F.1.1 §4 step 9.

Types

type AssistantTextEvent 

type AssistantTextEvent struct {
	// Text is the assistant text chunk.
	Text string `json:"text"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

AssistantTextEvent carries an incremental assistant-text output chunk. Verbatim port of AgentAssistantTextEvent. The runner accumulates Text across multiple events to scan for the WORK_RESULT marker.

func (AssistantTextEvent) Kind 

func (AssistantTextEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type AuthMode added in v0.28.0 

type AuthMode string

AuthMode — the canonical 5-mode set (no api-key mode; byok=user key, metered=Rensei key). 

const (
	AuthBYOK        AuthMode = "byok"
	AuthMetered     AuthMode = "metered"
	AuthShared      AuthMode = "shared"
	AuthHostSession AuthMode = "host-session"
	AuthLocal       AuthMode = "local"
)

AuthMode constants name the canonical 5 authentication modes.

type BackstopReport 

type BackstopReport struct {
	// Triggered is true when the backstop ran (i.e. the contract had
	// unfilled fields).
	Triggered bool `json:"triggered"`

	// Pushed is true when the backstop ran git push -u origin <branch>.
	Pushed bool `json:"pushed,omitempty"`

	// PRCreated is true when the backstop ran gh pr create.
	PRCreated bool `json:"prCreated,omitempty"`

	// PRURL is the URL of a PR the backstop created or detected.
	PRURL string `json:"prUrl,omitempty"`

	// UnfilledFields lists the contract fields the backstop could not
	// auto-recover (e.g. work_result, comment_posted). The platform
	// posts a diagnostic Linear comment for these.
	UnfilledFields []string `json:"unfilledFields,omitempty"`

	// Diagnostics is human-readable text describing what happened.
	Diagnostics string `json:"diagnostics,omitempty"`
}

BackstopReport captures what the post-session backstop did, if anything. Populated by runner/backstop.go (F.1.1 §5.6).

type Capabilities 

type Capabilities struct {
	// SupportsMessageInjection reports whether Handle.Inject works
	// (stateful providers: legacy TS Claude SDK, A2A). v0.5.0 Claude
	// CLI provider returns false here; steering reduces to stop+resume.
	SupportsMessageInjection bool `json:"supportsMessageInjection"`

	// SupportsSessionResume reports whether Provider.Resume can
	// continue a prior session.
	SupportsSessionResume bool `json:"supportsSessionResume"`

	// SupportsToolPlugins reports whether the provider can use MCP
	// tool plugins delivered via stdio servers (af_linear_*, af_code_*).
	SupportsToolPlugins bool `json:"supportsToolPlugins,omitempty"`

	// NeedsBaseInstructions reports whether the provider requires
	// persistent base instructions via Spec.BaseInstructions
	// (Codex app-server thread/start ‘instructions' field).
	NeedsBaseInstructions bool `json:"needsBaseInstructions,omitempty"`

	// NeedsPermissionConfig reports whether the provider requires
	// structured permission config via Spec.PermissionConfig (Codex
	// approval bridge).
	NeedsPermissionConfig bool `json:"needsPermissionConfig,omitempty"`

	// SupportsCodeIntelligenceEnforcement reports whether the provider
	// supports canUseTool-style code intelligence enforcement
	// (redirect Grep/Glob to af_code_* tools). v0.5.0 Claude provider
	// ships false; flip when a CLI wrapper exposes the callback.
	SupportsCodeIntelligenceEnforcement bool `json:"supportsCodeIntelligenceEnforcement,omitempty"`

	// EmitsSubagentEvents reports whether the provider emits
	// Anthropic-style subagent events (Claude Task tool progress).
	// Drives the Topology view's subagent stream rendering.
	EmitsSubagentEvents bool `json:"emitsSubagentEvents"`

	// SupportsReasoningEffort reports whether the provider honors the
	// per-step Spec.Effort (low | medium | high | xhigh). When false,
	// the dispatch path drops the value and emits a capability-mismatch
	// hook event so observers can flag silently-ignored cost-control
	// hints. Optional for backwards compatibility — a zero value is
	// treated as not supporting reasoning effort.
	SupportsReasoningEffort bool `json:"supportsReasoningEffort,omitempty"`

	// ToolPermissionFormat names the tool-permission grammar this
	// provider uses ("claude" | "codex" | "spring-ai"). When empty
	// callers should default to "claude".
	ToolPermissionFormat string `json:"toolPermissionFormat,omitempty"`

	// AcceptsAllowedToolsList reports whether the provider honors
	// Spec.AllowedTools end-to-end at Spawn time — translating it into
	// the upstream API's allow/permission grammar. Providers that ship
	// SupportsToolPlugins=true but cannot pass through AllowedTools
	// (e.g. codex routes permissions through the approval bridge) MUST
	// declare false here so the runner knows the field is silently
	// dropped. Tracks the v2 contract's acceptsAllowedToolsList flag
	// from 002-provider-base-contract.md §"Tool-use surface — forward
	// declaration".
	AcceptsAllowedToolsList bool `json:"acceptsAllowedToolsList,omitempty"`

	// AcceptsMcpServerSpec reports whether the provider honors
	// Spec.MCPServers end-to-end at Spawn time — either passing the
	// stdio configs through to the upstream API or spawning a local
	// MCP bridge that the upstream session can call. Distinct from
	// SupportsToolPlugins which only states whether tools are usable
	// at all; this flag specifies whether the Spec field shape is
	// honored.
	AcceptsMcpServerSpec bool `json:"acceptsMcpServerSpec,omitempty"`

	// HumanLabel is a human-readable provider-family display name
	// (e.g. "Claude", "Codex"). Used in TUI/dashboard surfaces and
	// log messages where the raw name is not user-friendly.
	HumanLabel string `json:"humanLabel,omitempty"`

	// SupportsTurnInputContext reports whether the provider can deliver
	// Spec.InitialContext once via the first turn's user input rather
	// than folding it into the persistent system prompt. Providers whose
	// wire protocol re-includes the system prompt on every model turn
	// (codex's baseInstructions) declare true so the runner can keep
	// large, volatile context (recalled agent memory, session history)
	// out of the per-turn re-sent prefix. Providers that have no such
	// split (or that already fold everything into one prompt) leave this
	// false; the runner then folds InitialContext into the system prompt
	// as before.
	SupportsTurnInputContext bool `json:"supportsTurnInputContext,omitempty"`
}

Capabilities is the typed capability matrix every provider declares.

Verbatim port of AgentProviderCapabilities. Flat struct (no nested objects) per the rensei-architecture base-contract validator constraint (002-provider-base-contract.md §Capabilities).

Per F.1.1 §3.1 and the locked coordinator decision, the v0.5.0 claude provider ships SupportsMessageInjection=false (no mid-session injection in CLI JSON-stream mode); flip when a wrapper sidecar lands in F.5.

Source: ../agentfactory/packages/core/src/providers/types.ts (AgentProviderCapabilities).

type Capability 

type Capability string

Capability names a single optional behavior a provider may support.

The 9 named capabilities mirror the AgentProviderCapabilities fields from the legacy TS interface verbatim. Use IsSupported(caps, cap) to gate runner behavior rather than try-catching unsupported provider operations.

Source: ../agentfactory/packages/core/src/providers/types.ts (AgentProviderCapabilities). 

const (
	CapMessageInjection           Capability = "message_injection"
	CapSessionResume              Capability = "session_resume"
	CapToolPlugins                Capability = "tool_plugins"
	CapBaseInstructions           Capability = "base_instructions"
	CapPermissionConfig           Capability = "permission_config"
	CapCodeIntelEnforcement       Capability = "code_intel_enforcement"
	CapSubagentEvents             Capability = "subagent_events"
	CapReasoningEffort            Capability = "reasoning_effort"
	CapToolPermissionFormatClaude Capability = "tool_perm_format_claude"
	// CapAcceptsAllowedToolsList reports whether the provider honors
	// Spec.AllowedTools end-to-end (translation into upstream API).
	// Tracks the v2 contract's `acceptsAllowedToolsList` flag from
	// 002-provider-base-contract.md §"Tool-use surface — forward declaration".
	CapAcceptsAllowedToolsList Capability = "accepts_allowed_tools_list"
	// CapAcceptsMcpServerSpec reports whether the provider honors
	// Spec.MCPServers end-to-end (translation into upstream API or a
	// session-local MCP bridge). Tracks the v2 contract's
	// `acceptsMcpServerSpec` flag.
	CapAcceptsMcpServerSpec Capability = "accepts_mcp_server_spec"
	// CapTurnInputContext reports whether the provider can deliver
	// session context (Spec.InitialContext) once via the first turn's
	// user input rather than folding it into the persistent system
	// prompt. Providers with a turn-input/system-prompt split (codex's
	// thread/start baseInstructions vs. turn/start input) declare true so
	// the runner can keep large, volatile context (e.g. recalled agent
	// memory) out of the re-sent system-prompt prefix.
	CapTurnInputContext Capability = "turn_input_context"
)

Named capability constants. Each maps 1:1 to a field on Capabilities.

type CodeIntelEnforcement 

type CodeIntelEnforcement struct {
	// EnforceUsage requires the agent to call at least one af_code_*
	// tool before native Grep/Glob is allowed.
	EnforceUsage bool `json:"enforceUsage"`

	// FallbackAfterAttempt allows native Grep/Glob after a single
	// af_code_* attempt, regardless of result.
	FallbackAfterAttempt bool `json:"fallbackAfterAttempt"`
}

CodeIntelEnforcement is the Grep/Glob redirect-to-af_code_* config. When set, the provider's tool callback redirects native Grep/Glob calls to af_code_* tools until the agent has attempted code intelligence at least once.

type Company added in v0.28.0 

type Company string

Company names a model-endpoint vendor (the SPEAK axis identity). 

const (
	CompanyAnthropic Company = "anthropic"
	CompanyOpenAI    Company = "openai"
	CompanyGoogle    Company = "google"
	CompanyLocal     Company = "local"
	CompanyStub      Company = "stub" // test-only, both axes
)

Company constants name each model-endpoint vendor.

type CostData 

type CostData struct {
	InputTokens       int64   `json:"inputTokens,omitempty"`
	OutputTokens      int64   `json:"outputTokens,omitempty"`
	CachedInputTokens int64   `json:"cachedInputTokens,omitempty"`
	TotalCostUsd      float64 `json:"totalCostUsd,omitempty"`
	NumTurns          int     `json:"numTurns,omitempty"`
}

CostData mirrors AgentCostData from the legacy TS providers/types.ts.

All fields are optional; providers populate what they have available.

type CostModel added in v0.28.0 

type CostModel string

CostModel — the per-cell economic model. 

const (
	CostHostSubscription CostModel = "host-subscription"
	CostMeteredPerToken  CostModel = "metered"
	CostLocalFree        CostModel = "local"
)

CostModel constants name each per-cell economic model.

type EffortLevel 

type EffortLevel string

EffortLevel mirrors EffortLevel from ../agentfactory/packages/core/src/providers/index.ts. Providers map this to their native reasoning-effort knob:

  • Claude : --effort flag
  • Codex : reasoningEffort / model_reasoning_effort
  • Gemini : thinkingBudget
const (
	EffortLow    EffortLevel = "low"
	EffortMedium EffortLevel = "medium"
	EffortHigh   EffortLevel = "high"
	EffortXHigh  EffortLevel = "xhigh"
)

EffortLevel constants. The xhigh tier matches Anthropic's reasoning-effort scale.

type EndpointBinding added in v0.28.0 

type EndpointBinding struct {
	Company       Company           `json:"company"`
	Model         string            `json:"model"`
	BaseURL       string            `json:"baseUrl"`
	Protocol      WireProtocol      `json:"protocol"`
	Host          ServingHost       `json:"host"`
	Auth          AuthMode          `json:"auth"`
	CostModel     CostModel         `json:"costModel"`
	BringsOwnAuth bool              `json:"bringsOwnAuth"`
	Env           map[string]string `json:"-"`
}

EndpointBinding — the resolved cell. The currency crossing into Spec.Endpoint.

func (EndpointBinding) IsZero added in v0.28.0 

func (b EndpointBinding) IsZero() bool

IsZero reports whether the binding is unset (today's behavior). Used by the (future, Phase-3) Spawn path to decide between Spec.Model and Endpoint.Model.

type EndpointRequest added in v0.28.0 

type EndpointRequest struct {
	Model       string            `json:"model"`
	Host        ServingHost       `json:"host"`
	Auth        AuthMode          `json:"auth"`
	Region      string            `json:"region,omitempty"`
	EnvProvided map[string]string `json:"-"`
}

EndpointRequest — every field already RESOLVED FROM CONFIG.

type ErrorEvent 

type ErrorEvent struct {
	// Message is the human-readable error message.
	Message string `json:"message"`

	// Code is an optional provider-defined error code (e.g.
	// "spawn_no_result", "rate_limited").
	Code string `json:"code,omitempty"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

ErrorEvent is a non-recoverable provider error fired before any terminal ResultEvent. The provider closes the events channel after emitting an ErrorEvent. Verbatim port of AgentErrorEvent.

func (ErrorEvent) Kind 

func (ErrorEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type Event 

type Event interface {
	// Kind returns the discriminant for this variant.
	Kind() EventKind
	// contains filtered or unexported methods
}

Event is the sealed-interface base type for all agent event variants.

Implementations: InitEvent, SystemEvent, AssistantTextEvent, ToolUseEvent, ToolResultEvent, ToolProgressEvent, ResultEvent, ErrorEvent. The unexported isAgentEvent marker prevents external packages from satisfying the interface, keeping the discriminated union closed.

To decode an Event polymorphically from JSON use UnmarshalEvent.

func UnmarshalEvent 

func UnmarshalEvent(data []byte) (Event, error)

UnmarshalEvent decodes an Event from JSON written by MarshalEvent. It reads the "kind" discriminator and dispatches to the matching variant struct. Unknown kinds return a wrapped error.

This is the polymorphic decode entry point per F.1.1 §2; runner/ uses it to read <worktree>/.agent/events.jsonl back during recovery.

type EventKind 

type EventKind string

EventKind is the discriminant for Event variants.

Verbatim port of the legacy TS AgentEvent.type literal union. Each variant is a dedicated struct; the discriminated-union pattern uses a Go interface with a private marker method. 

const (
	EventInit          EventKind = "init"
	EventSystem        EventKind = "system"
	EventAssistantText EventKind = "assistant_text"
	EventToolUse       EventKind = "tool_use"
	EventToolResult    EventKind = "tool_result"
	EventToolProgress  EventKind = "tool_progress"
	EventResult        EventKind = "result"
	EventError         EventKind = "error"
)

EventKind constants. The wire values match the legacy TS literal union (e.g. "init", "assistant_text", "tool_use") so providers can dispatch off the JSON type field.

type Family added in v0.28.0 

type Family string

Family discriminates the two axes + unchanged peer families. FamilyHarness is byte-identical to 002's string "agent-runtime". 

const (
	FamilyHarness       Family = "agent-runtime"
	FamilyModelEndpoint Family = "model-endpoint"
	FamilySandbox       Family = "sandbox"
	FamilyIssueTracker  Family = "issue-tracker"
	FamilyVersionCtrl   Family = "version-control"
)

Family constants discriminate the two axes + the unchanged peer families.

type Handle 

type Handle interface {
	// SessionID returns the provider-native session identifier
	// (Claude session UUID, Codex thread id). Empty until the
	// InitEvent fires; callers should consume events first.
	SessionID() string

	// Events returns the read-only event channel. The provider
	// closes this channel after emitting a terminal ResultEvent or
	// an unrecoverable ErrorEvent.
	Events() <-chan Event

	// Inject sends a follow-up user message into the session.
	// Returns ErrUnsupported when
	// !Provider.Capabilities().SupportsMessageInjection. Implementations
	// that support it should be safe to call concurrently with Events
	// consumption.
	Inject(ctx context.Context, text string) error

	// Stop aborts the session. Idempotent; safe to call after the
	// event channel has closed (returns nil). Implementations should
	// honor ctx cancellation for stop deadlines (typical: 5s grace
	// then SIGKILL for child-process providers).
	Stop(ctx context.Context) error
}

Handle is the live interface to one running session.

Verbatim port of the legacy TS AgentHandle interface from ../agentfactory/packages/core/src/providers/types.ts.

Returned by Provider.Spawn / Provider.Resume. The provider closes the channel returned by Events() after emitting a terminal ResultEvent or an unrecoverable ErrorEvent, signalling that the session is done and no more events will arrive.

type HarnessCaps added in v0.28.0 

type HarnessCaps struct {
	// agent-loop (carried forward from Capabilities)
	SupportsMessageInjection bool   `json:"inject"`
	SupportsSessionResume    bool   `json:"resume"`
	SupportsToolPlugins      bool   `json:"tools"`
	AcceptsMcpServerSpec     bool   `json:"mcp"`
	AcceptsAllowedToolsList  bool   `json:"allowedToolsList"`
	EmitsSubagentEvents      bool   `json:"subagents"`
	SupportsReasoningEffort  bool   `json:"reasoningEffort"`
	SupportsOneShot          bool   `json:"oneShot"`        // can satisfy a future SpawnComplete projection
	NativeJSONMode           bool   `json:"nativeJsonMode"` // strict structured-out vs spawn-collect-validate
	ToolPermissionFormat     string `json:"toolPermissionFormat"`
	StreamingTransport       string `json:"streamingTransport"` // "sse"|"ndjson"|"websocket"|"none"

	// the DRIVE surface (the axis link)
	Drives      []WireProtocol `json:"drives"`
	DrivesHosts []ServingHost  `json:"drivesHosts"`
	Transport   TransportKind  `json:"transport"`
}

HarnessCaps = today's flat agent-loop capabilities + the DRIVE surface. The agent-loop bools are a SUBSET projection of the existing Capabilities struct; the generator/manifest authors map Capabilities → HarnessCaps so the matrix is grounded in the live declaration (no second source of truth).

type HarnessManifest added in v0.28.0 

type HarnessManifest struct {
	Name        HarnessName `json:"name"`
	HumanLabel  string      `json:"humanLabel"`
	Family      Family      `json:"family"`      // FamilyHarness
	ContractABI string      `json:"contractAbi"` // "harness/v2"
	Caps        HarnessCaps `json:"capabilities"`
}

HarnessManifest — pre-load, readable WITHOUT constructing the provider (closes 002 §manifest-separation). ContractABI = "harness/v2".

type HarnessName added in v0.28.0 

type HarnessName string

HarnessName — the loop-driver identity (distinct from the within-family ProviderName wire enum, which P1 keeps for back-compat aliasing). 

const (
	HarnessClaudeCode  HarnessName = "claude-code"
	HarnessCodex       HarnessName = "codex"
	HarnessOpenCode    HarnessName = "opencode"
	HarnessAntigravity HarnessName = "antigravity"
	HarnessAmp         HarnessName = "amp"
	HarnessRaw         HarnessName = "raw" // in-box net/http loop (gemini-direct + ollama)
	HarnessStub        HarnessName = "stub"
)

HarnessName constants name each loop-driver identity.

type HarnessProvider added in v0.28.0 

type HarnessProvider interface {
	Provider
	Manifest() HarnessManifest
}

HarnessProvider — Family A. SUPERSET of the existing Provider interface (embeds it) + Manifest(). Every existing provider still satisfies Provider; it becomes a HarnessProvider only once a Manifest() method is added.

Because Session = Handle (alias) and Spec.Endpoint is additive, the existing Provider.Spawn(ctx, Spec) (Handle, error) signature is already the §2.2 signature — embedding Provider is the zero-churn realization of §2.2.

type HostDesc added in v0.28.0 

type HostDesc struct {
	Host          ServingHost  `json:"host"`
	Protocol      WireProtocol `json:"protocol"`
	AuthModes     []AuthMode   `json:"authModes"`
	BringsOwnAuth bool         `json:"bringsOwnAuth"`
	NeedsAPIKey   bool         `json:"needsApiKey"`
	CostModel     CostModel    `json:"costModel"`
	BaseURLTmpl   string       `json:"baseUrlTmpl"`
	EnvKeys       []string     `json:"envKeys"` // env-var NAMES (never values; OSS-safe)
}

HostDesc — one (serving-host × auth × cost × protocol) cell within a company.

type InitEvent 

type InitEvent struct {
	// SessionID is the provider-native session/thread id (Claude UUID,
	// Codex thread id). Captured by the runner for resume.
	SessionID string `json:"sessionId"`

	// Raw is the provider-native event payload, opaque to callers.
	Raw any `json:"raw,omitempty"`
}

InitEvent fires when the agent has initialized; it captures the provider-native session identifier. Verbatim port of AgentInitEvent.

func (InitEvent) Kind 

func (InitEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type MCPServerConfig 

type MCPServerConfig struct {
	Name string `json:"name"`
	// Type is the transport shape. Either "stdio" (default) or "http".
	Type    string            `json:"type,omitempty"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	// URL is the HTTP MCP endpoint when Type == "http".
	URL string `json:"url,omitempty"`
	// Headers are HTTP headers to send on every MCP request. Typically
	// holds the Authorization bearer for the platform's MCP route.
	Headers map[string]string `json:"headers,omitempty"`
}

MCPServerConfig is one MCP server the provider should configure on session start. Providers that support MCP tool plugins inject these on session init (Claude: via --mcp-config; Codex: via config/batchWrite mcpStdioServers).

Two transports are supported:

  • stdio — Command + Args + Env (the original / legacy shape)
  • http — URL + Headers (Streamable HTTP, used by the platform's per-session MCP endpoint at /api/mcp/<sessionId> — see the A2A per-session MCP ADR)

Type is the discriminator. When empty it defaults to "stdio" so existing callers that only set Command/Args/Env keep working unchanged.

type Message added in v0.33.0 

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message is one turn in a one-shot request. Role is "user" or "assistant" (empty defaults to "user"). Kept minimal — the one-shot consumers (KG, arch-intel) are single-prompt; multi-turn is supported but rarely needed.

type ModelDesc added in v0.28.0 

type ModelDesc struct {
	ID               string        `json:"id"`
	HumanLabel       string        `json:"humanLabel"`
	ContextWindow    int           `json:"contextWindow"`
	SupportsTools    bool          `json:"supportsTools"`
	SupportsJSONMode bool          `json:"supportsJsonMode"`
	Hosts            []ServingHost `json:"hosts"`
}

ModelDesc — one model a company serves, with the hosts it is reachable on.

type ModelEndpointManifest added in v0.28.0 

type ModelEndpointManifest struct {
	Company     Company        `json:"company"`
	HumanLabel  string         `json:"humanLabel"`
	Family      Family         `json:"family"` // FamilyModelEndpoint
	ContractABI string         `json:"contractAbi"`
	Speaks      []WireProtocol `json:"speaks"`
	Hosts       []HostDesc     `json:"hosts"`
	Models      []ModelDesc    `json:"models"`
}

ModelEndpointManifest — company-named declaration. ContractABI = "model-endpoint/v1".

type ModelEndpointProvider added in v0.28.0 

type ModelEndpointProvider interface {
	Manifest() ModelEndpointManifest
	Resolve(ctx context.Context, req EndpointRequest) (EndpointBinding, error)
}

ModelEndpointProvider — Family B. Declare + resolve. No existing implementor; the company endpoint packages are the only ones.

type OneShotProvider added in v0.33.0 

type OneShotProvider interface {
	Complete(ctx context.Context, req OneShotRequest) (OneShotResult, error)
}

OneShotProvider is the schema-constrained completion lane for providers that satisfy a one-shot request WITHOUT driving an interactive session — a pure direct-API completion (e.g. a future Anthropic Messages forced-tool one-shot). It deliberately carries only the completion verb. Most harnesses do NOT implement it: session harnesses (claude-code, codex, amp, antigravity, opencode, stub) ride SpawnComplete, and the raw harnesses (gemini, ollama) deliver STRICT structured natively by honoring Spec.ResponseSchema inside their existing Spawn — so SpawnComplete already yields native-strict output for them without a separate Complete method.

type OneShotRequest added in v0.33.0 

type OneShotRequest struct {
	System   string    `json:"system,omitempty"`
	Messages []Message `json:"messages"`
	// Model names the model to run when no Endpoint is bound; when Endpoint is
	// set, Endpoint.Model wins. Lets a caller request a one-shot against a model
	// id without constructing a full EndpointBinding (the KG-extraction case).
	Model          string           `json:"model,omitempty"`
	Endpoint       *EndpointBinding `json:"endpoint,omitempty"`
	Effort         EffortLevel      `json:"effort,omitempty"`
	ResponseSchema json.RawMessage  `json:"responseSchema,omitempty"` // nil => free text
	MaxTokens      int              `json:"maxTokens,omitempty"`      // honored by native Complete; CLI harnesses self-limit
}

OneShotRequest is a schema-constrained, non-interactive completion request. Endpoint is the resolved (company, model, host, auth) binding — the same binding currency the interactive Spawn path uses (Spec.Endpoint). A nil Endpoint falls back to the harness/env default, mirroring Spec.

type OneShotResult added in v0.33.0 

type OneShotResult struct {
	Text          string          `json:"text"`
	Structured    json.RawMessage `json:"structured,omitempty"`
	SchemaOK      bool            `json:"schemaOk"`
	Cost          *CostData       `json:"cost,omitempty"`
	TransportUsed TransportKind   `json:"transportUsed,omitempty"`
}

OneShotResult is the projection of a completion onto a (text, structured) pair. Structured is populated iff ResponseSchema was set; SchemaOK reports whether it extracted AND validated — false means the caller retries, repairs, or drops (the bounded-injection-to-a-junk-node posture). Cost is nil for BringsOwnAuth cells (the user's own subscription/login pays — nothing metered to attribute).

func Complete added in v0.34.0 

func Complete(ctx context.Context, h HarnessProvider, req OneShotRequest) (OneShotResult, error)

Complete is the public one-shot entry point — the strategy resolver of 02-two-axis-architecture.md §3.5. A provider that implements OneShotProvider (pure direct-API one-shot) is used directly; every HarnessProvider otherwise rides SpawnComplete, which delivers strict output when the harness honors Spec.ResponseSchema (Caps.NativeJSONMode — gemini/ollama) and soft output (prompt-instructed, validate-repair-drop) otherwise. Callers (KG, arch-intel) should call Complete, not SpawnComplete, so the strategy stays config-resolved.

func SpawnComplete added in v0.33.0 

func SpawnComplete(ctx context.Context, h HarnessProvider, req OneShotRequest) (OneShotResult, error)

SpawnComplete gives any HarnessProvider the one-shot lane for free: spawn an interactive session, drive it to terminal, and project the assistant output onto a OneShotResult. Native-JSON harnesses (raw) override with a direct Complete(); everything else (claude-code, codex, amp, antigravity, opencode, stub) rides this soft path.

SOFT JSON: when req.ResponseSchema is set, the schema instruction is appended to the prompt and the collected text is run through extractAndValidate. A !SchemaOK result is NOT an error — it is the documented validate-repair-drop signal returned on the OneShotResult for the caller to handle.

A session that ends with a failure ResultEvent, an ErrorEvent, or no terminal event at all IS an error (distinct from a successful-but-unparseable result).

type PermissionConfig 

type PermissionConfig struct {
	// AllowPatterns is the list of tool-call patterns auto-approved
	// without prompting (e.g. "Bash(pnpm:*)").
	AllowPatterns []string `json:"allowPatterns,omitempty"`

	// DisallowPatterns is the list of tool-call patterns auto-denied.
	DisallowPatterns []string `json:"disallowPatterns,omitempty"`

	// DefaultDecision is the fallback when no pattern matches.
	// Valid values: "allow" | "deny" | "prompt". Empty defaults to
	// "prompt" (provider-specific).
	DefaultDecision string `json:"defaultDecision,omitempty"`
}

PermissionConfig is the runtime permission policy for the codex approval bridge. Verbatim port of CodexPermissionConfig from ../agentfactory/packages/core/src/templates/adapters.ts.

Providers without NeedsPermissionConfig=true ignore this field.

type Provider 

type Provider interface {
	// Name returns this provider's identifier. Stable for the lifetime
	// of the Provider instance.
	Name() ProviderName

	// Capabilities returns this provider's capability flags. Stable
	// for the lifetime of the Provider instance.
	Capabilities() Capabilities

	// Spawn starts a new agent session. The returned Handle's Events
	// channel emits exactly one InitEvent, then zero or more
	// assistant/tool events, then exactly one terminal ResultEvent,
	// then closes. ctx cancellation aborts the session.
	Spawn(ctx context.Context, spec Spec) (Handle, error)

	// Resume continues a previously interrupted session. sessionID is
	// the value captured from a prior InitEvent. Behavior is
	// capability-gated by SupportsSessionResume; providers that do
	// not support resume return ErrUnsupported.
	Resume(ctx context.Context, sessionID string, spec Spec) (Handle, error)

	// Shutdown releases provider-level resources (long-lived child
	// processes such as the codex app-server). Providers with
	// per-session children may no-op and return nil. Called by the
	// runner on fleet shutdown.
	Shutdown(ctx context.Context) error
}

Provider is the contract every agent runtime implements.

Verbatim port of the legacy TS AgentProvider interface from ../agentfactory/packages/core/src/providers/types.ts.

Implementations live in github.com/RenseiAI/donmai/provider/ subpackages (claude, codex, stub for v0.5.0). Each implementation is independent and only depends on this package + its provider-native CLI/SDK + the standard library.

Lifecycle expectations (F.1.1 §3):

  • Provider construction (provider.New) does fail-fast probing such as `which claude`. Callers see provider unavailability before any worktree work.
  • Spawn returns a Handle whose Events channel emits exactly one InitEvent, then zero or more assistant/tool events, then exactly one terminal ResultEvent (or ErrorEvent followed by close), then closes.
  • Resume continues a previously interrupted session, gated by Capabilities().SupportsSessionResume; providers that do not support resume return ErrUnsupported.
  • Shutdown releases provider-level resources such as the long-lived codex app-server child. Providers with per-session children (Claude CLI) may no-op. Called once on daemon drain.

type ProviderName 

type ProviderName string

ProviderName is the stable identifier for an agent provider family.

It mirrors AgentProviderName from the legacy TS port. v0.5.0 ships claude, codex, and stub. Future families (spring-ai, a2a, gemini, ollama, opencode, jules, amp) extend this enum without breaking the contract.

Source: ../agentfactory/packages/core/src/providers/types.ts (AgentProviderName). 

const (
	ProviderClaude   ProviderName = "claude"
	ProviderCodex    ProviderName = "codex"
	ProviderStub     ProviderName = "stub" // test-only; deterministic
	ProviderSpringAI ProviderName = "spring-ai"
	ProviderA2A      ProviderName = "a2a"
	ProviderAmp      ProviderName = "amp"
	ProviderGemini   ProviderName = "gemini"
	ProviderAGYCLI   ProviderName = "agy-cli" // Antigravity `agy` CLI-wrap; OAuth/local/host-session, pty, no key. Successor to the removed gemini-cli wrap (gemini CLI EOL 2026-06-18).
	ProviderOllama   ProviderName = "ollama"
	ProviderOpenCode ProviderName = "opencode"
	ProviderJules    ProviderName = "jules"
)

ProviderName constants. v0.5.0 ships ProviderClaude, ProviderCodex, and ProviderStub. The remaining identifiers are reserved for v0.6.0+ providers per F.1.1 §1; declaring them now keeps the wire enum stable across waves so platform-side dispatch routing does not regress.

type QualityReport 

type QualityReport struct {
	// BaselineCaptured is true when the session-start baseline was
	// successfully recorded; false when the gate was unavailable
	// (e.g. testCommand missing).
	BaselineCaptured bool `json:"baselineCaptured"`

	// TestDelta is the change in failing test count vs baseline.
	// Negative means improvement, positive means regression.
	TestDelta int `json:"testDelta"`

	// TypeDelta is the change in typecheck error count vs baseline.
	TypeDelta int `json:"typeDelta"`

	// LintDelta is the change in lint error count vs baseline.
	LintDelta int `json:"lintDelta"`

	// BlockedPromotion is true when a regression triggered a
	// status-promotion block on the platform side.
	BlockedPromotion bool `json:"blockedPromotion"`
}

QualityReport captures the test/typecheck/lint deltas vs the session-start baseline. Populated by runner/quality.go (F.1.1 §5.5).

type Result 

type Result struct {
	// Status is the terminal session status. Drives platform-side
	// agent_session.status mutations downstream of /completion.
	// Valid values: "completed" | "failed" | "stopped".
	Status string `json:"status"`

	// ProviderName identifies which provider produced this result.
	ProviderName ProviderName `json:"providerName"`

	// ProviderSessionID is the provider-native session id (Claude UUID,
	// Codex thread id) captured from InitEvent.
	ProviderSessionID string `json:"providerSessionId,omitempty"`

	// WorktreePath is the absolute path of the worktree the session
	// ran in. Useful for debugging and for the
	// PreserveWorktreeOnFailure path.
	WorktreePath string `json:"worktreePath,omitempty"`

	// PullRequestURL is the URL of the PR opened (by the agent or the
	// backstop). Empty when no PR exists.
	PullRequestURL string `json:"pullRequestUrl,omitempty"`

	// CommitSHA is the head commit sha of the work branch when known.
	CommitSHA string `json:"commitSha,omitempty"`

	// Summary is a short human-readable summary of the work done.
	Summary string `json:"summary,omitempty"`

	// WorkResult is the QA/acceptance verdict. Valid values:
	// "passed" | "failed" | "unknown". Drives the acceptance gate on
	// the platform side.
	WorkResult string `json:"workResult,omitempty"`

	// Cost rolls up token usage and dollars across the session.
	Cost *CostData `json:"cost,omitempty"`

	// FailureMode classifies why a non-completed session failed.
	// Enum values are owned by runner/failure.go.
	FailureMode string `json:"failureMode,omitempty"`

	// BackstopReport captures what the post-session backstop did,
	// if it ran.
	BackstopReport *BackstopReport `json:"backstopReport,omitempty"`

	// QualityReport captures the test/typecheck/lint deltas vs the
	// session-start baseline.
	QualityReport *QualityReport `json:"qualityReport,omitempty"`

	// Error is the human-readable error message when Status is
	// "failed".
	Error string `json:"error,omitempty"`
}

Result is the runner's final session-result shape, distinct from the per-provider terminal ResultEvent.

The runner builds this from the terminal Event plus side-channel data (worktree path, backstop report, quality report, WORK_RESULT marker) and posts it to the platform via POST /api/sessions/<id>/completion (see F.1.1 §6).

type ResultEvent 

type ResultEvent struct {
	// Success reports whether the session ended successfully.
	Success bool `json:"success"`

	// Message is the completion message (typically only set on success).
	Message string `json:"message,omitempty"`

	// Errors is the list of error messages (typically only set on
	// failure).
	Errors []string `json:"errors,omitempty"`

	// ErrorSubtype is the provider-defined error subtype (e.g.
	// "error_during_execution", "error_max_turns").
	ErrorSubtype string `json:"errorSubtype,omitempty"`

	// Cost is the rolled-up cost/usage for the session.
	Cost *CostData `json:"cost,omitempty"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

ResultEvent is the terminal session-outcome event from the provider. Distinct from agent.Result which is the runner's higher-level session-result struct (see types.go). Verbatim port of AgentResultEvent.

func (ResultEvent) Kind 

func (ResultEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type SandboxLevel 

type SandboxLevel string

SandboxLevel mirrors AgentSpawnConfig.sandboxLevel from the legacy TS.

Source: ../agentfactory/packages/core/src/providers/types.ts. 

const (
	SandboxReadOnly       SandboxLevel = "read-only"
	SandboxWorkspaceWrite SandboxLevel = "workspace-write"
	SandboxFullAccess     SandboxLevel = "full-access"
)

SandboxLevel constants align with Codex sandbox policies (readOnly / workspaceWrite / dangerFullAccess) and the cross-provider sandbox taxonomy in F.1.1 §3.2.

type ServingHost added in v0.28.0 

type ServingHost string

ServingHost — WHERE the model is served, orthogonal to the wire protocol. 

const (
	HostDirect   ServingHost = "direct"
	HostBedrock  ServingHost = "bedrock"
	HostVertex   ServingHost = "vertex"
	HostAzure    ServingHost = "azure"
	HostLocal    ServingHost = "local"     // ollama / on-box
	HostOAuthCLI ServingHost = "oauth-cli" // host login (agy / claude-sub / codex-sub) — BringsOwnAuth
)

ServingHost constants name each place a model can be served.

type Session added in v0.28.0 

type Session = Handle

Session is the live session interface. P1 ALIASES it to the existing Handle so every existing implementor of Handle is already a Session — no rename, no churn. (Renaming Handle → Session is a later cosmetic phase, if ever.)

type Spec 

type Spec struct {
	// Prompt is the task-specific directive.
	Prompt string `json:"prompt"`

	// Cwd is the working directory the agent session runs in.
	// Typically the runner's worktree path.
	Cwd string `json:"cwd"`

	// Env is the environment variable map merged onto the process
	// environment (after AGENT_ENV_BLOCKLIST filtering).
	Env map[string]string `json:"env"`

	// Autonomous indicates the session has no interactive user;
	// providers should disable user-input tools when true.
	Autonomous bool `json:"autonomous"`

	// SandboxEnabled enables the provider's default filesystem/network
	// sandbox.
	SandboxEnabled bool `json:"sandboxEnabled"`

	// SandboxLevel overrides the sandbox tier when SandboxEnabled is
	// true. Maps to provider-native policies.
	SandboxLevel SandboxLevel `json:"sandboxLevel,omitempty"`

	// AllowedTools is the list of tool-call patterns auto-allowed
	// without prompting (Claude permission-pattern format
	// "Bash(prefix:glob)").
	AllowedTools []string `json:"allowedTools,omitempty"`

	// DisallowedTools is the list of tool-call patterns the provider
	// must reject.
	DisallowedTools []string `json:"disallowedTools,omitempty"`

	// MCPServers is the list of stdio MCP servers the provider should
	// configure on session start.
	MCPServers []MCPServerConfig `json:"mcpStdioServers,omitempty"`

	// MCPToolNames is the list of fully-qualified MCP tool names
	// (e.g. "mcp__af-code-intelligence__af_code_get_repo_map") that
	// should be added to AllowedTools so autonomous agents can call
	// them.
	MCPToolNames []string `json:"mcpToolNames,omitempty"`

	// MaxTurns caps agentic turns (API round-trips) before the
	// provider stops. nil falls back to the provider default.
	MaxTurns *int `json:"maxTurns,omitempty"`

	// Model is the model identifier (e.g. "claude-sonnet-4-5"). Empty
	// falls back to provider/env default.
	Model string `json:"model,omitempty"`

	// Endpoint is the RESOLVED model-endpoint binding. nil == today's
	// behavior: providers read Spec.Model / Spec.Env as before. nil is the
	// canonical "unset" sentinel; the Phase-3 Spawn read site gates on
	// Endpoint == nil (a non-nil pointer is treated as set — IsZero on the
	// pointee is a convenience, not the unset check). Wired into the Spawn
	// path in Phase 3; no provider reads it in P1. Spec.Model remains the
	// source of truth and is NOT yet derived from this.
	//
	// Declared as a POINTER (not a value) so the json:"endpoint,omitempty"
	// tag actually omits the field for pre-P1 producers — Go's encoding/json
	// never treats a non-pointer struct as "empty", so a value field would
	// always serialize "endpoint":{...} and break the wire round-trip
	// guarantee (P1-SPEC §6). nil is the canonical "unset" sentinel.
	Endpoint *EndpointBinding `json:"endpoint,omitempty"`

	// Effort is the normalized reasoning-effort tier. Honored only
	// when Capabilities.SupportsReasoningEffort is true.
	Effort EffortLevel `json:"effort,omitempty"`

	// ResponseSchema is the native structured-output JSON Schema for the
	// one-shot/structured lane (P4b). Honored ONLY by harnesses that
	// declare HarnessCaps.NativeJSONMode (the raw harnesses over gemini's
	// responseSchema and ollama's format) — they set the protocol's
	// structured primitive so output is constrained server-side (STRICT).
	// Harnesses without NativeJSONMode ignore it and rely on the soft prompt
	// instruction SpawnComplete appends. nil/empty == today's free-text
	// behavior; additive and omitempty so the wire round-trip is unchanged
	// for every existing producer, and interactive (non-one-shot) Spawns
	// never set it.
	ResponseSchema json.RawMessage `json:"responseSchema,omitempty"`

	// BaseInstructions are persistent system instructions
	// (Codex thread/start ‘instructions'). Honored only when
	// Capabilities.NeedsBaseInstructions is true.
	BaseInstructions string `json:"baseInstructions,omitempty"`

	// SystemPromptAppend is appended to the system prompt after
	// standard instruction sections (sourced from
	// RepositoryConfig.systemPrompt).
	SystemPromptAppend string `json:"systemPromptAppend,omitempty"`

	// InitialContext is session context delivered ONCE with the first
	// turn's user input rather than via the persistent system prompt.
	// Use it for large, volatile, reference-style context (e.g. recalled
	// agent memory) that the model needs available but that must NOT be
	// re-sent on every model turn.
	//
	// Honored only by providers that declare
	// Capabilities.SupportsTurnInputContext — i.e. those whose wire
	// protocol re-includes the system prompt on every turn (codex's
	// baseInstructions). For providers without that split the runner
	// folds the same content into the system prompt instead, so callers
	// never have to branch on provider identity. Keeping this content out
	// of the system-prompt prefix avoids O(turns × prefix) token
	// amplification on long codex sessions.
	InitialContext string `json:"initialContext,omitempty"`

	// PermissionConfig is the structured permission policy for
	// providers that consume one (Codex approval bridge).
	PermissionConfig *PermissionConfig `json:"permissionConfig,omitempty"`

	// CodeIntelEnforcement enables the af_code_* redirect for
	// providers that support it.
	CodeIntelEnforcement *CodeIntelEnforcement `json:"codeIntelligenceEnforcement,omitempty"`

	// ProviderConfig is provider-specific settings from the matched
	// model profile (e.g. {"serviceTier":"fast"} for OpenAI,
	// {"speed":"fast"} for Anthropic).
	ProviderConfig map[string]any `json:"providerConfig,omitempty"`

	// SubAgentProvider names the provider for spawned sub-agents when
	// different from the parent. Used by coordination templates.
	SubAgentProvider ProviderName `json:"subAgentProvider,omitempty"`

	// OnProcessSpawned is an optional callback that fires once the
	// provider has spawned its underlying process; used by the runner
	// to capture PIDs for metrics. Not serialized.
	OnProcessSpawned func(pid int) `json:"-"`
}

Spec is the input contract for Provider.Spawn.

Verbatim port of the AgentSpawnConfig from the legacy TS providers/types.ts. Capability-gated: providers consume the fields they support; unsupported fields are silently ignored. The runner is responsible for not setting incompatible fields (gate on Capabilities before invoking Spawn).

Source: ../agentfactory/packages/core/src/providers/types.ts (AgentSpawnConfig).

type SystemEvent 

type SystemEvent struct {
	// Subtype is the provider-defined event subtype (e.g. "compaction",
	// "rate_limited").
	Subtype string `json:"subtype"`

	// Message is an optional human-readable message.
	Message string `json:"message,omitempty"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

SystemEvent is a provider-emitted lifecycle/status event (compaction, rate-limit notice, etc.). Verbatim port of AgentSystemEvent.

func (SystemEvent) Kind 

func (SystemEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type ToolProgressEvent 

type ToolProgressEvent struct {
	// ToolName is the tool identifier.
	ToolName string `json:"toolName"`

	// ElapsedSeconds is how long the tool has been running.
	ElapsedSeconds float64 `json:"elapsedSeconds"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

ToolProgressEvent is a long-running tool's progress tick. Verbatim port of AgentToolProgressEvent.

func (ToolProgressEvent) Kind 

func (ToolProgressEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type ToolResultEvent 

type ToolResultEvent struct {
	// ToolName is the tool identifier; may be empty when the provider
	// only reports the tool-use id.
	ToolName string `json:"toolName,omitempty"`

	// ToolUseID pairs with ToolUseEvent.ToolUseID.
	ToolUseID string `json:"toolUseId,omitempty"`

	// Content is the tool's output text or stringified result.
	Content string `json:"content"`

	// IsError is true when the tool reported failure.
	IsError bool `json:"isError"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

ToolResultEvent carries a tool-execution result (success or error). Verbatim port of AgentToolResultEvent.

func (ToolResultEvent) Kind 

func (ToolResultEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type ToolUseEvent 

type ToolUseEvent struct {
	// ToolName is the tool identifier (e.g. "Bash", "Edit",
	// "mcp__af_linear__af_linear_get_issue").
	ToolName string `json:"toolName"`

	// ToolUseID is the provider-native tool-call identifier; pairs
	// with ToolResultEvent.ToolUseID.
	ToolUseID string `json:"toolUseId,omitempty"`

	// Input is the tool-call input map.
	Input map[string]any `json:"input"`

	// ToolCategory is the runner's categorization
	// ("filesystem"|"shell"|"network"|"linear"|"code-intel"). Empty
	// when the runner has not yet categorized the call.
	ToolCategory string `json:"toolCategory,omitempty"`

	// Raw is the provider-native event payload.
	Raw any `json:"raw,omitempty"`
}

ToolUseEvent fires when the agent invokes a tool. Verbatim port of AgentToolUseEvent.

func (ToolUseEvent) Kind 

func (ToolUseEvent) Kind() EventKind

Kind reports the EventKind discriminant.

type TransportKind added in v0.28.0 

type TransportKind string

TransportKind — HOW a (harness × host) pair runs the loop. 

const (
	TransportCLIInjection  TransportKind = "cli-injection"
	TransportSubprocessRPC TransportKind = "subprocess-jsonrpc"
	TransportPTY           TransportKind = "pty"
	TransportDirectAPI     TransportKind = "direct-api"
)

TransportKind constants name how a (harness × host) pair runs the loop.

type WireProtocol added in v0.28.0 

type WireProtocol string

WireProtocol — on-the-wire request/response shape a model endpoint speaks. A harness declares which it can DRIVE; an endpoint declares which it SPEAKS. 

const (
	ProtoAnthropicMessages WireProtocol = "anthropic-messages"
	ProtoOpenAIChat        WireProtocol = "openai-chat"       // /v1/chat/completions (+ compat)
	ProtoOpenAIResponses   WireProtocol = "openai-responses"  // Codex app-server / Responses API
	ProtoGeminiGenerate    WireProtocol = "gemini-generate"   // :generateContent, SSE
	ProtoOllama            WireProtocol = "ollama"            // /api/chat NDJSON (bare surface)
	ProtoAntigravityOAuth  WireProtocol = "antigravity-oauth" // agy CLI host-login channel (pty)
	ProtoStub              WireProtocol = "stub"              // test-only sentinel protocol
)

WireProtocol constants name each on-the-wire request/response shape.

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.