Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* TaskExecutor — runs a single task through the LLM tool-use loop.
*
* Disposable: created per task by AgentStateMachine, discarded on completion.
* Holds per-task state (task, conversation, tool count) that was previously
* singleton on the AgentStateMachine.
*/
import { randomUUID } from 'node:crypto'
import { snapshotTaskTokenBaseline } from '../budget/taskBrake'
import type { TaskTokenBaseline } from '../budget/taskBrake'
import { BRIDGE_TOOL_NAMES } from '../capabilities/toolCatalogTools'
import { config as appConfig } from '../config'
import { bindTaskSignal, withAbort } from '../core/adapters/abortableLlmPort'
import { maybeWrapFailover } from '../core/adapters/failoverLlmPort'
import { maybeWrapHookedLlmPort } from '../core/adapters/hookedLlmPort'
import { AdapterStaticContext, LlmPortAdapter } from '../core/adapters/llmPortAdapter'
import { CompositeToolRegistry, McpToolRegistryAdapter } from '../core/adapters/toolRegistryAdapter'
import {
AttachmentReadLedger,
mergeAttachmentReadLedgerSnapshots,
readAttachmentReadLedgerSnapshot,
} from '../core/attachments/attachmentReadBudget'
import { compactConversation } from '../core/conversation/compaction'
import { ConversationManager } from '../core/conversation/conversation'
import { deriveAutoTitle } from '../core/conversation/sessionTitle'
import { LlmError, LlmErrorCode } from '../core/errors'
import { ApprovalController } from '../core/extensions/approvalController'
import type { ApprovalConfig } from '../core/extensions/approvalTypes'
import {
COMPACTION_PRESSURE_THRESHOLD,
PressureContextManager,
tierDecisionTokens,
toolMessageBudgetTokens,
} from '../core/extensions/contextManager'
import {
UnifiedApprovalGateController,
buildConnectRequiredApproval,
extractConnectRequiredMarker,
} from '../core/extensions/mcpApprovalGateController'
import { type GuardrailsConfig, buildToolLaneGuardrail } from '../core/guardrails'
import type { AgentEventEmitter, LlmPort, LoopController, ToolRegistry } from '../core/interfaces'
import { DeferrableToolController } from '../core/orchestration/deferrableToolController'
import type { SimpleEventEmitter } from '../core/orchestration/eventEmitter'
import { buildLoopConfig } from '../core/orchestration/loopConfig'
import type { LoopConfig } from '../core/orchestration/loopConfig'
import { DefaultLoopController } from '../core/orchestration/loopConfig'
import { NativeToolPresentationController } from '../core/orchestration/nativeToolPresentationController'
import type { SpilloverResolver } from '../core/orchestration/spilloverResolver'
import { StubSpilloverResolver } from '../core/orchestration/spilloverResolver'
import {
resolveToolPresentation,
selectDeferredNatives,
} from '../core/orchestration/toolPresentationPolicy'
import {
buildOutputPreview,
executeSingleTool,
extractInputPreview,
runToolUseLoop,
validateToolLinkages,
} from '../core/orchestration/toolUseLoop'
import {
collectToolAttachments,
mergeCollectedAttachments,
} from '../core/orchestration/toolUseLoopMessages'
import { turnStopResult } from '../core/orchestration/toolUseLoopRuntime'
import {
type PreparedGfsFile,
attachedFilesForTurnContext,
buildTurnContextBlock,
} from '../core/orchestration/turnContext'
import { DefaultReasoningFactory } from '../core/reasoning'
import {
CAPABILITY_CONTRACT_TEXT,
DESKTOP_ENVIRONMENT_HINT,
DefaultPromptBuilder,
GFS_WORKSPACE_FILE_GUIDANCE_TEXT,
MCP_SERVER_SELECTION_TEXT,
MEMORY_GUIDANCE_TEXT,
WORKFLOW_RECIPES_TEXT,
toolDiscoveryText,
} from '../core/reasoning/promptBuilder'
import type { SystemPromptParts } from '../core/reasoning/systemPrompt'
import { BasicSafety } from '../core/safety/safety'
import type { SessionSearchService } from '../core/sessionSearch'
import { FsSpilloverResolver, SpilloverStorage } from '../core/spillover'
import { createTokenCounter } from '../core/tokenizer'
import type { TokenCounter } from '../core/tokenizer/tokenCounter'
import { registerDesktopTools } from '../core/tools/desktopTools'
import { NativeToolRegistry } from '../core/tools/nativeToolRegistry'
import { WorkflowBrokerClient } from '../core/tools/workflowBrokerClient'
import {
requestEffectiveWorkflowList,
resolveEffectiveWorkflowTarget,
} from '../core/tools/workflowEffectiveTargets'
import type { WorkflowCallerContext } from '../core/tools/workflowShared'
import { createWorkflowControlTokenProvider } from '../core/tools/workflowTokenProvider'
import type {
AgentEvent,
Attachment,
ChatMessage,
Conversation,
LoopResult,
MessageContentPart,
PendingApproval,
ToolDefinition,
ToolResult,
} from '../core/types'
import { ApprovalExpiredError } from '../core/types'
import { prependTextToParts, textContentFromParts } from '../core/types'
import type { UsageContext } from '../core/types'
import type { GfsDownloadStore } from '../internalTools/gfsDownloadStore'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import type { SingleTurnProvider } from '../llm'
import type { ImageInputResolver } from '../llm/imageInput'
import type { PromptCache } from '../llm/promptCache'
import { stampStableHashGauge } from '../llm/promptCacheMetrics'
import { descriptorFor, isLlmProvider, resolveContextWindow } from '../llm/registryCore'
import { logger } from '../logger'
import type { McpManager } from '../mcp'
import { getDisplayName, sanitizeError } from '../progress/intentExtraction.js'
import {
SseProgressReporter,
ensureReporter,
progressReporterRegistry,
} from '../progress/sseProgressReporter.js'
import type { Task, TaskError, TaskSource } from '../queue/types'
import { resolveCronTaskSessionKey, serializeSessionKey } from '../session'
import { GovernedRunReporter, UsageReporter } from '../usage/usageReporter.js'
import { resolveProviderWorkflowCallerContext } from '../workflow/providerWorkflowCallerContextClient'
import type { Workspace } from '../workspace/service'
import { attachmentContextWindow } from './attachmentContextWindow'
import type { CronScheduler } from './cronScheduler'
import { referencedFilesForTurnContext } from './fileReferenceResolver'
import {
gfsManagedWorkspaceExecution,
gfsStoreCallerIdentity,
gfsWorkspaceExecutionEnabled,
} from './gfsExecutionCapability'
import { hasLargeAvailableGfsReferences, prepareGfsFiles } from './gfsFilePreparation'
import {
type ProviderWorkflowAccessDenialReason,
isProviderWorkflowChannel,
looksLikeWorkflowAccessRequest,
looksLikeWorkflowTriggerRequest,
looksLikeWorkflowTriggerSuccess,
workflowAccessDeniedResponseForMessage,
} from './providerWorkflowAccessGate'
import { sourceMessageForResume } from './sourceMessageForResume'
import { TaskExecutionBudget, TaskLimitError } from './taskExecutionBudget'
import { TurnTimingRecorder } from './turnTiming'
import type { AgentConfig, ExecutorFailoverSupport } from './types'
export type ExecutorState = 'processing' | 'waiting_approval' | 'completed' | 'failed'
/**
* R2 — the serialized session key a task runs under. Extracted so the agent's
* per-task model resolver (`executeTask`) reads the SAME key the executor's
* `run()` uses for `getOrCreate`. INVARIANT: for `source==='cron'` this MUST
* agree with the key `cronDispatch.ts` enqueued under.
*/
export function resolveTaskSessionKey(task: Task): string {
const msg = task.sourceMessage
const cronSession = task.source === 'cron' ? resolveCronTaskSessionKey(task) : undefined
return serializeSessionKey(
cronSession ?? {
userId: msg?.sender || 'anonymous',
channelType: msg?.channelType || 'internal',
channelId: msg?.channelId || 'default',
threadId: msg?.threadId,
}
)
}
/**
* §6.3 — is there a human who can answer a guardrail `ask` in this run?
*
* Only `channel` tasks have one: a person is on the other end of the message that
* started them (including channelType `rpc`, the Desktop App). `cron` fires on a
* schedule and `internal` is a system-generated task with no requester, so an
* `ask` there would suspend into `pending_approval` with nobody able to respond —
* the task hangs. Unattended turns that into the fail-safe deny instead.
*
* Deliberately an allowlist of the attended source, not a denylist of the
* autonomous ones: a source added later defaults to "assume nobody is watching",
* which fails closed. The previous `source === 'cron' ? ... : 'interactive'` had
* the opposite default and already mislabelled `internal`.
*/
export function executionModeForSource(source: TaskSource): 'interactive' | 'unattended' {
return source === 'channel' ? 'interactive' : 'unattended'
}
/**
* The caller root generated files go under. A message with no sender would
* share one folder with every other sender-less message on its channel, so it
* gets none and the generators refuse to write. A task with no message at all
* (cron, system) keeps the reserved system folder.
*/
export function generatedOutputsRoot(
sourceMessage: Task['sourceMessage'],
callerRoot: string | undefined
): string | undefined {
if (sourceMessage && !(sourceMessage.sender ?? '').trim()) return undefined
return callerRoot
}
export interface TaskExecutorDeps {
conversationManager: ConversationManager
llmProvider: SingleTurnProvider
mcpManager: McpManager | null
workspaceService: Workspace | undefined
/** Host-owned store shared across tasks; task registries receive caller-bound handles. */
gfsDownloadStore?: GfsDownloadStore
/** Trusted caller workspace root, separate from memory-tool availability. */
gfsCallerWorkspacePath?: string
config: AgentConfig
modelName: string
/**
* R2 — context-window override for the effective model, read from the
* allowlist entry by the per-task resolver. Feeds the reasoning-factory
* breakdown denominator and the PressureContextManager budget. Undefined →
* fall back to `CLERUM_CONTEXT_MAX_TOKENS` (today's behaviour).
*/
contextWindowTokens?: number
approvalConfig: ApprovalConfig | undefined
guardrailsConfig?: GuardrailsConfig
coreEvents: SimpleEventEmitter
cronScheduler: CronScheduler | null
taskLifecycle: TaskLifecycle
/**
* Returns operator-managed env vars (ConfigStore snapshot) for the
* shell-tool spawn-time merge. Optional — falls back to {} when omitted.
*/
dynamicEnvProvider?: () => Record<string, string>
/**
* Returns ConfigStore-managed secret name/value pairs for the output
* sanitizer to redact from tool output. Optional — falls back to no
* extra redaction when omitted.
*/
secretEntriesProvider?: () => Array<{ name: string; value: string }>
/**
* Optional usage reporter + static host context. When both are present,
* every successful LLM round-trip enqueues an LlmUsageEvent. Absent in
* dev mode and in tests.
*/
usageReporter?: UsageReporter
usageStaticContext?: AdapterStaticContext
governedRunReporter?: GovernedRunReporter
/**
* IronClaw invariant #2 (P.3 + T1.5): resolver for spillover refs in the
* approval snapshot. Defaults to a fresh `FsSpilloverResolver` against
* `spilloverStorage` if provided, else `StubSpilloverResolver` (passthrough
* for inline content, throw for refs — useful for tests).
*/
spilloverResolver?: SpilloverResolver
/**
* T1.5 — Tool-result spillover. When set, oversized tool outputs are
* persisted out-of-band and the `tool` message ships a rich summary plus
* the `spillover_ref` URI. Also drives `clerum__spillover_read` registration
* in the native tool registry and the resolver default above.
*/
spilloverStorage?: SpilloverStorage
/**
* T2.2 — Process-wide system-prompt cache. When set together with
* `appConfig.promptCacheEnabled`, `buildLoopConfig` consults the cache
* (keyed by sessionKey) to fetch the tiered `SystemPromptParts` and
* forwards them to the cache-aware path of the LLM port. Absent in tests
* and when the flag is OFF.
*/
promptCache?: PromptCache
/**
* T3.1 — backend for `clerum__session_search`. When set together with a
* `sourceMessage`, the tool is registered in the native registry. Absent
* when the SQLite store is disabled (memory mode) or when the feature
* flag `CLERUM_SESSION_SEARCH_ENABLED` is OFF.
*/
sessionSearchService?: SessionSearchService
/**
* R5 — provider-fallback support for THIS task. When present with a non-empty
* `policy.fallbacks`, `buildLoopConfig` wraps the primary `LlmPort` so an
* eligible provider error switches to the next fallback (adapter-per-attempt
* so `usage_events` records the pair really served). Absent → no failover.
*/
failover?: ExecutorFailoverSupport
/**
* Issue #654 — live-catalog image-input capability lookup, keyed by the
* (provider, model) the adapter is about to send. Threaded to the primary
* port AND every failover adapter so the guard checks the pair that really
* runs. Absent → images fail closed with `LLM_IMAGE_INPUT_UNKNOWN` and
* text-only turns are unchanged.
*/
imageInput?: ImageInputResolver
// Callbacks to coordinator
onApprovalNeeded: (requestId: string, taskId: string, approval: PendingApproval) => void
onComplete: (task: Task) => void
onFail: (task: Task, error: TaskError, attachments?: Attachment[]) => void
}
interface TaskToolRegistry {
registry: ToolRegistry
nativeRegistry: NativeToolRegistry
loopController: LoopController
/** Natives hidden from `tools[]` by native `auto`; empty in `direct`. */
discoverableNatives: ToolDefinition[]
bridge?: LoopConfig['bridge']
}
export class TaskExecutor {
private readonly responseSafety: BasicSafety
readonly taskId: string
private task: Task
private conversation: Conversation | null = null
private state: ExecutorState = 'processing'
private deps: TaskExecutorDeps
private abortController = new AbortController()
private readonly executionBudget: TaskExecutionBudget
private legacyApprovalBudget = false
private readonly completedAttachments: Attachment[] = []
private toolRegistryPromise: Promise<TaskToolRegistry> | null = null
private preparedGfsFiles: PreparedGfsFile[] = []
private readonly spilloverResolver: SpilloverResolver
/**
* P.2 token counter. Built lazily on the first call to
* `getOrCreateTokenCounter()` and shared across `runAgentLoop`,
* `LlmPortAdapter`, and `PressureContextManager` so `recordObservedUsage`
* accumulates across iterations of the same task.
*/
private tokenCounter: TokenCounter | null = null
/** #731 — the task's context window, resolved and logged once. */
private contextWindow: number | null = null
/**
* C15/C16 — one turn-owned attachment read ledger per executor. An executor
* runs one task, and a task is one turn, so the ledger starts zeroed and is
* never reset. The native tool registry is memoized for the life of this
* executor, so the tool holds THIS instance by reference and the ledger
* mutates in place; `restore()` loads the persisted snapshot on an approval
* resume that continues the same turn.
*/
private readonly attachmentReadLedger = new AttachmentReadLedger()
/**
* P2 token budgets (§5.2) — snapshot of the conversation's lifetime token
* counters captured at task start, used as the per-task brake baseline.
* Set in `run()` (once per task) only when the P1 verdict carried a per-task
* cap; reused unchanged across `resumeAfterApproval`. `null` → brake disabled.
*/
private taskTokenBaseline: TaskTokenBaseline | null = null
private workflowCallerContextOverride: WorkflowCallerContext | null | undefined
private workflowAccessDeniedResponse: string | null = null
private workflowAccessDeniedReason: ProviderWorkflowAccessDenialReason | null = null
private currentTurnToolNames = new Set<string>()
private gfsRetentionOwnerSettlement: Promise<void> | undefined
/**
* Latency attribution (stateless-agents): per-turn phase timing. Created at
* run() start; emits one [TurnTiming] info line when the task completes.
* Purely observational — never affects control flow (fail-safe recorder).
*/
private turnTiming: TurnTimingRecorder | null = null
// Completion tracking for graceful shutdown
private resolveCompletion: (() => void) | null = null
private completionPromise: Promise<void>
constructor(task: Task, deps: TaskExecutorDeps) {
this.task = task
this.taskId = task.id
this.deps = deps
this.executionBudget = new TaskExecutionBudget(
deps.config.maxTaskDuration,
deps.config.maxToolCallsPerTask
)
this.responseSafety = new BasicSafety(deps.secretEntriesProvider)
// T1.5 — prefer a caller-supplied resolver (tests/mocks); else build the
// FS-backed one from the storage; else fall back to the P.3 stub so
// dev/test paths without spillover wired still work.
this.spilloverResolver =
deps.spilloverResolver ??
(deps.spilloverStorage
? new FsSpilloverResolver({ storage: deps.spilloverStorage })
: new StubSpilloverResolver())
this.completionPromise = new Promise<void>(resolve => {
this.resolveCompletion = resolve
})
}
get executorState(): ExecutorState {
return this.state
}
get pendingApproval(): PendingApproval | undefined {
return this.conversation?.pending_approval
}
private approvedToolCorrelation: { toolCallId: string; approvalRequestId: string } | undefined
/**
* The serialized session key this executor owns (the store's LRU/evict key,
* `<userId>:<channelType>:<channelId>[:<threadId>]`). Exposed so callers
* (e.g. `AgentStateMachine.compactSession`) can detect "this session is
* currently owned by an executor" without reaching into the private
* conversation field.
*
* MUST agree with the key the store evicts by and the prompt-cache key.
* Prefers `conversation.session_key` (the serialized key); falls back to
* `user_id` only for conversations created before that field existed.
* Do NOT return the bare `user_id`: `user_id` is `msg.sender`, which would
* (a) never match the serialized `opts.sessionKey` in the busy guard and
* (b) collide across channels/threads of the same user in the prompt cache.
*/
get sessionKey(): string | undefined {
return this.conversation?.session_key ?? this.conversation?.user_id
}
get sourceTask(): Task {
return this.task
}
/** The AbortSignal for this executor's loop. Used by Task 3 tests. */
get signal(): AbortSignal {
return this.abortController.signal
}
async rehydrateWaitingApproval(sessionKey: string, approval: PendingApproval): Promise<void> {
const message = this.task.sourceMessage
this.conversation = await this.deps.conversationManager.getOrCreate(sessionKey, {
userId: message?.sender,
channelType: message?.channelType,
channelId: message?.channelId,
threadId: message?.threadId,
source: message?.channelType,
})
if (
this.conversation.pending_approval?.request_id !== approval.request_id ||
this.conversation.activeTaskId !== this.taskId
) {
throw new Error('persisted approval does not match its active conversation task')
}
if (approval.task_budget !== undefined) this.executionBudget.restore(approval.task_budget)
else if (approval.legacy_budget === true) this.legacyApprovalBudget = true
else throw new Error('Pending approval has no verifiable execution budget')
if (approval.authorization_scope !== 'turn_tools') {
// Legacy rows predate consent provenance. A wildcard retained by an old
// process must not authorize a different risky tool after cold resume.
this.conversation.auto_approved_tools.delete('*')
}
this.task.traceContext = approval.traceContext ?? this.conversation.traceContext ?? null
this.state = 'waiting_approval'
}
/**
* Returns a promise that resolves when the executor finishes (completed, failed, or denied).
* Used by AgentStateMachine.stop() to await graceful shutdown.
*/
waitForCompletion(): Promise<void> {
return this.completionPromise
}
/**
* Run the task through the LLM tool-use loop.
* On completion, calls onComplete or onFail callback.
* On need_approval, sets state and calls onApprovalNeeded.
*/
async run(): Promise<void> {
logger.info({ taskId: this.taskId }, 'Task starting')
try {
this.state = 'processing'
this.executionBudget.start(this.abortController)
this.turnTiming = new TurnTimingRecorder(this.task.createdAt)
// 1. Resolve session key, get/create conversation
// INVARIANT: for source==='cron' this MUST produce the same session key that
// cronDispatch.ts enqueued the task under (both call resolveCronTaskSessionKey).
// A divergence would run the task in a different session than it was queued in.
const msg = this.task.sourceMessage
const cronSession =
this.task.source === 'cron' ? resolveCronTaskSessionKey(this.task) : undefined
const sessionKey = resolveTaskSessionKey(this.task)
logger.debug({ taskId: this.taskId }, 'Session resolved')
const sessionLoadStart = Date.now()
this.conversation = await this.deps.conversationManager.getOrCreate(sessionKey, {
userId: cronSession?.userId ?? msg?.sender,
channelType: cronSession?.channelType ?? msg?.channelType,
channelId: cronSession?.channelId ?? msg?.channelId,
threadId: cronSession?.threadId ?? msg?.threadId,
source: cronSession?.channelType ?? msg?.channelType,
// R2 — record the effective model served (resolved by the agent from the
// session's saved selection before this executor was built) in the
// `sessions.model` telemetry column at INSERT time.
model: this.deps.modelName,
})
if (this.task.traceContext?.origin === 'channel_event' && !this.task.traceContext.sessionId) {
this.task.traceContext = {
...this.task.traceContext,
sessionId: this.conversation.id,
}
}
const userInput = msg?.content || this.task.conversationHistory[0]?.content || ''
// Auto-title (spec 15): on turn 1 only, derive the server-authoritative
// session title. Security order is FIXED (§5): redact the FULL input with
// the operator secret list FIRST, then collapse+truncate — truncating
// first would split a secret across the cut and defeat the literal match.
// `sanitizeFreeformContent` (not `sanitizeOutput`) so we don't emit a log
// line per turn. Applies to channel sessions too (same sanitization).
//
// "Turn 1" gate: `turns.length === 0` is a RAM proxy for the durable
// turn-1 signal. It MUST stay in lock-step with the durable write gate in
// `SqliteConversationStore.persistTurnStart` (`turnNumber === 1`): if this
// set a RAM title on a turn the durable write skips, the memory store would
// project a title the SQLite store does not, breaking dual-store parity.
// The two agree today because a fresh session starts at `turns.length === 0`
// AND `nextTurnNumber === 1`, and a cold-load rehydrates both together.
// They would diverge only if compaction/LRU/paginated cold-load ever shrank
// `turns` without resetting the durable `turnNumber` — none of which exist
// yet. If any is enabled, gate this on the durable turn number instead
// (there is no clean durable turn-1 value at this call site today: the
// count lives in each store, so plumbing it up would change the
// ConversationStore contract — hence the proxy).
const derivedTitle =
this.conversation.turns.length === 0
? deriveAutoTitle(
this.responseSafety.sanitizeFreeformContent(userInput, {
secretWarning: 'Potential secret detected in session title',
}).content
)
: ''
// Empty first input (or whitespace-only) → no title; let the client keep
// its placeholder rather than persisting an empty string via COALESCE.
const autoTitle = derivedTitle.length > 0 ? derivedTitle : undefined
// D3 — awaited durability barrier: the user message must be durable
// before the LLM loop runs (it is the replay anchor after a crash). A
// rejected write rolls back the turn inside startTurn and lands in
// run()'s catch as a clean task failure.
await this.deps.conversationManager.startTurn(
this.conversation,
userInput,
this.taskId,
this.task.traceContext ?? null,
autoTitle
)
this.turnTiming?.addSessionLoadMs(Date.now() - sessionLoadStart)
// P2 token budgets (§5.2) — capture the per-task brake baseline NOW, before
// this task consumes anything. The conversation's lifetime counters are
// session-cumulative (persist across restarts), so the brake measures the
// DELTA vs this snapshot — a long-lived session is never aborted just for
// accumulated history. Gated on the P1 verdict carrying a per-task cap so
// the no-cap path stays identical to before (no baseline, brake disabled).
this.captureTaskTokenBaseline()
await withAbort(() => this.prepareChannelWorkflowCallerContext(), this.abortController.signal)
this.enqueueGovernedRunEvent('run_start', `task:${this.taskId}:start`)
if (this.workflowAccessDeniedResponse && looksLikeWorkflowAccessRequest(userInput)) {
this.logProviderWorkflowAccessDenied('request')
await this.completeWithStaticResponse(this.workflowAccessDeniedResponse)
return
}
// A durable turn and authorized caller context precede all file writes.
// Only metadata receipts join the first provider request; no source bytes
// or visual projection are requested by this generic preparation stage.
const references = this.task.sourceMessage?.fileReferenceResolutions
if (hasLargeAvailableGfsReferences(references)) {
const preparationLoopConfig = await withAbort(
() => this.buildLoopConfig({ skipContextManager: true }),
this.abortController.signal
)
// Await the transfer itself; withAbort would release the task while a
// signal-ignoring producer could still settle. The shared execution path
// carries the signal and cleanup must finish before terminal settlement.
this.preparedGfsFiles = await prepareGfsFiles(references!, {
config: preparationLoopConfig,
callerIdentity: this.task.sourceMessage?.sender,
toolTimeoutMs: appConfig.nativeTool.toolTimeout,
budget: this.executionBudget,
})
this.executionBudget.assertTime()
}
// 2. Run the tool-use loop
this.currentTurnToolNames.clear()
const result = await this.runAgentLoop()
// 3. Handle result
await this.handleLoopResult(result)
if (
(this.state as ExecutorState) !== 'waiting_approval' &&
!this.abortController.signal.aborted
) {
this.state = 'completed'
logger.info({ taskId: this.taskId }, 'Task completed')
this.turnTiming?.emit(this.taskId)
this.deps.onComplete(this.task)
} else if (this.abortController.signal.aborted) {
logger.info({ taskId: this.taskId }, 'Task cancelled')
}
} catch (error) {
if (
this.abortController.signal.aborted &&
!(this.abortController.signal.reason instanceof TaskLimitError)
) {
if (this.conversation)
await this.handleLoopResult({ type: 'cancelled', reason: 'signal_aborted' })
return
}
if (this.abortController.signal.reason instanceof TaskLimitError)
error = this.abortController.signal.reason
if (error instanceof TaskLimitError && this.conversation) {
this.executionBudget.pause()
try {
if (this.conversation.state === 'processing')
await this.deps.conversationManager.completeTurn(this.conversation, error.message)
else await this.deps.conversationManager.failTurn(this.conversation)
} catch (persistError) {
// A failed durable write must not prevent lifecycle failure or completion release.
logger.error(
{ taskId: this.taskId, err: persistError },
'Failed to persist task limit interruption'
)
}
}
const taskError = this.toTaskError(error)
logger.error(
{ taskId: this.taskId, code: taskError.code, retryable: taskError.retryable, err: error },
'Task failed'
)
this.state = 'failed'
if (error instanceof TaskLimitError && this.completedAttachments.length > 0) {
this.deps.onFail(this.task, taskError, [...this.completedAttachments])
} else {
this.deps.onFail(this.task, taskError)
}
} finally {
await this.settleGfsRetentionOwner()
this.executionBudget.pause()
if (this.state !== 'waiting_approval' || this.abortController.signal.aborted)
this.resolveCompletion?.()
}
}
/**
* Resume execution after approval was granted.
*/
async resumeAfterApproval(alwaysApprove: boolean): Promise<void> {
if (this.state !== 'waiting_approval' || !this.conversation) {
throw new Error(`Cannot resume: executor state is ${this.state}`)
}
logger.info({ taskId: this.taskId }, 'Resuming after approval')
try {
this.state = 'processing'
// Guard: abort may have been called between approval request and resume.
// The subscriber that aborted us already transitioned the task to cancelled.
// Just clean up our own execution state. (PR-186 review M2; Invariant I1)
if (this.abortController.signal.aborted) {
logger.info({ taskId: this.taskId }, 'Resume cancelled: already aborted')
return
}
const savedApproval = this.conversation.pending_approval
// Restore before legacy renewal or missing-context recovery can re-pause
// this turn. Those branches must not stamp a fresh attachment budget.
if (savedApproval) this.restoreAttachmentReadLedger(savedApproval)
mergeCollectedAttachments(this.completedAttachments, savedApproval?.attachments ?? [])
collectToolAttachments(savedApproval?.completed_results ?? [], this.completedAttachments)
this.executionBudget.start(this.abortController)
const approvalBeforeResolution = this.conversation.pending_approval
if (this.legacyApprovalBudget && approvalBeforeResolution) {
await this.handleLoopResult({
type: 'need_approval',
approval: {
...approvalBeforeResolution,
request_id: randomUUID(),
replaces_request_id: approvalBeforeResolution.request_id,
legacy_budget: false,
description:
'Confirm continuation with a new execution budget; prior consumption was not recorded. ' +
approvalBeforeResolution.description,
},
})
this.legacyApprovalBudget = false
return
}
await this.deps.conversationManager.approve(this.conversation, alwaysApprove)
if (approvalBeforeResolution?.tool_call_id) {
this.approvedToolCorrelation = {
toolCallId: approvalBeforeResolution.tool_call_id,
approvalRequestId: approvalBeforeResolution.request_id,
}
}
this.currentTurnToolNames.clear()
const approval = this.conversation.pending_approval
// Fallback: no snapshot, re-run from scratch
if (!approval?.context_snapshot?.length) {
// There is no frozen call to execute. A regenerated call must not
// consume the old approval through a name-only approval/guardrail gate.
this.executionBudget.assertTime()
this.conversation.pending_approval = undefined
logger.info({ taskId: this.taskId }, 'No snapshot, re-running from scratch')
const result = await this.runAgentLoop()
await this.handleLoopResult(result)
if (
(this.state as ExecutorState) !== 'waiting_approval' &&
!this.abortController.signal.aborted
) {
this.state = 'completed'
this.deps.onComplete(this.task)
} else if (this.abortController.signal.aborted) {
logger.info({ taskId: this.taskId }, 'Task cancelled')
}
return
}
// IronClaw invariant #2 (P.3 §4.3): resolve any spillover refs in the
// snapshot BEFORE we execute the approved tool. If a ref is dead (TTL
// expired or GC'd) we abort early — the audit invariant is that what
// executes equals what the user approved. Re-running prior tools to
// regenerate the blob could yield different output (web page changed,
// file modified) → audit broken.
const resolveCtx = {
taskId: this.taskId,
requestId: approval.request_id,
toolName: approval.tool_name,
}
const resolveOnce = async (
m: Pick<ToolResult, 'content' | 'spillover_ref'>
): Promise<string> => {
// FsSpilloverResolver attaches `resolveCtx` to any ApprovalExpiredError
// it throws. Other resolver implementations (e.g. test mocks) are
// expected to throw their own ApprovalExpiredError directly.
const resolver = this.spilloverResolver
if (resolver instanceof FsSpilloverResolver) {
return resolver.withContext(resolveCtx, () => resolver.resolve(m))
}
return resolver.resolve(m)
}
const resolvedCompletedResults: ToolResult[] = []
try {
for (const tr of approval.completed_results ?? []) {
const resolvedContent = await resolveOnce({
content: tr.content,
spillover_ref: tr.spillover_ref,
})
resolvedCompletedResults.push({ ...tr, content: resolvedContent })
}
} catch (error) {
if (error instanceof ApprovalExpiredError) {
logger.warn({ taskId: this.taskId }, 'Approval expired before tool execution')
await this.deps.conversationManager.failTurn(this.conversation!)
this.state = 'failed'
this.deps.onFail(this.task, {
code: 'approval_expired',
message: error.payload.user_message,
retryable: false,
provider: this.deps.llmProvider.getProviderType(),
})
return
}
throw error
}
// Execute approved tool outside loop.
// IronClaw invariant #1: the snapshot's frozen messages must reach the
// LLM verbatim — compaction would invalidate validateToolLinkages.
const loopConfig = await withAbort(
() => this.buildLoopConfig({ skipContextManager: true }),
this.abortController.signal
)
const suspendedCall = {
id: approval.tool_call_id,
name: approval.tool_name,
arguments: approval.parameters,
}
const displayName = getDisplayName(suspendedCall.name)
logger.info({ taskId: this.taskId, toolName: suspendedCall.name }, 'Executing approved tool')
this.currentTurnToolNames.add(suspendedCall.name)
// executeToolCalls emits reportToolStart AFTER the approval gate, so approved
// tools bypass it entirely. Emit the SSE bookends here so the UI sees the
// full tool_start → tool_progress × N → tool_complete sequence (matching the
// normal non-approval path). Without this, the UI has no step card to update
// on tool_progress and is stuck visually on the approval dialog.
const reporter = progressReporterRegistry.get(this.taskId)
if (reporter) {
reporter.reportToolStart({
taskId: '', // overridden by SseProgressReporter
toolCallId: suspendedCall.id,
toolName: suspendedCall.name,
displayName,
intentSummary: approval.intent_summary ?? `Using ${displayName}...`,
iteration: 0,
stepIndex: 0,
totalSteps: 1,
inputPreview: extractInputPreview(suspendedCall.name, suspendedCall.arguments),
})
}
const execStart = Date.now()
this.executionBudget.assertTime()
// approve() already resolved the durable approval. Consume its retained
// RAM copy before execution so the next model-generated call cannot reuse
// it through either approval gate. The local frozen approval still owns
// message reconstruction and any connect_required re-suspension below.
this.conversation.pending_approval = undefined
const toolResult = await executeSingleTool(suspendedCall, loopConfig)
collectToolAttachments([toolResult], this.completedAttachments)
this.executionBudget.assertTime()
if (reporter) {
reporter.reportToolComplete({
taskId: '',
toolCallId: toolResult.tool_call_id,
toolName: toolResult.name,
displayName,
durationMs: Date.now() - execStart,
isError: toolResult.is_error ?? false,
errorSummary: toolResult.is_error ? sanitizeError(toolResult.content) : undefined,
iteration: 0,
stepIndex: 0,
totalSteps: 1,
outputPreview: buildOutputPreview(toolResult.rawContent ?? toolResult.content),
metadata: toolResult.metadata,
})
}
// U5 — the re-executed tool surfaced a 401 on an oauth mcp-server. Suspend
// durably for reactive OAuth consent INSTEAD of feeding the auth error to
// the LLM. The connect suspension inherits the SAME tool coordinates
// (via `suspendedCall`) + the frozen `context_snapshot`/`completed_results`
// so the NEXT resume (after the user connects) re-executes the SAME tool.
// The failed connect `toolResult` is intentionally dropped — it never
// enters the reconstructed message history. No machine loop: each resume is
// human-gated (approve/connect), and the client already exhausted its
// single 401 refresh-retry before throwing (McpAuthError).
const connectMarker = extractConnectRequiredMarker(toolResult.metadata)
if (connectMarker) {
const connectApproval = buildConnectRequiredApproval(suspendedCall, connectMarker)
connectApproval.context_snapshot = approval.context_snapshot
connectApproval.completed_results = approval.completed_results
connectApproval.intent_summary = approval.intent_summary
connectApproval.attachments = approval.attachments
connectApproval.traceContext = approval.traceContext ?? this.task.traceContext ?? null
await this.handleLoopResult({ type: 'need_approval', approval: connectApproval })
if (
(this.state as ExecutorState) !== 'waiting_approval' &&
!this.abortController.signal.aborted
) {
this.state = 'completed'
this.turnTiming?.emit(this.taskId)
this.deps.onComplete(this.task)
} else if (this.abortController.signal.aborted) {
logger.info({ taskId: this.taskId }, 'Task cancelled')
}
return
}
// Reconstruct messages using the resolved completed_results.
// `resolvedCompletedResults` is `approval.completed_results` with any
// spillover refs swapped in for their blob bodies (invariant #2).
const messages: ChatMessage[] = [
...approval.context_snapshot,
...resolvedCompletedResults.map((tr: ToolResult) => ({
role: 'tool' as const,
content: tr.content,
tool_call_id: tr.tool_call_id,
name: tr.name,
})),
{
role: 'tool' as const,
content: toolResult.content,
tool_call_id: toolResult.tool_call_id,
name: toolResult.name,
},
]
validateToolLinkages(messages)
const previousAttachments = [
...(approval.attachments || []),
...this.collectAttachments([...(approval.completed_results || []), toolResult]),
]
// A15 U1 — the approved tool ended the turn: no further model call.
const result: LoopResult = toolResult.stopTurn
? turnStopResult(loopConfig, 0, toolResult.stopTurn.message, [])
: await runToolUseLoop(loopConfig, messages)
// Preserve attachments
if (previousAttachments.length > 0) {
if (result.type === 'response' || result.type === 'exhaustion') {
result.attachments = [...previousAttachments, ...(result.attachments || [])]
} else if (result.type === 'need_approval') {
result.approval.attachments = [
...(result.approval.attachments || []),
...previousAttachments,
]
result.approval.completed_results = [
...(approval.completed_results || []),
toolResult,
...(result.approval.completed_results || []),
]
}
}
await this.handleLoopResult(result)
if (
(this.state as ExecutorState) !== 'waiting_approval' &&
!this.abortController.signal.aborted
) {
this.state = 'completed'
this.turnTiming?.emit(this.taskId)
this.deps.onComplete(this.task)
} else if (this.abortController.signal.aborted) {
logger.info({ taskId: this.taskId }, 'Task cancelled')
}
} catch (error) {
if (
this.legacyApprovalBudget &&
!this.abortController.signal.aborted &&
!(error instanceof TaskLimitError) &&
this.conversation?.pending_approval?.legacy_budget === true
) {
this.state = 'waiting_approval'
const pending = this.conversation.pending_approval
this.deps.onApprovalNeeded(pending.request_id, this.taskId, pending)
logger.error(
{ taskId: this.taskId, err: error },
'Approval renewal failed; existing approval retained'
)
return
}
if (
this.abortController.signal.aborted &&
!(this.abortController.signal.reason instanceof TaskLimitError)
) {
if (this.conversation)
await this.handleLoopResult({ type: 'cancelled', reason: 'signal_aborted' })
return
}
if (this.abortController.signal.reason instanceof TaskLimitError)
error = this.abortController.signal.reason
if (error instanceof TaskLimitError && this.conversation) {
this.executionBudget.pause()
try {
if (this.conversation.state === 'processing')
await this.deps.conversationManager.completeTurn(this.conversation, error.message)
else await this.deps.conversationManager.failTurn(this.conversation)
} catch (persistError) {
// A failed durable write must not prevent lifecycle failure or completion release.
logger.error(
{ taskId: this.taskId, err: persistError },
'Failed to persist task limit interruption'
)
}
}
const taskError = this.toTaskError(error)
logger.error(
{ taskId: this.taskId, code: taskError.code, retryable: taskError.retryable, err: error },
'Resume failed'
)
this.state = 'failed'
if (error instanceof TaskLimitError && this.completedAttachments.length > 0) {
this.deps.onFail(this.task, taskError, [...this.completedAttachments])
} else {
this.deps.onFail(this.task, taskError)
}
} finally {
await this.settleGfsRetentionOwner()
this.executionBudget.pause()
if (this.state !== 'waiting_approval' || this.abortController.signal.aborted)
this.resolveCompletion?.()
}
}
/**
* Convert an unknown thrown error into a structured TaskError.
* LlmError → pass through its code/message/retryable/provider.
* Anything else → retryable ApiCallFailed with provider from the LLM.
*/
private toTaskError(error: unknown): TaskError {
if (error instanceof TaskLimitError)
return {
code: error.code,
message: error.message,
retryable: false,
provider: this.deps.llmProvider.getProviderType(),
}
if (error instanceof LlmError) {
return {
code: error.code,
message: error.message,
retryable: error.retryable,
provider: error.provider,
httpStatus: error.httpStatus,
providerCode: error.providerCode,
}
}
return {
code: LlmErrorCode.ApiCallFailed,
message: error instanceof Error ? error.message : String(error),
retryable: true,
provider: this.deps.llmProvider.getProviderType(),
}
}
/**
* Deny the pending approval.
*
* **IronClaw write-through (T2.1)**: `ConversationManager.deny` awaits the
* durable pending_approval delete before returning, so we await here too —
* the channel notification (responseCallback) only fires after the DB
* mutation lands. Callers that fire-and-forget should attach `.catch(...)`.
*/
async deny(): Promise<void> {
if (this.state !== 'waiting_approval' || !this.conversation) return
const toolName = this.conversation.pending_approval?.tool_name || 'unknown'
await this.deps.conversationManager.deny(this.conversation)
// Terminal SSE event emitted automatically when onComplete → queue.completeTask
// → lifecycle.transition('completed') fires (SseProgressReporter subscription).
const denialMessage = `Tool \`${toolName}\` was denied by the user. The operation was not performed.`
if (this.task.responseCallback) {
this.task.responseCallback({ response: denialMessage }).catch(err => {
logger.error({ taskId: this.taskId, err }, 'Failed to send denial')
})
}
this.state = 'completed'
await this.settleGfsRetentionOwner()
this.deps.onComplete(this.task)
this.resolveCompletion?.()
}
/**
* Signal an abort. The loop exits at its next checkpoint.
*
* Idempotent self-healing: drives the TaskLifecycle transition to 'cancelled'
* before firing the AbortController. In the normal v2 flow the AgentStateMachine
* lifecycle subscriber already transitioned the task before calling abort(), so
* this transition() call returns AlreadyTerminal — a zero-cost no-op. For any
* future direct caller that bypasses the subscriber (shutdown paths, test helpers,
* new approval-denial flows), the task self-heals to 'cancelled' instead of being
* stranded at 'processing'.
*
* Critically this does NOT write task.status directly — only TaskLifecycle writes
* task state (Invariant I1 preserved). PR-193 review #1.
*/
abort(): void {
const suspended = this.state === 'waiting_approval'
this.deps.taskLifecycle.transition(this.task.id, 'cancelled', 'user_requested')
this.abortController.abort()
if (suspended) {
// A suspended run has already returned, so its finally block will not
// re-enter. Its producers have settled; join owner release explicitly.
void this.settleGfsRetentionOwner().then(() => this.resolveCompletion?.())
}
}
// ── Private helpers ───────────────────────────────────────────────
/**
* P2 token budgets (§5.2) — snapshot the conversation's lifetime token
* counters as the per-task brake baseline. No-op (leaves `taskTokenBaseline`
* null → brake disabled) unless the P1 verdict carried a per-task cap.
*/
private captureTaskTokenBaseline(): void {
if (!this.hasTaskBudgetCap() || !this.conversation) return
this.taskTokenBaseline = snapshotTaskTokenBaseline(this.conversation)
}
/**
* A retention owner spans preparation and an approval suspension in this
* process; pins live in memory, so after a Host restart a cold resume finds
* no pin and its file may have expired or been evicted, and the model
* downloads it again. Release happens only after this executor reaches a
* terminal state. A failed release leaves the pin in place, so its files stay
* protected until the Host restarts or until each copy reaches its
* `expiresAt`, whichever comes first: expiry is absolute and a pin never
* protects an expired copy.
*/
private settleGfsRetentionOwner(): Promise<void> {
if (this.state === 'waiting_approval' && !this.abortController.signal.aborted)
return Promise.resolve()
if (this.gfsRetentionOwnerSettlement) return this.gfsRetentionOwnerSettlement
this.gfsRetentionOwnerSettlement = (async () => {
const callerIdentity = gfsStoreCallerIdentity(this.task.sourceMessage)
const store = this.deps.gfsDownloadStore
if (!store?.isAvailable()) return
try {
await store.releaseReceiptOwner(this.taskId, callerIdentity)
} catch (error) {
logger.error(
{ taskId: this.taskId, callerIdentity, err: error },
'GFS retention owner release failed; retained records remain protected until restart or expiry'
)
}
})()
return this.gfsRetentionOwnerSettlement
}
/** True when the P1 budget verdict carried a per-task cap (tokens or cost). */
private hasTaskBudgetCap(): boolean {
const v = this.task.budgetVerdict
return !!v && (v.maxTaskTokens != null || v.maxTaskCost != null)
}
/**
* R2.6 — model-aware context window. The allowlist entry for the effective
* model wins. Without one, a subscription provider uses its 256k default and
* every other provider the fixed `CLERUM_CONTEXT_MAX_TOKENS` env (#731).
* Subscription tasks log the window and its source once.
*/
private contextMaxTokens(): number {
if (this.contextWindow !== null) return this.contextWindow
const provider = this.deps.llmProvider.getProviderType()
const { contextWindowTokens, source } = resolveContextWindow(
provider,
this.deps.contextWindowTokens,
appConfig.contextMaxTokens
)
if (isLlmProvider(provider) && descriptorFor(provider).defaultContextWindowTokens) {
logger.info(
{
event: 'context_window_resolved',
component: 'TaskExecutor',
taskId: this.taskId,
provider,
model: this.deps.modelName,
// Not `contextWindowTokens`: SENSITIVE_KEY_RE in logger.ts redacts it;
// logPayloadKeys.test.ts rejects such keys.
contextWindow: contextWindowTokens,
source,
},
'Context window resolved for the task'
)
}
this.contextWindow = contextWindowTokens
return contextWindowTokens
}
/**
* C15/C16 — restore the turn ledger from the approval's own snapshot. The
* persisted value is authoritative and independent of message history, so
* compaction and earlier turns cannot change it. A missing or invalid
* snapshot fails closed: compacted history cannot prove that nothing was
* spent. New approvals always carry even the valid zero snapshot.
*/
private restoreAttachmentReadLedger(approval: PendingApproval): void {
const persisted = readAttachmentReadLedgerSnapshot(approval.task_budget?.attachmentReadLedger)
if (persisted) {
// Warm resume must never decrease what the live turn already recorded.
this.attachmentReadLedger.restore(
mergeAttachmentReadLedgerSnapshots(this.attachmentReadLedger.snapshot(), persisted)
)
return
}
logger.warn(
{ component: 'TaskExecutor', taskId: this.taskId, reason: 'attachment_read_ledger_missing' },
'Approval has no usable attachment ledger; failing closed for the rest of the turn'
)
this.attachmentReadLedger.exhaust(this.contextMaxTokens())
}
/**
* #731 — the attempt contract's `maxMessages` for the provider, or
* `undefined` when it has none. An unregistered provider type has no
* contract, the same case `buildSourceMessageContentParts` guards with
* `isLlmProvider`.
*/
private contractMaxMessages(): number | undefined {
const providerType = this.deps.llmProvider.getProviderType()
if (!isLlmProvider(providerType)) return undefined
return descriptorFor(providerType).maxMessages
}
private getOrCreateTokenCounter(): TokenCounter {
if (!this.tokenCounter) {
this.tokenCounter = createTokenCounter(this.deps.llmProvider, this.deps.modelName, {
offline: appConfig.tokenizerOffline,
})
// Fire warmup asynchronously. `count()` awaits internally if it races.
void this.tokenCounter.warmup().catch(err => {
logger.warn({ taskId: this.taskId, err }, 'Token counter warmup failed')
})
}
return this.tokenCounter
}
private async runAgentLoop(): Promise<LoopResult> {
const historyStart = Date.now()
let messages = this.deps.conversationManager.buildMessageHistory(this.conversation!)
// #731: the history is compacted at the same share of the model's window
// at which the context manager starts compacting, not at a fixed count,
// and measured the way the manager measures it for that decision (#739).
const compactionThreshold = Math.floor(COMPACTION_PRESSURE_THRESHOLD * this.contextMaxTokens())
const tokenCounter = this.getOrCreateTokenCounter()
messages = await compactConversation(
messages,
undefined,
compactionThreshold,
msgs => tierDecisionTokens(msgs, [], tokenCounter, appConfig.tokenizerDryrun),
{
enabled: appConfig.compactionPrePruneEnabled,
options: {
protectedTailTurns: appConfig.compactionPrePruneProtectedTailTurns,
summaryThresholdTokens: appConfig.compactionPrePruneSummaryTokens,
maxArgsBytes: appConfig.compactionPrePruneMaxArgsBytes,
dedupEnabled: appConfig.compactionPrePruneDedup,
oneLineSummariesEnabled: appConfig.compactionPrePruneOneLine,
jsonSafeTruncateEnabled: appConfig.compactionPrePruneJsonTruncate,
stripMediaEnabled: appConfig.compactionPrePruneStripMedia,
},
}
)
// History rehydration + pre-prune compaction are part of the session-load
// cost the user pays before the first model byte.
this.turnTiming?.addSessionLoadMs(Date.now() - historyStart)
const lastMessage = messages[messages.length - 1]
const sourceMessageAttachments = this.buildSourceMessageContentParts(
lastMessage?.role === 'user' ? lastMessage.content : ''
)
if (sourceMessageAttachments.length > 0) {
if (lastMessage?.role === 'user') {
messages[messages.length - 1] = {
...lastMessage,
// Parts are authoritative: `content` is restated from the text parts
// so a message with images cannot contradict its own projection.
content: textContentFromParts(sourceMessageAttachments),
contentParts: sourceMessageAttachments,
}
}
}
// T2.2 — when the prompt cache is on, the volatile per-turn metadata
// (date, channel, sender, cron) moves out of the (now byte-stable) system
// prompt and into a `<turn-context>` block prepended to the LAST user
// message of the turn. Only the first user message of the turn gets it;
// `tool` messages keep their content untouched.
// #666 — the block is also the only carrier of the `attached_file` and
// `referenced_file` lines, so a message with file attachments or resolved
// file references gets it with the cache off too; the attachment
// condition also registers `clerum__attachment_read`.
const hasFileAttachments =
this.task.sourceMessage?.attachments?.some(attachment => attachment.kind === 'file') === true
const hasFileReferences = (this.task.sourceMessage?.fileReferenceResolutions?.length ?? 0) > 0
if (appConfig.promptCacheEnabled || hasFileAttachments || hasFileReferences) {
this.prependTurnContextBlock(messages)
}
const promptAssemblyStart = Date.now()
const loopConfig = await withAbort(() => this.buildLoopConfig(), this.abortController.signal)
if (this.turnTiming) {
// buildLoopConfig assembles the tool registry (MCP schemas) and the
// system identity (workspace files / tiered prompt parts).
this.turnTiming.addPromptAssemblyMs(Date.now() - promptAssemblyStart)
let inputChars = 0
for (const m of messages) {
if (typeof m.content === 'string') inputChars += m.content.length
}
this.turnTiming.setInputCharsApprox(inputChars)
}
return runToolUseLoop(loopConfig, messages)
}
/**
* T2.2 — prepend the `<turn-context>` block to the latest user message
* (mutates in place). The block carries date/channel/sender/cron; an empty
* cron source still produces a valid block. For cron-originated turns with
* no human user text we inject a synthetic `<cron task>` placeholder so the
* wire shape stays consistent (P1-004 §5.5).
*/
private prependTurnContextBlock(messages: ChatMessage[]): void {
for (let i = messages.length - 1; i >= 0; i--) {
const m = messages[i]
if (m.role !== 'user') continue
const block = buildTurnContextBlock({
date: new Date(),
channel: {
type: this.task.sourceMessage?.channelType ?? 'internal',
sender: this.task.sourceMessage?.sender ?? null,
},
cron: this.task.cronJobId
? {
jobId: this.task.cronJobId,
scheduledFor: new Date().toISOString(),
}
: undefined,
attachedFiles: attachedFilesForTurnContext(this.task.sourceMessage?.attachments),
referencedFiles: referencedFilesForTurnContext(
this.task.sourceMessage?.fileReferenceResolutions
),
preparedGfsFiles: this.preparedGfsFiles,
})
const isCron = this.task.cronJobId !== undefined
if (m.contentParts && m.contentParts.length > 0) {
// Keep the parts/`content` invariant the Codex V2 parser enforces: the
// block moves with the text it is prepended to.
const contentParts = prependTextToParts(m.contentParts, block)
messages[i] = { ...m, contentParts, content: textContentFromParts(contentParts) }
return
}
const baseContent =
m.content && m.content.length > 0 ? m.content : isCron ? '<cron task>' : m.content
messages[i] = { ...m, content: block + baseContent }
return
}
}
private async handleLoopResult(result: LoopResult): Promise<void> {
if (result.type === 'need_approval') {
mergeCollectedAttachments(this.completedAttachments, result.approval.attachments ?? [])
collectToolAttachments(result.approval.completed_results ?? [], this.completedAttachments)
} else if ('attachments' in result) {
mergeCollectedAttachments(this.completedAttachments, result.attachments ?? [])
}
if (this.abortController.signal.reason instanceof TaskLimitError)
throw this.abortController.signal.reason
if (result.type !== 'cancelled') this.executionBudget.assertTime()
// T1.4 — clear anti-thrash bookkeeping at any terminal outcome. `need_approval`
// is NOT terminal (it suspends), so the state must survive into resume.
if (this.conversation && result.type !== 'need_approval' && this.conversation.compactionState) {
this.conversation.compactionState = undefined
}
switch (result.type) {
case 'response':
case 'exhaustion': {
if (
result.type === 'exhaustion' &&
result.reason !== 'task_budget' &&
result.reason !== 'turn_stop'
)
throw new TaskLimitError(
'TASK_ITERATION_LIMIT',
`Task stopped before completion after ${this.executionBudget.maxIterations} iterations. Continuation requires a new budget.`
)
const rawContent = result.type === 'response' ? result.content : result.message
const guardedContent = await withAbort(
() => this.guardProviderWorkflowTriggerClaim(rawContent),
this.abortController.signal
)
this.executionBudget.assertTime()
const sanitized = this.responseSafety.sanitizeAssistantResponse(guardedContent)
const content = sanitized.content
if (sanitized.was_modified) {
this.deps.coreEvents.emit({
type: 'safety:output_sanitized',
data: {
toolName: 'assistant_response',
originalLength: guardedContent.length,
sanitizedLength: content.length,
taskId: this.taskId,
},
timestamp: new Date(),
})
}
// D3 — awaited durability barrier: the turn must be durable BEFORE the
// client ACK (responseCallback). On a rejected write, follow the
// need_approval pattern below: fail the turn and rethrow so run()'s
// catch surfaces a clean failure — the client never gets an ACK for a
// turn that was not persisted.
this.executionBudget.assertTime()
this.executionBudget.pause()
try {
await this.deps.conversationManager.completeTurn(this.conversation!, content)
} catch (err) {
await this.deps.conversationManager.failTurn(this.conversation!)
throw err
}
if (this.task.responseCallback) {
await this.task.responseCallback({
response: content,
attachments: result.attachments,
})
}
// Terminal SSE event emitted automatically when onComplete → queue.completeTask
// → lifecycle.transition('completed') fires (SseProgressReporter subscription).
break
}
case 'need_approval': {
// C15/C16 — every pause (first, legacy re-pause, connect re-pause)
// funnels through here, so the turn's attachment read ledger is stamped
// inside the existing `task_budget` JSON column. Compaction cannot
// lose it; no new column or migration is needed.
const attachmentReadLedger = this.attachmentReadLedger.snapshot()
result.approval.task_budget = {
...this.executionBudget.pause(),
attachmentReadLedger,
}
// #666 R4-M2 — persist the sanitized source message so a cold restart
// rebuilds the file-reference pins and attachment metadata. The inline
// bytes (dataBase64) never persist.
result.approval.sourceMessage = sourceMessageForResume(this.task.sourceMessage)
// Durable write FIRST: under sqlite/dual the suspend can reject. We
// must not tell the client "suspended" (SSE) or register the approval
// before the durable state lands — otherwise a rejected write leaves a
// contradictory SSE + an un-resolvable, poisoned conversation. On
// failure, reset the turn (→ Idle) and rethrow so run()'s catch
// surfaces it as a clean failure (CRIT-1 / sqlite-stores-10).
try {
await this.deps.conversationManager.suspendForApproval(
this.conversation!,
result.approval
)
} catch (err) {
if (!result.approval.replaces_request_id)
await this.deps.conversationManager.failTurn(this.conversation!)
throw err
}
if (result.approval.replaces_request_id) this.legacyApprovalBudget = false
const reporter = progressReporterRegistry.get(this.taskId)
if (reporter) {
// U5 — carry the reason (+ mcpServerName for connect_required)
// so the desktop distinguishes an OAuth-consent suspension from the
// default HITL gate. Absent reason → 'approval_required' (back-compat).
reporter.emitSuspended(
getDisplayName(result.approval.tool_name),
result.approval.request_id,
{
reason: result.approval.reason ?? 'approval_required',
mcpServerName: result.approval.mcpServerName,
toolName: result.approval.tool_name,
parameters: result.approval.parameters,
}
)
}
this.state = 'waiting_approval'
this.deps.onApprovalNeeded(result.approval.request_id, this.taskId, result.approval)
break
}
case 'cancelled': {
// Release the conversation turn lock AND scrub the cancelled user_input from
// LLM history so it does not leak into the next turn (BUG-9).
// cancelTurn sets a synthetic assistant response on the current turn so that
// buildMessageHistory emits a clean user↔assistant alternation.
this.deps.conversationManager.cancelTurn(this.conversation!)
// NOTE: We do NOT write task.status or task.completedAt here — TaskLifecycle is the
// single writer (Invariant I1). The cancel subscriber in AgentStateMachine already
// transitioned the task to cancelled before the loop checkpoint fired executor.abort().
// Calling lifecycle.transition again would return AlreadyTerminal — redundant and
// misleading.
logger.info({ taskId: this.taskId }, 'Task cancelled')
this.enqueueGovernedRunEvent('run_end', `task:${this.taskId}:end`, {
status: 'cancelled',
})
break
}
case 'error': {
await this.deps.conversationManager.failTurn(this.conversation!)
throw result.error
}
default: {
const _exhaustive: never = result
void _exhaustive
}
}
}
private async completeWithStaticResponse(rawContent: string): Promise<void> {
this.abortController.signal.throwIfAborted()
this.executionBudget.assertTime()
this.ensureProgressReporter()
const sanitized = this.responseSafety.sanitizeAssistantResponse(rawContent)
const content = sanitized.content
if (sanitized.was_modified) {
this.deps.coreEvents.emit({
type: 'safety:output_sanitized',
data: {
toolName: 'assistant_response',
originalLength: rawContent.length,
sanitizedLength: content.length,
taskId: this.taskId,
},
timestamp: new Date(),
})
}
// D3 — same barrier-before-ACK contract as handleLoopResult 'response'.
this.executionBudget.assertTime()
this.executionBudget.pause()
try {
await this.deps.conversationManager.completeTurn(this.conversation!, content)
} catch (err) {
await this.deps.conversationManager.failTurn(this.conversation!)
throw err
}
this.task.result = {
response: content,
model: this.deps.modelName,
toolsUsed: [],
}
if (this.task.responseCallback) {
await this.task.responseCallback({ response: content })
}
this.state = 'completed'
logger.info({ taskId: this.taskId }, 'Completed with static response')
this.deps.onComplete(this.task)
}
private ensureProgressReporter(): SseProgressReporter {
// Idempotent get-or-create via the shared registry helper (same construction
// site now reused by AgentStateMachine.handleTaskFailure for pre-executor
// failures). Static fail-closed responses bypass the tool loop, but channel
// readers still rely on the task lifecycle terminal event to update the user.
return ensureReporter(
this.taskId,
this.deps.taskLifecycle,
new BasicSafety(this.deps.secretEntriesProvider)
)
}
/**
* R5 — wrap the primary `LlmPort` with provider-failover when a policy is
* wired for this task. Fallback entries are served by their OWN adapters,
* built with the SAME per-task usage sink as the primary (so session token
* accounting + `usage_events` stay correct) and a per-pair token counter.
* Returns the primary unchanged when no policy / no fallbacks (byte-identical).
*/
private wrapFailoverPort(primaryPort: LlmPortAdapter, conversation: Conversation): LlmPort {
const support = this.deps.failover
if (!support || support.policy.fallbacks.length === 0) return primaryPort
const primaryProvider = this.deps.llmProvider.getProviderType()
const primaryModel = this.deps.modelName
return maybeWrapFailover({
primaryPort,
primaryPair: { provider: primaryProvider, model: primaryModel },
engine: support.engine,
policy: support.policy,
buildFallbackPort: index => {
const entry = support.policy.fallbacks[index]
// R5.7 — a SAME-provider fallback (other key) respects the session's
// model; a CROSS-provider fallback serves its fixed entry model
// (ignoring the session selection). #654: resolve the effective model
// BEFORE building so the provider's SDK, the token counter, the usage
// event and the image guard all name the model that is really sent.
const servedModel = entry.provider === primaryProvider ? 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.deps.usageReporter,
this.deps.usageStaticContext,
this.buildDefaultUsageContext(),
counter,
usage => {
this.deps.conversationManager.recordSessionUsage(conversation, usage)
if (conversation.contextBreakdown && usage.input_tokens > 0) {
conversation.contextBreakdown.totalInputTokens = usage.input_tokens
}
},
this.deps.imageInput
)
},
})
}
private async buildLoopConfig(opts?: {
/**
* IronClaw invariant #1 (P.3): when `true`, the loop will skip
* `contextManager.manage()` for the entire run. Set by
* `resumeAfterApproval` so the snapshot reaches the LLM verbatim.
*
* When omitted, derived from `this.conversation.pending_approval`. The
* fall-through default exists so that callers (e.g. `runAgentLoop` on
* the initial turn) don't need to know about IronClaw — the conversation
* shape decides.
*/
skipContextManager?: boolean
}): Promise<LoopConfig> {
const progressReporter = this.ensureProgressReporter()
const tokenCounter = this.getOrCreateTokenCounter()
// Capture the conversation in a local const (not `this.conversation!` inside
// the closure) so a later reassignment of `this.conversation` can't re-point
// the usage sink at a different session.
const conversation = this.conversation!
const llmPort = new LlmPortAdapter(
this.deps.llmProvider,
this.deps.modelName,
this.deps.llmProvider.getProviderType(),
this.deps.usageReporter,
this.deps.usageStaticContext,
this.buildDefaultUsageContext(),
tokenCounter,
usage => {
this.deps.conversationManager.recordSessionUsage(conversation, usage)
// F1.3b — finalize the send-time breakdown's provisional total
// (Σbuckets) with the provider's authoritative `input_tokens` from the
// SAME call. Runs inside the usage sink so there is no lag/race (#8).
if (conversation.contextBreakdown && usage.input_tokens > 0) {
conversation.contextBreakdown.totalInputTokens = usage.input_tokens
}
},
this.deps.imageInput
)
// R5 — wrap the primary port with provider-failover when a policy is wired.
// Each fallback entry gets its OWN adapter (built with the SAME per-task
// usage sink + a per-pair token counter) so `usage_events` records the pair
// really served. No policy → returns `llmPort` unchanged (byte-identical).
const effectiveLlmPort = this.wrapFailoverPort(llmPort, conversation)
// LLM-lane guardrails (spec §7): wrap ABOVE failover so built-in request
// shaping fires once per logical request, not per fallback attempt. Inert
// (returns the port unchanged) when no built-ins are configured (§5).
const hookedLlmPort = bindTaskSignal(
maybeWrapHookedLlmPort(effectiveLlmPort, this.deps.guardrailsConfig),
this.abortController.signal
)
const metadata: Record<string, unknown> = {}
if (this.task.sourceMessage) {
if (this.task.sourceMessage.channelType === 'rpc') {
metadata.channelType = 'desktop'
} else {
metadata.channelType = this.task.sourceMessage.channelType
metadata.sender = this.task.sourceMessage.sender
}
}
const { registry, loopController, bridge, discoverableNatives } = await this.buildToolRegistry()
const applicableToolCounters = registry
.listDefinitions()
.some(tool => tool.name === 'clerum__attachment_read')
? (effectiveLlmPort.getToolTokenCounters?.() ?? [tokenCounter])
: [tokenCounter]
const toolCounters = [...new Set(applicableToolCounters)]
await Promise.all(
toolCounters.filter(counter => counter !== tokenCounter).map(counter => counter.warmup())
)
// T2.2 — when the prompt-cache flag is ON and we have the dependencies
// wired (PromptCache + WorkspaceService), build the tiered
// `SystemPromptParts` once per session via the cache and ship them
// out-of-band through `ReasoningPort`. Otherwise fall back to the legacy
// single-string identity built by `buildSystemIdentity`.
const reasoningFactory = new DefaultReasoningFactory(
hookedLlmPort,
new DefaultPromptBuilder({
nativeToolPresentation: appConfig.nativeToolPresentation,
discoverableNatives,
}),
metadata,
// F1.4 — wire the send-time context-window-breakdown capture. The sink is
// bound to the captured `conversation` local (not `this.conversation!`) so
// a later reassignment can't re-point it at a different session.
tokenCounter,
raw => this.deps.conversationManager.recordContextBreakdown(conversation, raw),
this.contextMaxTokens()
)
const parts = await this.maybeGetOrBuildParts(registry.listDefinitions())
const identity = parts ? undefined : await this.buildSystemIdentity(llmPort)
const reasoning = parts
? reasoningFactory.createWithParts(parts)
: reasoningFactory.create(identity)
// R9-14 / R21-1 — the text of the system prompt `reasoning` sends with a
// request that presents `tools`, for the context manager to count. The
// cache path sends the parts it built once, joined as `LlmPortAdapter`
// joins them, whatever the loop presents; the legacy path runs the builder
// `DefaultReasoningPort` runs, over the presented list. That builder stamps
// `new Date().toISOString()`, so the counted copy carries a different
// timestamp from the sent one; the ISO string is always 24 characters, so
// the byte count, which is all the gauge reads, is the same.
let systemPromptFor: (tools: ToolDefinition[]) => string
if (parts) {
const cachedPrompt = [parts.stable, parts.context].filter(s => s.length > 0).join('\n\n')
systemPromptFor = () => cachedPrompt
} else {
const promptBuilder = new DefaultPromptBuilder({
nativeToolPresentation: appConfig.nativeToolPresentation,
discoverableNatives,
})
systemPromptFor = tools => promptBuilder.buildSystemPrompt(tools, identity, metadata).content
}
const contextManager = new PressureContextManager(
this.contextMaxTokens(),
this.deps.workspaceService,
hookedLlmPort,
tokenCounter,
{
dryRun: appConfig.tokenizerDryrun,
ineffectiveRatio: appConfig.compactionIneffectiveRatio,
ineffectiveMaxRun: appConfig.compactionIneffectiveMaxRun,
events: this.deps.coreEvents,
taskId: this.taskId,
prePruneEnabled: appConfig.compactionPrePruneEnabled,
prePruneOptions: {
protectedTailTurns: appConfig.compactionPrePruneProtectedTailTurns,
summaryThresholdTokens: appConfig.compactionPrePruneSummaryTokens,
maxArgsBytes: appConfig.compactionPrePruneMaxArgsBytes,
dedupEnabled: appConfig.compactionPrePruneDedup,
oneLineSummariesEnabled: appConfig.compactionPrePruneOneLine,
jsonSafeTruncateEnabled: appConfig.compactionPrePruneJsonTruncate,
stripMediaEnabled: appConfig.compactionPrePruneStripMedia,
},
// T1.1 — structured summary template. Default OFF until the
// bake-week confirms ≥80% `parseStatus:'ok'` on the configured model.
structuredSummaryEnabled: appConfig.compactionStructuredSummary,
// T2.2 — when a `summarize` tier runs we invalidate the prompt cache
// (P0-005 §5.7): the daily-log snapshot is now stale (the summary just
// got appended to it), and the next turn should re-snapshot.
onCompactionEffective: this.deps.promptCache
? () => {
const key = this.sessionKey
if (key) this.deps.promptCache!.invalidate(key, 'compact')
}
: undefined,
// #731 — the subscription contracts refuse a request on message count
// alone; the registry carries that bound from each contract's LIMITS.
maxMessages: this.contractMaxMessages(),
}
)
const loopConfig = buildLoopConfig({
reasoning,
toolRegistry: registry,
safety: new BasicSafety(this.deps.secretEntriesProvider),
events: this.buildTrackingEventEmitter(),
// P.5: conversation is always set by the time buildLoopConfig runs —
// runAgentLoop / resumeAfterApproval both construct it after
// `getOrCreate(sessionKey)`. The non-null assertion mirrors how the
// surrounding code already accesses `this.conversation!`.
conversation: this.conversation!,
loopController,
contextManager,
progressReporter,
maxIterations: this.executionBudget.remainingIterations,
toolTimeout: appConfig.nativeTool.toolTimeout,
toolProgressInterval: appConfig.nativeTool.toolProgressInterval,
})
loopConfig.abortSignal = this.abortController.signal
loopConfig.visualInput = {
budget: this.executionBudget.visualInputs,
resolveCapability: signal =>
effectiveLlmPort.getImageInputCapability?.(signal) ??
Promise.resolve({ status: 'unknown' as const }),
}
loopConfig.systemPromptFor = systemPromptFor
loopConfig.imageSourceIdentity = this.providerChainRequiresImageSourceIdentity()
loopConfig.onAttachments = attachments =>
mergeCollectedAttachments(this.completedAttachments, attachments)
// Guardrails (spec §6) — build the tool-lane guardrail from the Host block.
// Undefined when no rules are configured (no-config compatibility, §5); a
// malformed set throws here (fail-closed admission, §3/§5).
loopConfig.guardrails = buildToolLaneGuardrail(this.deps.guardrailsConfig)
// §6.3: a run with no human to answer an approval must fail safe to deny.
loopConfig.executionMode = executionModeForSource(this.task.source)
loopConfig.skipContextManager =
opts?.skipContextManager ?? this.conversation?.pending_approval !== undefined
// T1.5 — pass the storage + taskId down so `executeSingleTool` can persist
// oversized outputs and stamp `spillover_ref` on the result.
loopConfig.spilloverStorage = this.deps.spilloverStorage
loopConfig.taskId = this.taskId
// C15/C16 — the exact synchronous measurement the bounded native readers
// use for a result: the full tool message (framing + the larger applicable
// provider/BPE estimate), never a content-only shortcut.
// Page limits are enforced even when compaction is in tokenizer dry-run.
// Use the largest applicable synchronous estimate for every destination;
// emitted pages can survive a provider change in a later reasoning round.
loopConfig.measureToolMessage = message =>
Math.max(...toolCounters.map(counter => toolMessageBudgetTokens(message, counter, false)))
// F3 (dynamic-tool-loading): context the `clerum__tool_call` bridge intercept
// needs in `executeToolCalls`. Undefined when the registry registered no
// bridge tools (no MCP discovery with an McpManager, and native `direct`).
loopConfig.bridge = bridge
// P2 token budgets (§5.2): wire the per-task emergency brake when the P1
// verdict carried a per-task cap AND we captured a start-of-task baseline.
// Same baseline is reused across resumeAfterApproval (set once in run()), so
// the delta spans the whole task. Left undefined otherwise → loop no-op.
const verdict = this.task.budgetVerdict
if (this.taskTokenBaseline && this.hasTaskBudgetCap() && verdict) {
loopConfig.taskBrake = {
maxTaskTokens: verdict.maxTaskTokens ?? null,
maxTaskCost: verdict.maxTaskCost ?? null,
price: verdict.price ?? null,
baseline: this.taskTokenBaseline,
}
}
return loopConfig
}
private buildTrackingEventEmitter(): AgentEventEmitter {
return {
emit: (event: AgentEvent) => {
if (event.type === 'loop:iteration') this.executionBudget.consumeIteration()
if (event.type === 'tool:called') {
const toolName = typeof event.data.toolName === 'string' ? event.data.toolName.trim() : ''
if (toolName) this.currentTurnToolNames.add(toolName)
}
if (event.type === 'llm:completed') {
const iteration = typeof event.data.iteration === 'number' ? event.data.iteration : 0
// Each approval resume starts a fresh loop at iteration zero.
const occurrence = `${event.timestamp.getTime()}-${iteration}`
this.enqueueGovernedRunEvent(
'llm_call',
`task:${this.taskId}:llm:${occurrence}`,
{
status: 'succeeded',
model: this.deps.modelName,
attempt: iteration + 1,
},
event.timestamp
)
}
if (event.type === 'tool:completed') {
const callId =
typeof event.data.toolCallId === 'string'
? event.data.toolCallId
: `${event.data.toolName ?? 'tool'}:${event.timestamp.getTime()}`
this.enqueueGovernedToolCompletion(
callId,
typeof event.data.toolName === 'string' ? event.data.toolName : 'tool',
event.data.toolKind === 'mcp_server_tool' || event.data.toolKind === 'workflow'
? event.data.toolKind
: 'internal_tool',
typeof event.data.toolSourceRef === 'string'
? event.data.toolSourceRef.trim() || null
: null,
Boolean(event.data.is_error),
event.timestamp
)
}
this.turnTiming?.recordEvent(event.type, event.data)
this.deps.coreEvents.emit(event)
},
on: this.deps.coreEvents.on.bind(this.deps.coreEvents),
off: this.deps.coreEvents.off.bind(this.deps.coreEvents),
}
}
private enqueueGovernedToolCompletion(
toolCallId: string,
toolName: string,
toolKind: 'internal_tool' | 'mcp_server_tool' | 'workflow',
toolSourceRef: string | null,
isError: boolean,
occurredAt: Date
): void {
const approvalRequestId =
this.approvedToolCorrelation?.toolCallId === toolCallId
? this.approvedToolCorrelation.approvalRequestId
: undefined
this.enqueueGovernedRunEvent(
'tool_call',
`task:${this.taskId}:tool:${toolCallId}`,
{
status: isError ? 'failed' : 'succeeded',
tool_name: toolName,
tool_kind: toolKind,
...(toolSourceRef ? { tool_source_ref: toolSourceRef } : {}),
},
occurredAt,
approvalRequestId
)
if (approvalRequestId) this.approvedToolCorrelation = undefined
}
private enqueueGovernedRunEvent(
eventType: 'run_start' | 'llm_call' | 'tool_call' | 'approval' | 'token_usage' | 'run_end',
sourceEventId: string,
payload?: {
status?: string
error_class?: string
tool_name?: string
tool_kind?: 'internal_tool' | 'mcp_server_tool' | 'workflow'
tool_source_ref?: string
model?: string
attempt?: number
count?: number
},
occurredAt = new Date(),
approvalRequestId?: string
): void {
const trace = this.task.traceContext
const hostRef = this.deps.usageStaticContext?.host_ref
if (!trace || !hostRef) return
this.deps.governedRunReporter?.enqueue({
sourceEventId,
occurredAt: occurredAt.toISOString(),
eventType,
runId: trace.runId,
approvalRequestId,
hostRef,
sessionId: trace.sessionId ?? null,
origin: trace.origin,
...(payload ? { payload } : {}),
})
}
private async guardProviderWorkflowTriggerClaim(rawContent: string): Promise<string> {
if (this.currentTurnToolNames.has('workflow_trigger')) return rawContent
const sourceMessageContent = this.task.sourceMessage?.content ?? ''
const sourceLooksLikeTriggerRequest = looksLikeWorkflowTriggerRequest(sourceMessageContent)
const usedWorkflowReadTool = [...this.currentTurnToolNames].some(
toolName => toolName.startsWith('workflow_') && toolName !== 'workflow_trigger'
)
if (usedWorkflowReadTool && !sourceLooksLikeTriggerRequest) return rawContent
if (!looksLikeWorkflowTriggerSuccess(rawContent) && !sourceLooksLikeTriggerRequest) {
return rawContent
}
const context = this.workflowCallerContextOverride
if (
!context ||
!context.targetUserId ||
(context.originChannelType !== 'telegram' &&
context.originChannelType !== 'slack' &&
context.originChannelType !== 'teams')
) {
if (
this.workflowAccessDeniedResponse &&
isProviderWorkflowChannel(this.task.sourceMessage?.channelType)
) {
this.logProviderWorkflowAccessDenied('trigger_claim')
return this.workflowAccessDeniedResponse
}
return rawContent
}
const workflowContext: WorkflowCallerContext & { targetUserId: string } = {
...context,
targetUserId: context.targetUserId,
}
try {
return await this.resolveUnverifiedProviderWorkflowTriggerClaim(workflowContext)
} catch (error) {
logger.warn(
{ taskId: this.taskId, err: error },
'Could not verify provider workflow trigger claim'
)
return 'I could not verify that a workflow was triggered from this message. List workflows and run the workflow by name again.'
}
}
private async resolveUnverifiedProviderWorkflowTriggerClaim(
context: WorkflowCallerContext & { targetUserId: string }
): Promise<string> {
const workflowName = await this.workflowNameMentionedInCurrentMessage(context)
if (!workflowName) {
return 'I could not verify which workflow should be triggered. List workflows and run the workflow by name again.'
}
const client = this.workflowBrokerClient()
const resolution = await resolveEffectiveWorkflowTarget(client, context, workflowName)
if (resolution.kind !== 'unique') {
return resolution.message
}
return `I could not verify that ${workflowName} was triggered. Run ${workflowName} again so I can request approval from this conversation.`
}
private async workflowNameMentionedInCurrentMessage(
context: WorkflowCallerContext & { targetUserId: string }
): Promise<string | null> {
const content = this.task.sourceMessage?.content ?? ''
const normalizedContent = content.toLocaleLowerCase('en-US')
if (!normalizedContent.trim()) return null
const result = await requestEffectiveWorkflowList(this.workflowBrokerClient(), context)
const record =
result && typeof result === 'object' && !Array.isArray(result)
? (result as Record<string, unknown>)
: {}
const items = Array.isArray(record.items) ? record.items : []
const names = items
.flatMap(item => {
if (!item || typeof item !== 'object' || Array.isArray(item)) return []
const name = (item as Record<string, unknown>).name
return typeof name === 'string' && name.trim() ? [name.trim()] : []
})
.sort((a, b) => b.length - a.length)
const listedName =
names.find(name => normalizedContent.includes(name.toLocaleLowerCase('en-US'))) ?? null
if (listedName) return listedName
const commandMatch = normalizedContent.match(
/\b(?:run|trigger|start|execute)\s+([a-z0-9][a-z0-9._-]*)/
)
return commandMatch?.[1] ?? null
}
private workflowBrokerClient(): WorkflowBrokerClient {
const getEnv = (key: string) => process.env[key]
return new WorkflowBrokerClient(getEnv, createWorkflowControlTokenProvider(getEnv))
}
/**
* Build the default UsageContext for this task. The adapter falls back to
* this when an individual CompletionRequest doesn't carry its own.
*
* Mapping rules (v1):
* - task.source = 'channel' + channelType = 'rpc' → source_kind = 'desktop',
* user_id = sender (the Desktop App is *not* a third-party channel; the
* RPC route stamps message.sender with the authenticated user's `sub`,
* so the UUID belongs in user_id, not sender.)
* - task.source = 'channel' → source_kind = 'channel', sender + channel_type from sourceMessage
* - task.source = 'cron' → source_kind = 'cron', cron_job_id from task.cronJobId
* - task.source = 'internal' → source_kind = 'desktop'
* Workflow-recipe LLM calls go through workflowService and are tagged
* separately at that call site.
*/
private buildDefaultUsageContext(): UsageContext | undefined {
const t = this.task
if (t.source === 'channel') {
if (t.sourceMessage?.channelType === 'rpc') {
const teamId =
typeof t.sourceMessage.metadata?.teamId === 'string'
? t.sourceMessage.metadata.teamId.trim()
: ''
return {
source_kind: 'desktop',
traceContext: t.traceContext ?? null,
team_id: teamId || null,
user_id: t.sourceMessage.sender ?? null,
task_id: t.id,
}
}
return {
source_kind: 'channel',
traceContext: t.traceContext ?? null,
sender: t.sourceMessage?.sender ?? null,
channel_type: t.sourceMessage?.channelType ?? null,
task_id: t.id,
}
}
if (t.source === 'cron') {
return {
source_kind: 'cron',
traceContext: t.traceContext ?? null,
cron_job_id: t.cronJobId ?? null,
task_id: t.id,
}
}
if (t.source === 'internal') {
return {
source_kind: 'desktop',
traceContext: t.traceContext ?? null,
task_id: t.id,
}
}
return { source_kind: 'unknown', traceContext: t.traceContext ?? null, task_id: t.id }
}
/**
* T2.2 — get-or-build the tiered `SystemPromptParts` for this session.
* Returns `undefined` when the cache flag is OFF or when no `PromptCache`
* / `WorkspaceService` is wired (legacy path stays bit-identical). When
* present the parts are looked up by sessionKey; a miss reads the four
* identity files + a fresh `snapshotDailyLogs(2)` (frozen for the life of
* this session) and runs the parts through `DefaultPromptBuilder.buildParts`.
*
* The lookup is per-task; the cache lives on the process and survives
* across tasks of the same session, so multi-turn conversations get a
* single build amortized over many LLM calls.
*/
private async maybeGetOrBuildParts(
tools: ToolDefinition[]
): Promise<SystemPromptParts | undefined> {
if (!appConfig.promptCacheEnabled) return undefined
if (!this.deps.promptCache || !this.deps.workspaceService) return undefined
const sessionKey = this.sessionKey
if (!sessionKey) return undefined
const cached = this.deps.promptCache.get(sessionKey)
const provider = this.deps.llmProvider.getProviderType()
// Only instruction-presence gates belong in the cache identity. Catalog
// count and schemas do not: discovery guidance is constant at any scale.
const toolGuidanceKey = JSON.stringify([
tools.some(t => t.name.startsWith('memory_')),
tools.some(t => t.name === 'clerum__get_capabilities'),
tools.some(t => t.name.startsWith('desktop_') || t.name.startsWith('browser_')),
tools.some(t => t.name.startsWith('workflow_')),
tools.some(t => t.name === 'clerum__gfs_download'),
tools.some(t => t.name.includes('__')),
tools.some(t => t.name === 'clerum__tool_search'),
// #1003 — the discovery guidance text depends on the native presentation.
appConfig.nativeToolPresentation,
])
// R2 — the system prompt embeds the model name, so a cache entry built for a
// different (e.g. just-swapped) model is a miss: rebuild, but keep the frozen
// dailyLogSnapshot so the daily-freeze invariant holds.
if (
cached?.parts &&
cached.model === this.deps.modelName &&
cached.provider === provider &&
cached.toolGuidanceKey === toolGuidanceKey
)
return cached.parts
const dailyLogSnapshot =
cached?.dailyLogSnapshot ?? (await this.deps.workspaceService.snapshotDailyLogs(2))
const identityFiles = await this.deps.workspaceService.readIdentityFiles()
const builder = new DefaultPromptBuilder({
nativeToolPresentation: appConfig.nativeToolPresentation,
})
const hasMemoryTools = tools.some(t => t.name.startsWith('memory_'))
const hasCapabilities = tools.some(t => t.name === 'clerum__get_capabilities')
const hasDesktopTools = tools.some(
t => t.name.startsWith('desktop_') || t.name.startsWith('browser_')
)
// Tool-presence gates MUST mirror `buildSystemPrompt` exactly so the cache
// path emits byte-identical guidance to the legacy path. Note `includes('__')`
// (not a strict MCP-server check) matches the legacy MCP-selection gate,
// which also fires for `clerum__get_capabilities`.
const hasWorkflowTools = tools.some(t => t.name.startsWith('workflow_'))
const hasGfsDownloadTool = tools.some(t => t.name === 'clerum__gfs_download')
// NOTE: this is intentionally still true when the bridge is active — the
// `clerum__tool_search/describe/call` native/bridge tools also contain `__`,
// so `MCP_SERVER_SELECTION_TEXT` still emits. That is fine: `TOOL_DISCOVERY_TEXT`
// (gated below and emitted right after) clarifies the discovery flow. We do NOT
// tighten the heuristic here — a stricter check would alter the flag-OFF default
// path on native-only hosts and break the byte-identical guarantee. A deeper
// suppression is deferred for that reason.
const hasMcpTools = tools.some(t => t.name.includes('__'))
// The registered bridge is the same source of truth as the legacy prompt.
const hasToolDiscovery = tools.some(t => t.name === 'clerum__tool_search')
const capabilities = hasCapabilities ? CAPABILITY_CONTRACT_TEXT : ''
const platformHints: string[] = []
if (hasDesktopTools) {
platformHints.push(DESKTOP_ENVIRONMENT_HINT)
}
const parts = builder.buildParts({
identityFiles,
dailyLogSnapshot,
model: this.deps.modelName,
provider: this.deps.llmProvider.getProviderType(),
platformHints,
capabilities,
workflowGuidance: hasWorkflowTools ? WORKFLOW_RECIPES_TEXT : '',
gfsWorkspaceGuidance: hasGfsDownloadTool ? GFS_WORKSPACE_FILE_GUIDANCE_TEXT : '',
mcpServerGuidance: hasMcpTools ? MCP_SERVER_SELECTION_TEXT : '',
toolDiscoveryGuidance: hasToolDiscovery
? toolDiscoveryText(appConfig.nativeToolPresentation)
: '',
memoryGuidance: hasMemoryTools ? MEMORY_GUIDANCE_TEXT : '',
})
this.deps.promptCache.set(sessionKey, {
parts,
dailyLogSnapshot,
model: this.deps.modelName,
provider,
toolGuidanceKey,
})
// P1-005: persist the stable_hash for auditability and so post-eviction
// rebuilds in the same session can verify identity-files didn't drift.
if (this.conversation) {
this.deps.conversationManager.recordSystemPromptStableHash(
this.conversation,
parts.stableHash
)
}
stampStableHashGauge(sessionKey, parts.stableHash)
return parts
}
private async buildSystemIdentity(llmPort: LlmPortAdapter): Promise<string> {
const providerType = this.deps.llmProvider.getProviderType()
const modelLine =
`You are an AI assistant powered by the ${this.deps.modelName} model (provider: ${providerType}). ` +
'Use the available tools when needed to help the user.'
if (this.deps.workspaceService) {
const workspaceIdentity = await this.deps.workspaceService.assembleSystemPrompt()
return workspaceIdentity ? `${workspaceIdentity}\n\n---\n\n${modelLine}` : modelLine
}
return modelLine
}
/**
* Best-effort per-turn catalog bootstrap. Opens the caller's grant-backed
* remote OAuth partitions (per-user and SHARED oauth-context) so their tools
* are in the catalog this turn builds — a failure only forfeits that head start
* and falls back to lazy admission, so it NEVER throws. It runs once per task
* (createToolRegistry is cached by toolRegistryPromise), and the abort only cuts
* this turn's wait: the admissions belong to the manager, are coalesced there,
* and outlive the turn.
*/
private async bootstrapMcpCatalog(): Promise<void> {
const manager = this.deps.mcpManager
const userId = this.task.sourceMessage?.sender
if (!manager || !userId) return
const started = Date.now()
try {
const summary = await withAbort(
() => manager.bootstrapUserCatalog(userId, { signal: this.abortController.signal }),
this.abortController.signal
)
if (summary.candidates > 0) {
logger.info({ taskId: this.taskId, ...summary }, 'MCP catalog bootstrap')
}
} catch (err) {
logger.warn(
{ taskId: this.taskId, err, elapsedMs: Date.now() - started },
'MCP catalog bootstrap failed; continuing with lazy admission'
)
}
}
private async buildToolRegistry(): Promise<TaskToolRegistry> {
if (!this.toolRegistryPromise) {
this.toolRegistryPromise = this.createToolRegistry()
}
try {
return await this.toolRegistryPromise
} catch (error) {
this.toolRegistryPromise = null
throw error
}
}
private async createToolRegistry(): Promise<TaskToolRegistry> {
const workflowCallerContext =
this.workflowCallerContextOverride === undefined
? await this.prepareChannelWorkflowCallerContext()
: this.workflowCallerContextOverride
// Failover reuses this registry: any Codex provider in the chain requires
// Codex-compatible presentation before the first provider attempt.
const presentation = resolveToolPresentation(
this.deps.llmProvider.getProviderType(),
appConfig,
this.deps.failover?.policy.fallbacks
)
// #1003 — native-tool presentation is host-wide and provider-independent:
// it never depends on the MCP presentation resolved above.
const nativeAuto = appConfig.nativeToolPresentation === 'auto'
// The store is keyed like the caller root, never by the raw sender.
const gfsCallerIdentity = gfsStoreCallerIdentity(this.task.sourceMessage)
const gfsWorkspace = gfsManagedWorkspaceExecution({
approvalEnabled: appConfig.enableApproval,
source: this.task.source,
callerIdentity: gfsCallerIdentity,
store: this.deps.gfsDownloadStore,
callerWorkspacePath: this.deps.gfsCallerWorkspacePath,
approvalConfig: this.deps.approvalConfig,
retentionOwnerId: this.taskId,
})
const gfsDeliveryEligible = gfsWorkspace
? gfsWorkspaceExecutionEnabled({
approvalEnabled: appConfig.enableApproval,
source: this.task.source,
callerIdentity: this.task.sourceMessage?.sender,
store: gfsWorkspace.store,
callerWorkspacePath: gfsWorkspace.callerWorkspacePath,
approvalConfig: this.deps.approvalConfig,
retentionOwnerId: this.taskId,
})
: false
const nativeRegistry = new NativeToolRegistry(
appConfig.nativeTool,
this.conversation!.id,
this.deps.cronScheduler ?? undefined,
this.task.sourceMessage,
this.deps.workspaceService,
this.deps.dynamicEnvProvider,
workflowCallerContext,
{
maxBytes: appConfig.attachmentMaxBytes,
secretEntriesProvider: this.deps.secretEntriesProvider,
// Keep the ledger and bound pages for every model this task may serve.
ledger: this.attachmentReadLedger,
contextWindowTokens: attachmentContextWindow(
this.contextMaxTokens(),
this.deps.llmProvider.getProviderType(),
this.deps.failover?.policy.fallbacks ?? [],
this.deps.failover?.contextWindowForPair,
appConfig.contextMaxTokens
),
},
this.deps.spilloverStorage,
this.deps.sessionSearchService,
// F2 (dynamic-tool-loading): backs the read-only discovery meta-tools
// (clerum__tool_search / clerum__tool_describe). Reuses the same manager
// already threaded into the MCP tool registry below.
this.deps.mcpManager ?? undefined,
// #1003 — MCP discovery and native discovery are separate decisions;
// either one registers the bridge tools.
{ mcpDiscovery: presentation.bridgeEnabled, nativeDiscovery: nativeAuto },
// §13 (stateless agents): the active provider's credential slot is the
// only one that survives into shell_exec's child env.
this.deps.llmProvider.getProviderType(),
gfsWorkspace ? { ...gfsWorkspace, deliveryAvailable: gfsDeliveryEligible } : undefined,
generatedOutputsRoot(this.task.sourceMessage, this.deps.gfsCallerWorkspacePath)
)
await registerDesktopTools(nativeRegistry)
// Eagerly open this caller's remote OAuth partitions before the catalog is
// read, so grant-backed tools exist in the very first turn instead of after a
// failed lazy call. Best-effort: a failure here must never invalidate the
// registry promise or the task.
await this.bootstrapMcpCatalog()
const mcpRegistry = this.deps.mcpManager
? // Thread the authenticated caller identity so oauth grantScope='user'
// tools dispatch to the caller's per-user partition (fail-closed when
// absent). buildToolRegistry runs per turn, so one userId per adapter.
new McpToolRegistryAdapter(
this.deps.mcpManager,
this.task.sourceMessage?.sender ?? undefined,
{ strictValidation: presentation.codexMode !== undefined }
)
: nativeRegistry
const compositeRegistry = this.deps.mcpManager
? new CompositeToolRegistry(nativeRegistry, mcpRegistry)
: nativeRegistry
// Cron tasks run autonomously by design: the human trust decision happens at
// job-creation time, so the runtime approval gate does NOT apply per-tool at
// fire time (there is no user to approve). Containment is infrastructural
// (Context allowlist, NetworkPolicy, tool-call and duration limits). See
// issue #529.
//
// NARROW EXCEPTION (cron×stateless self-propagation containment): a
// cron-sourced task may still call cron_manage. On a stateless host,
// cron_manage create/enable each pin the pod awake (activeCronSchedules) and
// let an already-approved schedule autonomously spawn/enable MORE schedules
// — a prompt-injection self-propagation + cost lever. So on a stateless host
// we DO wrap a cron-sourced task with the approval chain, but in
// `cronManageGateOnly` mode: ONLY cron_manage create/enable can suspend;
// every other tool call (incl. cron_manage list/get/delete/disable/trigger
// and all non-cron_manage work) keeps #529's autonomy and proceeds. The
// resulting suspension has no human to answer it in an autonomous run — that
// is the desired containment: the suspicious create/enable is BLOCKED, not
// auto-approved.
const interactiveApprovalApplies = appConfig.enableApproval && this.task.source !== 'cron'
const cronManageGateApplies =
appConfig.enableApproval && this.task.source === 'cron' && appConfig.statelessLifecycle
const approvalApplies = interactiveApprovalApplies || cronManageGateApplies
const approvalGate = approvalApplies
? new UnifiedApprovalGateController(
compositeRegistry,
this.deps.approvalConfig,
nativeRegistry,
// Cron×stateless: forces HITL approval for cron_manage create/enable on
// stateless hosts regardless of the per-tool approval override.
// `cronManageGateOnly` narrows that to be the ONLY gate for a
// cron-sourced task, preserving #529 autonomy for every other tool.
{
statelessLifecycle: appConfig.statelessLifecycle,
cronManageGateOnly: cronManageGateApplies,
}
)
: null
const innerController = approvalGate
? new ApprovalController(
this.conversation!,
approvalGate,
gfsWorkspace &&
appConfig.enableApproval &&
this.task.source === 'channel' &&
this.deps.approvalConfig?.tools?.shell_exec !== false
? new Set(['clerum__gfs_download'])
: undefined,
// The same gate's forced approvals (stateless cron create/enable) run
// before any stored approval, so none of them can cover such a call.
approvalGate
)
: new DefaultLoopController()
const mcpManager = this.deps.mcpManager
// Exact native membership preserves every native/plugin capability.
const nativeDefinitions = nativeRegistry.listDefinitions()
const nativeNames = new Set(nativeDefinitions.map(d => d.name))
// #1003 — native presentation wraps OUTSIDE the MCP decision on every
// return, so it can only remove natives from the list the MCP presentation
// produced. In `direct` it returns that list unchanged.
const withNativePresentation = (controller: LoopController): LoopController =>
new NativeToolPresentationController(controller, nativeDefinitions, {
mode: appConfig.nativeToolPresentation,
discoveryBytes: appConfig.nativeToolDiscoveryBytes,
})
// The natives that controller hides, for the prompt builder's guidance.
const deferredNatives = nativeAuto
? selectDeferredNatives(nativeDefinitions, appConfig.nativeToolDiscoveryBytes)
: new Set<string>()
const discoverableNatives = nativeDefinitions.filter(d => deferredNatives.has(d.name))
// The bridge intercept (executeToolCalls) needs `nativeNames` + the live
// deferrable catalog. It exists exactly when NativeToolRegistry registered
// the bridge tools (MCP discovery with an McpManager, or native `auto`), so
// it is derived from the registry rather than repeating that predicate.
// Codex direct with native `direct` observes presentation without
// installing discovery interception or registering bridge tools.
const bridge: LoopConfig['bridge'] = [...BRIDGE_TOOL_NAMES].every(name => nativeNames.has(name))
? {
nativeNames,
getDeferrableCatalogNames: () =>
mcpManager
? new Set(
mcpManager
.getAllTools()
.map(t => t.name)
.filter(name => !nativeNames.has(name))
)
: new Set<string>(),
nativeTargets: nativeAuto,
}
: undefined
// Codex direct still observes the live catalog; observation must not enable discovery.
if (!presentation.bridgeEnabled && presentation.codexMode === undefined) {
return {
registry: compositeRegistry,
nativeRegistry,
loopController: withNativePresentation(innerController),
discoverableNatives,
// Native `auto` only: MCP presentation is unchanged (no MCP decision on
// this path) but the bridge serves natives and keeps MCP tools callable.
bridge,
}
}
// LOCKED #6: the latch lives on the session-scoped Conversation, NOT on the
// per-task controller, so a server connecting/disconnecting BETWEEN turns
// cannot flip `tools[]` and re-introduce cache invalidation. Ephemeral RAM
// (not a DB column), recomputed on cold-load — consistent with #3.
const conversation = this.conversation!
const loopController: LoopController = new DeferrableToolController(
innerController,
nativeNames,
{
dynamicToolsEnabled: presentation.bridgeEnabled,
codexMode: presentation.codexMode,
codexToolDiscoveryBytes: appConfig.codexToolDiscoveryBytes,
dynamicToolsThreshold: appConfig.dynamicToolsThreshold,
},
{
get: () => conversation.dynamicToolsBridgeActive,
set: value => {
conversation.dynamicToolsBridgeActive = value
},
}
)
return {
registry: compositeRegistry,
nativeRegistry,
loopController: withNativePresentation(loopController),
discoverableNatives,
bridge,
}
}
private async prepareChannelWorkflowCallerContext(): Promise<
WorkflowCallerContext | null | undefined
> {
if (this.workflowCallerContextOverride !== undefined) return this.workflowCallerContextOverride
const message = this.task.sourceMessage
if (!message || message.channelType === 'rpc') {
this.workflowAccessDeniedResponse = null
this.workflowAccessDeniedReason = null
this.workflowCallerContextOverride = undefined
return undefined
}
if (
message.channelType !== 'telegram' &&
message.channelType !== 'slack' &&
message.channelType !== 'teams'
) {
this.workflowAccessDeniedResponse = null
this.workflowAccessDeniedReason = null
this.workflowCallerContextOverride = null
return null
}
if (!message.providerIdentity) {
this.setProviderWorkflowAccessDenied(message, 'missing_provider_identity')
return null
}
try {
const context = await resolveProviderWorkflowCallerContext(
message,
key => process.env[key],
this.task.traceContext
)
if (context) {
this.workflowAccessDeniedResponse = null
this.workflowAccessDeniedReason = null
this.workflowCallerContextOverride = context
return context
}
} catch (error) {
logger.warn(
{ taskId: this.taskId, err: error },
'Provider workflow identity resolution failed'
)
}
this.setProviderWorkflowAccessDenied(message, 'unverified_provider_identity')
return null
}
private setProviderWorkflowAccessDenied(
message: NonNullable<Task['sourceMessage']>,
reason: ProviderWorkflowAccessDenialReason
): void {
this.workflowCallerContextOverride = null
this.workflowAccessDeniedResponse = workflowAccessDeniedResponseForMessage(message)
this.workflowAccessDeniedReason = reason
}
private logProviderWorkflowAccessDenied(stage: 'request' | 'trigger_claim'): void {
const message = this.task.sourceMessage
const channel = isProviderWorkflowChannel(message?.channelType)
? message.channelType
: 'unknown'
logger.warn(
{
taskId: this.taskId,
channel,
stage,
reason: this.workflowAccessDeniedReason ?? 'unverified_provider_identity',
},
'Provider workflow access denied'
)
}
private collectAttachments(results: ToolResult[]): Attachment[] {
const attachments: Attachment[] = []
collectToolAttachments(results, attachments)
return attachments
}
/**
* Codex V2 hashes each image source. Bind identity only when this chain
* (primary or a configured fallback) requires it so a non-Codex wire stays
* on the #654 shape.
*/
private providerChainRequiresImageSourceIdentity(): boolean {
return (
this.deps.llmProvider.requiresImageSourceIdentity === true ||
[
this.deps.llmProvider.getProviderType(),
...(this.deps.failover?.policy.fallbacks.map(entry => entry.provider) ?? []),
].some(
provider =>
isLlmProvider(provider) && descriptorFor(provider).requiresImageSourceIdentity === true
)
)
}
private buildSourceMessageContentParts(messageContent: string): MessageContentPart[] {
const providerType = this.deps.llmProvider.getProviderType()
// getProviderType() always returns a registered LlmProvider, so in practice
// this never drops images for a known provider — that's the point: a new
// registry provider keeps its image attachments instead of silently losing
// them to a stale allow-list.
if (!isLlmProvider(providerType)) {
return []
}
const sourceAttachments = this.task.sourceMessage?.attachments
if (!sourceAttachments || sourceAttachments.length === 0) {
return []
}
// Frozen provenance identity (#650). `messageId` is the delivery identity
// the channel supplied; internal/cron sources carry an empty id, so the
// queued task id stands in as the real identity of that task's message.
// Neither value is a placeholder, and neither is rewritten here: a value
// the shared contract does not accept fails its projection check instead.
const messageId = this.task.sourceMessage?.messageId?.trim() || this.task.id
const bindSource = this.providerChainRequiresImageSourceIdentity()
const imageParts = sourceAttachments
.filter(
att =>
att.kind === 'image' && (att.mimeType === 'image/jpeg' || att.mimeType === 'image/png')
)
.map(
(att): MessageContentPart => ({
type: 'image',
mimeType: att.mimeType as 'image/jpeg' | 'image/png',
data: att.dataBase64,
...(bindSource
? { source: { kind: 'attachment' as const, attachmentId: att.id, messageId } }
: {}),
})
)
if (!imageParts.length) {
return []
}
// Preserve the actual history text (including any contextual enrichment).
// Reading sourceMessage again would overwrite text already assembled above.
const userText = messageContent.trim() ? messageContent : 'User attached image(s).'
return [{ type: 'text', text: userText }, ...imageParts]
}
}