runtimecontrol

package
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package runtimecontrol owns replacement of one active Coding Runtime.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrBusy means an operation or Runtime replacement is already active.
	ErrBusy = errors.New("coding runtime control: busy")
	// ErrClosed means the Controller no longer owns a Runtime.
	ErrClosed = errors.New("coding runtime control: closed")
	// ErrDetached means replacement and rollback both failed.
	ErrDetached = errors.New("coding runtime control: detached")
	// ErrInvalid means construction or replacement input is invalid.
	ErrInvalid = errors.New("coding runtime control: invalid input")
)

Functions

This section is empty.

Types

type Controller 

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

Controller owns one active Runtime and the process-local model/permission overrides used for later Runtime replacements.

func New 

func New(ctx context.Context, options coding.OpenOptions) (*Controller, error)

New opens the initial Runtime and returns its lifecycle Controller.

func (*Controller) ApplyTeamIntegration 

func (c *Controller) ApplyTeamIntegration(
	ctx context.Context,
	approval coding.TeamIntegrationApproval,
) (coding.TeamIntegrationResult, error)

ApplyTeamIntegration applies one exact process-local preview approval.

func (*Controller) Cancel 

func (c *Controller) Cancel() error

Cancel requests cancellation of the active Runtime operation.

func (*Controller) CancelSubagent 

func (c *Controller) CancelSubagent(ctx context.Context, childSessionID string) error

CancelSubagent requests cancellation of one child owned by the selected Session.

func (*Controller) Capabilities 

func (c *Controller) Capabilities() ai.Capabilities

Capabilities returns the current bound model's declared capabilities.

func (*Controller) CleanupTeam 

func (c *Controller) CleanupTeam(
	ctx context.Context,
	request coding.TeamCleanupRequest,
) (coding.TeamCleanupResult, error)

CleanupTeam performs one exact revision-bound non-force cleanup transaction.

func (*Controller) Close 

func (c *Controller) Close(ctx context.Context) error

Close closes the owned Runtime once. It waits for an in-flight replacement and bounds cleanup independently from cancellation of the caller context.

func (*Controller) Compact 

func (c *Controller) Compact(
	ctx context.Context,
	request coding.CompactionRequest,
) iter.Seq2[coding.Event, error]

Compact confirms and executes a manual compaction.

func (*Controller) Config 

func (c *Controller) Config() config.Config

Config returns the effective process-local configuration. The value does not grant mutation of the Controller or persistence layers.

func (*Controller) ConfirmTeam 

func (c *Controller) ConfirmTeam(
	ctx context.Context,
	confirmation coding.TeamConfirmation,
) (coding.TeamReference, error)

ConfirmTeam admits one exact proposal and explicit clean/HEAD-only choice.

func (*Controller) Continue 

func (c *Controller) Continue(ctx context.Context) iter.Seq2[coding.Event, error]

Continue delegates recovery of an already-open pending interaction.

func (*Controller) DeclineTeam 

func (c *Controller) DeclineTeam(ctx context.Context, proposalID string) error

DeclineTeam consumes one exact proposal under the current Runtime lease.

func (*Controller) Detached 

func (c *Controller) Detached() bool

Detached reports whether replacement and rollback both failed.

func (*Controller) DiscoverTeamRecovery 

func (c *Controller) DiscoverTeamRecovery(
	ctx context.Context,
) ([]coding.TeamRecoveryCandidate, error)

DiscoverTeamRecovery returns fresh read-only retained Team candidates.

func (*Controller) FollowUp 

func (c *Controller) FollowUp(messages ...ai.Message) error

FollowUp queues messages after the active model invocation.

func (*Controller) ForkSession 

func (c *Controller) ForkSession(ctx context.Context, entryID string) error

ForkSession creates a new Session from one node and replaces the current Runtime with it while preserving the effective process-local model.

func (*Controller) GenerateTeamProposal 

func (c *Controller) GenerateTeamProposal(
	ctx context.Context,
	prompt coding.TeamProposalPrompt,
) (coding.TeamProposal, error)

GenerateTeamProposal runs one constrained proposal operation under the current Runtime lease.

func (*Controller) InspectSubagent 

func (c *Controller) InspectSubagent(
	ctx context.Context,
	childSessionID string,
) (subagent.Detail, error)

InspectSubagent loads one child owned by the currently selected Session.

func (*Controller) InspectSubagentState 

func (c *Controller) InspectSubagentState(
	ctx context.Context,
	childSessionID string,
) (coding.State, error)

InspectSubagentState loads the ordinary Session State for one child.

func (*Controller) InspectTeamWorkerState 

func (c *Controller) InspectTeamWorkerState(
	ctx context.Context,
	target coding.TeamWorkerTarget,
) (coding.State, error)

InspectTeamWorkerState reconstructs one exact terminal Worker State.

func (*Controller) ListAgentProfiles 

func (c *Controller) ListAgentProfiles(ctx context.Context) (coding.AgentLibrary, error)

ListAgentProfiles returns the content-safe Agent Library for the selected Runtime. It is optional on runtimeInstance so older embedders retain their existing Runtime contract while current Coding runtimes can expose dynamic definition metadata to the TUI.

func (*Controller) ListSessionSummaries 

func (c *Controller) ListSessionSummaries(ctx context.Context) ([]SessionSummary, error)

ListSessionSummaries returns current-Workspace conversations with bounded Team recovery hints. It never opens a Runtime, child Session, Team lease, scheduler, model, or Tool.

func (*Controller) ListSessions 

func (c *Controller) ListSessions(ctx context.Context) ([]session.Metadata, error)

ListSessions returns newest-first sessions owned by the current Workspace.

func (*Controller) ListSubagents 

func (c *Controller) ListSubagents(ctx context.Context) ([]subagent.Summary, error)

ListSubagents returns children owned by the currently selected Session.

func (*Controller) ListWorkspaceFiles 

func (c *Controller) ListWorkspaceFiles(
	ctx context.Context,
) (attachment.Snapshot, error)

ListWorkspaceFiles returns the current Runtime's bounded content-free file snapshot while holding its lease against replacement.

func (*Controller) Mode 

func (c *Controller) Mode() ModeState

Mode returns the configured and effective process-local operating mode.

func (*Controller) Model 

func (c *Controller) Model() ModelState

Model returns the effective process-local model selection.

func (*Controller) Models 

func (c *Controller) Models() []modelcatalog.Entry

Models returns the immutable local catalog entries available to the TUI.

func (*Controller) Navigate 

func (c *Controller) Navigate(
	ctx context.Context,
	entryID string,
	summarize bool,
) iter.Seq2[coding.Event, error]

Navigate moves the active leaf while holding the Controller lease through the complete event sequence.

func (*Controller) NewFullAccessConfirmation 

func (c *Controller) NewFullAccessConfirmation(
	ctx context.Context,
	update PermissionUpdate,
) (*FullAccessConfirmation, error)

NewFullAccessConfirmation issues a target-bound, one-shot capability for a user-confirmed Full Access transition. It performs no Runtime replacement. The caller must show its own explicit warning and call SetPermissions with the returned capability only after the user confirms that warning.

func (*Controller) NewSession 

func (c *Controller) NewSession(ctx context.Context) error

NewSession replaces the current Runtime with a new writable Session.

func (*Controller) ObserveEvents 

func (c *Controller) ObserveEvents() (coding.EventObservation, error)

ObserveEvents atomically attaches to the current Runtime's event stream. The short Controller lease prevents replacement between selecting the Runtime and creating its snapshot-backed subscription.

func (*Controller) ObserveTeamWorker 

func (c *Controller) ObserveTeamWorker(
	ctx context.Context,
	target coding.TeamWorkerTarget,
) (coding.EventObservation, error)

ObserveTeamWorker atomically attaches to one exact live Worker event stream.

func (*Controller) Permissions 

func (c *Controller) Permissions() PermissionState

Permissions returns the effective and configured permission profile.

func (*Controller) PlanDocumentPath 

func (c *Controller) PlanDocumentPath() (string, error)

PlanDocumentPath returns the current Session's private Plan display path.

func (*Controller) PrepareTeamIntegration 

func (c *Controller) PrepareTeamIntegration(
	ctx context.Context,
	request coding.TeamIntegrationRequest,
) (coding.TeamIntegrationPreview, error)

PrepareTeamIntegration creates process-local approval evidence for selected results.

func (*Controller) PreviewCompaction 

func (c *Controller) PreviewCompaction(ctx context.Context) (coding.CompactionPreview, error)

PreviewCompaction returns a point-in-time manual compaction plan.

func (*Controller) Prompt 

func (c *Controller) Prompt(
	ctx context.Context,
	messages ...ai.Message,
) iter.Seq2[coding.Event, error]

Prompt delegates one interaction while preventing Runtime replacement until iteration finishes.

func (*Controller) ReadPlanDocument 

func (c *Controller) ReadPlanDocument(ctx context.Context) (coding.PlanDocument, error)

ReadPlanDocument loads the current session plan file for review.

func (*Controller) ReadTeam 

func (c *Controller) ReadTeam(
	ctx context.Context,
	request coding.TeamReadRequest,
) (coding.TeamView, error)

ReadTeam returns a detached current Team view under the Runtime lease.

func (*Controller) RecoverTeamIntegration 

func (c *Controller) RecoverTeamIntegration(
	ctx context.Context,
	request coding.TeamIntegrationRecoveryRequest,
) (coding.TeamIntegrationResult, error)

RecoverTeamIntegration explicitly completes or rolls back one exact journal.

func (*Controller) RejectQuestion 

func (c *Controller) RejectQuestion(
	ctx context.Context,
	requestID string,
	schemaDigest string,
) iter.Seq2[coding.Event, error]

RejectQuestion delegates one explicit structured-input cancellation.

func (*Controller) RejectSubagentQuestion 

func (c *Controller) RejectSubagentQuestion(
	ctx context.Context,
	childSessionID string,
	requestID string,
	schemaDigest string,
) (coding.ChildControlState, error)

RejectSubagentQuestion records an explicit cancellation only on the target custom child question controller.

func (*Controller) RejectTeamIntegration 

func (c *Controller) RejectTeamIntegration(
	ctx context.Context,
	approval coding.TeamIntegrationApproval,
) error

RejectTeamIntegration consumes one exact preview without applying it.

func (*Controller) RejectTeamWorkerQuestion 

func (c *Controller) RejectTeamWorkerQuestion(
	ctx context.Context,
	target coding.TeamWorkerTarget,
	requestID string,
	schemaDigest string,
) (coding.TeamControlReference, error)

RejectTeamWorkerQuestion submits one exact Worker question rejection.

func (*Controller) Reload 

func (c *Controller) Reload(ctx context.Context) error

Reload refreshes Runtime resources without reloading the main configuration.

func (*Controller) Resolve 

func (c *Controller) Resolve(
	ctx context.Context,
	resolution approval.Resolution,
) iter.Seq2[coding.Event, error]

Resolve delegates one explicit approval resolution.

func (*Controller) ResolvePlanReview 

func (c *Controller) ResolvePlanReview(
	ctx context.Context,
	resolution planreview.Resolution,
) iter.Seq2[coding.Event, error]

ResolvePlanReview delegates one exact explicit Plan review decision.

func (*Controller) ResolveQuestion 

func (c *Controller) ResolveQuestion(
	ctx context.Context,
	resolution question.Resolution,
) iter.Seq2[coding.Event, error]

ResolveQuestion delegates one exact structured input response.

func (*Controller) ResolveSubagentApproval 

func (c *Controller) ResolveSubagentApproval(
	ctx context.Context,
	childSessionID string,
	resolution approval.Resolution,
) (coding.ChildControlState, error)

ResolveSubagentApproval sends one exact decision only to the target custom child approval controller. It never falls back to the parent controller.

func (*Controller) ResolveSubagentQuestion 

func (c *Controller) ResolveSubagentQuestion(
	ctx context.Context,
	childSessionID string,
	resolution question.Resolution,
) (coding.ChildControlState, error)

ResolveSubagentQuestion sends one structured response only to the target custom child question controller.

func (*Controller) ResolveTeamWorkerApproval 

func (c *Controller) ResolveTeamWorkerApproval(
	ctx context.Context,
	target coding.TeamWorkerTarget,
	resolution approval.Resolution,
) (coding.TeamControlReference, error)

ResolveTeamWorkerApproval submits one exact user approval resolution.

func (*Controller) ResolveTeamWorkerQuestion 

func (c *Controller) ResolveTeamWorkerQuestion(
	ctx context.Context,
	target coding.TeamWorkerTarget,
	resolution question.Resolution,
) (coding.TeamControlReference, error)

ResolveTeamWorkerQuestion submits exact structured answers for one Worker.

func (*Controller) ResolveWorkspaceFile 

func (c *Controller) ResolveWorkspaceFile(
	ctx context.Context,
	reference attachment.Reference,
) (attachment.Resolved, error)

ResolveWorkspaceFile resolves one selected file while holding the active Runtime lease against replacement.

func (*Controller) ResumeSession 

func (c *Controller) ResumeSession(ctx context.Context, id string) error

ResumeSession replaces the current Runtime with an existing Session.

func (*Controller) ResumeTeam 

func (c *Controller) ResumeTeam(
	ctx context.Context,
	teamID team.ID,
	decision coding.TeamResumeDecision,
) (coding.TeamReference, error)

ResumeTeam applies one explicit, revision-bound recovery decision.

func (*Controller) ReviseTeamProposal 

func (c *Controller) ReviseTeamProposal(
	ctx context.Context,
	proposalID string,
	feedback string,
) (coding.TeamProposal, error)

ReviseTeamProposal failure-atomically replaces one exact proposal under the current Runtime lease.

func (*Controller) RunAgent 

func (c *Controller) RunAgent(
	ctx context.Context,
	request coding.AgentRunRequest,
) (subagent.Result, error)

RunAgent directly starts one user-selected foreground Agent. It is an optional Runtime capability because historical embedders may expose only model-authored subagent dispatch.

func (*Controller) RunAgentEvents 

func (c *Controller) RunAgentEvents(
	ctx context.Context,
	request coding.AgentRunRequest,
) iter.Seq2[coding.Event, error]

RunAgentEvents streams an explicit user-selected Agent invocation while holding the Controller lease. This keeps session replacement from racing a live child and lets the interactive TUI render child controls immediately.

func (*Controller) SessionID 

func (c *Controller) SessionID() string

SessionID returns the currently selected Session ID.

func (*Controller) SetMode 

func (c *Controller) SetMode(ctx context.Context, mode coding.OperatingMode) error

SetMode changes the current Runtime and Controller state under one lease. It neither persists configuration nor writes Session history.

func (*Controller) SetPermissions 

func (c *Controller) SetPermissions(
	ctx context.Context,
	update PermissionUpdate,
	confirmations ...*FullAccessConfirmation,
) error

SetPermissions applies one permission update by replacing the current Runtime at an idle boundary. It never writes configuration files or Session history. A Full Access transition requires the opaque confirmation issued by NewFullAccessConfirmation; the variadic form preserves callers that only update sandboxed profiles.

func (*Controller) SetSkillEnabled 

func (c *Controller) SetSkillEnabled(
	ctx context.Context,
	id coding.SkillID,
	enabled bool,
) error

SetSkillEnabled persists one project-scoped Skill enablement decision.

func (*Controller) Skills 

func (c *Controller) Skills(ctx context.Context) (coding.SkillSnapshot, error)

Skills returns the current Runtime's content-free Skill discovery snapshot.

func (*Controller) Snapshot 

func (c *Controller) Snapshot() coding.State

Snapshot returns the current Runtime state, or the last attached state after a failed replacement leaves the Controller detached.

func (*Controller) Steer 

func (c *Controller) Steer(messages ...ai.Message) error

Steer queues messages into the active interaction.

func (*Controller) SubagentControlState 

func (c *Controller) SubagentControlState(
	_ context.Context,
	childSessionID string,
) (coding.ChildControlState, error)

SubagentControlState returns the independently owned pending-input state for one live custom child. It is intentionally an optional Runtime surface so historical/embedder runtimes retain their existing control contract.

func (*Controller) SubmitTeamControl 

func (c *Controller) SubmitTeamControl(
	ctx context.Context,
	request coding.TeamControlRequest,
) (coding.TeamControlReference, error)

SubmitTeamControl durably records one exact user-authorized Team command.

func (*Controller) SwitchModel 

func (c *Controller) SwitchModel(ctx context.Context, selected modelcatalog.Selection) error

SwitchModel replaces the current Runtime using a process-local model override. It does not modify Session history or configuration files.

func (*Controller) SwitchSessionModel 

func (c *Controller) SwitchSessionModel(
	ctx context.Context,
	selected modelcatalog.Selection,
) error

SwitchSessionModel replaces the current Runtime while preserving its exact Session identity, including when the durable conversation is still empty.

func (*Controller) TeamIntegrationRecoveries 

func (c *Controller) TeamIntegrationRecoveries(
	ctx context.Context,
) ([]coding.TeamIntegrationRecovery, error)

TeamIntegrationRecoveries returns manager-provided interrupted apply choices.

func (*Controller) Tree 

func (c *Controller) Tree(ctx context.Context) (coding.SessionTree, error)

Tree returns the current Runtime's bounded Session tree.

func (*Controller) WaitSubagent 

func (c *Controller) WaitSubagent(
	ctx context.Context,
	childSessionID string,
) (subagent.Result, error)

WaitSubagent waits for one child owned by the selected Session.

func (*Controller) WorkspaceStatus 

func (c *Controller) WorkspaceStatus(
	ctx context.Context,
) (changes.WorktreeStatus, error)

WorkspaceStatus returns a bounded point-in-time Git snapshot while holding the Controller lease against Runtime replacement.

type FullAccessConfirmation 

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

FullAccessConfirmation is an opaque, one-shot capability issued by the Controller after the user has confirmed an exact Full Access target. Its fields are intentionally private so model/tool input cannot forge one.

type ModeState 

type ModeState struct {
	Current    coding.OperatingMode
	Configured coding.OperatingMode
	Overridden bool
}

ModeState describes the configured and effective process-local operating mode.

type ModelState 

type ModelState struct {
	Selection  modelcatalog.Selection
	Resolved   modelcatalog.ResolvedModel
	Overridden bool
}

ModelState describes the model effective for the current process.

type PermissionApprovalState 

type PermissionApprovalState struct {
	Effective        config.ApprovalMode
	Configured       config.ApprovalMode
	EffectiveSource  config.SourceKind
	ConfiguredSource config.SourceKind
	Overridden       bool
}

PermissionApprovalState describes approval independently from Sandbox filesystem and Network permissions.

type PermissionFilesystemState 

type PermissionFilesystemState struct {
	Effective        config.SandboxMode
	Configured       config.SandboxMode
	EffectiveSource  config.SourceKind
	ConfiguredSource config.SourceKind
	Overridden       bool
}

PermissionFilesystemState describes one effective/configured filesystem profile and its safe provenance labels.

type PermissionNetworkState 

type PermissionNetworkState struct {
	Effective        config.SandboxNetworkMode
	Configured       config.SandboxNetworkMode
	EffectiveSource  config.SourceKind
	ConfiguredSource config.SourceKind
	Overridden       bool
}

PermissionNetworkState describes the retained sandbox Network setting. The setting remains observable while Full Access is active, but is not enforced by that profile; SandboxPermissionState.NetworkEnforced carries that fact.

type PermissionState 

type PermissionState struct {
	// Deprecated compatibility aliases. New consumers should use the nested
	// SandboxProfile and ApprovalPolicy projections below.
	Sandbox            config.SandboxMode
	ConfiguredSandbox  config.SandboxMode
	SandboxSource      config.SourceKind
	SandboxOverridden  bool
	Approval           config.ApprovalMode
	ConfiguredApproval config.ApprovalMode
	ApprovalSource     config.SourceKind
	ApprovalOverridden bool
	Network            config.SandboxNetworkMode
	ConfiguredNetwork  config.SandboxNetworkMode
	NetworkSource      config.SourceKind
	NetworkOverridden  bool
	NetworkEnforced    bool

	SandboxProfile SandboxPermissionState
	ApprovalPolicy PermissionApprovalState
}

PermissionState describes effective and configured process-local execution permissions. The legacy flat fields remain as compatibility aliases until all frontends consume SandboxProfile and ApprovalPolicy.

type PermissionUpdate 

type PermissionUpdate struct {
	SandboxProfile *SandboxPermissionUpdate
	Sandbox        *config.SandboxMode
	Approval       *config.ApprovalMode
	Network        *config.SandboxNetworkMode
}

PermissionUpdate is one bounded process-local execution-permission change. SandboxProfile is the preferred nested form; the flat fields are retained for compatibility with the first /permissions implementation.

type SandboxPermissionState 

type SandboxPermissionState struct {
	Filesystem      PermissionFilesystemState
	Network         PermissionNetworkState
	NetworkEnforced bool
}

SandboxPermissionState is the nested process-local Sandbox projection used by permission frontends. Config remains backward-compatible and flat.

type SandboxPermissionUpdate 

type SandboxPermissionUpdate struct {
	Filesystem *config.SandboxMode
	Network    *config.SandboxNetworkMode
}

SandboxPermissionUpdate is the nested Sandbox update accepted by the Controller boundary. Nil values retain the current effective value.

type SessionSummary 

type SessionSummary struct {
	Session      session.Metadata `json:"session"`
	TeamRecovery TeamRecoveryHint `json:"team_recovery,omitzero"`
}

SessionSummary adds read-only Team recovery hints to ordinary conversation metadata without changing the generic Session repository contract.

type TeamRecoveryClass 

type TeamRecoveryClass string

TeamRecoveryClass is the closed conversation-list classification for retained Team resources. Detailed recovery remains a Runtime operation. 

const (
	TeamRecoveryRetained TeamRecoveryClass = "retained"
	TeamRecoveryBlocked  TeamRecoveryClass = "blocked"
)

Team recovery hint classifications.

type TeamRecoveryHint 

type TeamRecoveryHint struct {
	Count     int               `json:"count"`
	UpdatedAt time.Time         `json:"updated_at,omitzero"`
	Class     TeamRecoveryClass `json:"class,omitempty"`
}

TeamRecoveryHint is a bounded content-free summary for one Lead Session.

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.