esm

package
v1.3.103 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	WorkerStatusContinue          = "continue"
	WorkerStatusCompleteCandidate = "complete_candidate"
	WorkerStatusBlockedCandidate  = "blocked_candidate"

	AuditVerdictPass = "pass"
	AuditVerdictFail = "fail"

	RecoveryDecisionResume  = "resume"
	RecoveryDecisionBlocked = "blocked"
)
View Source 
const (
	// RoleTimeout intentionally has no hard deadline. ESM is the long-task
	// execution mode, so it continues until its work finishes or an explicit
	// cancellation/ownership decision stops it.
	RoleTimeout             time.Duration = 0
	RecoveryObserverTimeout               = 5 * time.Minute
)
View Source 
const BlockedAuditLimit = 3

BlockedAuditLimit is the number of consecutive ESM runs reporting the same blocker before the objective becomes blocked.

View Source 
const LongTaskMaxIterations = -1

LongTaskMaxIterations deliberately leaves an ESM worker or reviewer unbounded. ESM owns long-running objectives, so an arbitrary turn count must never turn ongoing work into a completed-looking role result.

Variables

View Source 
var (
	ErrNotFound          = errors.New("esm objective not found")
	ErrObjectiveExists   = errors.New("esm objective already exists")
	ErrInvalidObjective  = errors.New("esm objective cannot be empty")
	ErrInvalidTransition = errors.New("invalid esm status transition")
)
View Source 
var ErrRoleIncomplete = errors.New("ESM role incomplete")

ErrRoleIncomplete identifies a role that stopped before completing its assigned work. It is recoverable for an active ESM objective: the next continuation resumes from persisted repository state rather than treating the partial role as success or pausing the objective.

Functions

func AuditTaskPrompt 

func AuditTaskPrompt(obj *Objective) string

AuditTaskPrompt is the isolated read-only audit sub-agent task for a completion candidate.

func ContinuationMessage 

func ContinuationMessage(obj *Objective) provider.Message

ContinuationMessage is used when the TUI starts an idle continuation run.

func ContinuationPrompt 

func ContinuationPrompt(_ *Objective) string

func CriticTaskPrompt 

func CriticTaskPrompt(obj *Objective) string

CriticTaskPrompt is the isolated skeptical review sub-agent task for a completion candidate. It runs before the verifier and is biased toward finding scope shrinkage, demos, and missing requirements.

func FinalAssistantResponse 

func FinalAssistantResponse(messages []agentpkg.Message) string

FinalAssistantResponse returns the final assistant text of a run. It prefers Content and falls back to concatenated text blocks, so both adapters parse the same structured ESM report from the same canonical extraction.

func FormatAuditReview 

func FormatAuditReview(report AuditReport, raw string) string

func FormatGuidanceSuffix 

func FormatGuidanceSuffix(items []session.ESMGuidance) string

FormatGuidanceSuffix renders queued user guidance as a prompt section. The guidance is user data: it is listed verbatim and never treated as system or developer instructions by the role prompts.

func FormatItemDetail 

func FormatItemDetail(label string, items []string) string

func FormatObjective 

func FormatObjective(obj *Objective) string

FormatObjective returns a compact plain-text representation safe for TUI and tools.

func FormatReportParts 

func FormatReportParts(primaryLabel, primary string, firstLabel string, first []string, secondLabel string, second []string, raw string) string

func FormatWorkerBlocker 

func FormatWorkerBlocker(report WorkerReport) string

func FormatWorkerCompletion 

func FormatWorkerCompletion(report WorkerReport, raw string) string

func InvalidSupervisorPassReason 

func InvalidSupervisorPassReason(role string, result RoleResult, report AuditReport) string

func InvalidWorkerCandidateReason 

func InvalidWorkerCandidateReason(result RoleResult, report WorkerReport) string

func IsRunnableStatus 

func IsRunnableStatus(status Status) bool

IsRunnableStatus reports whether normal ESM tools should remain visible.

func IsUnfinishedStatus 

func IsUnfinishedStatus(status Status) bool

IsUnfinishedStatus reports whether a status still represents an open objective. "complete" is terminal; clearing the objective deletes the row.

func IsUsageLimitError 

func IsUsageLimitError(err error) bool

IsUsageLimitError applies a conservative text heuristic for provider/account limits that should stop unattended continuation.

func NewGetTool 

func NewGetTool(store *Store, sessionID sessionIDFunc) tools.Tool

NewGetTool returns the model-facing ESM state query tool.

func NewRoleIncompleteError 

func NewRoleIncompleteError(role Role, stopReason string, cause error) error

NewRoleIncompleteError preserves an adapter's terminal detail while giving Supervisor one shared classification independent of protocol projection.

func NewUpdateTool 

func NewUpdateTool(store *Store, sessionID sessionIDFunc, runID ...runIDFunc) tools.Tool

NewUpdateTool returns the model-facing ESM status update tool.

func RecoveryObserverTaskPrompt 

func RecoveryObserverTaskPrompt(obj *Objective, role, interruption string) string

RecoveryObserverTaskPrompt asks a read-only observer to inspect the repository after an ESM role was interrupted before it could report state.

func RoleContext 

func RoleContext(parent context.Context, role Role) (context.Context, context.CancelFunc)

RoleContext applies the ESM-owned deadline policy once for every adapter. A zero timeout preserves the parent context rather than creating an already expired context with context.WithTimeout.

func SteeringMessage 

func SteeringMessage(obj *Objective) provider.Message

SteeringMessage injects current ESM instructions into a run without changing the frozen system prompt.

func SteeringPrompt 

func SteeringPrompt(obj *Objective) string

func WorkerContinueMessage 

func WorkerContinueMessage(report WorkerReport) string

func WorkerOutstandingWork 

func WorkerOutstandingWork(report WorkerReport) []string

func WorkerTaskPrompt 

func WorkerTaskPrompt(obj *Objective) string

WorkerTaskPrompt is the isolated worker sub-agent task for one ESM run.

Types

type AuditReport 

type AuditReport struct {
	Verdict             string   `json:"verdict"`
	Review              string   `json:"review"`
	RequirementsChecked []string `json:"requirements_checked"`
	MissingWork         []string `json:"missing_work"`
	Evidence            []string `json:"evidence"`
}

AuditReport is the structured final response from an isolated ESM auditor.

func ParseAuditReport 

func ParseAuditReport(text string) (AuditReport, error)

type EvidenceTracker 

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

EvidenceTracker accumulates tool-call evidence for one ESM role run. TUI and WebUI adapters must share this tracker so the "tool-backed evidence" checks in ApplyWorkerResult/ApplyReviewResult cannot diverge between adapters.

func NewEvidenceTracker 

func NewEvidenceTracker() *EvidenceTracker

NewEvidenceTracker returns an empty tracker for one role run.

func (*EvidenceTracker) Observe 

func (t *EvidenceTracker) Observe(ev agentpkg.Event)

Observe records one agent event's tool evidence. Tool calls are counted once per unique tool-call ID; events without an ID are counted as they arrive.

func (*EvidenceTracker) Summary 

func (t *EvidenceTracker) Summary() (int, map[string]int, map[string]bool)

Summary returns the accumulated evidence for a RoleResult.

type Objective 

type Objective struct {
	SessionID        string
	ESMID            string
	Objective        string
	Status           Status
	TokensUsed       int64
	TimeUsedMS       int64
	BlockedCount     int
	BlockedReason    string
	BlockedRunID     string
	CompletionReason string
	CompletionRunID  string
	CompletionReview string
	Phase            Phase
	ProgressSummary  string
	RemainingWork    []string
	RejectionCount   int
	RejectionRunID   string
	RecoveryCount    int
	RecoveryReason   string
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

Objective is the per-session Enable Supervisor Mode objective. TokensUsed and TimeUsedMS are observability counters only; ESM no longer enforces token or time limits.

func (*Objective) CanAutoRun 

func (o *Objective) CanAutoRun() bool

CanAutoRun reports whether TUI idle continuation may start a new agent run.

func (*Objective) HasObjective 

func (o *Objective) HasObjective() bool

HasObjective reports whether the row contains a real objective.

type Outcome 

type Outcome struct {
	Objective *Objective
	Subject   string
	Message   string
	Reason    string
	Rejected  bool
	Completed bool
}

Outcome describes the state transition produced by applying one ESM role result.

func ApplyReviewResult 

func ApplyReviewResult(ctx context.Context, store *Store, sessionID, runID, role string, result RoleResult) (Outcome, bool, error)

ApplyReviewResult applies the canonical TUI ESM critic/audit semantics to durable state.

func ApplyWorkerResult 

func ApplyWorkerResult(ctx context.Context, store *Store, sessionID, runID string, result RoleResult) (Outcome, bool, error)

ApplyWorkerResult applies the canonical TUI ESM worker semantics to durable state.

type Phase 

type Phase string

Phase identifies the current role in the ESM completion pipeline. 

const (
	PhaseWorker   Phase = "worker"
	PhaseCritic   Phase = "critic"
	PhaseAudit    Phase = "audit"
	PhaseComplete Phase = "complete"
)

type RecoveryReport 

type RecoveryReport struct {
	Decision      string   `json:"decision"`
	Summary       string   `json:"summary"`
	Evidence      []string `json:"evidence"`
	RemainingWork []string `json:"remaining_work"`
	Blockers      []string `json:"blockers"`
}

RecoveryReport is the structured result of an observer inspecting work left behind by an interrupted ESM role.

func ParseRecoveryReport 

func ParseRecoveryReport(text string) (RecoveryReport, error)

type Role 

type Role string

Role is the role in the TUI-defined ESM pipeline. 

const (
	RoleWorker   Role = "worker"
	RoleCritic   Role = "critic"
	RoleAudit    Role = "audit"
	RoleRecovery Role = "recovery"
)

type RoleRequest 

type RoleRequest struct {
	SessionID     string
	RunID         string
	Role          Role
	WorkDir       string
	Mode          string
	Tools         []string
	MaxIterations int
	Prompt        string
	Objective     *Objective
}

RoleRequest is the complete host execution contract. The host runs an isolated agent; it must not make ESM state decisions.

type RoleResult 

type RoleResult struct {
	Response   string
	Tokens     int64
	DurationMS int64
	ToolCalls  int
	ToolNames  map[string]int
	ToolError  map[string]bool
}

RoleResult is the UI/runtime-neutral result of one isolated ESM role run.

type RuntimeAdapter 

type RuntimeAdapter interface {
	RunRole(context.Context, RoleRequest) (RoleResult, error)
	RunRecoveryObserver(context.Context, RoleRequest, error) (RoleResult, error)
}

RuntimeAdapter is implemented by TUI/WebUI agent hosts. ESM policy remains in Supervisor; adapters only execute roles and project host events.

type RuntimeEvent 

type RuntimeEvent struct {
	SessionID string
	RunID     string
	Role      Role
	Type      string
	Status    string
	Message   string
}

RuntimeEvent is UI-neutral lifecycle output. It is informational only.

type RuntimeEventSink 

type RuntimeEventSink interface {
	PublishESMEvent(context.Context, RuntimeEvent) error
}

type Status 

type Status string

Status is the persisted lifecycle state for a supervised objective. 

const (
	StatusActive            Status = "active"
	StatusPaused            Status = "paused"
	StatusBlocked           Status = "blocked"
	StatusUsageLimited      Status = "usage_limited"
	StatusCompleteCandidate Status = "complete_candidate"
	StatusComplete          Status = "complete"
)

type SteeringSource 

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

SteeringSource projects the latest active ESM objective into an already running Agent at its normal steering boundaries. It never starts a run: the adapter remains responsible for idle continuation scheduling.

A source is intentionally scoped to one Agent run. It is safe for the agent loop to call Next repeatedly and emits each persisted objective version at most once.

func NewSteeringSource 

func NewSteeringSource(store *Store, sessionID string) *SteeringSource

NewSteeringSource creates a run-scoped source for one session. A nil Store or empty session ID is accepted so adapters can use the source uniformly in partially initialized or compatibility paths; Next then returns no message.

func (*SteeringSource) Next 

func (s *SteeringSource) Next() []provider.Message

Next returns a single system-injected steering message when an active ESM objective is first observed or has changed since the prior call. Paused, blocked, limited, completed, and missing objectives deliberately produce no steering instruction.

type Store 

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

Store persists Enable Supervisor Mode state in the shared sessions database.

func NewStore 

func NewStore(sessionDir string) *Store

NewStore returns a store backed by the root sessions.db under sessionDir.

func (*Store) AccountUsage 

func (s *Store) AccountUsage(ctx context.Context, sessionID string, tokens, durationMS int64) (*Objective, error)

AccountUsage accumulates one agent run's usage. Usage counters are observability only; ESM no longer enforces token or time limits.

func (*Store) AddGuidance 

func (s *Store) AddGuidance(ctx context.Context, sessionID, text string) (*Objective, error)

AddGuidance queues user guidance for the session's objective. The guidance is stamped with the objective's current version so adapters can detect stale submissions, and the Supervisor injects it into the next role prompts.

func (*Store) Clear 

func (s *Store) Clear(ctx context.Context, sessionID string) error

Clear deletes the objective for a session.

func (*Store) ConsumeGuidance 

func (s *Store) ConsumeGuidance(ctx context.Context, sessionID string, ids []string) error

ConsumeGuidance marks queued guidance as applied after a role run used it.

func (*Store) Create 

func (s *Store) Create(ctx context.Context, sessionID, objective string) (*Objective, error)

Create creates a new objective. A completed row may be replaced; unfinished objectives must be edited or cleared explicitly.

func (*Store) Edit 

func (s *Store) Edit(ctx context.Context, sessionID, objective string) (*Objective, error)

Edit updates the objective text for an unfinished objective.

func (*Store) FinishRun 

func (s *Store) FinishRun(ctx context.Context, sessionID, runID string) (*Objective, error)

FinishRun clears repeated blocker/rejection streaks when an active ESM run finishes without reporting the same condition.

func (*Store) Get 

func (s *Store) Get(ctx context.Context, sessionID string) (*Objective, error)

Get returns the current objective for a session.

func (*Store) MarkCompleteFromAudit 

func (s *Store) MarkCompleteFromAudit(ctx context.Context, sessionID, review string) (*Objective, error)

MarkCompleteFromAudit marks a completion candidate terminal complete after an independent ESM audit has verified the objective against the current state.

func (*Store) MarkUsageLimited 

func (s *Store) MarkUsageLimited(ctx context.Context, sessionID string) (*Objective, error)

MarkUsageLimited records a runtime/provider limit and stops continuation.

func (*Store) Pause 

func (s *Store) Pause(ctx context.Context, sessionID string) (*Objective, error)

Pause disables idle continuation for an unfinished objective.

func (*Store) PendingGuidance 

func (s *Store) PendingGuidance(ctx context.Context, sessionID string) ([]session.ESMGuidance, error)

PendingGuidance returns queued guidance not yet injected into a role run.

func (*Store) RecordCompletionReview 

func (s *Store) RecordCompletionReview(ctx context.Context, sessionID, review string) (*Objective, error)

RecordCompletionReview stores a completion rejection/review note without changing the current lifecycle state. This lets later worker runs learn why a previous completion claim was not accepted.

func (*Store) RecordRecovery 

func (s *Store) RecordRecovery(ctx context.Context, sessionID, reason, summary string, remainingWork []string) (*Objective, error)

RecordRecovery persists a recovery diagnosis after an interrupted ESM role. Recovery is observability, not a circuit breaker: an active long-task objective remains active until it completes, is explicitly stopped, or a real blocker is recorded.

func (*Store) RecordWorkerProgress 

func (s *Store) RecordWorkerProgress(ctx context.Context, sessionID, summary string, remainingWork []string) (*Objective, error)

RecordWorkerProgress persists the latest structured worker result so later runs and the TUI can show concrete progress and remaining work.

func (*Store) RejectCompletionCandidate 

func (s *Store) RejectCompletionCandidate(ctx context.Context, sessionID, review string) (*Objective, error)

RejectCompletionCandidate records a failed completion candidate. A rejected claim means work remains, so unattended continuation stays active.

func (*Store) RejectCompletionCandidateForRun 

func (s *Store) RejectCompletionCandidateForRun(ctx context.Context, sessionID, runID, review string, missingWork []string) (*Objective, error)

RejectCompletionCandidateForRun records a critic/audit rejection with its structured missing work. A run contributes at most once to the streak.

func (*Store) RejectWorkerReport 

func (s *Store) RejectWorkerReport(ctx context.Context, sessionID, runID, review string, remainingWork []string) (*Objective, error)

RejectWorkerReport records a worker report rejected before supervisor review while the objective is still active.

func (*Store) Resume 

func (s *Store) Resume(ctx context.Context, sessionID string) (*Objective, error)

Resume returns paused/blocked/limited objectives to active when allowed.

func (*Store) SetPhase 

func (s *Store) SetPhase(ctx context.Context, sessionID string, phase Phase) (*Objective, error)

SetPhase records the current role in the worker/critic/audit pipeline.

func (*Store) UpdateFromModel 

func (s *Store) UpdateFromModel(ctx context.Context, sessionID string, status Status, reason string) (*Objective, error)

UpdateFromModel accepts the two model-controlled transitions: complete and blocked. Complete records a candidate only; the orchestrator must audit the candidate before marking the objective terminal complete. Blocked transitions should normally use UpdateFromModelForRun so the repeated-blocker audit is counted across consecutive agent runs.

func (*Store) UpdateFromModelForRun 

func (s *Store) UpdateFromModelForRun(ctx context.Context, sessionID string, status Status, reason, runID string) (*Objective, error)

UpdateFromModelForRun accepts model-controlled complete/blocked transitions. Complete becomes complete_candidate, never terminal complete. The terminal complete state is reserved for the ESM orchestrator after an independent audit sub-agent passes. Blocked only becomes terminal after the same blocker repeats in three consecutive ESM agent runs. A run can contribute at most once to the audit.

type Supervisor 

type Supervisor struct {
	Store   *Store
	Adapter RuntimeAdapter
	Events  RuntimeEventSink
}

Supervisor is the single ESM runtime extracted from the TUI implementation.

func (*Supervisor) Run 

func (s *Supervisor) Run(ctx context.Context, sessionID, runID, workDir, mode string) (*Objective, error)

Run executes one continuation using the TUI order: worker, then critic and audit only for a completion candidate. A normal worker continue returns active and is resumed by the next continuation.

runID is the base continuation run ID. All durable state reporting inside the continuation uses this base ID so FinishRun and the per-run idempotency checks line up; role sub-agents and events keep suffixed IDs derived from it. The Supervisor owns the terminal FinishRun call for both adapters.

type WorkerReport 

type WorkerReport struct {
	Status        string   `json:"status"`
	Summary       string   `json:"summary"`
	Evidence      []string `json:"evidence"`
	RemainingWork []string `json:"remaining_work"`
	Blockers      []string `json:"blockers"`
}

WorkerReport is the structured final response from an isolated ESM worker.

func ParseWorkerReport 

func ParseWorkerReport(text string) (WorkerReport, error)

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.