launch

package
v0.61.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package launch defines the versioned contracts shared by launch orchestration, harness adapters, and terminal backends.

Package launch trust state uses physical project identity and fails closed where that identity is unavailable. Windows callers must surface exit 6 (action_required); they must never substitute a path-based identity.

Index

Constants

View Source 
const (
	ClaudeProvider = "claude"
	CodexProvider  = "codex"
)
View Source 
const (
	BindingVersion     = 1
	ResourceSetVersion = 1
)
View Source 
const (
	CommandsBackendName = "commands"
	// InternalLaunchNonceEnv marks a command emitted by the trusted launch
	// reconciler. coop exec consumes it and never forwards it to the provider.
	InternalLaunchNonceEnv  = "AMQ_INTERNAL_LAUNCH_NONCE"
	PlanOnlyInspectEvidence = "plan_only backend has no query surface"
	PlanOnlyCloseReason     = "plan_only backend owns no terminal resource"
)
View Source 
const (
	ProjectConfigSchema = 1
	LocalConfigSchema   = 1
	DefaultSessionName  = "collab"
	LayoutColumns       = "columns"
	LauncherCMux        = "cmux"
	LauncherGhostty     = "ghostty"
	LauncherTMux        = "tmux"
	LauncherCommands    = "commands"
)
View Source 
const (
	ReasonNoSavedConversation    = "no_saved_conversation"
	ReasonPriorLaunchNotExecuted = "prior_launch_not_executed"
	ReasonStaleConversation      = "stale_conversation"
)
View Source 
const (
	ConversationVersion = 1
)
View Source 
const ExecutionTicketVersion = 1
View Source 
const (
	JournalVersion = 1
)
View Source 
const LauncherAuto = "auto"
View Source 
const (
	LeaseVersion = 1
)
View Source 
const PlanVersion = 1
View Source 
const TrustVersion = 1

Variables

This section is empty.

Functions

func BindingPath 

func BindingPath(sessionRoot string) string

BindingPath is for diagnostics and tests only. I/O must use a pinned root.

func ClearJournal 

func ClearJournal(root *fsq.DeliveryRoot, lease *Lease, expected LaunchJournal) error

func ConversationPath 

func ConversationPath(sessionRoot, handle string) string

func ExecutionTicketPath 

func ExecutionTicketPath(sessionRoot, handle string) string

func ExecutionTrustDigest 

func ExecutionTrustDigest(plan Plan, session string, root *fsq.DeliveryRoot) (string, error)

ExecutionTrustDigest binds the static provider plan to the session root in which the plan will be emitted. The plan digest alone cannot distinguish a selector-free launch after default_session changes.

func JournalPath 

func JournalPath(sessionRoot string) string

func LeasePath 

func LeasePath(sessionRoot string) string

func MarshalLocalConfig 

func MarshalLocalConfig(cfg LocalConfig) ([]byte, error)

func MarshalProjectConfig 

func MarshalProjectConfig(cfg ProjectConfig) ([]byte, error)

func RemoveExecutionTicket 

func RemoveExecutionTicket(root *fsq.DeliveryRoot, lease *Lease, handle, nonce string) error

RemoveExecutionTicket removes only the exact pending generation while the caller still holds both the launch lease and the handle lock.

func RevertExecution 

func RevertExecution(root *fsq.DeliveryRoot, handle, nonce string) (returnErr error)

RevertExecution records a provider exec failure. It demotes only a ready mint generation created by this exact ticket; an older resumed identity is retained.

func RunConformance 

func RunConformance(t *testing.T, b Backend)

RunConformance exercises declared capabilities identically for any backend and requires stable unsupported / unknown for the rest. The Inspect-unknown injection and typo-refusal cases always run so tmux/cmux/ghostty can reuse them unchanged.

func ValidateAdapterCapabilities 

func ValidateAdapterCapabilities(adapter HarnessAdapter, capabilities AdapterCapabilities) error

func ValidateAdapterPlan 

func ValidateAdapterPlan(adapter HarnessAdapter, plan AgentPlan) error

func ValidateCommittedConfig 

func ValidateCommittedConfig(adapter HarnessAdapter, request CommittedConfigRequest) error

func ValidateExecutionEnvelope 

func ValidateExecutionEnvelope(root *fsq.DeliveryRoot, ticket ExecutionTicket, envelope ExecutionEnvelope) error

func WriteBinding 

func WriteBinding(root *fsq.DeliveryRoot, lease *Lease, record BindingRecord) error

WriteBinding replaces the session binding. A live *Lease is required; there is no lease-free write path.

func WriteConversation 

func WriteConversation(root *fsq.DeliveryRoot, lease *Lease, record ConversationRecord) error

func WriteExecutionTicket 

func WriteExecutionTicket(root *fsq.DeliveryRoot, lease *Lease, ticket ExecutionTicket) error

func WriteJournal 

func WriteJournal(root *fsq.DeliveryRoot, lease *Lease, record LaunchJournal) error

Types

type AdapterCapabilities 

type AdapterCapabilities struct {
	Provider        string      `json:"provider"`
	Mode            AdapterMode `json:"mode"`
	Available       bool        `json:"available"`
	Executable      string      `json:"executable,omitempty"`
	ProviderVersion string      `json:"provider_version,omitempty"`
	Fresh           bool        `json:"fresh"`
	Resume          bool        `json:"resume"`
	Capture         bool        `json:"capture"`
	Reason          string      `json:"reason,omitempty"`
}

type AdapterMode 

type AdapterMode string
const (
	AdapterModeMint        AdapterMode = "mint"
	AdapterModeCapture     AdapterMode = "capture"
	AdapterModeUnsupported AdapterMode = "unsupported"
)

type AgentPlan 

type AgentPlan struct {
	Handle         string            `json:"handle"`
	Argv           []string          `json:"argv"`
	EnvOverlay     map[string]string `json:"env_overlay,omitempty"`
	Cwd            string            `json:"cwd"`
	AdapterMode    AdapterMode       `json:"adapter_mode"`
	ResumePolicy   ResumePolicy      `json:"resume_policy"`
	LaunchNonce    string            `json:"launch_nonce,omitempty"`
	ConversationID string            `json:"conversation_id,omitempty"`
	DynamicArgv    []DynamicArg      `json:"dynamic_argv,omitempty"`
}

func (AgentPlan) Validate 

func (a AgentPlan) Validate() error

Validate checks one backend-ready agent plan independently of its parent.

type AgentReconcileResult 

type AgentReconcileResult struct {
	Handle                  string                  `json:"handle"`
	Code                    int                     `json:"code"`
	ConversationDisposition ConversationDisposition `json:"conversation_disposition"`
	Reason                  string                  `json:"reason"`
}

type ArbitraryCommandGrant 

type ArbitraryCommandGrant struct {
	Name       string            `json:"name"`
	Argv       []string          `json:"argv"`
	EnvOverlay map[string]string `json:"env_overlay,omitempty"`
	Cwd        string            `json:"cwd"`
}

type Backend 

type Backend interface {
	Detect() DetectResult
	Create(CreateRequest) (CreateResult, error)
	Inspect(InspectRequest) (InspectResult, error)
	Close(CloseRequest) (CloseResult, error)
}

Backend is the launcher contract from #480 v1.1 §6. Attach-or-recreate is an orchestration decision from Inspect evidence, never a backend method.

type BackendFocuser 

type BackendFocuser interface {
	Focus(FocusRequest) (FocusResult, error)
}

BackendFocuser is the optional managed attach surface. It stays separate from the four-method backend floor: plan_only backends do not own resources, while a managed profile that declares CapFocus must implement this seam.

type BackendReclaimer 

type BackendReclaimer interface {
	Reclaim(ReclaimRequest) (ReclaimResult, error)
}

BackendReclaimer is the optional recovery surface for a managed resource that may have been created before its authoritative binding was committed. It must inspect only the exact journal generation and must not mutate it.

type BindingRecord 

type BindingRecord struct {
	Version          int                 `json:"version"`
	Backend          string              `json:"backend"`
	HostIdentity     string              `json:"host_identity"`
	InstanceIdentity string              `json:"instance_identity"`
	Profile          string              `json:"profile"`
	LaunchNonce      string              `json:"launch_nonce"`
	Resources        ResourceIdentitySet `json:"resources"`
}

BindingRecord is disposable runtime state. It never identifies an AMQ session and never grants authority to execute a plan.

func LoadBinding 

func LoadBinding(root *fsq.DeliveryRoot) (BindingRecord, error)

func (BindingRecord) Validate 

func (record BindingRecord) Validate() error

type Capability 

type Capability string
const (
	// CapPlanOnly is the commands-backend floor: emit an executable plan,
	// never claim a managed terminal resource.
	CapPlanOnly Capability = "plan_only"
	// CapCreate is managed layout creation (writes a binding).
	CapCreate Capability = "create"
	// CapInspect means the backend can distinguish present from absent.
	CapInspect Capability = "inspect"
	// CapClose means the backend can dispose of a resource it owns.
	CapClose Capability = "close"
	// CapFocus means the backend can attach to a present layout.
	CapFocus Capability = "focus"
	// CapReclaim means the backend can prove the state of a journaled create.
	CapReclaim Capability = "reclaim"
)

type CaptureEvidence 

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

CaptureEvidence is an observer-correlated envelope around provider-owned evidence. Source names the provider protocol event; LaunchNonce binds the observation to the launch generation held by the caller's session lease.

func ParseCodexThreadStartedEvidence 

func ParseCodexThreadStartedEvidence(raw []byte, launchNonce string, activeElsewhere bool) (CaptureEvidence, error)

ParseCodexThreadStartedEvidence verifies the provider event shape and binds the observation to the launch generation of the channel that received it. It does not scan the Codex session store or accept newest-file evidence.

type CaptureEvidenceSource 

type CaptureEvidenceSource string
const CodexThreadStartedV2 CaptureEvidenceSource = "codex_app_server_thread_started_v2"

type CaptureReason 

type CaptureReason string
const (
	CaptureReasonAdapterMintsIdentity CaptureReason = "adapter_mints_identity"
	CaptureReasonEvidenceMissing      CaptureReason = "evidence_missing"
	CaptureReasonEvidenceAmbiguous    CaptureReason = "evidence_ambiguous"
	CaptureReasonProviderMismatch     CaptureReason = "provider_mismatch"
	CaptureReasonProviderVersion      CaptureReason = "provider_version_mismatch"
	CaptureReasonLaunchNonceMismatch  CaptureReason = "launch_nonce_mismatch"
	CaptureReasonEvidenceSource       CaptureReason = "evidence_source_unsupported"
	CaptureReasonEvidenceUnverified   CaptureReason = "evidence_unverified"
	CaptureReasonInvalidIdentity      CaptureReason = "invalid_conversation_identity"
	CaptureReasonConversationActive   CaptureReason = "conversation_active_elsewhere"
)

type CaptureRequest 

type CaptureRequest struct {
	LaunchNonce             string
	ExpectedProviderVersion string
	Final                   bool
	Evidence                []CaptureEvidence
}

type CaptureResult 

type CaptureResult struct {
	State    CaptureState
	Identity ConversationIdentity
	Degraded bool
	Reason   CaptureReason
}

func (CaptureResult) CanPersist 

func (result CaptureResult) CanPersist() bool

type CaptureState 

type CaptureState string
const (
	CapturePending     CaptureState = "pending"
	CaptureReady       CaptureState = "ready"
	CaptureStale       CaptureState = "stale"
	CaptureUnsupported CaptureState = "unsupported"
)

type ClaudeAdapter 

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

func NewClaudeAdapter 

func NewClaudeAdapter(executable string) *ClaudeAdapter

func (*ClaudeAdapter) Capabilities 

func (adapter *ClaudeAdapter) Capabilities(ctx context.Context) AdapterCapabilities

func (*ClaudeAdapter) CaptureIdentity 

func (adapter *ClaudeAdapter) CaptureIdentity(CaptureRequest) CaptureResult

func (*ClaudeAdapter) CommittedEnvKeys 

func (adapter *ClaudeAdapter) CommittedEnvKeys() []string

func (*ClaudeAdapter) Mode 

func (adapter *ClaudeAdapter) Mode() AdapterMode

func (*ClaudeAdapter) Name 

func (adapter *ClaudeAdapter) Name() string

func (*ClaudeAdapter) PlanFresh 

func (adapter *ClaudeAdapter) PlanFresh(request PlanRequest) (AgentPlan, error)

func (*ClaudeAdapter) PlanResume 

func (adapter *ClaudeAdapter) PlanResume(request ResumeRequest) (AgentPlan, error)

func (*ClaudeAdapter) ValidateCommittedConfig 

func (adapter *ClaudeAdapter) ValidateCommittedConfig(request CommittedConfigRequest) error

type CloseRequest 

type CloseRequest struct {
	Binding BindingRecord
	Root    *fsq.DeliveryRoot
}

type CloseResult 

type CloseResult struct {
	Outcome Outcome `json:"outcome"`
	Reason  string  `json:"reason,omitempty"`
}

type CodexAdapter 

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

func NewCodexAdapter 

func NewCodexAdapter(executable string) *CodexAdapter

func (*CodexAdapter) Capabilities 

func (adapter *CodexAdapter) Capabilities(ctx context.Context) AdapterCapabilities

func (*CodexAdapter) CaptureIdentity 

func (adapter *CodexAdapter) CaptureIdentity(request CaptureRequest) CaptureResult

func (*CodexAdapter) CommittedEnvKeys 

func (adapter *CodexAdapter) CommittedEnvKeys() []string

func (*CodexAdapter) Mode 

func (adapter *CodexAdapter) Mode() AdapterMode

func (*CodexAdapter) Name 

func (adapter *CodexAdapter) Name() string

func (*CodexAdapter) PlanFresh 

func (adapter *CodexAdapter) PlanFresh(request PlanRequest) (AgentPlan, error)

func (*CodexAdapter) PlanResume 

func (adapter *CodexAdapter) PlanResume(request ResumeRequest) (AgentPlan, error)

func (*CodexAdapter) ValidateCommittedConfig 

func (adapter *CodexAdapter) ValidateCommittedConfig(request CommittedConfigRequest) error

type Commands 

type Commands struct{}

Commands is the plan_only backend. It emits exact coop-exec invocations from a prebuilt plan and never owns a terminal resource.

func (Commands) Close 

func (Commands) Close(CloseRequest) (CloseResult, error)

func (Commands) Create 

func (Commands) Create(req CreateRequest) (CreateResult, error)

func (Commands) Detect 

func (Commands) Detect() DetectResult

func (Commands) Inspect 

func (Commands) Inspect(InspectRequest) (InspectResult, error)

type CommittedConfigRequest 

type CommittedConfigRequest struct {
	ProjectRoot string
	Cwd         string
	Args        []string
	EnvOverlay  map[string]string
}

CommittedConfigRequest is the static, repository-controlled subset of an adapter plan. Validation does not require the provider executable to be installed, so setup can reject unsafe committed carriers on any machine.

type CommittedConfigValidator 

type CommittedConfigValidator interface {
	ValidateCommittedConfig(CommittedConfigRequest) error
}

CommittedConfigValidator is implemented by adapters that can own committed argv, environment, and cwd validation independently from live capability probing and per-launch identity generation.

type ConfigAuthorityConflictError 

type ConfigAuthorityConflictError struct {
	Path  string
	Field string
}

func (*ConfigAuthorityConflictError) Error 

func (e *ConfigAuthorityConflictError) Error() string

type ConfirmRebindFunc 

type ConfirmRebindFunc func(BindingRecord, bool) (RebindDisposition, bool, error)

type ConfirmTrustFunc 

type ConfirmTrustFunc func(Plan, string) (bool, error)

type ConversationDisposition 

type ConversationDisposition string
const (
	DispositionResumed         ConversationDisposition = "resumed"
	DispositionFresh           ConversationDisposition = "fresh"
	DispositionFreshAfterStale ConversationDisposition = "fresh_after_stale"
	DispositionDisabled        ConversationDisposition = "disabled"
	DispositionUnsupported     ConversationDisposition = "unsupported"
	DispositionDegraded        ConversationDisposition = "degraded"
	DispositionActionRequired  ConversationDisposition = "action_required"
)

type ConversationExecutionEvidence 

type ConversationExecutionEvidence struct {
	Backend        string  `json:"backend"`
	Profile        string  `json:"profile"`
	Outcome        Outcome `json:"outcome"`
	LaunchNonce    string  `json:"launch_nonce"`
	ConversationID string  `json:"conversation_id,omitempty"`
}

ConversationExecutionEvidence records the managed backend result that proves a planned agent process started. It does not grant execution authority; it prevents a minted identity from becoming resumable from plan output alone.

type ConversationIdentity 

type ConversationIdentity struct {
	Provider string `json:"provider"`
	ID       string `json:"id"`
}

type ConversationRecord 

type ConversationRecord struct {
	Version           int                            `json:"version"`
	Handle            string                         `json:"handle"`
	State             CaptureState                   `json:"state"`
	Identity          ConversationIdentity           `json:"identity,omitempty"`
	ProviderVersion   string                         `json:"provider_version,omitempty"`
	LaunchNonce       string                         `json:"launch_nonce"`
	ExecutionEvidence *ConversationExecutionEvidence `json:"execution_evidence,omitempty"`
	Reason            CaptureReason                  `json:"reason,omitempty"`
}

ConversationRecord is provider-qualified runtime state for one (session, handle). It carries no execution authority.

func LoadConversation 

func LoadConversation(root *fsq.DeliveryRoot, handle string) (ConversationRecord, error)

func (ConversationRecord) Validate 

func (record ConversationRecord) Validate() error

type CreateRequest 

type CreateRequest struct {
	ProjectRoot string
	Session     string
	Plan        Plan
	AMQPath     string
	Root        *fsq.DeliveryRoot
}

type CreateResult 

type CreateResult struct {
	Outcome        Outcome `json:"outcome"`
	ActionRequired bool    `json:"action_required"`
	Profile        string  `json:"profile,omitempty"`
	// Binding is a managed backend's candidate runtime record. The
	// reconciliation engine is the only layer allowed to persist it under the
	// session lease. plan_only backends leave it empty.
	Binding         BindingRecord                `json:"binding,omitempty"`
	CaptureEvidence map[string][]CaptureEvidence `json:"-"`
	Commands        []EmittedCommand             `json:"commands,omitempty"`
	Plan            []byte                       `json:"plan,omitempty"`
	Reason          string                       `json:"reason,omitempty"`
}

type DefinitePreCreateError 

type DefinitePreCreateError struct{ Err error }

DefinitePreCreateError means Create proved that it made no backend resource. All other Create errors are uncertain and retain the journal for recovery.

func (*DefinitePreCreateError) Error 

func (e *DefinitePreCreateError) Error() string

func (*DefinitePreCreateError) Unwrap 

func (e *DefinitePreCreateError) Unwrap() error

type Degradation 

type Degradation struct {
	Capability Capability `json:"capability"`
	Reason     string     `json:"reason"`
}

type DetectResult 

type DetectResult struct {
	Available        bool          `json:"available"`
	Profile          Profile       `json:"profile"`
	HostIdentity     string        `json:"host_identity,omitempty"`
	InstanceIdentity string        `json:"instance_identity,omitempty"`
	Effective        []Capability  `json:"effective"`
	Degradations     []Degradation `json:"degradations,omitempty"`
}

func (DetectResult) Validate 

func (d DetectResult) Validate() error

type DynamicArg 

type DynamicArg struct {
	Index int            `json:"index"`
	Kind  DynamicArgKind `json:"kind"`
}

DynamicArg marks one runtime-generated argv value. Unmarked argv values are always trust-bearing. Version 1 has no dynamic environment slots; adding them requires a plan schema version change when an adapter needs one.

type DynamicArgKind 

type DynamicArgKind string
const (
	DynamicArgLaunchNonce    DynamicArgKind = "launch_nonce"
	DynamicArgConversationID DynamicArgKind = "conversation_id"
)

type EmittedCommand 

type EmittedCommand struct {
	Handle      string            `json:"handle"`
	Argv        []string          `json:"argv"`
	Cwd         string            `json:"cwd"`
	Env         map[string]string `json:"env,omitempty"`
	LaunchNonce string            `json:"launch_nonce,omitempty"`
	Line        string            `json:"line"`
}

type ExecutionEnvelope 

type ExecutionEnvelope struct {
	Cwd, AMQExecutable, ProviderExecutable string
	TargetArgv, Environment                []string
}

type ExecutionState 

type ExecutionState string
const (
	ExecutionPending        ExecutionState = "pending"
	ExecutionSpawnAttempted ExecutionState = "spawn_attempted"
	ExecutionAcknowledged   ExecutionState = "acknowledged"
)

type ExecutionTicket 

type ExecutionTicket struct {
	Version int `json:"version"`

	Handle         string      `json:"handle"`
	LaunchNonce    string      `json:"launch_nonce"`
	Mode           AdapterMode `json:"mode"`
	Provider       string      `json:"provider"`
	ConversationID string      `json:"conversation_id,omitempty"`

	ProjectRoot     string `json:"project_root"`
	ProjectIdentity string `json:"project_identity"`
	SessionRoot     string `json:"session_root"`
	SessionIdentity string `json:"session_identity"`
	Cwd             string `json:"cwd"`
	CwdIdentity     string `json:"cwd_identity"`

	ProviderExecutable         string `json:"provider_executable"`
	ProviderExecutableIdentity string `json:"provider_executable_identity"`
	AMQExecutable              string `json:"amq_executable"`
	AMQExecutableIdentity      string `json:"amq_executable_identity"`

	TargetArgv []string          `json:"target_argv"`
	TargetEnv  map[string]string `json:"target_env,omitempty"`
	EnvDigest  string            `json:"env_digest"`
	State      ExecutionState    `json:"state"`
	Reason     string            `json:"reason,omitempty"`
}

ExecutionTicket is the durable, nonce-bound handoff between planning and the process which actually starts a command. It is evidence, not execution authority: writes require the live launch lease and the matching handle lock.

func CompareAndSwapExecutionTicket 

func CompareAndSwapExecutionTicket(root *fsq.DeliveryRoot, lease *Lease, handle string, expected ExecutionState, next ExecutionState, reason string) (ExecutionTicket, error)

CompareAndSwapExecutionTicket changes one ticket state while the caller's live lease and handle lock exclude competing launch/reconcile operations.

func LoadExecutionTicket 

func LoadExecutionTicket(root *fsq.DeliveryRoot, handle string) (ExecutionTicket, error)

func NewExecutionTicket 

func NewExecutionTicket(request ExecutionTicketRequest) (ExecutionTicket, error)

NewExecutionTicket canonicalizes every filesystem input and snapshots its physical identity before the ticket can be persisted.

func PrepareExecution 

func PrepareExecution(root *fsq.DeliveryRoot, handle, nonce string, envelope ExecutionEnvelope) (ticket ExecutionTicket, returnErr error)

PrepareExecution performs the final envelope check and durable execution acknowledgement under the exact launch nonce and handle lock.

func (ExecutionTicket) Validate 

func (ticket ExecutionTicket) Validate() error

type ExecutionTicketRequest 

type ExecutionTicketRequest struct {
	Handle, LaunchNonce               string
	Mode                              AdapterMode
	Provider, ConversationID          string
	ProjectRoot, SessionRoot, Cwd     string
	ProviderExecutable, AMQExecutable string
	TargetArgv                        []string
	TargetEnv                         map[string]string
	State                             ExecutionState
	Reason                            string
}

type FocusRequest 

type FocusRequest struct {
	Binding BindingRecord
	Root    *fsq.DeliveryRoot
}

type FocusResult 

type FocusResult struct {
	Outcome Outcome `json:"outcome"`
	Reason  string  `json:"reason,omitempty"`
}

type HarnessAdapter 

type HarnessAdapter interface {
	Name() string
	Mode() AdapterMode
	CommittedEnvKeys() []string
	Capabilities(context.Context) AdapterCapabilities
	PlanFresh(PlanRequest) (AgentPlan, error)
	PlanResume(ResumeRequest) (AgentPlan, error)
	CaptureIdentity(CaptureRequest) CaptureResult
}

HarnessAdapter owns conversation identity and produces backend-ready plans. It must not create, inspect, focus, or close terminal resources.

type HolderIdentity 

type HolderIdentity struct {
	PID          int    `json:"pid"`
	ProcessStart string `json:"process_start,omitempty"`
	BootID       string `json:"boot_id,omitempty"`
}

HolderIdentity is the wake-lock idiom: pid plus kernel start token and boot id. A lease is stale only when that holder is proven dead; unverified fails closed.

type InspectRequest 

type InspectRequest struct {
	Binding BindingRecord
	Root    *fsq.DeliveryRoot
}

type InspectResult 

type InspectResult struct {
	Status         InspectStatus `json:"status"`
	Evidence       string        `json:"evidence"`
	ActionRequired bool          `json:"action_required"`
}

type InspectStatus 

type InspectStatus string
const (
	InspectPresent InspectStatus = "present"
	InspectAbsent  InspectStatus = "absent"
	InspectUnknown InspectStatus = "unknown"
)

type JournalPhase 

type JournalPhase string
const (
	JournalIntent  JournalPhase = "intent"
	JournalCreated JournalPhase = "created"
)

type LaunchJournal 

type LaunchJournal struct {
	Version          int                    `json:"version"`
	Phase            JournalPhase           `json:"phase"`
	ProjectIdentity  string                 `json:"project_identity"`
	RootIdentity     string                 `json:"root_identity"`
	ProjectPhysical  string                 `json:"project_physical_identity,omitempty"`
	RootPhysical     string                 `json:"root_physical_identity,omitempty"`
	Session          string                 `json:"session"`
	Backend          string                 `json:"backend"`
	Profile          string                 `json:"profile"`
	HostIdentity     string                 `json:"host_identity"`
	InstanceIdentity string                 `json:"instance_identity"`
	RosterDigest     string                 `json:"roster_digest"`
	PlanDigest       string                 `json:"plan_digest"`
	LaunchNonce      string                 `json:"launch_nonce"`
	CreatedAt        time.Time              `json:"created_at"`
	Plan             Plan                   `json:"plan"`
	Agents           []AgentReconcileResult `json:"agents"`
	Conversations    []ConversationRecord   `json:"conversations"`
	Binding          *BindingRecord         `json:"binding,omitempty"`
}

LaunchJournal is a recovery transaction, not a launcher binding. A resource recorded here is never owned or adoptable until a backend proves its live identity or a matching authoritative binding already exists.

func LoadJournal 

func LoadJournal(root *fsq.DeliveryRoot) (LaunchJournal, error)

func NewLaunchJournal 

func NewLaunchJournal(request ReconcileRequest, backend string, detect DetectResult, plan Plan, planDigest, nonce string, agents []AgentReconcileResult, conversations []ConversationRecord, now time.Time) (LaunchJournal, error)

func (LaunchJournal) Validate 

func (record LaunchJournal) Validate() error

func (LaunchJournal) ValidateRequest 

func (record LaunchJournal) ValidateRequest(request ReconcileRequest) error

type LayoutIntent 

type LayoutIntent struct {
	Type string `json:"type"`
}

type Lease 

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

Lease is a live, process-local capability. Unexported fields keep a forged value from authorizing WriteBinding.

func AcquireLease 

func AcquireLease(root *fsq.DeliveryRoot, nonce string) (*Lease, error)

func (*Lease) LaunchNonce 

func (l *Lease) LaunchNonce() string

func (*Lease) LockHandles 

func (l *Lease) LockHandles(handles ...string) error

func (*Lease) LockedHandles 

func (l *Lease) LockedHandles() []string

func (*Lease) Release 

func (l *Lease) Release() error

type LeaseHeldError 

type LeaseHeldError struct {
	Nonce    string
	Evidence string
}

func (*LeaseHeldError) Error 

func (e *LeaseHeldError) Error() string

type LeaseInspection 

type LeaseInspection struct {
	State    LeaseState
	Evidence string
	Holder   HolderIdentity
	Nonce    string
}

func InspectLease 

func InspectLease(root *fsq.DeliveryRoot) (LeaseInspection, error)

type LeaseState 

type LeaseState string
const (
	LeaseMissing    LeaseState = "missing"
	LeaseValid      LeaseState = "valid"
	LeaseStale      LeaseState = "stale"
	LeaseUnverified LeaseState = "unverified"
)

type LeaseUnverifiedError 

type LeaseUnverifiedError struct {
	Evidence string
}

func (*LeaseUnverifiedError) Error 

func (e *LeaseUnverifiedError) Error() string

type LocalConfig 

type LocalConfig struct {
	Schema             int      `json:"schema"`
	LauncherPreference []string `json:"launcher_preference"`
}

LocalConfig is deliberately preference-only. Execution authority, roster, environment, cwd, bypass arguments, and session selection do not belong in this in-worktree file, even when the file is already tracked.

func ParseLocalConfig 

func ParseLocalConfig(path string, data []byte) (LocalConfig, error)

func (LocalConfig) Validate 

func (cfg LocalConfig) Validate() error

type Outcome 

type Outcome string
const (
	OutcomeCreated         Outcome = "created"
	OutcomeCommandsEmitted Outcome = "commands_emitted"
	OutcomeActionRequired  Outcome = "action_required"
	OutcomeUnsupported     Outcome = "unsupported"
	OutcomeAttached        Outcome = "attached"
	OutcomeClosed          Outcome = "closed"
)

type Plan 

type Plan struct {
	Version int         `json:"version"`
	Agents  []AgentPlan `json:"agents"`
}

Plan is the public, backend-independent execution contract. Nonce and ConversationID are per-launch values and are deliberately not trusted.

func DecodePlan 

func DecodePlan(data []byte) (Plan, error)

func (Plan) SemanticDigest 

func (p Plan) SemanticDigest() (string, error)

SemanticDigest hashes the adapter-normalized static execution template. Fresh and resume argv shapes have different digests because only the resume shape carries a conversation slot; each shape therefore requires trust once.

func (Plan) Validate 

func (p Plan) Validate() error

type PlanRequest 

type PlanRequest struct {
	Handle        string
	ProjectRoot   string
	Cwd           string
	LaunchNonce   string
	ResumePolicy  ResumePolicy
	CommittedArgs []string
	BypassArgs    []string
	EnvOverlay    map[string]string
}

type Profile 

type Profile struct {
	Backend      string       `json:"backend"`
	Platform     string       `json:"platform"`
	VersionRange string       `json:"version_range"`
	Version      int          `json:"version"`
	Capabilities []Capability `json:"capabilities"`
}

Profile is the versioned static maximum envelope for one (backend, platform, version-range). Conformance graduates this identity; Detect reports the runtime subset separately so the envelope cannot shrink to dodge a failing test.

func CommandsProfile 

func CommandsProfile() Profile

func TmuxProfile 

func TmuxProfile() Profile

func (Profile) Has 

func (p Profile) Has(c Capability) bool

func (Profile) Identity 

func (p Profile) Identity() string

type ProjectAgentConfig 

type ProjectAgentConfig struct {
	Handle       string            `json:"handle"`
	Adapter      string            `json:"adapter"`
	Command      []string          `json:"command"`
	Env          map[string]string `json:"env,omitempty"`
	Cwd          string            `json:"cwd,omitempty"`
	ResumePolicy ResumePolicy      `json:"resume_policy"`
}

type ProjectConfig 

type ProjectConfig struct {
	Schema         int                  `json:"schema"`
	DefaultSession string               `json:"default_session"`
	Agents         []ProjectAgentConfig `json:"agents"`
	Layout         LayoutIntent         `json:"layout"`
}

func ParseProjectConfig 

func ParseProjectConfig(data []byte) (ProjectConfig, error)

func (ProjectConfig) Validate 

func (cfg ProjectConfig) Validate() error

type RebindDisposition 

type RebindDisposition string
const (
	RebindClose RebindDisposition = "close"
	RebindLeave RebindDisposition = "leave"
)

type ReclaimRequest 

type ReclaimRequest struct {
	Context context.Context
	Journal LaunchJournal
	Root    *fsq.DeliveryRoot
}

type ReclaimResult 

type ReclaimResult struct {
	Status          ReclaimStatus                `json:"status"`
	Evidence        string                       `json:"evidence"`
	Resources       []ResourceIdentity           `json:"resources"`
	Binding         BindingRecord                `json:"binding,omitempty"`
	CaptureEvidence map[string][]CaptureEvidence `json:"-"`
}

type ReclaimStatus 

type ReclaimStatus string
const (
	ReclaimAbsent     ReclaimStatus = "absent"
	ReclaimAdoptable  ReclaimStatus = "adoptable"
	ReclaimIncomplete ReclaimStatus = "incomplete"
	ReclaimUnknown    ReclaimStatus = "unknown"
	ReclaimForeign    ReclaimStatus = "foreign"
)

type ReconcileRequest 

type ReconcileRequest struct {
	Context            context.Context
	ProjectRoot        string
	Session            string
	AMQPath            string
	Root               *fsq.DeliveryRoot
	Config             ProjectConfig
	Launcher           string
	Preferences        []string
	Backends           map[string]Backend
	Adapters           map[string]HarnessAdapter
	TrustStore         *TrustStore
	ConfirmTrust       ConfirmTrustFunc
	ConfirmRebind      ConfirmRebindFunc
	Fresh              bool
	AllowFreshFallback bool
	ResumeOnly         bool
	Rebind             bool
	HostIdentity       string
	CrashHook          func(string) error
}

type ReconcileResult 

type ReconcileResult struct {
	Session        string                 `json:"session"`
	Backend        string                 `json:"backend"`
	Outcome        Outcome                `json:"outcome"`
	AggregateCode  int                    `json:"aggregate_code"`
	Reason         string                 `json:"reason"`
	Agents         []AgentReconcileResult `json:"agents"`
	Commands       []EmittedCommand       `json:"commands"`
	Plan           *Plan                  `json:"plan"`
	SemanticDigest string                 `json:"semantic_digest"`
	Recovery       *RecoveryReport        `json:"recovery"`
}

func Reconcile 

func Reconcile(request ReconcileRequest) (result ReconcileResult, returnErr error)

type RecoveryReport 

type RecoveryReport struct {
	Status    ReclaimStatus      `json:"status"`
	Evidence  string             `json:"evidence"`
	Resources []ResourceIdentity `json:"resources"`
}

type ResourceIdentity 

type ResourceIdentity struct {
	OpaqueID string `json:"opaque_id"`
	Agent    string `json:"agent,omitempty"`
}

type ResourceIdentitySet 

type ResourceIdentitySet struct {
	Version   int                `json:"version"`
	Resources []ResourceIdentity `json:"resources"`
}

type ResumePolicy 

type ResumePolicy string
const (
	ResumeEnabled  ResumePolicy = "resume"
	ResumeFresh    ResumePolicy = "fresh"
	ResumeDisabled ResumePolicy = "disabled"
)

type ResumeRequest 

type ResumeRequest struct {
	PlanRequest
	Conversation ConversationIdentity
}

type TmuxBackend 

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

TmuxBackend manages one deterministic tmux session per AMQ project/session. The socket namespace is stable across tmux server restarts; resource IDs are still live tmux IDs and are never reconstructed from display names.

func NewTmuxBackend 

func NewTmuxBackend(binary string) *TmuxBackend

func (*TmuxBackend) Close 

func (b *TmuxBackend) Close(req CloseRequest) (CloseResult, error)

func (*TmuxBackend) Create 

func (b *TmuxBackend) Create(req CreateRequest) (CreateResult, error)

func (*TmuxBackend) Detect 

func (b *TmuxBackend) Detect() DetectResult

func (*TmuxBackend) Focus 

func (b *TmuxBackend) Focus(req FocusRequest) (FocusResult, error)

func (*TmuxBackend) Inspect 

func (b *TmuxBackend) Inspect(req InspectRequest) (InspectResult, error)

func (*TmuxBackend) Reclaim 

func (b *TmuxBackend) Reclaim(req ReclaimRequest) (ReclaimResult, error)

type TrustRecord 

type TrustRecord struct {
	Version           int                     `json:"version"`
	ProjectIdentity   string                  `json:"project_identity"`
	SemanticDigest    string                  `json:"semantic_digest"`
	BypassArgs        map[string][]string     `json:"bypass_args,omitempty"`
	ArbitraryCommands []ArbitraryCommandGrant `json:"arbitrary_commands,omitempty"`
}

TrustRecord contains all local execution authority for one project. Replace overwrites the prior digest, so a semantic change invalidates every prior bypass argument and arbitrary-command grant.

type TrustStore 

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

func OpenTrustStore 

func OpenTrustStore(userStateDir, projectRoot string) (*TrustStore, error)

func (*TrustStore) LoadForDigest 

func (store *TrustStore) LoadForDigest(digest string) (TrustRecord, bool, error)

LoadForDigest returns no record when the plan changed. Malformed, unreadable, cross-project, or overly permissive state is an error and must fail closed.

func (*TrustStore) Path 

func (store *TrustStore) Path() string

func (*TrustStore) Replace 

func (store *TrustStore) Replace(record TrustRecord) error

Replace atomically installs the only active authority record for a project.

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.