Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Agent State Machine
*
* Manages the processing of tasks from the message queue.
* Coordinates TaskExecutor instances for per-task execution.
*
* Phase 6: Approval handling, ApprovalController wiring.
* Concurrent refactor: Delegates execution to TaskExecutor, routes
* approvals via approvalMap keyed by requestId.
*/
import { EventEmitter } from 'events'
import { BudgetClient, deriveBudgetAttribution } from '../budget/budgetClient'
import type { BudgetVerdict } from '../budget/types'
import { config as appConfig } from '../config'
import { maybeWrapFailover } from '../core/adapters/failoverLlmPort'
import { AdapterStaticContext, LlmPortAdapter } from '../core/adapters/llmPortAdapter'
import { ConversationManager } from '../core/conversation/conversation'
import type { ConversationStore } from '../core/conversation/conversationStore'
import { LlmErrorCode } from '../core/errors'
// Phase 6 imports
import type { ApprovalConfig } from '../core/extensions/approvalTypes'
import { PressureContextManager } from '../core/extensions/contextManager'
import { STATELESS_CRON_APPROVAL_PROMPT } from '../core/extensions/mcpApprovalGateController'
import type { GuardrailsConfig } from '../core/guardrails/config'
import type { LlmPort } from '../core/interfaces'
// Core architecture imports
import { SimpleEventEmitter } from '../core/orchestration/eventEmitter'
import { BasicSafety } from '../core/safety/safety'
// Phase 7–8 imports
import type { SessionSearchService } from '../core/sessionSearch'
import type { SpilloverStorage } from '../core/spillover'
import { createTokenCounter } from '../core/tokenizer'
import type {
Attachment,
Conversation,
AgentEventType as CoreAgentEventType,
PendingApproval,
} from '../core/types'
import type { ReapedSession } from '../db/worker/protocol'
import type { GfsDownloadStore } from '../internalTools/gfsDownloadStore'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import { isTerminal } from '../lifecycle/types'
import { SingleTurnProvider } from '../llm'
import type { ImageInputResolver } from '../llm/imageInput'
import type { PromptCache } from '../llm/promptCache'
import { resolveContextWindow } from '../llm/registryCore'
import { logger } from '../logger'
import { McpManager } from '../mcp'
import { ensureReporter } from '../progress/sseProgressReporter'
import { MessageQueue, Task } from '../queue'
import type { TaskError } from '../queue/types'
import { SessionProcessor, serializeSessionKey } from '../session'
import { parseSessionKey } from '../session/types'
import { ApprovalPromptHistoryClient } from '../usage/approvalPromptHistoryClient.js'
import { GovernedRunReporter, UsageReporter } from '../usage/usageReporter.js'
import { resolveCallerRootBinding } from '../workspace/callerRootBinding'
import type { ScopedWorkspaceProvider } from '../workspace/scopedWorkspace'
import { CronScheduler } from './cronScheduler'
import { TaskExecutor, resolveTaskSessionKey } from './taskExecutor'
import {
AgentConfig,
AgentEvent,
AgentEventType,
AgentState,
AgentStats,
DEFAULT_AGENT_CONFIG,
type FailoverSupportProvider,
type TaskModelResolver,
} from './types'
/**
* Pending approval info exposed via /status endpoint.
*/
export interface PendingApprovalInfo {
requestId: string
userId: string
toolName: string
parameters: Record<string, unknown>
description: string
since: string
// U5 — suspension discriminator, mirrored from the underlying PendingApproval
// so the polling projections match the SSE `suspended` event. Absent reason ⇒
// generic HITL approval (back-compat). mcpServerName set iff
// reason==='connect_required' (oauth connect flow).
reason?: 'approval_required' | 'connect_required'
mcpServerName?: string
}
/**
* IronClaw invariant #3 (P.3): contract for rehydrating `pending_approvals`
* from durable storage at cold start. T2.1 ships the SQLite-backed
* implementation; P.3 ships the no-op so the wiring is in place.
*
* Pre-flight rules:
* - approvals where `expires_at < now()` → mark `denied:expired`, notify the
* user via channel of origin, do NOT rehydrate.
* - approvals where the snapshot has spillover refs and `probe()` reports any
* expired → same: `denied:expired`.
* - the rest → rehydrate.
*
* MUST be awaited before SessionProcessor starts processing new messages so a
* user retry cannot race the rehydration.
*/
export interface ColdStartLoader {
loadPendingApprovals(now: number): Promise<RehydratedApproval[]>
/**
* D.2 — boot-time reap of sessions stuck in 'processing' (their reporter died
* with the previous pod). Optional: the NoOp loader and any non-durable store
* skip it. Returns the reaped sessions for logging / future notification.
*/
reapProcessingSessions?(now: number): Promise<ReapedSession[]>
/**
* D.8 (F7) — boot-time reap of sessions stuck in 'awaiting_approval' whose
* approval can no longer resolve (all expired, or orphaned). Optional, same
* contract as reapProcessingSessions. Runs before approval rehydration.
*/
reapExpiredAwaitingApprovalSessions?(now: number): Promise<ReapedSession[]>
/**
* Legacy explicit recovery hook that reaps every awaiting approval. The normal
* boot path does not call it now that live executors are reconstructed.
*/
reapAwaitingApprovalSessions?(now: number): Promise<ReapedSession[]>
}
export interface RehydratedApproval {
request_id: string
task_id: string
session_key?: string
approval: PendingApproval
expiresAt?: number
/**
* Optional snapshot of the originating message — used by T2.1 to re-route
* notifications when the cold-start sweep marks an approval as expired.
* P.3 doesn't act on this field (NoOp loader returns []).
*/
source_message?: Record<string, unknown>
}
/**
* Default no-op loader: returns []. Replaced by T2.1's
* `SqliteColdStartLoader`. With this default the bootstrap is effectively a
* no-op and main.ts can safely skip awaiting it during P.3.
*/
export class NoOpColdStartLoader implements ColdStartLoader {
async loadPendingApprovals(): Promise<RehydratedApproval[]> {
return []
}
}
type ApprovalDecisionBinding = {
userId?: string
channelType?: string
channelId?: string
sessionKey?: string
}
/** Server-validated (provider, model) pair that a visual send is pinned to. */
interface VisualSelectionSnapshot {
provider: string
model: string
}
/**
* #654 — read the server-owned visual selection snapshot from a queued task.
*
* `IncomingMessage.imageModel` is written by the server lane only after the
* image was validated, and the client-supplied copy is removed from the
* normalized message, so the value is authoritative rather than caller input.
* Values are still validated at runtime: anything malformed or absent means
* "no pinned selection" rather than a partial pin.
*/
function readVisualSelectionSnapshot(task: Task): VisualSelectionSnapshot | undefined {
const raw = task.sourceMessage?.imageModel
if (!raw || typeof raw !== 'object') return undefined
const { provider, model } = raw as { provider?: unknown; model?: unknown }
if (typeof provider !== 'string' || !provider) return undefined
if (typeof model !== 'string' || !model) return undefined
return { provider, model }
}
/**
* Agent State Machine for task processing.
*/
export class AgentStateMachine extends EventEmitter {
private state: AgentState = 'idle'
private queue: MessageQueue
private llmProvider: SingleTurnProvider | null = null
private mcpManager: McpManager | null = null
private sessionProcessor: SessionProcessor | null = null
private cronScheduler: CronScheduler | null = null
private config: AgentConfig
// Start time for uptime calculation
private startedAt: Date
// Per-task execution (managed via executor map)
private activeExecutors = new Map<string, TaskExecutor>()
private approvalMap = new Map<
string,
{
taskId: string
timerId?: ReturnType<typeof setTimeout>
registeredAt: Date
expiresAt?: number
binding: ApprovalDecisionBinding
}
>()
// T1.1 — sessionKeys with an in-flight operator-triggered compaction.
// Serializes overlapping `compactSession()` calls for the same session so
// they don't race on shared `Conversation` state (compactionState, daily
// log writes) across the LLM await.
private compactionsInFlight = new Set<string>()
// B5 — durable `clearPendingApproval` retry queue. The cancel-during-approval
// path used to fire-and-forget the SQLite delete; a transient worker
// failure left an orphan pending_approval row that cold-start would
// resurrect with no source task. The retry queue + bounded backoff makes
// the durable write best-effort with eventual consistency. Layer 2 (the
// B7 TTL filter in `SqliteColdStartLoader`) is the safety net for rows
// we ultimately give up on.
private clearPendingApprovalRetries = new Map<string, { attempts: number; nextTry: number }>()
private clearRetryTimer: ReturnType<typeof setInterval> | null = null
private isRunning: boolean = false
// Core infrastructure
private conversationManager = new ConversationManager()
private modelName: string = 'unknown'
// R2 — per-task effective-model resolver (provider instance + model + context
// window) from the session's saved selection. Null in dev/tests → default.
private taskModelResolver: TaskModelResolver | null = null
// R5 — provider-fallback support provider. Returns the current failover
// engine + policy + provider factory, or null when no policy is configured.
// Null in dev/tests → no failover (byte-identical to today).
private failoverSupportProvider: FailoverSupportProvider | null = null
// #654 — live-catalog image-input capability resolver (provider, model →
// evidence + policy admission). Null in dev/tests/unwired hosts → images
// fail closed with LLM_IMAGE_INPUT_UNKNOWN; text-only turns are unchanged.
private imageInputResolver: ImageInputResolver | null = null
// Persistent core event emitter (Gap 3 resolution: bridges agent-level events to SimpleEventEmitter)
private coreEvents = new SimpleEventEmitter()
// Phase 6: Approval
private approvalConfig: ApprovalConfig | undefined
private guardrailsConfig: GuardrailsConfig | undefined
// Phase 7–8: Workspace memory & personalization
private workspaceProvider: ScopedWorkspaceProvider | undefined
private gfsWorkspaceProvider: ScopedWorkspaceProvider | undefined
private gfsDownloadStore: GfsDownloadStore | undefined
// T1.5 — Tool-result spillover store. Undefined when the feature flag is
// off; populated from main.ts and propagated into each TaskExecutor.
private spilloverStorage: SpilloverStorage | undefined
// T2.2 — Process-wide PromptCache. Undefined when the prompt-cache flag
// is OFF; populated from main.ts and forwarded into each TaskExecutor.
private promptCache: PromptCache | undefined
// T3.1 — Session search backend. Undefined when SQLite store is OFF or the
// feature flag `CLERUM_SESSION_SEARCH_ENABLED` is false; populated from
// main.ts and forwarded into each TaskExecutor.
private sessionSearchService: SessionSearchService | undefined
// ConfigStore snapshot getter, merged into shell-tool spawn env
private dynamicEnvProvider: (() => Record<string, string>) | undefined
// ConfigStore secret entries getter, used by output sanitizer
private secretEntriesProvider: (() => Array<{ name: string; value: string }>) | undefined
// LLM usage tracking — see docs/plans/llm-token-usage-tracking-*.md
private usageReporter: UsageReporter | undefined
private governedRunReporter: GovernedRunReporter | undefined
private approvalPromptHistoryClient: ApprovalPromptHistoryClient | undefined
private usageStaticContext: AdapterStaticContext | undefined
// P1 token budgets — pre-task budget check. Both undefined unless
// `CLERUM_BUDGETS_ENABLED` is on and main.ts wired them (needs runtime auth).
private budgetClient: BudgetClient | undefined
private getHostBudgetContext:
| (() => {
host_ref: string
context_ref: string | null
llm_secret_name: string | null
} | null)
| undefined
// P2b token budgets (§5.4) — task ids whose check created a danger-zone
// reservation in control-api (verdict carried non-empty `reservationIds`),
// mapped to the EXACT `host_ref` that check sent. The terminal-release
// subscriber drops the reservation early for exactly these tasks, replaying
// the stored host_ref so control-api's claim-binding + host-scoping matches
// the reservation (§control-api /release). The common far-from-limit task
// makes no reservation and is never added, so no needless release call is
// issued. Always empty when the budgets flag is off (checkTaskBudget no-ops
// before populating it).
private tasksWithBudgetReservation = new Map<string, string>()
// Phase A.6: TaskLifecycle dual-write
private lifecycle: TaskLifecycle
// P.3 IronClaw invariant #3: cold-start loader for pending_approvals.
// Defaults to NoOp; T2.1 swaps in the SqliteColdStartLoader.
private coldStartLoader: ColdStartLoader = new NoOpColdStartLoader()
constructor(queue: MessageQueue, lifecycle: TaskLifecycle, config: Partial<AgentConfig> = {}) {
super()
this.queue = queue
this.lifecycle = lifecycle
this.config = { ...DEFAULT_AGENT_CONFIG, ...config }
this.startedAt = new Date()
// Subscribe to TaskLifecycle cancel transitions (spec §4.4)
this.subscribeLifecycle()
// P2b token budgets (§5.4) — release danger-zone reservations on terminal.
this.subscribeBudgetReleaseOnTerminal()
}
/**
* Set the LLM provider.
*/
setLLMProvider(provider: SingleTurnProvider, modelName?: string): void {
this.llmProvider = provider
if (modelName) {
this.modelName = modelName
}
logger.info({ component: 'Agent' }, 'LLM provider set')
}
/**
* R2 — inject the per-task model resolver (built in `main.ts` over the live
* ConfigStore keys + allowlist). When set, each task resolves its effective
* provider+model from the session's saved selection instead of using the
* process-wide default. Absent in dev/tests → the default provider is used.
*/
setTaskModelResolver(resolver: TaskModelResolver): void {
this.taskModelResolver = resolver
logger.info({ component: 'Agent' }, 'Task model resolver set')
}
/**
* R5 — inject the provider-fallback support provider (built in `main.ts`).
* When set and it returns a non-null support with fallbacks, each task's
* `LlmPort` (and the manual `/compact` port) is wrapped so an eligible
* provider error switches to a configured fallback below the loop. Absent in
* dev/tests → no failover.
*/
setFailoverSupport(provider: FailoverSupportProvider): void {
this.failoverSupportProvider = provider
logger.info({ component: 'Agent' }, 'Failover support provider set')
}
/**
* #654 — inject the image-input capability resolver (built in `main.ts` over
* the live model catalog). When set, every task port and the manual
* `/compact` port check the capability of the exact (provider, model) they
* are about to send before dispatching an image-bearing request. Absent →
* images are rejected as unknown instead of being dropped silently.
*/
setImageInputResolver(resolver: ImageInputResolver): void {
this.imageInputResolver = resolver
logger.info({ component: 'Agent' }, 'Image-input capability resolver set')
}
/**
* R5 — wrap the manual `/compact` port with provider-failover, mirroring
* `TaskExecutor.wrapFailoverPort`. Fallback entries get their own adapter with
* the compact usage sink (session lifetime counters) + a per-pair counter.
* Returns the primary unchanged when no policy / no fallbacks.
*/
private wrapCompactFailover(
primaryPort: LlmPortAdapter,
primaryProvider: SingleTurnProvider,
primaryModel: string,
conv: Conversation
): LlmPort {
const support = this.failoverSupportProvider?.()
if (!support || support.policy.fallbacks.length === 0) return primaryPort
const primaryProviderType = primaryProvider.getProviderType()
return maybeWrapFailover({
primaryPort,
primaryPair: { provider: primaryProviderType, model: primaryModel },
engine: support.engine,
policy: support.policy,
buildFallbackPort: index => {
const entry = support.policy.fallbacks[index]
// R5.7 — same-provider fallback respects the session model; cross-provider
// serves the fixed entry model. #654: resolve the effective model BEFORE
// building so SDK, token counter, usage event and image guard agree.
const servedModel = entry.provider === primaryProviderType ? primaryModel : entry.model
const provider = support.buildProvider({ ...entry, model: servedModel })
if (!provider) return null
const counter = createTokenCounter(provider, servedModel, {
offline: appConfig.tokenizerOffline,
})
return new LlmPortAdapter(
provider,
servedModel,
provider.getProviderType(),
this.usageReporter,
this.usageStaticContext,
undefined,
counter,
usage => this.conversationManager.recordSessionUsage(conv, usage),
this.imageInputResolver ?? undefined
)
},
})
}
/**
* Set the MCP manager.
*/
setMcpManager(manager: McpManager): void {
this.mcpManager = manager
logger.info({ component: 'Agent' }, 'MCP manager set')
}
/**
* Set the session processor for concurrent session-based dispatch.
*/
setSessionProcessor(processor: SessionProcessor): void {
this.sessionProcessor = processor
logger.info({ component: 'Agent' }, 'Session processor set')
}
/**
* Set the cron scheduler for scheduled task management.
*/
setCronScheduler(scheduler: CronScheduler): void {
this.cronScheduler = scheduler
logger.info({ component: 'Agent' }, 'Cron scheduler set')
}
/**
* Phase 7–8: Set the workspace service for persistent memory and personalization.
*/
setWorkspaceProvider(provider: ScopedWorkspaceProvider): void {
this.workspaceProvider = provider
logger.info({ component: 'Agent' }, 'Workspace provider set')
}
setGfsWorkspaceProvider(provider: ScopedWorkspaceProvider | undefined): void {
this.gfsWorkspaceProvider = provider
}
setGfsDownloadStore(store: GfsDownloadStore | undefined): void {
this.gfsDownloadStore = store
}
/**
* T1.5 — Inject the spillover storage so each TaskExecutor can persist
* oversized tool outputs and register the `clerum__spillover_read` tool.
* Optional; when omitted the agent behaves bit-identical to pre-T1.5.
*/
setSpilloverStorage(storage: SpilloverStorage | undefined): void {
this.spilloverStorage = storage
logger.info({ configured: Boolean(storage) }, 'Spillover storage configured')
}
/**
* T2.2 — Inject the process-wide PromptCache. Called from `main.ts` after
* the conversation store + workspace service exist. The cache hooks
* `conversationStore.onEvict` to drop entries when sessions leave the LRU.
*/
setPromptCache(cache: PromptCache | undefined): void {
this.promptCache = cache
logger.info({ configured: Boolean(cache) }, 'Prompt cache configured')
}
/**
* T3.1 — Inject the session search backend. When set together with a
* `sourceMessage`, each TaskExecutor registers `clerum__session_search`.
* Optional; when omitted the tool is not exposed (no degraded mode — the
* caller simply does not see it in the registry).
*/
setSessionSearchService(service: SessionSearchService | undefined): void {
this.sessionSearchService = service
logger.info({ configured: Boolean(service) }, 'Session search configured')
}
/**
* Inject the ConfigStore snapshot getter so shell-tool subprocesses
* see operator-managed env vars (per-Host CM/Secret + LLM key).
*/
setDynamicEnvProvider(provider: () => Record<string, string>): void {
this.dynamicEnvProvider = provider
logger.info({ component: 'Agent' }, 'Dynamic env provider set')
}
/**
* Inject the ConfigStore secret-entries getter so the output sanitizer
* can redact ConfigStore-managed secret values from tool stdout.
*/
setSecretEntriesProvider(provider: () => Array<{ name: string; value: string }>): void {
this.secretEntriesProvider = provider
logger.info({ component: 'Agent' }, 'Secret entries provider set')
}
/**
* Inject the LLM usage reporter and the host's static attribution
* context. Both must be set together; either being undefined disables
* usage capture for this agent.
*/
setUsageReporter(reporter: UsageReporter, staticContext: AdapterStaticContext): void {
this.usageReporter = reporter
this.usageStaticContext = staticContext
logger.info({ component: 'Agent' }, 'Usage reporter set')
}
setGovernedRunReporter(reporter: GovernedRunReporter): void {
this.governedRunReporter = reporter
}
setApprovalPromptHistoryClient(client: ApprovalPromptHistoryClient): void {
this.approvalPromptHistoryClient = client
}
/**
* P1 token budgets (§5.1) — inject the BudgetClient and a lazy getter for the
* host attribution fields. `getHostContext` reads `currentHost` (a main.ts
* global, NOT an AgentStateMachine member) at call time so Host CRD updates
* are reflected. Only wired when `CLERUM_BUDGETS_ENABLED` is on.
*/
setBudgetCheck(
client: BudgetClient,
getHostContext: () => {
host_ref: string
context_ref: string | null
llm_secret_name: string | null
} | null
): void {
this.budgetClient = client
this.getHostBudgetContext = getHostContext
logger.info({ component: 'Agent' }, 'Budget check wired')
}
/**
* P1 token budgets (§5.1) — one-shot pre-task budget check. Builds the
* control-api request from the host context (host_ref/context_ref/
* llm_secret_name), the active provider/model, and the per-task attribution
* derived from the Task (source_kind/user_id/team_id/cron_job_id).
*
* No-op `{allowed:true}` (no network) when the budgets flag is off or the
* client/host context is not wired. Delegates fail-open semantics to
* `BudgetClient.check` — this method itself never throws on a transport error.
*/
async checkTaskBudget(task: Task): Promise<BudgetVerdict> {
if (!appConfig.budgetsEnabled || !this.budgetClient || !this.getHostBudgetContext) {
return { allowed: true }
}
const hostCtx = this.getHostBudgetContext()
if (!hostCtx || !this.llmProvider) {
return { allowed: true }
}
const attribution = deriveBudgetAttribution(task)
const verdict = await this.budgetClient.check({
host_ref: hostCtx.host_ref,
context_ref: hostCtx.context_ref,
llm_secret_name: hostCtx.llm_secret_name,
provider: this.llmProvider.getProviderType(),
model: this.modelName,
source_kind: attribution.source_kind,
user_id: attribution.user_id,
team_id: attribution.team_id,
recipe_name: attribution.recipe_name,
cron_job_id: attribution.cron_job_id,
// P2b (§5.4) — stable correlation so control-api can attach any
// danger-zone reservation to this task; `task.id` is stable for its life.
task_ref: task.id,
})
// P2b (§5.4) — remember tasks that carry a reservation so the terminal
// subscriber only issues a release for them. We key on reservationIds (not
// `allowed`): control-api self-releases reservations when it denies, so a
// denied verdict normally arrives with reservationIds=[] and is not tracked;
// tracking on the field stays correct even if a stray reservation survives.
if (verdict.reservationIds && verdict.reservationIds.length > 0) {
// Store the SAME host_ref the check used so the early release replays it
// verbatim (control-api binds the release to it and only drops matching
// reservations); the value is the per-instance host identity.
this.tasksWithBudgetReservation.set(task.id, hostCtx.host_ref)
}
return verdict
}
/**
* P1 token budgets (§5.3) — deliver a budget-denied verdict to the user
* through the SAME canonical failure path as any task error: responseCallback
* (channel / sync-POST / polling) + queue.failTask → lifecycle 'failed' (SSE
* terminal + queue 'task:failed' listener cleanup) + the agent 'task:failed'
* activity event. `reason` is the machine reason from control-api; the user
* sees the friendly message below.
*/
handleBudgetDenied(task: Task, reason?: string): void {
logger.warn({ taskId: task.id, reason: reason ?? 'budget_exceeded' }, 'Task denied by budget')
this.handleTaskFailure(task, {
code: 'BUDGET_EXCEEDED',
message: "This period's consumption budget has been reached. Please try again later.",
// Not retryable: the period spend will not have changed on an immediate
// retry, so it would just be denied again until the budget resets.
retryable: false,
provider: this.llmProvider?.getProviderType() ?? 'unknown',
})
}
/**
* P2b token budgets (§5.4) — early reservation release.
*
* Subscribes to the SINGLE canonical terminal sink: every task — completed,
* failed, cancelled, brake-tripped, or shutdown-drained — ends with a
* `lifecycle.transition` to a terminal state (queue.completeTask → 'completed',
* queue.failTask → 'failed', cancel/drain → 'cancelled'). Hooking the terminal
* transition therefore covers ALL branches uniformly, including the
* cancel-during-approval and brake paths that never reach the executor's
* onComplete/onFail callbacks.
*
* For tasks that carried a danger-zone reservation, it tells control-api to
* drop the reservation NOW instead of waiting for the TTL. Best-effort and
* fire-and-forget: it is never awaited on the terminal path, so it cannot
* delay the user's response, and `BudgetClient.release` is itself fail-open —
* a lost release just lets the reservation expire by TTL (§0.2). No-op when
* the budgets flag is off (the tracking map stays empty).
*/
private subscribeBudgetReleaseOnTerminal(): void {
this.lifecycle.on('transition', ev => {
if (!isTerminal(ev.to)) return
// Atomic check-and-remove: only release tasks we recorded a reservation
// for, and only once even if a terminal transition somehow re-fires. The
// stored value is the host_ref the check used, replayed on the release so
// control-api's claim-binding + host-scoping matches the reservation.
const hostRef = this.tasksWithBudgetReservation.get(ev.taskId)
if (hostRef === undefined) return
this.tasksWithBudgetReservation.delete(ev.taskId)
if (!this.budgetClient) return
// Fire-and-forget — NOT awaited. release() never throws (fail-open), but
// guard defensively so a rejected promise never becomes an unhandled one.
this.budgetClient.release({ task_ref: ev.taskId, host_ref: hostRef }).catch(() => undefined)
})
}
/**
* Phase 6: Set the approval configuration (from Host CRD or dev env).
*/
/** Guardrails block from the Host CRD (spec §5). Absent = no guardrails = today. */
setGuardrailsConfig(config: GuardrailsConfig | undefined): void {
this.guardrailsConfig = config
logger.info({ rules: config?.rules?.length ?? 0 }, 'Guardrails configured')
}
setApprovalConfig(config: ApprovalConfig | undefined): void {
this.approvalConfig = config
logger.info({ defaultPolicy: config?.defaultPolicy || 'none' }, 'Approval policy configured')
}
/**
* P.3 IronClaw invariant #3: install a cold-start loader. T2.1 calls this
* with the SqliteColdStartLoader; tests can inject a fake.
*/
setColdStartLoader(loader: ColdStartLoader): void {
this.coldStartLoader = loader
logger.info({ component: 'Agent' }, 'Cold-start loader set')
}
private buildApprovalBinding(
sourceMessage: Task['sourceMessage'] | undefined,
sessionKey?: string
): ApprovalDecisionBinding {
const parsed = sessionKey ? parseSessionKey(sessionKey) : null
return {
userId: sourceMessage?.sender ?? parsed?.userId,
channelType: sourceMessage?.channelType ?? parsed?.channelType,
channelId: sourceMessage?.channelId ?? parsed?.channelId,
sessionKey,
}
}
private validateApprovalDecisionBinding(
binding: ApprovalDecisionBinding,
userId: string,
channelType?: string,
channelId?: string
): string | null {
if (binding.userId && binding.userId !== userId) {
return 'Approval decision does not match the originating user'
}
// CLI approval routes historically carry the user/request ids only. Keep
// them valid for the original owner, while channel-aware routes must match
// the originating session channel below.
if (channelType === undefined && channelId === undefined) {
return null
}
if (binding.channelType && binding.channelType !== channelType) {
return 'Approval decision does not match the originating channel type'
}
if (binding.channelId && binding.channelId !== channelId) {
return 'Approval decision does not match the originating channel'
}
return null
}
private makeApprovalTimeout(
requestId: string,
expiresAt: number | undefined,
now: number
): ReturnType<typeof setTimeout> | undefined {
if (typeof expiresAt === 'number' && Number.isFinite(expiresAt)) {
return setTimeout(
() => {
this.handleApprovalTimeout(requestId)
},
Math.max(0, expiresAt - now)
)
}
if (this.config.approvalTimeout > 0) {
return setTimeout(() => {
this.handleApprovalTimeout(requestId)
}, this.config.approvalTimeout)
}
return undefined
}
/**
* T2.1: inject a custom `ConversationStore` (typically the SQLite-backed
* implementation built by `createConversationStore`). Must be called BEFORE
* `agent.bootstrap()` so the cold-start loader sees the durable store.
* Default is the in-memory store created in the ConversationManager
* constructor.
*/
setConversationStore(store: ConversationStore): void {
this.conversationManager.setStore(store)
logger.info({ component: 'Agent' }, 'Conversation store set')
}
/**
* P.3 IronClaw invariant #3: rehydrate `pending_approvals` from durable
* storage before any new messages are processed. Idempotent and safe to
* skip when the loader is the NoOp default (the case during P.3).
*
* MUST be awaited in main.ts before `start()` once T2.1 wires the real
* SqliteColdStartLoader, otherwise a user retry could race the rehydration
* and create duplicate approvals.
*/
async bootstrap(): Promise<void> {
const now = Date.now()
// D.2 PHASE 1 — reap sessions stuck in 'processing' (their reporter died
// with the previous pod) BEFORE accepting traffic. Idempotent; runs before
// approval rehydration so a session left in processing+pending isn't both
// reaped and rehydrated (disjoint sets: reap touches state='processing',
// approvals touch state='awaiting_approval'). Order is for clean logs.
if (typeof this.coldStartLoader.reapProcessingSessions === 'function') {
try {
const reaped = await this.coldStartLoader.reapProcessingSessions(now)
if (reaped.length > 0) {
logger.info({ count: reaped.length }, 'Processing sessions reaped on boot')
}
} catch (err) {
// A reap failure must not block boot; pending approvals still rehydrate.
logger.error({ err: err }, 'Processing reaper failed on boot:')
}
}
if (typeof this.coldStartLoader.reapExpiredAwaitingApprovalSessions === 'function') {
const reaped = await this.coldStartLoader.reapExpiredAwaitingApprovalSessions(now)
if (reaped.length > 0) {
logger.info({ count: reaped.length }, 'Expired approvals reaped on boot')
}
}
// PHASE 2 — reconstruct live executors before SessionProcessor accepts work.
const rehydrated = await this.coldStartLoader.loadPendingApprovals(now)
for (const entry of rehydrated) {
if (!entry.session_key) throw new Error('rehydrated approval is missing its session key')
// The persisted message has no inline file bytes (ResumeSourceMessage).
// Task carries the wider incoming type; the readers of file attachments
// check `dataBase64` at runtime (attachmentRead.ts) instead of assuming it.
const sourceMessage = entry.source_message as Task['sourceMessage']
const task: Task = {
id: entry.task_id,
source: 'channel',
sourceMessage,
traceContext: entry.approval.traceContext ?? null,
priority: 'normal',
status: 'waiting_approval',
conversationHistory: [],
createdAt: new Date(now),
}
const executor = this.createTaskExecutor(task)
await executor.rehydrateWaitingApproval(entry.session_key, entry.approval)
this.activeExecutors.set(task.id, executor)
this.approvalMap.set(entry.request_id, {
taskId: task.id,
registeredAt: new Date(now),
expiresAt: entry.expiresAt,
timerId: this.makeApprovalTimeout(entry.request_id, entry.expiresAt, now),
binding: this.buildApprovalBinding(sourceMessage, entry.session_key),
})
}
if (rehydrated.length > 0)
logger.info({ count: rehydrated.length }, 'Pending approval executors rehydrated')
}
/**
* Phase 6: Public accessor for the conversation manager.
*/
getConversationManager(): ConversationManager {
return this.conversationManager
}
/**
* Gap 3 resolution: Public accessor for the core SimpleEventEmitter.
*
* This emitter carries ALL 12 AgentEventType events through the typed
* SimpleEventEmitter (core layer), bridging agent-level events that
* previously only flowed through the Node.js EventEmitter.
*/
getCoreEvents(): SimpleEventEmitter {
return this.coreEvents
}
/**
* T1.1 — operator-triggered compaction (`POST /v1/runtime/compact`).
*
* The endpoint reaches the agent through this method; it constructs a
* one-shot `PressureContextManager` using the same deps that
* `TaskExecutor.buildLoopConfig` wires for in-loop compaction, runs
* `manage()` with `forceTier: 'summarize'`, and emits the same
* `context:compacted` event the in-loop path emits (P1-002 unified bus).
*
* Pre-flight:
* - 404 when the session does not exist.
* - 409 when `pending_approval !== undefined` (IronClaw invariant #1).
* - 409 when an executor is actively driving this session (it owns the
* snapshot — racing a manual compaction would cause a torn write).
*
* `_previousSummary` does NOT persist across calls in T1.1: every endpoint
* invocation builds a fresh manager. T2.1 (SQLite store) is what makes
* delta-patch survive cross-call (§18.4 of the plan). Today's
* compactSession() always produces a full re-summary.
*/
async compactSession(opts: {
sessionKey: string
focus?: string
useMainLlm?: boolean
}): Promise<
| { kind: 'ok'; before: number; after: number; focus: string | null }
| { kind: 'not_found' }
| { kind: 'pending_approval' }
| { kind: 'session_busy' }
| { kind: 'error'; message: string }
> {
const conv = this.conversationManager.getSessionByKey(opts.sessionKey)
if (!conv) {
return { kind: 'not_found' }
}
if (conv.pending_approval !== undefined) {
return { kind: 'pending_approval' }
}
// Refuse if any active executor owns this session — the executor's
// PressureContextManager is the source of truth while it's running.
for (const exec of this.activeExecutors.values()) {
if (exec.sessionKey === opts.sessionKey) {
return { kind: 'session_busy' }
}
}
// Refuse if another operator-triggered compaction is already in flight
// for this session. Without this, two overlapping `POST /v1/runtime/compact`
// calls would both pass the executor check, then race on
// `conv.compactionState` and on the daily-log append across the LLM await.
if (this.compactionsInFlight.has(opts.sessionKey)) {
return { kind: 'session_busy' }
}
if (!this.llmProvider) {
return { kind: 'error', message: 'LLM provider not initialized' }
}
this.compactionsInFlight.add(opts.sessionKey)
try {
// R2 — resolve the effective provider+model (and context window) for THIS
// session so the manual /compact adapter spends tokens under, and reports
// usage for, the session's selected model — not the process-wide default.
let compactProvider = this.llmProvider
let compactModel = this.modelName
let compactContextWindow: number | undefined
if (this.taskModelResolver) {
const resolved = this.taskModelResolver(conv.modelSelections)
if (resolved) {
compactProvider = resolved.provider
compactModel = resolved.model
compactContextWindow = resolved.contextWindowTokens
}
}
const tokenCounter = createTokenCounter(compactProvider, compactModel, {
offline: appConfig.tokenizerOffline,
})
const llmPort = new LlmPortAdapter(
compactProvider,
compactModel,
compactProvider.getProviderType(),
this.usageReporter,
this.usageStaticContext,
undefined,
tokenCounter,
// Operator-triggered /compact still spends LLM tokens on this session —
// count them toward the session's lifetime totals (crit #2).
usage => this.conversationManager.recordSessionUsage(conv, usage),
// #654 — the compaction summary is a real provider attempt: an image in
// the message history must be checked against this pair's capability
// instead of being dropped by a serializer that cannot carry it.
this.imageInputResolver ?? undefined
)
// R5 — apply provider-failover to the manual /compact port too, so an
// eligible provider error during compaction switches to a fallback and the
// summary call meters the pair really served (adapter-per-attempt).
const compactPort = this.wrapCompactFailover(llmPort, compactProvider, compactModel, conv)
const manager = new PressureContextManager(
resolveContextWindow(
compactProvider.getProviderType(),
compactContextWindow,
appConfig.contextMaxTokens
).contextWindowTokens,
this.workspaceProvider?.forSessionKey(opts.sessionKey),
compactPort,
tokenCounter,
{
dryRun: appConfig.tokenizerDryrun,
structuredSummaryEnabled: appConfig.compactionStructuredSummary,
events: this.coreEvents,
}
)
const messagesBefore = this.conversationManager.buildMessageHistory(conv)
const messagesAfter = await manager.manage(messagesBefore, conv, {
focus: opts.focus,
forceTier: 'summarize',
useMainLlm: opts.useMainLlm,
})
// P1-002 — unified `context:compacted` event so T2.2 (prompt cache
// invalidation) doesn't need to distinguish manual vs. in-loop
// compactions. The in-loop emitter lives in `toolUseLoop.ts:103,298`.
this.coreEvents.emit({
type: 'context:compacted',
data: {
conversationId: conv.id,
sessionKey: opts.sessionKey,
triggeredBy: 'operator',
focus: opts.focus ?? null,
before: messagesBefore.length,
after: messagesAfter.length,
},
timestamp: new Date(),
})
return {
kind: 'ok',
before: messagesBefore.length,
after: messagesAfter.length,
focus: opts.focus ?? null,
}
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
logger.error({ err: err }, 'compactSession failed:')
return { kind: 'error', message }
} finally {
this.compactionsInFlight.delete(opts.sessionKey)
}
}
/**
* Phase 6: Get pending approvals for the /status endpoint.
* Collects from all active executors in waiting_approval state.
*/
getPendingApprovals(): PendingApprovalInfo[] {
const approvals: PendingApprovalInfo[] = []
for (const executor of this.activeExecutors.values()) {
if (executor.executorState === 'waiting_approval' && executor.pendingApproval) {
const msg = executor.sourceTask.sourceMessage
const entry = this.approvalMap.get(executor.pendingApproval.request_id)
const approval = executor.pendingApproval
approvals.push({
requestId: approval.request_id,
userId: msg?.sender || 'anonymous',
toolName: approval.tool_name,
parameters: approval.parameters,
description: approval.description,
since: entry?.registeredAt?.toISOString() ?? new Date().toISOString(),
// U5 — thread the connect_required discriminator; omitted for generic
// approvals so the legacy shape is byte-identical (back-compat).
// mcpServerName rides ONLY connect_required, matching the SSE
// producer and the other polling projections (no stray field on a
// corrupt/legacy row whose reason normalized away).
...(approval.reason ? { reason: approval.reason } : {}),
...(approval.reason === 'connect_required' && approval.mcpServerName
? { mcpServerName: approval.mcpServerName }
: {}),
})
}
}
return approvals
}
/**
* Register an approval request with timeout timer.
* Called from TaskExecutor's onApprovalNeeded callback.
*/
private registerApproval(
requestId: string,
taskId: string,
task: Task,
approval: PendingApproval
): void {
const now = Date.now()
const expiresAt =
this.config.approvalTimeout > 0 ? now + this.config.approvalTimeout : undefined
const timerId = this.makeApprovalTimeout(requestId, expiresAt, now)
this.approvalMap.set(requestId, {
taskId,
timerId,
registeredAt: new Date(now),
expiresAt,
binding: this.buildApprovalBinding(task.sourceMessage),
})
this.enqueueTaskTrace(
task,
'approval',
`task:${taskId}:approval:${requestId}:requested`,
{
status: 'requested',
tool_name: approval.tool_name,
...(approval.tool_kind ? { tool_kind: approval.tool_kind } : {}),
...(approval.tool_source_ref ? { tool_source_ref: approval.tool_source_ref } : {}),
},
requestId
)
const trace = task.traceContext
const hostRef = this.usageStaticContext?.host_ref
if (trace?.sessionId && hostRef) {
void this.approvalPromptHistoryClient?.capture(
{
approvalRequestId: requestId,
runId: trace.runId,
hostRef,
sessionId: trace.sessionId,
origin: trace.origin,
prompt: approval.description,
},
this.secretEntriesProvider?.().map(entry => entry.value) ?? []
)
}
// Build notification and emit event
const msg = task.sourceMessage
const userId = msg?.sender || 'anonymous'
const notificationMsg = this.buildApprovalNotification(approval, userId, msg?.channelType)
logger.info({ toolName: approval.tool_name }, 'Tool requires approval')
this.emitEvent('tool:approval_needed', {
taskId,
toolName: approval.tool_name,
requestId: approval.request_id,
userId,
notification: notificationMsg,
// U5 — carry the connect_required discriminator down the polling chain
// (messageHandler → pendingTaskResults → handleTaskResult) so a REST poll
// reconstructs the connect suspension, matching the SSE `suspended` event.
// Omitted for generic approvals (back-compat).
...(approval.reason ? { reason: approval.reason } : {}),
// mcpServerName rides ONLY the connect_required discriminator, matching
// the SSE producer (sseProgressReporter) — so corrupt/legacy rows can never emit
// a stray field without its reason.
...(approval.reason === 'connect_required' && approval.mcpServerName
? { mcpServerName: approval.mcpServerName }
: {}),
})
}
/**
* Handle approval timeout: auto-deny the executor and clean up.
*/
private handleApprovalTimeout(requestId: string): void {
const entry = this.approvalMap.get(requestId)
if (!entry) return
const executor = this.activeExecutors.get(entry.taskId)
if (!executor || executor.executorState !== 'waiting_approval') return
logger.warn({ requestId }, 'Approval timed out; denying')
// Clean up coordinator state FIRST so transition subscribers always observe
// consistent state (PR-193 review #2). EventEmitter.emit() is synchronous;
// current subscribers filter ev.to !== 'cancelled' and early-exit, but a
// future subscriber reading approvalMap/activeExecutors on a non-cancel
// terminal would see stale entries.
this.approvalMap.delete(requestId)
this.activeExecutors.delete(entry.taskId)
this.releaseSessionForTask(executor.sourceTask)
// Now fire the lifecycle transition. Subscribers see clean coordinator state.
// Distinguishes timeout-triggered denial from user-triggered denial in the
// audit trail (PR-186 review M6). Subsequent transitions from executor.deny()'s
// downstream queue.completeTask become AlreadyTerminal no-ops.
this.lifecycle.transition(entry.taskId, 'completed', 'approval_timeout')
// deny() propagates denialMessage via responseCallback. Downstream
// queue.completeTask → lifecycle.transition('completed', 'natural') is
// AlreadyTerminal no-op. onComplete's activeExecutors.delete is a no-op
// (already deleted above).
//
// T2.1: deny() is now async (sync write-through to delete pending_approval
// before the channel notification fires). Fire-and-forget here so the
// timeout handler returns promptly; errors are logged. Wrap in
// Promise.resolve so legacy synchronous test doubles (which return void)
// still flow through the same path.
Promise.resolve(executor.deny()).catch(err => {
logger.error({ err: err }, `executor.deny() raised after timeout:`)
})
}
/**
* Phase 6: Handle an approval decision.
* Looks up by requestId -> approvalMap -> activeExecutors.
*/
async handleApproval(
userId: string,
requestId: string,
alwaysApprove: boolean,
channelType?: string,
channelId?: string
): Promise<{ success: boolean; error?: string }> {
const entry = this.approvalMap.get(requestId)
if (!entry) {
return { success: false, error: `No pending approval for request ${requestId}` }
}
const executor = this.activeExecutors.get(entry.taskId)
if (!executor || executor.executorState !== 'waiting_approval') {
this.approvalMap.delete(requestId)
return { success: false, error: 'Task is no longer awaiting approval' }
}
if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
this.handleApprovalTimeout(requestId)
return { success: false, error: 'Approval request has expired' }
}
const bindingError = this.validateApprovalDecisionBinding(
entry.binding,
userId,
channelType,
channelId
)
if (bindingError) {
return { success: false, error: bindingError }
}
// Clear timeout
if (entry.timerId) clearTimeout(entry.timerId)
this.approvalMap.delete(requestId)
// Emit approval granted event via emitEvent so it reaches BOTH the Node
// EventEmitter (where messageHandler.onApprovalConsumed subscribes to
// clear pendingTaskResults) AND coreEvents (where eventWiring subscribes
// to publish activity). Direct coreEvents.emit bypassed the Node EE, so
// PR #291's cache-clear listener never fired in production.
const pendingApproval = executor.pendingApproval
const toolName = pendingApproval?.tool_name || 'unknown'
this.enqueueTaskTrace(
executor.sourceTask,
'approval',
`task:${entry.taskId}:approval:${requestId}:approved`,
{
status: 'approved',
tool_name: toolName,
...(pendingApproval?.tool_kind ? { tool_kind: pendingApproval.tool_kind } : {}),
...(pendingApproval?.tool_source_ref
? { tool_source_ref: pendingApproval.tool_source_ref }
: {}),
},
requestId
)
this.emitEvent('tool:approval_granted', {
toolName,
requestId,
userId,
alwaysApprove,
taskId: entry.taskId,
})
// Resume execution (fire and forget).
// Session release happens in onComplete/onFail callbacks.
executor.resumeAfterApproval(alwaysApprove).catch(err => {
logger.error({ err: err }, `Resume after approval failed:`)
})
return { success: true }
}
/**
* Phase 6: Handle a denial decision.
* Looks up by requestId -> approvalMap -> activeExecutors.
*/
async handleDenial(
userId: string,
requestId: string,
channelType?: string,
channelId?: string
): Promise<{ success: boolean; error?: string }> {
const entry = this.approvalMap.get(requestId)
if (!entry) {
return { success: false, error: `No pending approval for request ${requestId}` }
}
const executor = this.activeExecutors.get(entry.taskId)
if (!executor || executor.executorState !== 'waiting_approval') {
this.approvalMap.delete(requestId)
return { success: false, error: 'Task is no longer awaiting approval' }
}
if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
this.handleApprovalTimeout(requestId)
return { success: false, error: 'Approval request has expired' }
}
const bindingError = this.validateApprovalDecisionBinding(
entry.binding,
userId,
channelType,
channelId
)
if (bindingError) {
return { success: false, error: bindingError }
}
// Clear timeout
if (entry.timerId) clearTimeout(entry.timerId)
this.approvalMap.delete(requestId)
const pendingApproval = executor.pendingApproval
const toolName = pendingApproval?.tool_name || 'unknown'
this.enqueueTaskTrace(
executor.sourceTask,
'approval',
`task:${entry.taskId}:approval:${requestId}:denied`,
{
status: 'denied',
tool_name: toolName,
...(pendingApproval?.tool_kind ? { tool_kind: pendingApproval.tool_kind } : {}),
...(pendingApproval?.tool_source_ref
? { tool_source_ref: pendingApproval.tool_source_ref }
: {}),
},
requestId
)
this.emitEvent('tool:approval_denied', {
toolName,
requestId,
userId,
taskId: entry.taskId,
})
// T2.1: deny() is now async. We await so the HTTP 200 only returns once
// the durable pending_approval row is gone (IronClaw write-through). A
// future restart cannot resurrect a phantom approval. Promise.resolve()
// wraps legacy synchronous test doubles.
try {
await Promise.resolve(executor.deny())
} catch (err) {
logger.error({ err: err }, `executor.deny() failed:`)
}
this.activeExecutors.delete(entry.taskId)
this.releaseSessionForTask(executor.sourceTask)
return { success: true }
}
/**
* Start the agent (begin processing tasks).
*/
start(): void {
if (this.isRunning) {
logger.info({ component: 'Agent' }, 'Already running')
return
}
logger.info({ component: 'Agent' }, 'Starting agent')
this.isRunning = true
// B5 — start the clear-pending-approval retry drain. Every 30s we try
// every entry whose `nextTry` has passed. The interval is `.unref()`'d
// so it doesn't keep the process alive on its own.
if (this.clearRetryTimer === null) {
this.clearRetryTimer = setInterval(() => {
this.drainClearPendingApprovalRetries()
}, 30_000)
this.clearRetryTimer.unref()
}
this.setState('idle')
}
/**
* Stop the agent (finish current tasks, then stop).
*/
async stop(): Promise<void> {
logger.info({ component: 'Agent' }, 'Stopping agent')
this.isRunning = false
// B5 — stop the clear-pending-approval retry drain. Anything still in
// the map will be re-loaded on next boot by `loadAllPendingApprovals`
// (and filtered by the B7 TTL guard if too old).
if (this.clearRetryTimer !== null) {
clearInterval(this.clearRetryTimer)
this.clearRetryTimer = null
}
// Shutdown drain — transition every non-terminal task to cancelled with
// reason='system_shutdown' (spec §5.7). This fires the same subscribers
// as a user cancel: executor.abort() for processing tasks, approval cleanup
// for waiting_approval, SSE emission for clients.
const drained = this.lifecycle.drainNonTerminal()
if (drained > 0) {
logger.info({ count: drained }, 'Shutdown cancelled non-terminal tasks')
}
// Clear all approval timers (drain already cleared the approvalMap entries
// for waiting_approval tasks; this is a defensive sweep for any residuals)
for (const [_requestId, entry] of this.approvalMap) {
if (entry.timerId) clearTimeout(entry.timerId)
}
this.approvalMap.clear()
// Await active executors with a bounded grace period (spec §5.7)
if (this.activeExecutors.size > 0) {
const gracePeriodMs = 10_000
await Promise.race([
Promise.all(Array.from(this.activeExecutors.values()).map(e => e.waitForCompletion())),
new Promise(r => setTimeout(r, gracePeriodMs)),
])
}
this.setState('idle')
}
/**
* Pause the agent (stop processing new tasks).
*/
pause(): void {
logger.info({ component: 'Agent' }, 'Pausing agent')
this.isRunning = false
this.setState('paused')
}
/**
* Resume the agent.
*/
resume(): void {
logger.info({ component: 'Agent' }, 'Resuming agent')
this.isRunning = true
this.setState('idle')
}
/**
* Get current agent state.
* Aggregate: priority waiting_approval > processing > idle.
*/
getState(): AgentState {
if (!this.isRunning) return this.state // respect paused/error
for (const exec of this.activeExecutors.values()) {
if (exec.executorState === 'waiting_approval') return 'waiting_approval'
}
if (this.activeExecutors.size > 0) return 'processing'
return this.state
}
/**
* Get agent statistics. Derived from TaskLifecycle for accuracy.
* Legacy fields totalToolCalls and lastTaskCompletedAt return stub values
* for wire-compat — they were removed in Phase E.
*/
getStats(): AgentStats {
const lifecycleStats = this.lifecycle.getStats()
return {
state: this.getState(),
currentTaskId:
this.activeExecutors.size > 0 ? (this.activeExecutors.keys().next().value ?? null) : null,
tasksProcessed: lifecycleStats.completed + lifecycleStats.failed + lifecycleStats.cancelled,
tasksSucceeded: lifecycleStats.completed,
tasksFailed: lifecycleStats.failed,
totalToolCalls: 0, // removed in Phase E — deprecated field; return 0 for wire-compat
uptime: Date.now() - this.startedAt.getTime(),
lastTaskCompletedAt: null, // removed in Phase E — deprecated; returns null
}
}
/**
* Execute a single task by delegating to a TaskExecutor.
* Creates executor, registers callbacks, and awaits run().
* Returns true if the task is suspended (awaiting approval), false otherwise.
*/
public async executeTask(task: Task): Promise<boolean> {
logger.info({ taskId: task.id }, 'Dispatching task')
if (!this.llmProvider) {
this.handleTaskFailure(task, {
code: 'LLM_API_CALL_FAILED',
message: 'LLM provider not initialized',
retryable: false,
provider: 'unknown',
})
return false
}
// #654 — a visual send carries the (provider, model) pair the user's UI
// validated when the image was accepted. That pair is server-owned
// (`IncomingMessage.imageModel`, populated after validation with the body
// already stripped) and it PINS this task: a later selection change must not
// redirect a queued image to another model.
const visualSelection = readVisualSelectionSnapshot(task)
let effectiveProvider = this.llmProvider
let effectiveModel = this.modelName
let effectiveContextWindow: number | undefined
if (this.taskModelResolver) {
try {
const sessionKey = resolveTaskSessionKey(task)
const existing = await this.conversationManager.getSessionByKeyAsync(sessionKey)
const resolved = this.taskModelResolver(
visualSelection
? { [visualSelection.provider]: visualSelection.model }
: existing?.modelSelections
)
if (resolved) {
effectiveProvider = resolved.provider
effectiveModel = resolved.model
effectiveContextWindow = resolved.contextWindowTokens
}
} catch (err) {
// A visual send is pinned: if resolution throws we must NOT silently run
// on the Host default, because that would send the validated image under
// a model the user never approved.
if (visualSelection) {
logger.warn(
{ taskId: task.id, err, requested: visualSelection },
'visual selection snapshot could not be resolved; failing the task'
)
this.handleTaskFailure(task, {
code: LlmErrorCode.ModelNotAvailable,
message:
`This message carries an image validated for ${visualSelection.provider}/${visualSelection.model}, ` +
'but the host could not resolve that model. Reselect the model or remove the image and send again.',
retryable: false,
provider: visualSelection.provider,
})
return false
}
logger.warn({ err: err }, 'per-task model resolution failed; using Host default:')
}
}
if (visualSelection) {
const effectiveProviderType = effectiveProvider.getProviderType()
if (
effectiveProviderType !== visualSelection.provider ||
effectiveModel !== visualSelection.model
) {
// NOTE: this pins the TASK's resolved model, not every physical attempt.
// A later policy-authorized failover may still serve another pair; that
// attempt is independently validated by the image-input guard in
// `LlmPortAdapter`, which checks the capability of the pair it sends.
logger.warn(
{
taskId: task.id,
requested: visualSelection,
effective: { provider: effectiveProviderType, model: effectiveModel },
},
'visual selection snapshot could not be honored; failing the task instead of redirecting the image'
)
this.handleTaskFailure(task, {
code: LlmErrorCode.ModelNotAvailable,
message:
`This message carries an image validated for ${visualSelection.provider}/${visualSelection.model}, ` +
`but the host would run it on ${effectiveProviderType}/${effectiveModel}. ` +
'Reselect the model or remove the image and send again.',
retryable: false,
provider: effectiveProviderType,
})
return false
}
}
const executor = this.createTaskExecutor(task, {
provider: effectiveProvider,
model: effectiveModel,
contextWindowTokens: effectiveContextWindow,
})
this.activeExecutors.set(task.id, executor)
try {
await executor.run()
} finally {
// Remove if completed/failed but NOT if waiting_approval
if (executor.executorState !== 'waiting_approval') {
this.activeExecutors.delete(task.id)
}
}
return executor.executorState === 'waiting_approval'
}
private createTaskExecutor(
task: Task,
effective?: {
provider: SingleTurnProvider
model: string
contextWindowTokens?: number
}
): TaskExecutor {
if (!this.llmProvider) throw new Error('LLM provider not initialized')
const gfsCallerRoot = this.gfsDownloadStore
? resolveCallerRootBinding(this.gfsWorkspaceProvider, task.sourceMessage)
: {}
if (gfsCallerRoot.failureCode) {
logger.warn(
{
component: 'Agent',
event: 'gfs_caller_root_unavailable',
code: gfsCallerRoot.failureCode,
taskId: task.id,
},
'Managed GFS caller root unavailable; managed file and shell tools fail closed'
)
}
return new TaskExecutor(task, {
conversationManager: this.conversationManager,
llmProvider: effective?.provider ?? this.llmProvider,
mcpManager: this.mcpManager,
workspaceService: this.workspaceProvider?.forSource(task.sourceMessage),
gfsDownloadStore: this.gfsDownloadStore,
gfsCallerWorkspacePath: gfsCallerRoot.root,
config: this.config,
modelName: effective?.model ?? this.modelName,
contextWindowTokens: effective?.contextWindowTokens,
approvalConfig: this.approvalConfig,
guardrailsConfig: this.guardrailsConfig,
coreEvents: this.coreEvents,
cronScheduler: this.cronScheduler,
taskLifecycle: this.lifecycle,
dynamicEnvProvider: this.dynamicEnvProvider,
secretEntriesProvider: this.secretEntriesProvider,
usageReporter: this.usageReporter,
usageStaticContext: this.usageStaticContext,
governedRunReporter: this.governedRunReporter,
spilloverStorage: this.spilloverStorage,
promptCache: this.promptCache,
sessionSearchService: this.sessionSearchService,
// R5 — resolved per task (reads live policy/engine from main.ts). Absent →
// no failover.
failover: this.failoverSupportProvider?.() ?? undefined,
imageInput: this.imageInputResolver ?? undefined,
onApprovalNeeded: (requestId, taskId, approval) => {
this.registerApproval(requestId, taskId, task, approval)
},
onComplete: t => {
this.enqueueTaskTrace(t, 'run_end', `task:${t.id}:end`, { status: 'succeeded' })
this.activeExecutors.delete(t.id)
this.releaseSessionForTask(t)
this.queue.completeTask(t)
this.emitEvent('task:completed', { task: t })
},
onFail: (t: Task, error: TaskError, attachments?: Attachment[]) => {
this.enqueueTaskTrace(t, 'run_end', `task:${t.id}:end`, {
status: 'failed',
error_class: error.code,
})
this.activeExecutors.delete(t.id)
this.releaseSessionForTask(t)
this.handleTaskFailure(t, error, attachments)
},
})
}
private enqueueTaskTrace(
task: Task,
eventType: 'approval' | 'run_end',
sourceEventId: string,
payload: {
status: string
tool_name?: string
tool_kind?: 'internal_tool' | 'mcp_server_tool' | 'workflow'
tool_source_ref?: string
error_class?: string
},
approvalRequestId?: string
): void {
const trace = task.traceContext
const hostRef = this.usageStaticContext?.host_ref
if (!trace || !hostRef) return
this.governedRunReporter?.enqueue({
sourceEventId,
occurredAt: new Date().toISOString(),
eventType,
runId: trace.runId,
approvalRequestId,
hostRef,
sessionId: trace.sessionId ?? null,
origin: trace.origin,
payload,
})
}
/**
* Phase 6: Build a human-readable approval notification message.
*/
private buildApprovalNotification(
approval: PendingApproval,
_userId: string,
channelType?: string
): string {
const workflowName =
approval.tool_name === 'workflow_trigger' && typeof approval.parameters.name === 'string'
? approval.parameters.name.trim()
: ''
const paramSummary =
Object.keys(approval.parameters).length > 0
? JSON.stringify(approval.parameters).substring(0, 200)
: 'none'
// Check if the user's channel can approve
const canApproveViaChannel =
this.approvalConfig && this.approvalConfig.defaultPolicy !== 'cli_only'
if (workflowName && canApproveViaChannel) {
return [
`Approval needed to run workflow ${workflowName}.`,
channelType === 'slack'
? 'Use the approval buttons to continue or cancel.'
: 'Reply /approve to continue or /deny to cancel.',
].join(' ')
}
if (workflowName) {
return [
`Approval needed to run workflow ${workflowName}.`,
'Please approve through the configured approval channel.',
].join(' ')
}
if (approval.description === STATELESS_CRON_APPROVAL_PROMPT) {
// Cron×stateless gate: the user must see the cost consequence, not
// the generic tool-approval line. Parameters stay visible for
// transparency; the approve/deny instructions mirror the generic paths.
return (
`${approval.description} ` +
`Parameters: ${paramSummary}. ` +
(canApproveViaChannel
? channelType === 'slack'
? 'Use the approval controls to continue or cancel.'
: 'Reply /approve or /deny to this message.'
: `Request ID: ${approval.request_id}. Please approve via CLI: POST /v1/runtime/approvals/approve`)
)
}
if (canApproveViaChannel) {
return (
`Tool \`${approval.tool_name}\` requires approval. ` +
`Parameters: ${paramSummary}. ` +
(channelType === 'slack'
? `Use the approval controls to continue or cancel.`
: `Reply /approve or /deny to this message.`)
)
}
return (
`Tool \`${approval.tool_name}\` requires approval. ` +
`Parameters: ${paramSummary}. ` +
`Request ID: ${approval.request_id}. ` +
`Please approve via CLI: POST /v1/runtime/approvals/approve`
)
}
/**
* Release a suspended session in the SessionProcessor after approval resolves.
*/
private releaseSessionForTask(task: Task): void {
if (!this.sessionProcessor?.releaseSuspendedSession) return
const msg = task.sourceMessage
const sessionKey = serializeSessionKey({
userId: msg?.sender || 'anonymous',
channelType: msg?.channelType || 'internal',
channelId: msg?.channelId || 'default',
threadId: msg?.threadId,
})
this.sessionProcessor.releaseSuspendedSession(sessionKey)
}
/**
* Handle task failure — the single delivery point for user-visible errors.
*/
private handleTaskFailure(task: Task, error: TaskError, attachments?: Attachment[]): void {
logger.error(
{ taskId: task.id, code: error.code, retryable: error.retryable, provider: error.provider },
'Task failed'
)
// Deliver to user via canonical callback — this is the core bug fix.
// Previously responseCallback was never called on failure.
if (task.responseCallback) {
task
.responseCallback({ error, ...(attachments?.length ? { attachments } : {}) })
.catch(cbErr => {
logger.error({ err: cbErr }, `responseCallback threw on failure delivery:`)
})
}
// §5.3.1 — guarantee a registered SSE reporter BEFORE the terminal transition
// for failures that never reached the executor (budget deny, null llmProvider,
// any pre-executor path). The executor is the only OTHER place that constructs
// a reporter; when a task fails before it exists, no reporter is subscribed to
// the lifecycle, so the terminal SSE event is lost and the desktop stream hangs
// on `waitFor(taskId, 180_000)` for the full timeout. Creating one here (which
// registers it → wakes the blocked waiter as a microtask) means the reporter is
// subscribed when the synchronous failTask→transition('failed') below fires, so
// it buffers/emits the terminal in ~0ms instead of ~180s.
//
// Guard (CRITICAL, anti-leak): only create when the task is NOT already
// terminal. If it were, the following transition returns already_terminal and
// the reporter's lifecycle handler never emits a terminal → the fresh reporter
// keeps completedAt=Infinity and is never evicted by the TTL sweep (reporter +
// lifecycle-listener leak). Idempotent for the executor path: a reporter that
// already exists is returned as-is (no duplicate, no double terminal).
//
// Fail-open: on any error we log and fall through — the durable result was
// already stored above and failTask still runs, so the worst case degrades to
// the pre-fix ~180s poll, never worse.
try {
// Only create a reporter when a COMPLETING terminal transition will follow:
// the task must be registered AND not-yet-terminal. `isTerminal` alone
// returns false for an unregistered task too, whose failTask→transition
// returns not_found (no emit) — a reporter created then would keep
// completedAt=Infinity and never be evicted by the TTL sweep (leak).
const record = this.lifecycle.get(task.id)
if (record && !this.lifecycle.isTerminal(task.id)) {
ensureReporter(task.id, this.lifecycle, new BasicSafety(this.secretEntriesProvider))
}
} catch (err) {
logger.error({ err: err }, 'ensure progress reporter failed')
}
// Terminal SSE emission is handled by SseProgressReporter's lifecycle subscription.
// queue.failTask calls lifecycle.transition('failed'), which SseProgressReporter
// intercepts to emit the typed 'terminal' event automatically.
this.queue.failTask(task, error)
this.emitEvent('task:failed', { task, error })
}
/**
* Subscribe to TaskLifecycle transition events. On `to='cancelled'`, route to the
* appropriate cleanup branch (processing or waiting_approval).
*
* Wrapped in try/catch per Invariant I11: Node EventEmitter.emit() halts on the
* first thrown error. A throwing subscriber would stall terminal SSE emission
* (B.5 adds SseProgressReporter as a later subscriber). Log + swallow.
*
* Processing branch: executor.abort() signals the AbortController. The tool-use
* loop exits at its next checkpoint, and run()'s finally block handles
* activeExecutors.delete — do NOT delete here.
*
* Waiting-approval branch: executor.run() has already returned (suspended), so
* run()'s finally will NOT re-fire. We must do ALL cleanup here.
*/
private subscribeLifecycle(): void {
this.lifecycle.on('transition', ev => {
if (ev.to !== 'cancelled') return
const executor = this.activeExecutors.get(ev.taskId)
if (!executor) return
try {
if (executor.pendingApproval) {
// Waiting-approval branch: executor.run() has already returned (suspended).
// We must do ALL cleanup here — the finally block in run() will not re-fire.
const reqId = executor.pendingApproval.request_id
const entry = this.approvalMap.get(reqId)
if (entry?.timerId) clearTimeout(entry.timerId)
this.approvalMap.delete(reqId)
const msg = executor.sourceTask.sourceMessage
const sessionKey = serializeSessionKey({
userId: msg?.sender || 'anonymous',
channelType: msg?.channelType || 'internal',
channelId: msg?.channelId || 'default',
threadId: msg?.threadId,
})
this.conversationManager.cancelTurnBySessionKey(sessionKey)
// T2.1: clearPendingApproval is async (IronClaw write-through for
// the cancel-during-approval path). B5 — wrapped in a bounded
// retry queue so transient SQLite failures don't leave an orphan
// pending_approval row. `tryClearPendingApproval` is fire-and-
// forget by design (the lifecycle subscriber is sync); the retry
// timer drains pending failures.
this.tryClearPendingApproval(sessionKey)
this.releaseSessionForTask(executor.sourceTask)
executor.abort() // defensive; no-op while suspended
this.activeExecutors.delete(ev.taskId) // explicit — no finally will run
return
}
// Processing branch: executor is in the tool-use loop.
// run()'s finally block handles activeExecutors.delete after the loop exits.
executor.abort()
} catch (err) {
logger.error({ taskId: ev.taskId, err }, 'Lifecycle cleanup failed')
// Invariant I11: do NOT re-throw; SseProgressReporter must still fire
}
})
}
// ─── B5 — clear-pending-approval retry queue ────────────────────────────
/** Max number of attempts before we drop a clearPendingApproval entry
* and rely on the cold-start TTL filter (B7) as last-resort cleanup. */
private static readonly CLEAR_RETRY_MAX_ATTEMPTS = 10
/** Base backoff (ms). Each retry waits `base * 2^(attempt-1)`, capped at 1h. */
private static readonly CLEAR_RETRY_BASE_MS = 5_000
private static readonly CLEAR_RETRY_CAP_MS = 3_600_000
/**
* Attempt to clear a pending approval and enqueue a retry on failure.
* Replaces the legacy fire-and-forget `.catch(log)` pattern so transient
* SQLite errors don't silently leak orphan `pending_approval` rows that
* cold-start would later resurrect.
*/
private tryClearPendingApproval(sessionKey: string): void {
this.conversationManager
.clearPendingApproval(sessionKey)
.then(() => {
// Success — drop any prior retry bookkeeping.
this.clearPendingApprovalRetries.delete(sessionKey)
})
.catch(err => {
this.scheduleClearRetry(sessionKey, err)
})
}
private scheduleClearRetry(sessionKey: string, lastErr: unknown): void {
const prior = this.clearPendingApprovalRetries.get(sessionKey)
const attempts = (prior?.attempts ?? 0) + 1
if (attempts > AgentStateMachine.CLEAR_RETRY_MAX_ATTEMPTS) {
logger.error(
{
attempts: attempts - 1,
err: lastErr instanceof Error ? lastErr : new Error('Non-error persistence failure'),
},
'Approval cleanup exhausted retries; awaiting cold-start recovery'
)
this.clearPendingApprovalRetries.delete(sessionKey)
return
}
const backoff = Math.min(
AgentStateMachine.CLEAR_RETRY_BASE_MS * 2 ** (attempts - 1),
AgentStateMachine.CLEAR_RETRY_CAP_MS
)
const nextTry = Date.now() + backoff
this.clearPendingApprovalRetries.set(sessionKey, { attempts, nextTry })
logger.warn(
{
attempts,
backoffMs: backoff,
err: lastErr instanceof Error ? lastErr : new Error('Non-error persistence failure'),
},
'Approval cleanup failed; retry scheduled'
)
}
private drainClearPendingApprovalRetries(): void {
if (this.clearPendingApprovalRetries.size === 0) return
const now = Date.now()
for (const [sessionKey, entry] of this.clearPendingApprovalRetries) {
if (entry.nextTry > now) continue
// Re-attempt. `tryClearPendingApproval` either deletes the entry on
// success or re-schedules via `scheduleClearRetry`.
this.tryClearPendingApproval(sessionKey)
}
}
/**
* Set the agent state.
*/
private setState(newState: AgentState): void {
if (this.state === newState) return
const oldState = this.state
this.state = newState
logger.info({ oldState, newState }, 'Agent state changed')
this.emitEvent('state:changed', { oldState, newState })
}
/** Agent-level events that should also be bridged to the core SimpleEventEmitter. */
private static readonly BRIDGED_EVENT_TYPES = new Set([
'state:changed',
'task:completed',
'task:failed',
'task:started',
'tool:approval_granted',
'tool:approval_denied',
])
private emitEvent(type: AgentEventType, data: unknown): void {
const event: AgentEvent = {
type,
data,
timestamp: new Date(),
}
this.emit(type, event)
this.emit('event', event)
if (AgentStateMachine.BRIDGED_EVENT_TYPES.has(type)) {
this.coreEvents.emit({
type: type as CoreAgentEventType,
data: data as Record<string, unknown>,
timestamp: event.timestamp,
})
}
}
}