engine

package
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package engine hosts private resolution, thread coordination, profile, and runtime-service operations used by the public Agent pipeline.

Layering rules:

  • engine MUST NOT import the root package.
  • Driver-facing contracts live in package driver; application vocabulary lives in public leaf packages.
  • The root package owns orchestration and calls these operations through narrow free-function boundaries.

Package engine owns only the internal thread-coordination sentinels. Domain errors remain owned by their public leaf packages so errors.Is and errors.As identities do not depend on this internal package.

Index

Constants

View Source 
const (
	RunEventChunk      = driver.RunEventChunk
	RunEventItem       = driver.RunEventItem
	RunEventInvocation = driver.RunEventInvocation
	RunEventSpawn      = driver.RunEventSpawn
	RunEventRuntime    = driver.RunEventRuntime
	RunEventLifecycle  = driver.RunEventLifecycle
)
View Source 
const (
	TranscriptAssistant  = driver.TranscriptAssistant
	TranscriptThinking   = driver.TranscriptThinking
	TranscriptUser       = driver.TranscriptUser
	TranscriptToolCall   = driver.TranscriptToolCall
	TranscriptToolResult = driver.TranscriptToolResult
	TranscriptInit       = driver.TranscriptInit
	TranscriptResult     = driver.TranscriptResult
	TranscriptStdout     = driver.TranscriptStdout
	TranscriptStderr     = driver.TranscriptStderr
	TranscriptSystem     = driver.TranscriptSystem
	TranscriptSummary    = driver.TranscriptSummary
	TranscriptQuestion   = driver.TranscriptQuestion
	TranscriptFailure    = driver.TranscriptFailure
)
View Source 
const (
	StreamRunStarted       = driver.StreamRunStarted
	StreamRunFinished      = driver.StreamRunFinished
	StreamRunError         = driver.StreamRunError
	StreamStepStarted      = driver.StreamStepStarted
	StreamStepFinished     = driver.StreamStepFinished
	StreamTextStart        = driver.StreamTextStart
	StreamTextContent      = driver.StreamTextContent
	StreamTextEnd          = driver.StreamTextEnd
	StreamToolCallStart    = driver.StreamToolCallStart
	StreamToolCallArgs     = driver.StreamToolCallArgs
	StreamToolCallEnd      = driver.StreamToolCallEnd
	StreamToolCallResult   = driver.StreamToolCallResult
	StreamReasoningStart   = driver.StreamReasoningStart
	StreamReasoningContent = driver.StreamReasoningContent
	StreamReasoningEnd     = driver.StreamReasoningEnd
	StreamHITLRequested    = driver.StreamHITLRequested
	StreamHITLResolved     = driver.StreamHITLResolved
	StreamDropped          = driver.StreamDropped
)
View Source 
const (
	RoleAssistant = driver.RoleAssistant
	RoleUser      = driver.RoleUser
)
View Source 
const (
	StructuredOutputFailRun       = driver.StructuredOutputFailRun
	StructuredOutputReturnInvalid = driver.StructuredOutputReturnInvalid
)
View Source 
const (
	StructuredOutputSourceNative         = driver.StructuredOutputSourceNative
	StructuredOutputSourcePromptValidate = driver.StructuredOutputSourcePromptValidate
)
View Source 
const (
	SessionContinueOrStart = driver.SessionContinueOrStart
	SessionContinueOnly    = driver.SessionContinueOnly
	SessionFork            = driver.SessionFork
	SessionStateless       = driver.SessionStateless
)
View Source 
const (
	AgentProfileSourceBindingEnv    = driver.AgentProfileSourceBindingEnv
	AgentProfileSourceProfileOption = driver.AgentProfileSourceProfileOption
	AgentProfileSourceProcessEnv    = driver.AgentProfileSourceProcessEnv
	AgentProfileSourceDefault       = driver.AgentProfileSourceDefault
	AgentProfileSourceManaged       = driver.AgentProfileSourceManaged
	AgentProfileSourceUnsupported   = driver.AgentProfileSourceUnsupported
)
View Source 
const (
	EnvironmentPass = driver.EnvironmentPass
	EnvironmentWarn = driver.EnvironmentWarn
	EnvironmentFail = driver.EnvironmentFail
)
View Source 
const (
	WorkspaceStrategyProjectPrimary = driver.WorkspaceStrategyProjectPrimary
	WorkspaceStrategyGitWorktree    = driver.WorkspaceStrategyGitWorktree
	WorkspaceStrategyDriverManaged  = driver.WorkspaceStrategyDriverManaged
	WorkspaceStrategyCloudSandbox   = driver.WorkspaceStrategyCloudSandbox
)
View Source 
const (
	WorkspaceModeShared       = driver.WorkspaceModeShared
	WorkspaceModeIsolated     = driver.WorkspaceModeIsolated
	WorkspaceModeOperator     = driver.WorkspaceModeOperator
	WorkspaceModeReuse        = driver.WorkspaceModeReuse
	WorkspaceModeAgentDefault = driver.WorkspaceModeAgentDefault
)
View Source 
const (
	RuntimeServiceStarting = driver.RuntimeServiceStarting
	RuntimeServiceRunning  = driver.RuntimeServiceRunning
	RuntimeServiceStopped  = driver.RuntimeServiceStopped
	RuntimeServiceFailed   = driver.RuntimeServiceFailed
)
View Source 
const (
	RuntimeLifecycleShared    = driver.RuntimeLifecycleShared
	RuntimeLifecycleEphemeral = driver.RuntimeLifecycleEphemeral
)
View Source 
const (
	RuntimeHealthUnknown   = driver.RuntimeHealthUnknown
	RuntimeHealthHealthy   = driver.RuntimeHealthHealthy
	RuntimeHealthUnhealthy = driver.RuntimeHealthUnhealthy
)
View Source 
const (
	InstructionScopeDefault = driver.InstructionScopeDefault
	InstructionScopeUser    = driver.InstructionScopeUser
	InstructionScopeProject = driver.InstructionScopeProject
	InstructionScopeLocal   = driver.InstructionScopeLocal
	InstructionScopeRun     = driver.InstructionScopeRun
)
View Source 
const (
	InstructionModeAdditive = driver.InstructionModeAdditive
	InstructionModeReplace  = driver.InstructionModeReplace
)
View Source 
const (
	SkillMetadataRuntimeName = driver.SkillMetadataRuntimeName
	SkillMetadataDisplayName = driver.SkillMetadataDisplayName
)
View Source 
const (
	SkillSyncUnsupported = driver.SkillSyncUnsupported
	SkillSyncEphemeral   = driver.SkillSyncEphemeral
	SkillSyncPersistent  = driver.SkillSyncPersistent
)
View Source 
const (
	SkillStateAvailable  = driver.SkillStateAvailable
	SkillStateConfigured = driver.SkillStateConfigured
	SkillStateInstalled  = driver.SkillStateInstalled
	SkillStateMissing    = driver.SkillStateMissing
	SkillStateStale      = driver.SkillStateStale
	SkillStateExternal   = driver.SkillStateExternal
)
View Source 
const (
	SkillOriginManaged  = driver.SkillOriginManaged
	SkillOriginRequired = driver.SkillOriginRequired
	SkillOriginUser     = driver.SkillOriginUser
	SkillOriginUnknown  = driver.SkillOriginUnknown
)
View Source 
const (
	MCPTransportStdio = driver.MCPTransportStdio
	MCPTransportHTTP  = driver.MCPTransportHTTP
	MCPTransportSSE   = driver.MCPTransportSSE
)
View Source 
const (
	HumanDecisionPermission = driver.HumanDecisionPermission
	HumanDecisionPlanReview = driver.HumanDecisionPlanReview
	HumanDecisionQuestion   = driver.HumanDecisionQuestion
)
View Source 
const (
	HumanDecisionUnset       = driver.HumanDecisionUnset
	HumanDecisionAsk         = driver.HumanDecisionAsk
	HumanDecisionAutoApprove = driver.HumanDecisionAutoApprove
	HumanDecisionAutoReject  = driver.HumanDecisionAutoReject
)
View Source 
const (
	QuestionUnset      = driver.QuestionUnset
	QuestionAsk        = driver.QuestionAsk
	QuestionAutoReject = driver.QuestionAutoReject
)
View Source 
const (
	FailureActionUnset = driver.FailureActionUnset
	FailureAbort       = driver.FailureAbort
	FailureContinue    = driver.FailureContinue
	FailureRetry       = driver.FailureRetry
)
View Source 
const (
	FailureReject      = driver.FailureReject
	FailureTimeout     = driver.FailureTimeout
	FailureAgentError  = driver.FailureAgentError
	FailureCancelled   = driver.FailureCancelled
	FailurePolicyError = driver.FailurePolicyError
)
View Source 
const (
	DecisionApproved = driver.DecisionApproved
	DecisionRejected = driver.DecisionRejected
	DecisionAnswered = driver.DecisionAnswered
	DecisionTimedOut = driver.DecisionTimedOut
	DecisionAborted  = driver.DecisionAborted
)
View Source 
const (
	IsolationInherit        = driver.IsolationInherit
	IsolationReadOnly       = driver.IsolationReadOnly
	IsolationWorkspaceWrite = driver.IsolationWorkspaceWrite
	IsolationUnrestricted   = driver.IsolationUnrestricted
)
View Source 
const (
	FeatureInherit = driver.FeatureInherit
	FeatureAllow   = driver.FeatureAllow
	FeatureDeny    = driver.FeatureDeny
)
View Source 
const (
	// DefaultHumanDecisionTimeout is the timeout used for Ask decisions when
	// the host does not set HumanDecisionPolicy.Timeout.
	DefaultHumanDecisionTimeout = driver.DefaultHumanDecisionTimeout
	// DefaultHumanDecisionMaxRetries is the retry cap used when the host
	// requests FailureRetry without setting MaxRetries.
	DefaultHumanDecisionMaxRetries = driver.DefaultHumanDecisionMaxRetries
)
View Source 
const (
	ProfileModeUnset     = driver.ProfileModeUnset
	ProfileModeNative    = driver.ProfileModeNative
	ProfileModeDedicated = driver.ProfileModeDedicated
	ProfileModeClone     = driver.ProfileModeClone
)
View Source 
const (
	CloneProfileAuthNone = driver.CloneProfileAuthNone
	CloneProfileAuthCopy = driver.CloneProfileAuthCopy
	CloneProfileAuthLink = driver.CloneProfileAuthLink
)
View Source 
const (
	HookEventSessionStart      = driver.HookEventSessionStart
	HookEventSessionEnd        = driver.HookEventSessionEnd
	HookEventPromptSubmit      = driver.HookEventPromptSubmit
	HookEventPromptExpand      = driver.HookEventPromptExpand
	HookEventPreTool           = driver.HookEventPreTool
	HookEventPostTool          = driver.HookEventPostTool
	HookEventToolFailure       = driver.HookEventToolFailure
	HookEventPermissionRequest = driver.HookEventPermissionRequest
	HookEventPreShell          = driver.HookEventPreShell
	HookEventPostShell         = driver.HookEventPostShell
	HookEventPreMCP            = driver.HookEventPreMCP
	HookEventPostMCP           = driver.HookEventPostMCP
	HookEventPreFileRead       = driver.HookEventPreFileRead
	HookEventPostFileEdit      = driver.HookEventPostFileEdit
	HookEventSubagentStart     = driver.HookEventSubagentStart
	HookEventSubagentStop      = driver.HookEventSubagentStop
	HookEventPreCompact        = driver.HookEventPreCompact
	HookEventPostCompact       = driver.HookEventPostCompact
	HookEventStop              = driver.HookEventStop
	HookEventStopFailure       = driver.HookEventStopFailure
)
View Source 
const (
	HookMatcherSubjectDefault  = driver.HookMatcherSubjectDefault
	HookMatcherSubjectTool     = driver.HookMatcherSubjectTool
	HookMatcherSubjectCommand  = driver.HookMatcherSubjectCommand
	HookMatcherSubjectMCP      = driver.HookMatcherSubjectMCP
	HookMatcherSubjectPath     = driver.HookMatcherSubjectPath
	HookMatcherSubjectPrompt   = driver.HookMatcherSubjectPrompt
	HookMatcherSubjectSubagent = driver.HookMatcherSubjectSubagent
	HookMatcherSubjectSource   = driver.HookMatcherSubjectSource
)
View Source 
const (
	HookMatcherSyntaxProvider = driver.HookMatcherSyntaxProvider
	HookMatcherSyntaxExact    = driver.HookMatcherSyntaxExact
	HookMatcherSyntaxRegex    = driver.HookMatcherSyntaxRegex
	HookMatcherSyntaxPrefix   = driver.HookMatcherSyntaxPrefix
	HookMatcherSyntaxContains = driver.HookMatcherSyntaxContains
)
View Source 
const (
	HookHandlerCommand = driver.HookHandlerCommand
	HookHandlerPrompt  = driver.HookHandlerPrompt
	HookHandlerHTTP    = driver.HookHandlerHTTP
	HookHandlerMCPTool = driver.HookHandlerMCPTool
	HookHandlerAgent   = driver.HookHandlerAgent
)
View Source 
const (
	HookFailPolicyProviderDefault = driver.HookFailPolicyProviderDefault
	HookFailPolicyOpen            = driver.HookFailPolicyOpen
	HookFailPolicyClosed          = driver.HookFailPolicyClosed
)
View Source 
const (
	ProfileConfigFileJSON = driver.ProfileConfigFileJSON
	ProfileConfigFileTOML = driver.ProfileConfigFileTOML
)
View Source 
const (
	// SessionParamCWD records the workspace directory captured in a session.
	SessionParamCWD = driver.SessionParamCWD
	// SessionParamWorkspaceID records the SDK workspace lease identifier.
	SessionParamWorkspaceID = driver.SessionParamWorkspaceID
	// SessionParamProfileFingerprint records the provider-visible effective
	// profile resource fingerprint captured by a resumable session.
	SessionParamProfileFingerprint = driver.SessionParamProfileFingerprint
)

Well-known session parameter keys used by the thread coordinator. Package driver owns the SPI identities; these aliases keep the engine algorithms on the canonical values.

View Source 
const OutputFormatJSONSchema = driver.OutputFormatJSONSchema

Variables

View Source 
var (
	// ErrResumeRejected is the base sentinel; ResumeRejectedError below
	// carries the structured Reason / Cause.
	ErrResumeRejected = errors.New("agentadaptor: driver rejected session resume")

	// ErrSessionBusy is the base sentinel; SessionBusyError below carries
	// the structured Target.
	ErrSessionBusy = errors.New("agentadaptor: session busy")

	// ErrSessionCheckpointMissing is returned when the SessionStore
	// reports the resolved record but the driver state on it is empty.
	ErrSessionCheckpointMissing = errors.New("agentadaptor: session checkpoint missing")

	// ErrSessionIncompatible is the base sentinel; SessionIncompatibleError
	// below carries the structured Reason / fingerprints.
	ErrSessionIncompatible = errors.New("agentadaptor: session incompatible")

	// ErrSessionLeaseLost is the base sentinel; SessionLeaseLostError below
	// carries the structured Target.
	ErrSessionLeaseLost = errors.New("agentadaptor: session lease lost")

	// ErrSessionNotFound is returned when SessionStore.Resolve cannot
	// locate the requested SessionID / (Namespace,Key).
	ErrSessionNotFound = errors.New("agentadaptor: session not found")

	// ErrSessionStoreRequired is returned when a session-aware Run
	// (continue_only / fork / ...) is invoked on an SDK that has no
	// SessionStore configured.
	ErrSessionStoreRequired = errors.New("agentadaptor: session store required")

	// ErrThreadAlreadyExists is returned by structured fork coordination when
	// the requested child key already has an active record. The parent and
	// existing target remain unchanged.
	ErrThreadAlreadyExists = errors.New("agentadaptor: fork target thread already exists")

	// ErrInvalidSessionRequest is returned before store access when selectors
	// are incomplete, contradictory, or invalid for the requested mode.
	ErrInvalidSessionRequest = errors.New("agentadaptor: invalid session request")
)
View Source 
var (
	// ErrInvalidMCPConfig is returned when WithMCP is given a malformed
	// MCPConfig.
	ErrInvalidMCPConfig = mcp.ErrInvalidConfig

	// ErrMCPUnsupported is returned when an MCP-bound Run targets an
	// adapter that does not declare MCP support in its descriptor.
	ErrMCPUnsupported = mcp.ErrUnsupported

	// ErrMCPTransportUnsupported is returned when the adapter declares
	// MCP support but not for the transport the host requested.
	ErrMCPTransportUnsupported = mcp.ErrTransportUnsupported
)
View Source 
var (
	// ErrStructuredOutputUnsupported is returned before Driver launch when
	// structured output cannot be honored by the bound Driver or selected
	// provider transport.
	ErrStructuredOutputUnsupported = driver.ErrStructuredOutputUnsupported

	// ErrInvalidOutputSchema is returned before Driver launch when the host
	// supplies malformed JSON, an unsupported output format, or a JSON
	// Schema document that cannot be compiled for local validation.
	ErrInvalidOutputSchema = driver.ErrInvalidOutputSchema
)
View Source 
var (
	// ErrSkillKeyConflict is the base sentinel; SkillKeyConflictError in
	// skill_types.go carries the conflicting sources slice.
	ErrSkillKeyConflict = skill.ErrSkillKeyConflict

	// ErrSkillMaterializationFailed is returned when a selected skill was
	// resolved but could not be materialized into a local SKILL.md directory.
	// SkillMaterializationError carries the skill key and underlying cause.
	ErrSkillMaterializationFailed = skill.ErrSkillMaterializationFailed

	// ErrSkillSourceMissing is returned when a Skill value is registered
	// or selected without a non-nil Source.
	ErrSkillSourceMissing = skill.ErrSkillSourceMissing

	// ErrSkillKeyMissing is returned when a Skill is constructed with an
	// empty Key.
	ErrSkillKeyMissing = skill.ErrSkillKeyMissing

	// ErrSkillNotFound is returned during Run-time selection when a bare
	// SkillKey reference cannot be resolved against the configured
	// provider, default skills, or per-call skills.
	ErrSkillNotFound = skill.ErrSkillNotFound
)
View Source 
var (
	LeaseTTL           = func() time.Duration { return 5 * time.Minute }
	LeaseRenewInterval = func() time.Duration { return 2 * time.Minute }
)

LeaseTTL and LeaseRenewInterval report the session lease timing knobs. The defaults are self-sufficient: no wiring is required for the session pipeline to work. They stay function variables (not plain durations) so tests — both engine-side and facade-side — can shorten the timings without touching the production call sites.

View Source 
var ErrInvalidDriverConfig = driver.ErrInvalidDriverConfig

Functions

func FinalizeStructuredOutput 

func FinalizeStructuredOutput(
	schema *OutputSchema,
	source StructuredOutputSource,
	output string,
	structured *StructuredOutput,
	failure *RunFailure,
) (*StructuredOutput, *RunFailure)

FinalizeStructuredOutput applies the post-run structured output contract to a driver response: suppress unrequested structured output, prompt-validate raw text when the source is PromptValidate, synthesise the "driver did not return native structured output" invalid marker, backfill Source/Format/SchemaHash, re-validate returned RawJSON, and escalate invalid output into a FailurePolicyError failure when the schema's OnInvalid is StructuredOutputFailRun.

func InstructionFingerprint 

func InstructionFingerprint(ref *InstructionsBundleRef) string

InstructionFingerprint exposes instructionFingerprint for the root package.

func NormalizeJSON 

func NormalizeJSON(raw []byte) (json.RawMessage, error)

NormalizeJSON exposes normalizeJSON for the root package.

func NormalizeProfileDir 

func NormalizeProfileDir(dir string) (string, error)

NormalizeProfileDir expands ~, resolves relative paths, and cleans the result. It is exported for hosts that want to validate profile paths before building an SDK, and used by the driver-side profile runtime.

func NormalizeSkillKey 

func NormalizeSkillKey(value string) string

NormalizeSkillKey exposes normalizeSkillKey for the root package.

func ReleaseRuntimeServicesByRun 

func ReleaseRuntimeServicesByRun(ctx context.Context, manager RuntimeServiceManager, runID string) error

ReleaseRuntimeServicesByRun runs one RuntimeServiceManager.ReleaseByRun. A nil manager is a no-op.

func ReleaseWorkspaceLease 

func ReleaseWorkspaceLease(ctx context.Context, manager WorkspaceManager, lease WorkspaceLease, mode WorkspaceReleaseMode) error

ReleaseWorkspaceLease runs one WorkspaceManager.Release. A nil manager is a no-op because nothing was leased through a manager.

func ResolveSkills 

func ResolveSkills(
	ctx context.Context,
	provider SkillProvider,
	materializer SkillMaterializer,
	identity AgentIdentity,
	defaultRefs []SkillRef,
	runRefs []SkillRef,
	candidateRefs []SkillRef,
) (ResolvedSkills, []string, []Skill, error)

ResolveSkills runs the skill resolution algorithm — candidate registration, default/run absorption, batched provider fetch, required auto-selection, conflict detection, materialization, fingerprinting — against an explicit provider and materializer.

Rationale for the entry: the algorithm's semantics (source labels, ErrSkillNotFound wording, SkillMaterializationError, sorted selection, SkillSyncEphemeral/Unsupported downgrade, stableHash recipe) are the public contract. A nil provider performs no fetch; a nil materializer uses the process default.

func StableHash 

func StableHash(parts ...any) string

StableHash exposes stableHash for the root package.

func StructuredOutputPromptInstruction 

func StructuredOutputPromptInstruction(schema *OutputSchema) string

StructuredOutputPromptInstruction exposes structuredOutputPromptInstruction for the root package.

func ValidateThreadSessionDriver 

func ValidateThreadSessionDriver(driver Driver) (string, error)

ValidateThreadSessionDriver validates the explicit resume capability and returns the stable codec name without touching a Thread store.

func WithCallerIdentity 

func WithCallerIdentity(ctx context.Context, id AgentIdentity) context.Context

WithCallerIdentity returns a new context that carries id as the "caller identity" metadata for SDK hooks (currently SkillProvider.GetSkills and SkillCatalog.Catalogue). SDK invokes this internally before dispatching; adapters or middleware composing providers may also use it to forward identity through their own ctx chains.

Most hosts do not need to call this directly: SDK already injects the AgentIdentity resolved from Agent defaults / WithIdentity before invoking provider hooks.

Types

type AgentIdentity 

type AgentIdentity = driver.AgentIdentity

func CallerIdentityFromContext 

func CallerIdentityFromContext(ctx context.Context) (AgentIdentity, bool)

CallerIdentityFromContext returns the AgentIdentity SDK injected into ctx before invoking SkillProvider.GetSkills / SkillCatalog.Catalogue.

Provider implementations that need scoping (TenantID for catalogue partitioning, ProfileID for user-private skills, etc.) read it via this helper: 

func (p *MyProvider) GetSkills(ctx context.Context, keys []string) (map[string]agentadaptor.Skill, error) {
    id, _ := agentadaptor.CallerIdentityFromContext(ctx)
    return p.store.BatchGet(ctx, id.TenantID, keys)
}

The boolean is false when ctx has no identity attached (e.g. tests invoking the provider directly without SDK plumbing). Public providers and providers serving zero-tenant catalogues can ignore the helper entirely.

type AgentPayload 

type AgentPayload = driver.AgentPayload

func PrepareAgentPayload 

func PrepareAgentPayload(specs []AgentSpec) (AgentPayload, error)

PrepareAgentPayload exposes prepareAgentPayload for the root package.

type AgentProfile 

type AgentProfile = driver.AgentProfile

type AgentProfileSource 

type AgentProfileSource = driver.AgentProfileSource

type AgentSpec 

type AgentSpec = driver.AgentSpec

func CloneAgentSpecs 

func CloneAgentSpecs(values []AgentSpec) []AgentSpec

CloneAgentSpecs exposes cloneAgentSpecs for the root package.

type AgentToolPolicy 

type AgentToolPolicy = driver.AgentToolPolicy

type Checkpoint 

type Checkpoint = driver.Checkpoint

Checkpoint is an alias for driver.Checkpoint.

type ClaudeConfig 

type ClaudeConfig struct {
	CommonConfig
	Model          string
	Effort         ThinkingEffort
	MaxTurnsPerRun int
}

ClaudeConfig configures the built-in claude adapter. MaxTurnsPerRun is a guardrail for a single adapter invocation, not a session length.

type CloneProfileAuthMode 

type CloneProfileAuthMode = driver.CloneProfileAuthMode

type CloneProfileOptions 

type CloneProfileOptions = driver.CloneProfileOptions

type CodeBuddyConfig 

type CodeBuddyConfig struct {
	CommonConfig
	Model          string
	Effort         ThinkingEffort
	PermissionMode CodeBuddyPermissionMode
	MaxTurnsPerRun int
}

CodeBuddyConfig configures the built-in codebuddy adapter. CommonConfig controls process/profile/workspace defaults; Model / Effort map to CodeBuddy session settings. PermissionMode is the CodeBuddy headless permission mode; when empty the driver derives it from the run policy. MaxTurnsPerRun is a guardrail for a single adapter invocation, not a session length.

type CodeBuddyPermissionMode 

type CodeBuddyPermissionMode string

CodeBuddyPermissionMode is the CodeBuddy `--permission-mode` flag value. 

const (
	// CodeBuddyPermissionUnset lets the driver derive the mode from run policy.
	CodeBuddyPermissionUnset CodeBuddyPermissionMode = ""
	// CodeBuddyPermissionDefault prompts on first use of each tool.
	CodeBuddyPermissionDefault CodeBuddyPermissionMode = "default"
	// CodeBuddyPermissionAcceptEdits auto-accepts file edit permissions.
	CodeBuddyPermissionAcceptEdits CodeBuddyPermissionMode = "acceptEdits"
	// CodeBuddyPermissionPlan restricts the agent to analysis / planning.
	CodeBuddyPermissionPlan CodeBuddyPermissionMode = "plan"
	// CodeBuddyPermissionAuto lets an AI classifier auto-approve safe actions.
	CodeBuddyPermissionAuto CodeBuddyPermissionMode = "auto"
	// CodeBuddyPermissionDontAsk runs pre-approved actions and denies the rest.
	CodeBuddyPermissionDontAsk CodeBuddyPermissionMode = "dontAsk"
	// CodeBuddyPermissionBypass skips all permission prompts.
	CodeBuddyPermissionBypass CodeBuddyPermissionMode = "bypassPermissions"
)

type CodexConfig 

type CodexConfig struct {
	CommonConfig
	Model           string
	ReasoningEffort ReasoningEffort
	FastMode        bool
}

CodexConfig configures the built-in codex adapter. CommonConfig controls process/profile/workspace defaults; Model and ReasoningEffort map to Codex model settings.

type CommonConfig 

type CommonConfig struct {
	Command                 string
	CWD                     string
	Env                     []EnvBinding
	Instructions            *InstructionsBundleRef
	PromptTemplate          string
	BootstrapPromptTemplate string
	WorkspaceStrategy       *WorkspaceStrategy
	WorkspaceRuntime        *WorkspaceRuntimeConfig
	Timeout                 time.Duration
	GracePeriod             time.Duration
	ExtraArgs               []string
}

CommonConfig contains adapter-independent CLI/process defaults embedded by CodexConfig, ClaudeConfig, and CursorConfig. Adapter packages may interpret a subset, but hosts can set common fields without knowing the concrete agent.

type ConfigField 

type ConfigField = driver.ConfigField

Capability declaration blocks referenced by Descriptor.

type ConfigOption 

type ConfigOption = driver.ConfigOption

Capability declaration blocks referenced by Descriptor.

type ConfigSchema 

type ConfigSchema = driver.ConfigSchema

Capability declaration blocks referenced by Descriptor.

func CloneConfigSchema 

func CloneConfigSchema(schema *ConfigSchema) *ConfigSchema

CloneConfigSchema exposes cloneConfigSchema for the root package.

type ConfigSchemaProvider 

type ConfigSchemaProvider = driver.ConfigSchemaProvider

ConfigSchemaProvider is an alias for driver.ConfigSchemaProvider.

type CursorConfig 

type CursorConfig struct {
	CommonConfig
	Model string
	Mode  CursorMode
}

CursorConfig configures the built-in cursor adapter.

type CursorMode 

type CursorMode string

CursorMode is the Cursor Agent mode flag value.

type DecisionCapableSink 

type DecisionCapableSink = driver.DecisionCapableSink

DecisionCapableSink is an alias for driver.DecisionCapableSink.

type DecisionChoice 

type DecisionChoice = driver.DecisionChoice

type DecisionRequest 

type DecisionRequest = driver.DecisionRequest

type DecisionResponse 

type DecisionResponse = driver.DecisionResponse

type DecisionResult 

type DecisionResult = driver.DecisionResult

type Descriptor 

type Descriptor = driver.Descriptor

Descriptor is the Driver's static capability declaration. It is an alias for driver.Descriptor.

type DetectedModel 

type DetectedModel = driver.DetectedModel

type Driver 

type Driver = driver.Driver

Driver is the SPI implemented by built-in and third-party agent integrations. It is an alias for driver.Driver.

type DriverManagedWorkspace 

type DriverManagedWorkspace struct{}

DriverManagedWorkspace lets the Driver/provider choose or create its own workspace according to native behavior.

type EnvBinding 

type EnvBinding = driver.EnvBinding

func CloneEnvBindings 

func CloneEnvBindings(values []EnvBinding) []EnvBinding

CloneEnvBindings exposes cloneEnvBindings for the root package.

func CollectRuntimeSecretEnv 

func CollectRuntimeSecretEnv(refs []RuntimeServiceRef) []EnvBinding

CollectRuntimeSecretEnv gathers the subprocess-only secret bindings of a set of refs (per-run MCP bearer tokens and friends) into the payload-level SecretEnv slice driverutil.RuntimeEnvBindings injects into driver env.

type EnvironmentCheck 

type EnvironmentCheck = driver.EnvironmentCheck

type EnvironmentProbe 

type EnvironmentProbe = driver.EnvironmentProbe

EnvironmentProbe is an alias for driver.EnvironmentProbe.

type EnvironmentReport 

type EnvironmentReport = driver.EnvironmentReport

func SummarizeEnvironment 

func SummarizeEnvironment(driverType string, checks []EnvironmentCheck) EnvironmentReport

SummarizeEnvironment folds raw environment checks into the aggregate report with fail > warn > pass precedence and canonical summaries. (fail > warn > pass precedence, canonical summary strings).

type EnvironmentStatus 

type EnvironmentStatus = driver.EnvironmentStatus

type EventSink 

type EventSink = driver.EventSink

EventSink is an alias for driver.EventSink.

type FailureAction 

type FailureAction = driver.FailureAction

type FailureCode 

type FailureCode = driver.FailureCode

type FeatureLevel 

type FeatureLevel = driver.FeatureLevel

type GitWorktreeWorkspace 

type GitWorktreeWorkspace struct {
	BaseRef           string
	BranchTemplate    string
	WorktreeParentDir string
}

GitWorktreeWorkspace requests an isolated git worktree for the run.

type HITLRequestedPayload 

type HITLRequestedPayload = driver.HITLRequestedPayload

type HITLResolvedPayload 

type HITLResolvedPayload = driver.HITLResolvedPayload

type HookEvent 

type HookEvent = driver.HookEvent

type HookFailPolicy 

type HookFailPolicy = driver.HookFailPolicy

type HookHandler 

type HookHandler = driver.HookHandler

type HookHandlerType 

type HookHandlerType = driver.HookHandlerType

type HookMatcher 

type HookMatcher = driver.HookMatcher

type HookMatcherSubject 

type HookMatcherSubject = driver.HookMatcherSubject

type HookMatcherSyntax 

type HookMatcherSyntax = driver.HookMatcherSyntax

type HookPayload 

type HookPayload = driver.HookPayload

func PrepareHookPayload 

func PrepareHookPayload(specs []HookSpec) (HookPayload, error)

PrepareHookPayload exposes prepareHookPayload for the root package.

type HookSpec 

type HookSpec = driver.HookSpec

func CloneHookSpecs 

func CloneHookSpecs(values []HookSpec) []HookSpec

CloneHookSpecs exposes cloneHookSpecs for the root package.

type HumanDecisionFailure 

type HumanDecisionFailure = driver.HumanDecisionFailure

type HumanDecisionKind 

type HumanDecisionKind = driver.HumanDecisionKind

type HumanDecisionMode 

type HumanDecisionMode = driver.HumanDecisionMode

type HumanDecisionPolicy 

type HumanDecisionPolicy = driver.HumanDecisionPolicy

type HumanDecisionSupport 

type HumanDecisionSupport = driver.HumanDecisionSupport

type InstructionMode 

type InstructionMode = driver.InstructionMode

type InstructionScope 

type InstructionScope = driver.InstructionScope

type InstructionsBundleRef 

type InstructionsBundleRef = driver.InstructionsBundleRef

func CloneInstructions 

func CloneInstructions(ref *InstructionsBundleRef) *InstructionsBundleRef

CloneInstructions exposes cloneInstructions for the root package.

func PrepareInstructionsBundle 

func PrepareInstructionsBundle(ref *InstructionsBundleRef) (*InstructionsBundleRef, error)

PrepareInstructionsBundle exposes prepareInstructionsBundle for the root package.

type InstructionsCapability 

type InstructionsCapability = driver.InstructionsCapability

Capability declaration blocks referenced by Descriptor.

type InvalidOutputSchemaError 

type InvalidOutputSchemaError = driver.InvalidOutputSchemaError

InvalidOutputSchemaError is owned by package driver.

type IsolationLevel 

type IsolationLevel = driver.IsolationLevel

type MCPCapability 

type MCPCapability = driver.MCPCapability

type MCPConfig 

type MCPConfig struct {
	Servers []MCPServerSpec
}

MCPConfig is the Agent-level or per-run collection of MCP servers. Per-run WithMCP replaces the full effective config rather than appending to defaults.

type MCPPayload 

type MCPPayload = driver.MCPPayload

func ResolveMCPPayload 

func ResolveMCPPayload(defaults, override *MCPConfig, caps MCPCapability) (MCPPayload, error)

ResolveMCPPayload exposes resolveMCPPayload for the root package.

func ResolveMCPPayloadWithRuntime 

func ResolveMCPPayloadWithRuntime(defaults, override *MCPConfig, refs []RuntimeServiceRef, caps MCPCapability) (MCPPayload, error)

ResolveMCPPayloadWithRuntime exposes resolveMCPPayloadWithRuntime for the root package.

type MCPServerSpec 

type MCPServerSpec = driver.MCPServerSpec

func CloneMCPServerSpecs 

func CloneMCPServerSpecs(values []MCPServerSpec) []MCPServerSpec

CloneMCPServerSpecs exposes cloneMCPServerSpecs for the root package.

type MCPTransport 

type MCPTransport = driver.MCPTransport

type ModelDetector 

type ModelDetector = driver.ModelDetector

ModelDetector is an alias for driver.ModelDetector.

type ModelInfo 

type ModelInfo = driver.ModelInfo

type ModelLister 

type ModelLister = driver.ModelLister

ModelLister is an alias for driver.ModelLister.

type NativeConfigPatch 

type NativeConfigPatch = driver.NativeConfigPatch

type OutputFormat 

type OutputFormat = driver.OutputFormat

type OutputSchema 

type OutputSchema = driver.OutputSchema

func CloneOutputSchema 

func CloneOutputSchema(schema *OutputSchema) *OutputSchema

CloneOutputSchema exposes cloneOutputSchema for the root package.

func NormalizeOutputSchema 

func NormalizeOutputSchema(schema *OutputSchema) (*OutputSchema, error)

NormalizeOutputSchema exposes normalizeOutputSchema for the root package.

type ProfileConfigFileKind 

type ProfileConfigFileKind = driver.ProfileConfigFileKind

type ProfileConfigPatch 

type ProfileConfigPatch = driver.ProfileConfigPatch

func CloneProfileConfigPatches 

func CloneProfileConfigPatches(values []ProfileConfigPatch) []ProfileConfigPatch

CloneProfileConfigPatches exposes cloneProfileConfigPatches for the root package.

type ProfileConfigPayload 

type ProfileConfigPayload = driver.ProfileConfigPayload

func PrepareProfileConfigPayload 

func PrepareProfileConfigPayload(patches []ProfileConfigPatch) (ProfileConfigPayload, error)

PrepareProfileConfigPayload exposes prepareProfileConfigPayload for the root package.

type ProfileKind 

type ProfileKind string

ProfileKind is the SDK's internal effective-profile classification. It separates where the provider profile lives from the public ProfileSelection option that requested it. 

const (
	// ProfileKindShared means the effective profile is the provider-native
	// shared profile such as ~/.claude, ~/.codex, or ~/.cursor.
	ProfileKindShared ProfileKind = "shared"
	// ProfileKindHostManaged means the effective profile is isolated or
	// managed by the host/adapter, such as a dedicated, cloned, or managed home.
	ProfileKindHostManaged ProfileKind = "host_managed"
)

type ProfileMode 

type ProfileMode = driver.ProfileMode

type ProfilePayload 

type ProfilePayload = driver.ProfilePayload

func BuildProfilePayload 

func BuildProfilePayload(skills ResolvedSkills, mcp MCPPayload, agents AgentPayload, hooks HookPayload, instructions *InstructionsBundleRef, config ProfileConfigPayload, declared ProfileResourceDeclarations) ProfilePayload

BuildProfilePayload exposes buildProfilePayload for the root package.

type ProfileReporter 

type ProfileReporter = driver.ProfileReporter

ProfileReporter is an alias for driver.ProfileReporter.

type ProfileResourceDeclarations 

type ProfileResourceDeclarations = driver.ProfileResourceDeclarations

type ProfileResourceDriver 

type ProfileResourceDriver = profileResourceDriver

ProfileResourceDriver is the optional Driver capability ProfileState and SyncProfile probe before falling back to payload-derived snapshots.

type ProfileResourceKind 

type ProfileResourceKind string

ProfileResourceKind names one provider-visible resource family managed as part of the effective profile desired state. 

const (
	ProfileResourceSkills       ProfileResourceKind = "skills"
	ProfileResourceMCP          ProfileResourceKind = "mcp"
	ProfileResourceAgents       ProfileResourceKind = "agents"
	ProfileResourceHooks        ProfileResourceKind = "hooks"
	ProfileResourceInstructions ProfileResourceKind = "instructions"
	ProfileResourceConfig       ProfileResourceKind = "config"
)

type ProfileResourceMaterialization 

type ProfileResourceMaterialization string
const (
	ProfileResourceMaterializationNativeManaged   ProfileResourceMaterialization = "native_managed"
	ProfileResourceMaterializationFileManaged     ProfileResourceMaterialization = "file_managed"
	ProfileResourceMaterializationPromptInjected  ProfileResourceMaterialization = "prompt_injected"
	ProfileResourceMaterializationFallback        ProfileResourceMaterialization = "fallback"
	ProfileResourceMaterializationNotMaterialized ProfileResourceMaterialization = "not_materialized"
)

type ProfileResourceSupport 

type ProfileResourceSupport string
const (
	ProfileResourceSupportPortableCore     ProfileResourceSupport = "portable_core"
	ProfileResourceSupportPortableExtended ProfileResourceSupport = "portable_extended"
	ProfileResourceSupportNativeEscape     ProfileResourceSupport = "native_escape"
	ProfileResourceSupportFallback         ProfileResourceSupport = "fallback"
	ProfileResourceSupportUnsupported      ProfileResourceSupport = "unsupported"
)

type ProfileResources 

type ProfileResources struct {
	Skills       []SkillRef
	MCP          *MCPConfig
	Agents       []AgentSpec
	Hooks        []HookSpec
	Instructions *InstructionsBundleRef
	Config       []ProfileConfigPatch
}

ProfileResources is the host-facing desired-state bundle accepted by WithProfileResources at agent construction or per-call scope. Existing sugar options (WithSkills, WithMCP, WithInstructions, etc.) continue to work and are folded into the same ProfilePayload before invoking a driver.

type ProfileSelection 

type ProfileSelection = driver.ProfileSelection

func CloneProfileSelection 

func CloneProfileSelection(sel *ProfileSelection) *ProfileSelection

CloneProfileSelection deep-copies a profile selection (nil-safe). Drivers receive defensive copies rather than caller-owned state.

type ProfileSnapshot 

type ProfileSnapshot struct {
	DriverType  string
	Profile     AgentProfile
	Kind        ProfileKind
	Fingerprint string
	Resources   []ResourceSnapshot
	Warnings    []string
}

ProfileSnapshot reports the control-plane view of an effective profile.

func SnapshotProfilePayload 

func SnapshotProfilePayload(driverType string, profile AgentProfile, selection *ProfileSelection, payload ProfilePayload, synced bool) ProfileSnapshot

SnapshotProfilePayload converts a computed ProfilePayload into the ProfileSnapshot shape ProfileState/SyncProfile return return for Drivers without profileResourceDriver: a PortableCore skills row plus honest unsupported rows (desired-but-not-observed warnings when synced is false, not-materialized warnings + Error when synced is true).

type QuestionMode 

type QuestionMode = driver.QuestionMode

type QuestionSupport 

type QuestionSupport = driver.QuestionSupport

type QuotaProbe 

type QuotaProbe = driver.QuotaProbe

QuotaProbe is an alias for driver.QuotaProbe.

type QuotaReport 

type QuotaReport = driver.QuotaReport

type QuotaWindow 

type QuotaWindow = driver.QuotaWindow

type RawStreams 

type RawStreams = driver.RawStreams

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort is the Codex reasoning effort flag value.

type Request 

type Request = driver.Request

Request is the fully resolved invocation passed to a Driver. It is an alias for driver.Request.

type ResolvedSkill 

type ResolvedSkill = driver.ResolvedSkill

type ResolvedSkills 

type ResolvedSkills = driver.ResolvedSkills

func CloneResolvedSkills 

func CloneResolvedSkills(r ResolvedSkills) ResolvedSkills

CloneResolvedSkills exposes cloneResolvedSkills for the root package.

type ResourceSnapshot 

type ResourceSnapshot struct {
	Kind            ProfileResourceKind
	Fingerprint     string
	Managed         []string
	External        []string
	Support         ProfileResourceSupport
	Materialization ProfileResourceMaterialization
	Warnings        []string
	Error           string
}

ResourceSnapshot reports the observed state for one profile resource kind.

type Response 

type Response = driver.Response

Response is the Driver-facing execution result. It is an alias for driver.Response.

type ResumeRejectedError 

type ResumeRejectedError struct {
	Reason string
	Cause  error
}

ResumeRejectedError carries the adapter-supplied Reason and the underlying Cause when the driver rejects a resume. Unwrap joins ErrResumeRejected with Cause.

func (*ResumeRejectedError) Error 

func (e *ResumeRejectedError) Error() string

Error reports the resume rejection reason when present.

func (*ResumeRejectedError) Unwrap 

func (e *ResumeRejectedError) Unwrap() error

Unwrap joins ErrResumeRejected with the adapter-supplied Cause when set.

type Role 

type Role = driver.Role

type RunEvent 

type RunEvent = driver.RunEvent

type RunEventType 

type RunEventType = driver.RunEventType

type RunFailure 

type RunFailure = driver.RunFailure

type RunPolicy 

type RunPolicy = driver.RunPolicy

func MergeRunPolicy 

func MergeRunPolicy(base, override *RunPolicy) (RunPolicy, error)

MergeRunPolicy exposes mergeRunPolicy for the root package (the root package keeps a same-named unexported delegate that its policy-merge test exercises).

type RunPolicyCapabilities 

type RunPolicyCapabilities = driver.RunPolicyCapabilities

Capability declaration blocks referenced by Descriptor.

type RuntimeCapability 

type RuntimeCapability = driver.RuntimeCapability

Capability declaration blocks referenced by Descriptor.

type RuntimePayload 

type RuntimePayload = driver.RuntimePayload

func PrepareRuntimePayload 

func PrepareRuntimePayload(ctx context.Context, manager RuntimeServiceManager, req RuntimeServiceRequest, desired []RuntimeServiceSpec) (RuntimePayload, error)

PrepareRuntimePayload resolves one run's runtime services: clone the desired specs, fingerprint them, call RuntimeServiceManager.Ensure, collect the subprocess-only SecretEnv, and normalize the returned refs against the requested specs (ID/Name/URL/lifecycle/metadata backfill, status/health defaults, owner attribution).

req.Desired is filled by the callee; a nil manager behaves like the noop default, which keeps "declared but unmanaged" services out of the driver payload instead of inventing endpoints.

type RuntimeServiceHealth 

type RuntimeServiceHealth = driver.RuntimeServiceHealth

type RuntimeServiceLifecycle 

type RuntimeServiceLifecycle = driver.RuntimeServiceLifecycle

type RuntimeServiceManager 

type RuntimeServiceManager interface {
	// Ensure starts or locates the runtime services needed for one run and
	// returns concrete refs the adapter can inject into the prompt/profile.
	Ensure(ctx context.Context, req RuntimeServiceRequest) ([]RuntimeServiceRef, error)
	// ReleaseByRun releases services scoped to one SDK RunID. The SDK calls it
	// during normal cleanup for run-scoped services.
	ReleaseByRun(ctx context.Context, runID string) error

	// ReleaseByLabels releases every service whose Metadata contains
	// every key-value pair in labels. The semantics match a logical
	// AND across the labels map, NOT individual matches.
	//
	// An empty labels map releases nothing — callers must explicitly
	// opt-in to broad releases by passing at least one key-value
	// pair. This is a deliberate guard against accidental "release
	// everything you have" calls (compare ReleaseByRun, which always
	// scopes to one runID).
	//
	// Implementations should not error when no service matches; the
	// invariant after a successful call is "no service whose
	// Metadata covers labels remains running", which is trivially
	// satisfied by an empty match. Backend errors (Docker daemon
	// down, permission denied, etc.) propagate as-is.
	//
	// This method exists primarily to support host-side cleanup by
	// task / tenant / workspace label after a process restart, when
	// the runID-scoped index from a previous incarnation has been
	// lost. It is deliberately narrower than a host-driven global
	// Reconcile(aliveRunIDs) contract. See docs/api-reference.md §12.
	ReleaseByLabels(ctx context.Context, labels map[string]string) error
}

RuntimeServiceManager is the host hook for preparing services a run depends on, such as local dev servers, databases, or tool sidecars. The SDK only coordinates lifecycle; the host owns process/container orchestration.

type RuntimeServiceRef 

type RuntimeServiceRef = driver.RuntimeServiceRef

func CloneRuntimeServiceRefs 

func CloneRuntimeServiceRefs(values []RuntimeServiceRef) []RuntimeServiceRef

CloneRuntimeServiceRefs exposes cloneRuntimeServiceRefs for the root package.

func NormalizeRuntimeServiceRefs 

func NormalizeRuntimeServiceRefs(requested []RuntimeServiceSpec, ensured []RuntimeServiceRef, owner AgentIdentity) []RuntimeServiceRef

NormalizeRuntimeServiceRefs backfills and defaults a set of ensured refs against the requested specs, exactly like the Ensure post-processing step. The root pipeline uses it for refs from a RunServiceProvider attachment rather than from a RuntimeServiceManager, so both sources reach the driver in the same normalized shape.

type RuntimeServiceReport 

type RuntimeServiceReport = driver.RuntimeServiceReport

func RuntimeReportsFromRefs 

func RuntimeReportsFromRefs(refs []RuntimeServiceRef, owner AgentIdentity) []RuntimeServiceReport

RuntimeReportsFromRefs synthesises the truthful runtime-service reports for drivers that ensure services but report none back.

type RuntimeServiceRequest 

type RuntimeServiceRequest struct {
	RunID      string
	DriverType string
	Agent      AgentIdentity
	Config     any
	Workspace  WorkspaceLease
	Desired    []RuntimeServiceSpec
	Metadata   map[string]string
}

RuntimeServiceRequest is passed to RuntimeServiceManager.Ensure with the run identity, resolved workspace, agent identity, and desired services.

type RuntimeServiceSpec 

type RuntimeServiceSpec = driver.RuntimeServiceSpec

func CloneRuntimeServiceSpecs 

func CloneRuntimeServiceSpecs(values []RuntimeServiceSpec) []RuntimeServiceSpec

CloneRuntimeServiceSpecs exposes cloneRuntimeServiceSpecs for the root package.

type RuntimeServiceStatus 

type RuntimeServiceStatus = driver.RuntimeServiceStatus

type SessionBusyError 

type SessionBusyError struct {
	Target string
}

SessionBusyError is wrapped by ErrSessionBusy when the busy target (a sessionID, a namespace+key tuple, etc.) is known.

func (*SessionBusyError) Error 

func (e *SessionBusyError) Error() string

Error reports the busy session target when present.

func (*SessionBusyError) Unwrap 

func (e *SessionBusyError) Unwrap() error

Unwrap returns ErrSessionBusy so errors.Is(err, ErrSessionBusy) holds.

type SessionCapability 

type SessionCapability = driver.SessionCapability

Capability declaration blocks referenced by Descriptor.

type SessionCodec 

type SessionCodec = driver.SessionCodec

func SessionCodecFor 

func SessionCodecFor(driver Driver) SessionCodec

SessionCodecFor returns the driver's explicit session codec when available, otherwise it falls back to a passthrough codec that simply round-trips SessionState fields. This permissive helper exists for stateless tooling and direct SPI inspection. Thread coordination must use resumeSessionCodecFor so an undeclared or incomplete resume capability can never become stateful by accident.

type SessionCodecProvider 

type SessionCodecProvider = driver.SessionCodecProvider

SessionCodecProvider is an alias for driver.SessionCodecProvider.

type SessionCompatibility 

type SessionCompatibility struct {
	Status              SessionCompatibilityStatus
	Reason              string
	ExpectedFingerprint string
	ActualFingerprint   string
}

SessionCompatibility explains why a stored session did or did not match the current invocation fingerprint.

type SessionCompatibilityStatus 

type SessionCompatibilityStatus string

SessionCompatibilityStatus classifies whether a stored checkpoint can be reused with the current resolved invocation. 

const (
	// SessionCompatibilityNew means no previous checkpoint was reused.
	SessionCompatibilityNew SessionCompatibilityStatus = "new"
	// SessionCompatibilityCompatible means the stored checkpoint matched the
	// current invocation fingerprint and was safe to resume.
	SessionCompatibilityCompatible SessionCompatibilityStatus = "compatible"
	// SessionCompatibilityIncompatible means a stored checkpoint existed but
	// resume was rejected because important context changed.
	SessionCompatibilityIncompatible SessionCompatibilityStatus = "incompatible"
)

type SessionContext 

type SessionContext = driver.SessionContext

SessionContext is an alias for driver.SessionContext.

type SessionFinalizeRequest 

type SessionFinalizeRequest struct {
	Record           SessionRecord
	PreviousID       string
	Namespace        string
	Key              string
	HeldLeases       []SessionLease
	ArchiveOld       bool
	RebindActive     bool
	RequireKeyAbsent bool
}

SessionFinalizeRequest tells a SessionStore how to persist the post-run session state. It includes the new record, any old active mapping, held leases, and whether the store should archive/rebind atomically.

type SessionIncompatibleError 

type SessionIncompatibleError struct {
	Reason              string
	ExpectedFingerprint string
	ActualFingerprint   string
}

SessionIncompatibleError carries the fingerprint diff that triggered the rejection. Unwrap returns ErrSessionIncompatible.

func (*SessionIncompatibleError) Error 

func (e *SessionIncompatibleError) Error() string

Error reports the incompatibility reason when present.

func (*SessionIncompatibleError) Unwrap 

func (e *SessionIncompatibleError) Unwrap() error

Unwrap returns ErrSessionIncompatible.

type SessionLease 

type SessionLease struct {
	Target string
	Owner  string
	Token  string
}

SessionLease is the optimistic/concurrent-use guard returned by SessionStore.AcquireLease. Stores should validate Token ownership during Finalize and ReleaseLease.

type SessionLeaseLostError 

type SessionLeaseLostError struct {
	Target string
}

SessionLeaseLostError is wrapped by ErrSessionLeaseLost when the lease target is known.

func (*SessionLeaseLostError) Error 

func (e *SessionLeaseLostError) Error() string

Error reports the lost lease target when present.

func (*SessionLeaseLostError) Unwrap 

func (e *SessionLeaseLostError) Unwrap() error

Unwrap returns ErrSessionLeaseLost so errors.Is(err, ErrSessionLeaseLost) holds.

type SessionMode 

type SessionMode = driver.SessionMode

SessionMode tells a Driver whether to start, resume, fork, or avoid a provider session. It is an alias for driver.SessionMode.

type SessionParams 

type SessionParams = driver.SessionParams

type SessionQuery 

type SessionQuery struct {
	ID              string
	Namespace       string
	Key             string
	IncludeArchived bool
}

SessionQuery is the lookup shape passed to SessionStore.Resolve.

type SessionRecord 

type SessionRecord struct {
	ID                       string
	Namespace                string
	Key                      string
	Status                   SessionStatus
	DriverType               string
	Agent                    AgentIdentity
	Fingerprint              string
	CompatibilityFingerprint string
	SessionCodec             string
	DriverState              *SessionState
	CreatedAt                time.Time
	UpdatedAt                time.Time
}

SessionRecord is the durable SDK session record stored by SessionStore. DriverState is adapter-owned checkpoint data; Fingerprint fields are used to reject unsafe resumes when workspace/skills/MCP/policy context changes.

type SessionRef 

type SessionRef struct {
	ID            string
	Namespace     string
	Key           string
	DisplayID     string
	Reused        bool
	Created       bool
	PreviousID    string
	Compatibility SessionCompatibility
}

SessionRef reports the engine record reused, created, or rebound by a Thread operation.

type SessionRequest 

type SessionRequest struct {
	ID           string
	Namespace    string
	Key          string
	Mode         SessionMode
	ForkFrom     string
	ForkFromKey  string
	SessionCodec string
}

SessionRequest is the engine's thread-state instruction for one run. ForkFromKey lets the coordinator lock and resolve both parent and target thread keys without a caller-side prelookup.

type SessionState 

type SessionState = driver.SessionState

SessionState is an alias for driver.SessionState.

func NormalizeResumableSessionState 

func NormalizeResumableSessionState(driver Driver, state *SessionState) (*SessionState, error)

NormalizeResumableSessionState validates and normalizes a stored checkpoint through the configured Driver's required Thread codec.

func NormalizeSessionState 

func NormalizeSessionState(driver Driver, state *SessionState) *SessionState

NormalizeSessionState exposes normalizeSessionState for the root package.

type SessionStatus 

type SessionStatus string

SessionStatus is the storage lifecycle state of a SessionRecord. 

const (
	// SessionStatusActive marks the current record for a SessionKey.
	SessionStatusActive SessionStatus = "active"
	// SessionStatusArchived marks a previous record retained for audit/forking.
	SessionStatusArchived SessionStatus = "archived"
)

type SessionStore 

type SessionStore interface {
	Resolve(ctx context.Context, q SessionQuery) (*SessionRecord, error)
	Finalize(ctx context.Context, req SessionFinalizeRequest) error
	AcquireLease(ctx context.Context, sessionID, owner string, ttl time.Duration) (SessionLease, error)
	RenewLease(ctx context.Context, lease SessionLease, ttl time.Duration) error
	ReleaseLease(ctx context.Context, lease SessionLease) error
}

SessionStore is the private coordination port behind the public threadstore contract. It persists resume checkpoints, compatibility fingerprints, and leases; chat history and pending approvals remain host concerns. Finalize must validate lease ownership and atomically save, archive, and rebind the active record. AcquireLease implementations must return an error matching ErrSessionBusy only for a genuine live-owner conflict and preserve context cancellation, deadlines, and backend error identity for all other failures.

type SharedWorkspace 

type SharedWorkspace struct{}

SharedWorkspace requests direct reuse of the project workspace.

type Skill 

type Skill = driver.Skill

type SkillCapability 

type SkillCapability = driver.SkillCapability

Capability declaration blocks referenced by Descriptor.

type SkillCatalog 

type SkillCatalog interface {
	SkillProvider
	Catalogue(ctx context.Context) ([]Skill, error)
}

SkillCatalog extends SkillProvider with deterministic enumeration for inspection surfaces.

type SkillKey 

type SkillKey = driver.SkillKey

type SkillKeyConflictError 

type SkillKeyConflictError = skill.SkillKeyConflictError

SkillKeyConflictError is owned by package skill.

type SkillMaterializationError 

type SkillMaterializationError = skill.SkillMaterializationError

SkillMaterializationError is owned by package skill.

type SkillMaterializer 

type SkillMaterializer interface {
	Materialize(ctx context.Context, s Skill) (sourcePath string, err error)
}

SkillMaterializer writes a skill source to a directory containing SKILL.md.

type SkillOrigin 

type SkillOrigin = driver.SkillOrigin

type SkillProvider 

type SkillProvider interface {
	GetSkills(ctx context.Context, keys []string) (map[string]Skill, error)
}

SkillProvider resolves catalogue keys into concrete skills for a run. Providers may return additional Required skills that were not explicitly requested. Caller identity is carried in context by the engine.

type SkillRef 

type SkillRef = driver.SkillRef

func CloneSkillRefs 

func CloneSkillRefs(values []SkillRef) []SkillRef

CloneSkillRefs exposes cloneSkillRefs for the root package.

func CollectSkillCandidates 

func CollectSkillCandidates(ctx context.Context, provider SkillProvider, identity AgentIdentity, defaultSkills []SkillRef) ([]SkillRef, error)

CollectSkillCandidates returns the candidate pool for Inspector.Skills and Agent.SelectSkills: the Agent defaults plus the provider catalogue entries. Catalogue errors propagate verbatim.

Inspect().Skills and SelectSkills use the same pool composition.

type SkillSnapshot 

type SkillSnapshot = driver.SkillSnapshot

func BuildSkillSnapshot 

func BuildSkillSnapshot(ctx context.Context, adapter Driver, config any, payload ResolvedSkills, selected []string, resolved []Skill, profile *ProfileSelection) (SkillSnapshot, error)

BuildSkillSnapshot routes a resolved payload to the Driver's ListSkills when it is skill-aware, or synthesises the truthful "unsupported" snapshot otherwise (Supported=false, SkillSyncUnsupported, cloned selection/warnings, payload fingerprint).

The returned snapshot reports actual materialization support.

func SyncSkillSnapshot 

func SyncSkillSnapshot(ctx context.Context, adapter Driver, config any, payload ResolvedSkills, selected []string, resolved []Skill, profile *ProfileSelection) (SkillSnapshot, error)

SyncSkillSnapshot routes a resolved payload to the Driver's SyncSkills when it is skill-aware, with the same unsupported fallback as BuildSkillSnapshot. SyncProfile and SelectSkills share this operation.

type SkillSource 

type SkillSource = driver.SkillSource

type SkillState 

type SkillState = driver.SkillState

type SkillSupport 

type SkillSupport = driver.SkillSupport

SkillSupport is an alias for driver.SkillSupport.

type SkillSyncMode 

type SkillSyncMode = driver.SkillSyncMode

type SnapshotEntry 

type SnapshotEntry = driver.SnapshotEntry

type StreamCapability 

type StreamCapability = driver.StreamCapability

StreamCapability is an alias for driver.StreamCapability.

type StreamKind 

type StreamKind = driver.StreamKind

type StreamPayload 

type StreamPayload = driver.StreamPayload

type StreamSupport 

type StreamSupport = driver.StreamSupport

StreamSupport is an alias for driver.StreamSupport.

type StructuredOutput 

type StructuredOutput = driver.StructuredOutput

type StructuredOutputCapability 

type StructuredOutputCapability = driver.StructuredOutputCapability

Capability declaration blocks referenced by Descriptor.

type StructuredOutputInvalidPolicy 

type StructuredOutputInvalidPolicy = driver.StructuredOutputInvalidPolicy

type StructuredOutputSource 

type StructuredOutputSource = driver.StructuredOutputSource

func ResolveStructuredOutputSource 

func ResolveStructuredOutputSource(desc Descriptor, schema *OutputSchema, streaming bool, policy RunPolicy) (StructuredOutputSource, error)

ResolveStructuredOutputSource exposes resolveStructuredOutputSource for the root package.

type StructuredOutputUnsupportedError 

type StructuredOutputUnsupportedError = driver.StructuredOutputUnsupportedError

StructuredOutputUnsupportedError is owned by package driver.

type ThinkingEffort 

type ThinkingEffort string

ThinkingEffort is the Claude thinking effort flag value.

type ThreadSessionPlan 

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

ThreadSessionPlan owns one Thread operation's leases, compatibility state, resume/fork plan, and atomic persistence request.

func PrepareThreadSession 

func PrepareThreadSession(
	ctx context.Context,
	store SessionStore,
	req SessionRequest,
	identity AgentIdentity,
	driverType string,
	fingerprint string,
) (*ThreadSessionPlan, error)

PrepareThreadSession resolves a session plan against store for the given request:

  • Stateless mode (or an empty request) yields (nil, nil).
  • A nil store yields ErrSessionStoreRequired.
  • Key and session leases are acquired (busy → *SessionBusyError), the current record is resolved, and the per-mode plan logic runs (ContinueOnly / ContinueOrStart / Fork).

On success the caller owns the plan and must call Release when done.

func PrepareThreadSessionForDriver 

func PrepareThreadSessionForDriver(
	ctx context.Context,
	store SessionStore,
	req SessionRequest,
	identity AgentIdentity,
	driverImpl Driver,
	fingerprint string,
) (*ThreadSessionPlan, error)

PrepareThreadSessionForDriver is the v1 coordinator entry. In addition to normal planning it derives the codec identity from the configured Driver and proves every reused checkpoint or fork parent's checkpoint can be normalized by that exact codec before returning a runnable plan. Callers must prefer this entry over supplying SessionRequest.SessionCodec themselves.

func (*ThreadSessionPlan) DriverSession 

func (p *ThreadSessionPlan) DriverSession(adapter Driver) *SessionContext

DriverSession builds the per-run driver session context. Driver state is forwarded only when a record exists and the plan either reuses it or forks from it, normalized through the driver's session codec.

func (*ThreadSessionPlan) Mode 

func (p *ThreadSessionPlan) Mode() SessionMode

Mode reports the effective session mode of the plan.

func (*ThreadSessionPlan) Persist 

func (p *ThreadSessionPlan) Persist(
	ctx context.Context,
	identity AgentIdentity,
	adapter Driver,
	fingerprint string,
	checkpoint *Checkpoint,
) (*SessionRef, error)

Persist finalizes the post-run session state through the store: it validates held leases, saves the record (state normalized through the driver codec), archives the previous record when one was displaced, and rebinds the key's active mapping. A nil/invalid checkpoint yields ErrSessionCheckpointMissing.

func (*ThreadSessionPlan) PrepareFresh 

func (p *ThreadSessionPlan) PrepareFresh(ctx context.Context, driverType, fingerprint string) error

PrepareFresh rewires the plan to a brand-new session after the driver rejected a resume: the old engine ID becomes PreviousID (archived on persist) and a new session lease is acquired. This resume-rejection fallback only applies when Reused() and the mode is SessionContinueOrStart.

func (*ThreadSessionPlan) Release 

func (p *ThreadSessionPlan) Release()

Release stops renewal and releases all held leases in reverse acquisition order. It is safe to call after Persist and on every error path.

func (*ThreadSessionPlan) ReleaseContext 

func (p *ThreadSessionPlan) ReleaseContext(ctx context.Context) error

ReleaseContext stops renewal and releases every held lease, returning any store error. The call is bounded by ctx even when a broken Store ignores cancellation. Final coordinators use this method and surface its error.

func (*ThreadSessionPlan) RenewalError 

func (p *ThreadSessionPlan) RenewalError() error

RenewalError reports the first lease renewal failure, if any. Callers must check it after StopLeaseRenewal and treat a non-nil result as fatal for the run (the session state must not be persisted).

func (*ThreadSessionPlan) Reused 

func (p *ThreadSessionPlan) Reused() bool

Reused reports whether the plan resumes an existing compatible record.

func (*ThreadSessionPlan) StartLeaseRenewal 

func (p *ThreadSessionPlan) StartLeaseRenewal(ctx context.Context, cancel context.CancelFunc)

StartLeaseRenewal spawns the ticker-driven renewal goroutine over every held lease. On renewal failure the error is recorded (RenewalError) and cancel is invoked so the in-flight run aborts instead of continuing without exclusivity.

func (*ThreadSessionPlan) StopLeaseRenewal 

func (p *ThreadSessionPlan) StopLeaseRenewal()

StopLeaseRenewal stops the renewal goroutine and waits for it to exit.

type TranscriptItem 

type TranscriptItem = driver.TranscriptItem

type TranscriptKind 

type TranscriptKind = driver.TranscriptKind

type Usage 

type Usage = driver.Usage

type WorkspaceCapability 

type WorkspaceCapability = driver.WorkspaceCapability

Capability declaration blocks referenced by Descriptor.

type WorkspaceLease 

type WorkspaceLease = driver.WorkspaceLease

func ResolveWorkspaceLease 

func ResolveWorkspaceLease(ctx context.Context, manager WorkspaceManager, req WorkspaceRequest) (WorkspaceLease, error)

ResolveWorkspaceLease runs one WorkspaceManager.Resolve. A nil manager uses the passthrough manager (base CWD defaulting to os.Getwd, shared/project-primary request data, "workspace_manager: passthrough" metadata, stableHash lease ID and fingerprint).

type WorkspaceManager 

type WorkspaceManager interface {
	Resolve(ctx context.Context, req WorkspaceRequest) (WorkspaceLease, error)
	Release(ctx context.Context, lease WorkspaceLease, mode WorkspaceReleaseMode) error
}

WorkspaceManager is the host hook that turns a WorkspaceSpec into a concrete working directory lease. Implementations may return the project directory unchanged, create git worktrees, provision sandboxes, or delegate to an external workspace service. The SDK releases the lease after the run using the requested WorkspaceReleaseMode.

type WorkspaceMode 

type WorkspaceMode = driver.WorkspaceMode

type WorkspaceReleaseMode 

type WorkspaceReleaseMode string

WorkspaceReleaseMode tells a WorkspaceManager what to do after the run. 

const (
	// WorkspaceReleaseKeep leaves the workspace available after the run.
	WorkspaceReleaseKeep WorkspaceReleaseMode = "keep"
	// WorkspaceReleaseStop asks the manager to tear down run-scoped resources.
	WorkspaceReleaseStop WorkspaceReleaseMode = "stop"
)

type WorkspaceRequest 

type WorkspaceRequest struct {
	BaseCWD  string
	Spec     WorkspaceSpec
	Metadata map[string]string
}

WorkspaceRequest is passed to WorkspaceManager.Resolve after SDK defaults and per-run workspace options have been merged.

type WorkspaceRequestData 

type WorkspaceRequestData struct {
	Mode           WorkspaceMode
	StrategyType   WorkspaceStrategyType
	BaseRef        string
	BranchTemplate string
	ParentDir      string
}

WorkspaceRequestData is the normalized internal form of a WorkspaceSpec.

type WorkspaceRuntimeConfig 

type WorkspaceRuntimeConfig struct {
	Services []RuntimeServiceSpec
}

WorkspaceRuntimeConfig declares runtime services associated with a workspace or Agent default. The service manager resolves them before Driver launch.

type WorkspaceSpec 

type WorkspaceSpec interface {
	// contains filtered or unexported methods
}

WorkspaceSpec is implemented by host-facing workspace request values. The unexported method keeps the set of built-in specs closed for now while still letting hosts choose between them.

type WorkspaceStrategy 

type WorkspaceStrategy struct {
	Type              WorkspaceStrategyType
	BaseRef           string
	BranchTemplate    string
	WorktreeParentDir string
}

WorkspaceStrategy describes how a host would like a workspace provisioned. It is primarily carried through CommonConfig for adapter/default plumbing; hosts usually use concrete WorkspaceSpec values with WithWorkspace.

type WorkspaceStrategyType 

type WorkspaceStrategyType = driver.WorkspaceStrategyType

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.