Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): enforce durable task and tool execution limits (#643)

ALFREDO J LOPEZ H (alfredolopez80.eth)81cd64ab9efb
diff --git a/deploy/overlays/minikube/configmaps/mcp-host-config.yaml b/deploy/overlays/minikube/configmaps/mcp-host-config.yaml
index 34f97cf2e..196297ce0 100644
--- a/deploy/overlays/minikube/configmaps/mcp-host-config.yaml
+++ b/deploy/overlays/minikube/configmaps/mcp-host-config.yaml
@@ -19,13 +19,13 @@ data:
HCC_AUTHORITY_MAX_STALENESS_MS: '60000'
MCP_PROXY_URL: 'http://mcp-proxy.mcp-server.svc.cluster.local:8083'
CLERUM_AGENT_TASK_DELAY: '3'
- CLERUM_AGENT_MAX_TASK_DURATION: '1800000'
- CLERUM_SHELL_TIMEOUT: '600000'
- CLERUM_TOOL_TIMEOUT: '660000'
- CLERUM_MCP_TOOL_TIMEOUT_MS: '3600000'
- CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS: '3600000'
+ CLERUM_AGENT_MAX_TASK_DURATION: '86400000'
+ CLERUM_SHELL_TIMEOUT: '1500000'
+ CLERUM_TOOL_TIMEOUT: '1500000'
+ CLERUM_MCP_TOOL_TIMEOUT_MS: '1500000'
+ CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS: '1500000'
CLERUM_TOOL_PROGRESS_INTERVAL_MS: '5000'
- CLERUM_AGENT_MAX_TOOL_CALLS: '100'
+ CLERUM_AGENT_MAX_TOOL_CALLS: '1000'
CLERUM_AGENT_MAX_QUEUE_SIZE: '100'
CLERUM_BUDGETS_ENABLED: 'true'
TRACING_APPROVAL_PROMPT_HISTORY_ENABLED: 'false'
diff --git a/desktop-app/ui/src/components/agents/ChatThread.tsx b/desktop-app/ui/src/components/agents/ChatThread.tsx
index 7ead4bad6..c272bc721 100644
--- a/desktop-app/ui/src/components/agents/ChatThread.tsx
+++ b/desktop-app/ui/src/components/agents/ChatThread.tsx
@@ -719,9 +719,9 @@ export function ChatThread({ showAgentLabel = false, onScrollPositionChange }: C
/>
</p>
) : null}
- <MessageAttachmentList attachments={displayAttachments} />
</>
)}
+ <MessageAttachmentList attachments={displayAttachments} />
{isLastAssistantMessage &&
prevGroup?.role === 'user' &&
(() => {
diff --git a/desktop-app/ui/src/components/agents/__tests__/ChatThread.renderSemantics.test.tsx b/desktop-app/ui/src/components/agents/__tests__/ChatThread.renderSemantics.test.tsx
index 0de17bc40..d8acc55c7 100644
--- a/desktop-app/ui/src/components/agents/__tests__/ChatThread.renderSemantics.test.tsx
+++ b/desktop-app/ui/src/components/agents/__tests__/ChatThread.renderSemantics.test.tsx
@@ -1,6 +1,6 @@
// @vitest-environment jsdom
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, render } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
import { buildLoadedChatSemanticModels } from '../../../lib/chatMessageSemantics'
import type { AgentChatMessage } from '../../../uiTypes'
import { ChatThread } from '../ChatThread'
@@ -63,6 +63,8 @@ afterEach(() => {
cleanup()
messages = []
vi.clearAllMocks()
+ vi.restoreAllMocks()
+ vi.unstubAllGlobals()
})
describe('ChatThread semantic renderer compatibility', () => {
@@ -86,3 +88,54 @@ describe('ChatThread semantic renderer compatibility', () => {
expect(container.querySelector('.error-bubble-details-text')?.textContent).toBe(content)
})
})
+
+it('keeps generated files visible and downloadable on an interrupted error message', () => {
+ messages = [
+ {
+ id: 'interrupted',
+ role: 'assistant',
+ content: 'Task interrupted',
+ timestamp: 1,
+ isError: true,
+ errorCode: 'TASK_ITERATION_LIMIT',
+ attachments: [
+ {
+ id: 'report',
+ type: 'response_file',
+ label: 'report.md',
+ filename: 'report.md',
+ mimeType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: 'IyByZXBvcnQ=',
+ },
+ ],
+ },
+ ]
+ // Only the browser download boundary is replaced in this component test.
+ const createObjectURL = vi.fn(() => 'blob:unit-download')
+ const revokeObjectURL = vi.fn()
+ const NativeURL = URL
+ vi.stubGlobal(
+ 'URL',
+ class extends NativeURL {
+ static createObjectURL = createObjectURL
+ static revokeObjectURL = revokeObjectURL
+ }
+ )
+ const clicked: string[] = []
+ vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(function (
+ this: HTMLAnchorElement
+ ) {
+ clicked.push(this.download)
+ })
+ render(<ChatThread />)
+ expect(screen.getByText('Task interrupted', { selector: '.error-bubble-message' })).toBeTruthy()
+ expect(screen.getByTestId('agent-response').classList.contains('chat-bubble--error')).toBe(true)
+ fireEvent.click(screen.getByRole('button', { name: 'Download' }))
+ expect(clicked).toEqual(['report.md'])
+ expect(createObjectURL).toHaveBeenCalledWith(
+ expect.objectContaining({ size: 8, type: 'text/markdown' })
+ )
+ expect(revokeObjectURL).toHaveBeenCalledWith('blob:unit-download')
+ expect(screen.getByTestId('agent-response').classList.contains('chat-bubble--error')).toBe(true)
+})
diff --git a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/__tests__/taskTracker.test.ts b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/__tests__/taskTracker.test.ts
index 78e54c0ff..bd21597ad 100644
--- a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/__tests__/taskTracker.test.ts
+++ b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/__tests__/taskTracker.test.ts
@@ -139,7 +139,7 @@ describe('TaskTracker', () => {
},
})
- expect(rpc.getTaskResult).not.toHaveBeenCalled()
+ expect(rpc.getTaskResult).toHaveBeenCalledWith('agent-x', 'task-1', ['agent-x'])
const [, state] = onTerminal.mock.calls[0]!
expect(state.terminalResult).toEqual({
kind: 'error',
@@ -1053,3 +1053,62 @@ describe('TaskTracker — tool_complete token narrowing', () => {
expect(step?.tokens).toBeUndefined()
})
})
+
+describe('failed task artifact contract', () => {
+ it('retrieves generated files without converting failure into success', async () => {
+ const onTerminal = vi.fn()
+ tracker.setCallbacks({ onTerminal })
+ tracker.start(KEY, 'task-artifact', 'um-1')
+ rpc.getTaskResult.mockResolvedValue({
+ success: false,
+ error: { message: 'limit' },
+ attachments: [
+ {
+ id: 'file-1',
+ kind: 'file',
+ encoding: 'base64',
+ filename: 'report.md',
+ mimeType: 'text/markdown',
+ dataBase64: 'IyByZXBvcnQ=',
+ },
+ ],
+ })
+ await rpc.emit({
+ type: 'terminal',
+ data: {
+ taskId: 'task-artifact',
+ status: 'failed',
+ error: { message: 'limit', code: 'TASK_ITERATION_LIMIT' },
+ },
+ })
+ expect(onTerminal).toHaveBeenCalledTimes(1)
+ const state = onTerminal.mock.calls[0]![1]
+ expect(state.status).toBe('failed')
+ expect(state.terminalResult).toMatchObject({
+ kind: 'error',
+ source: 'failed',
+ code: 'TASK_ITERATION_LIMIT',
+ attachments: [{ type: 'response_file', label: 'report.md' }],
+ })
+ })
+ it('retains the terminal error if its artifacts cannot be fetched', async () => {
+ const onTerminal = vi.fn()
+ tracker.setCallbacks({ onTerminal })
+ tracker.start(KEY, 'task-error', 'um-1')
+ rpc.getTaskResult.mockRejectedValue(new Error('offline'))
+ await rpc.emit({
+ type: 'terminal',
+ data: {
+ taskId: 'task-error',
+ status: 'failed',
+ error: { message: 'limit', code: 'TASK_DURATION_LIMIT' },
+ },
+ })
+ expect(onTerminal.mock.calls[0]![1].terminalResult).toMatchObject({
+ kind: 'error',
+ source: 'failed',
+ message: 'limit',
+ code: 'TASK_DURATION_LIMIT',
+ })
+ })
+})
diff --git a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts
index ff3b3667b..8400de60e 100644
--- a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts
+++ b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/taskTracker.ts
@@ -2,7 +2,11 @@ import { classifyTier } from '@hooks/useTaskTier'
import { buildResponseFileAttachments } from '@lib/chatMessageAttachments'
import { extractAssistantReply } from '@lib/format'
import type { ProgressStep } from '@/uiTypes'
-import type { SessionTokensLite, TaskProgressStreamEvent } from '../../../../src/types'
+import type {
+ ChatMessageAttachment,
+ SessionTokensLite,
+ TaskProgressStreamEvent,
+} from '../../../../src/types'
import {
type AgentTaskTracker,
type AttachOptions,
@@ -619,12 +623,23 @@ export class TaskTracker implements AgentTaskTracker {
return
}
if (td.status === 'failed' && td.error?.message) {
+ const failedTaskId = state.taskId
+ let attachments: ChatMessageAttachment[] = []
+ try {
+ const { agentRef } = parseTaskKey(key)
+ const result = await window.clerum.rpc.getTaskResult(agentRef, failedTaskId, [agentRef])
+ attachments = buildResponseFileAttachments(result)
+ } catch {
+ // Preserve the authoritative terminal error if artifact retrieval fails.
+ }
+ if (this.states.get(key)?.taskId !== failedTaskId) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'failed',
message: td.error!.message!,
+ ...(attachments.length ? { attachments } : {}),
code: td.error!.code,
provider: td.error!.provider,
}
diff --git a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/types.ts b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/types.ts
index 9ee5a8cfc..9bc88667f 100644
--- a/desktop-app/ui/src/contexts/AgentTaskTrackerContext/types.ts
+++ b/desktop-app/ui/src/contexts/AgentTaskTrackerContext/types.ts
@@ -58,6 +58,7 @@ export type TaskTerminalResult =
| {
kind: 'error'
source: 'failed' | 'result_fetch' | 'stream'
+ attachments?: ChatMessageAttachment[]
message: string
code?: string
provider?: string
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx
index 5d5ff20d0..7e319ded1 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/useAgentChatController.test.tsx
@@ -1715,3 +1715,48 @@ describe('useAgentChatController — characterization (D.0)', () => {
})
})
})
+
+describe('interrupted generated-file contract', () => {
+ it('persists a generated-file attachment on the failed assistant message', async () => {
+ clerum.rpc.invokeHostMessage.mockResolvedValue({ taskId: 'task-file' })
+ clerum.rpc.getTaskResult.mockResolvedValue({
+ success: false,
+ error: { message: 'Task interrupted', code: 'TASK_ITERATION_LIMIT' },
+ attachments: [
+ {
+ id: 'report',
+ kind: 'file',
+ filename: 'report.md',
+ mimeType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: 'IyByZXBvcnQ=',
+ },
+ ],
+ })
+ const { result } = renderController()
+ await settleMount()
+ const send = act(async () => {
+ await result.current.handleSendAgentMessage('Create a report')
+ })
+ await waitFor(() => expect(clerum.hasProgressHandler('task-file')).toBe(true))
+ await act(async () => {
+ clerum.emitTaskProgress('task-file', {
+ type: 'terminal',
+ data: {
+ taskId: 'task-file',
+ status: 'failed',
+ error: { message: 'Task interrupted', code: 'TASK_ITERATION_LIMIT' },
+ },
+ })
+ })
+ await send
+ const saved = clerum.chat.appendMessages.mock.calls.at(-1)?.[2]
+ expect(saved).toEqual([
+ expect.objectContaining({
+ isError: true,
+ errorCode: 'TASK_ITERATION_LIMIT',
+ attachments: [expect.objectContaining({ type: 'response_file', label: 'report.md' })],
+ }),
+ ])
+ })
+})
diff --git a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
index f27ddeffa..a9f828caa 100644
--- a/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
+++ b/desktop-app/ui/src/hooks/domain/useAgentChatController.ts
@@ -1696,12 +1696,14 @@ export function useAgentChatController({
const message = typeof durableError === 'string' ? durableError : durableError.message
const errorCode = typeof durableError === 'string' ? undefined : durableError.code
const errorProvider = typeof durableError === 'string' ? undefined : durableError.provider
+ const attachments = buildResponseFileAttachments(taskResult)
await appendAssistantMessage(agentRef, chatId, {
id: crypto.randomUUID(),
role: 'assistant',
content: message,
timestamp: Date.now(),
task_id: taskIdHint,
+ ...(attachments.length ? { attachments } : {}),
isError: true,
...(errorCode ? { errorCode } : {}),
...(errorProvider ? { errorProvider } : {}),
@@ -1991,6 +1993,7 @@ export function useAgentChatController({
const errorCode = typeof durableError === 'string' ? undefined : durableError.code
const errorProvider =
typeof durableError === 'string' ? undefined : durableError.provider
+ const attachments = buildResponseFileAttachments(taskResult)
dropActivity()
await appendAssistantMessage(agentRef, chatId, {
id: crypto.randomUUID(),
@@ -1998,6 +2001,7 @@ export function useAgentChatController({
content: message,
timestamp: Date.now(),
task_id: state.taskId,
+ ...(attachments.length ? { attachments } : {}),
isError: true,
...(errorCode ? { errorCode } : {}),
...(errorProvider ? { errorProvider } : {}),
@@ -2194,6 +2198,7 @@ export function useAgentChatController({
timestamp: Date.now(),
task_id: state.taskId,
isError: true,
+ ...(result.attachments?.length ? { attachments: result.attachments } : {}),
errorCode: result.code,
errorProvider: result.provider,
})
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 7ea628254..b4ef088c3 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -669,9 +669,9 @@ stateDiagram-v2
**Configurable limits**:
-- `maxToolCallsPerTask` (default: 50) - Prevents infinite tool calling loops
-- `maxTaskDuration` (default: 300000ms / 5 min) - Task timeout
-- `taskDelay` (default: 100ms) - Delay between processing tasks
+- `maxToolCallsPerTask` (default: 1000) - Bounds LLM/tool iterations per task; each iteration may call multiple tools
+- `maxTaskDuration` (default: 86400000ms / 24 hours) - Maximum active execution time; excludes approval waiting and persists across resumptions
+- `taskDelay` (default: 3ms) - Minimum interval between task dispatches
### LLM Providers
@@ -834,9 +834,9 @@ The HTTP response is held open until the agent finishes processing. The response
| `BAILIAN_API_KEY` | - | Bailian/DashScope key (dev mode) |
| `CLERUM_HOST_CONFIG` | - | JSON host config (dev mode) |
| `CLERUM_MCP_SERVERS` | - | JSON MCP server array (dev mode) |
-| `CLERUM_AGENT_TASK_DELAY` | `100` | Delay between tasks (ms) |
-| `CLERUM_AGENT_MAX_TASK_DURATION` | `300000` | Max task duration (ms) |
-| `CLERUM_AGENT_MAX_TOOL_CALLS` | `50` | Max tool calls per task |
+| `CLERUM_AGENT_TASK_DELAY` | `3` | Delay between tasks (ms) |
+| `CLERUM_AGENT_MAX_TASK_DURATION` | `86400000` | Max active task duration, excluding approval waits (ms) |
+| `CLERUM_AGENT_MAX_TOOL_CALLS` | `1000` | Max LLM/tool iterations per task, configured per Host process |
| `CLERUM_AGENT_MAX_QUEUE_SIZE` | `100` | Max pending queue size |
### Dependencies
diff --git a/mcp-host/README.md b/mcp-host/README.md
index b525d022d..14b29d64c 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -30,15 +30,15 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |
| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |
| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
-| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=3600000` |
-| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=3600000` |
+| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |
+| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |
| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
-| `CLERUM_AGENT_TASK_DELAY` | Delay in milliseconds between queued task processing attempts in the state machine loop. | `CLERUM_AGENT_TASK_DELAY=100` |
-| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum task runtime in milliseconds before task execution is treated as timed out. | `CLERUM_AGENT_MAX_TASK_DURATION=1800000` |
-| `CLERUM_AGENT_MAX_TOOL_CALLS` | Hard cap on tool calls per task to prevent unbounded tool loops. | `CLERUM_AGENT_MAX_TOOL_CALLS=50` |
+| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |
+| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |
+| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |
| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
@@ -46,8 +46,8 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction logic before pruning/summarization. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
-| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=600000` |
-| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=660000` |
+| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |
+| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |
| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
@@ -334,3 +334,42 @@ per-Host ServiceAccount (`host-<hostRef>-sa`) bound to a narrow Role
(`host-<hostRef>-config-reader`) on every reconcile, scoped to exactly the Host
CRD by name, its env ConfigMap/Secret, and the LLM Secret named by
`spec.secretRef` — so one Host cannot read another Host's resources.
+
+### Long-running task limits
+
+The task keeps one active-time and iteration budget across approval resumptions.
+`CLERUM_AGENT_MAX_TASK_DURATION=86400000` allows 24 hours of active execution,
+and `CLERUM_AGENT_MAX_TOOL_CALLS=1000` allows at most 1000 agent iterations.
+An iteration may call several tools. Waiting for approval consumes neither
+budget. Approval snapshots persist consumption and original limits; a restart
+cannot replenish them. A lower operator limit applies on restoration, while a
+higher ENV value does not enlarge an already-issued budget.
+
+On exhaustion, the task reports an incomplete execution with a structured
+`TASK_DURATION_LIMIT` or `TASK_ITERATION_LIMIT` error and retains an interruption
+message in the conversation. It does not report successful completion.
+
+Tool, shell and MCP execution defaults are 1500000 ms (25 minutes). Shell
+termination starts at the shorter shell/caller deadline, or when the task is
+cancelled. The caller permits up to 6 additional seconds for bounded process
+termination and result collection (5 seconds for SIGKILL escalation and 1 second
+for close delivery); this is cleanup time, not a longer execution allowance.
+MCP receives both the caller deadline and cancellation signal. A remote MCP
+server must cooperate with cancellation; the Host cannot guarantee remote
+side effects stop after the request is cancelled.
+
+Migration 014 marks existing pending approvals as legacy. They cannot silently
+receive a new budget: the same task requests a new approval explicitly stating
+that prior consumption was not recorded. The old approval and its replay state
+are replaced atomically, and no pending tool executes until the new approval
+is granted. Newly written or malformed accounting is never treated as legacy.
+
+`CLERUM_AGENT_TASK_DELAY=3` is a 3-millisecond minimum between task dispatches,
+not seconds and not a delay between tool iterations. Zero disables dispatch
+spacing. Invalid or overflowing execution limits fail configuration validation.
+
+Execution-limit defaults apply only when their environment variable is absent.
+Explicit empty strings, whitespace, zero (except task dispatch spacing), malformed
+numbers and timer overflows are rejected. Incomplete duration/iteration outcomes
+retain already-produced, provenance-checked attachments in the failure response;
+this does not turn the interrupted task into a successful completion.
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 47760cf25..4bc42dd59 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.332",
+ "version": "0.1.337",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.332",
+ "version": "0.1.337",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 8946336ac..ca60516eb 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.332",
+ "version": "0.1.337",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/ironclaw/resume-across-pod-restart.test.ts b/mcp-host/src/__tests__/ironclaw/resume-across-pod-restart.test.ts
index 18865032c..ba7c51794 100644
--- a/mcp-host/src/__tests__/ironclaw/resume-across-pod-restart.test.ts
+++ b/mcp-host/src/__tests__/ironclaw/resume-across-pod-restart.test.ts
@@ -63,6 +63,12 @@ describe('IronClaw invariant #3: resume across Pod restart', () => {
description: 'queued before restart',
tool_call_id: `tc_${opts.requestId}`,
context_snapshot: [],
+ task_budget: {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ },
}
const manager = agent.getConversationManager()
const conv = await manager.getOrCreate(opts.sessionKey)
@@ -101,6 +107,12 @@ describe('IronClaw invariant #3: resume across Pod restart', () => {
description: 'queued before restart',
tool_call_id: 'tc_r1',
context_snapshot: [],
+ task_budget: {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ },
},
source_message: {
sender: 'alice',
diff --git a/mcp-host/src/__tests__/mcp/mcpClient.test.ts b/mcp-host/src/__tests__/mcp/mcpClient.test.ts
index 9bdf40ab7..0745c3cb1 100644
--- a/mcp-host/src/__tests__/mcp/mcpClient.test.ts
+++ b/mcp-host/src/__tests__/mcp/mcpClient.test.ts
@@ -193,7 +193,7 @@ describe('McpClient — callTool', () => {
expect(internalClient.callTool).toHaveBeenCalledWith(
{ name: 'my-tool', arguments: { key: 'val' } },
undefined,
- expect.objectContaining({ timeout: 3600000 })
+ expect.objectContaining({ timeout: 1500000 })
)
} else {
// Fallback: just verify no error is thrown
diff --git a/mcp-host/src/__tests__/mcp/mcpClient.timeout.test.ts b/mcp-host/src/__tests__/mcp/mcpClient.timeout.test.ts
index b3bc45dd7..12e629f9f 100644
--- a/mcp-host/src/__tests__/mcp/mcpClient.timeout.test.ts
+++ b/mcp-host/src/__tests__/mcp/mcpClient.timeout.test.ts
@@ -132,7 +132,7 @@ describe('McpClient SDK request timeouts', () => {
expect(sdkState.callToolCalls[0]).toEqual([
{ name: 'read', arguments: { id: 1 } },
undefined,
- expect.objectContaining({ timeout: 3_600_000 }),
+ expect.objectContaining({ timeout: 1_500_000 }),
])
})
@@ -155,7 +155,7 @@ describe('McpClient SDK request timeouts', () => {
expect(sdkState.callToolCalls).toHaveLength(2)
expect(sdkState.callToolCalls[0][2]).toEqual(expect.objectContaining({ timeout: 30_000 }))
expect(sdkState.callToolCalls[1][2]).toEqual(expect.objectContaining({ timeout: 29_000 }))
- expect(sdkState.listToolsCalls[1][1]).toEqual(expect.objectContaining({ timeout: 3_600_000 }))
+ expect(sdkState.listToolsCalls[1][1]).toEqual(expect.objectContaining({ timeout: 1_500_000 }))
})
it('lets a slower peer adopt the completed recovery of their shared session', async () => {
@@ -396,16 +396,19 @@ describe('McpClient SDK request timeouts', () => {
expect(c.isConnected).toBe(true)
})
- it('fails closed for invalid timeout env before SDK tool discovery', async () => {
- vi.stubEnv('CLERUM_MCP_TOOL_TIMEOUT_MS', '0')
- const c = client()
-
- await expect(c.connect()).rejects.toThrow(
- 'CLERUM_MCP_TOOL_TIMEOUT_MS must be a positive safe integer'
- )
- expect(sdkState.listToolsCalls).toHaveLength(0)
- expect(sdkState.callToolCalls).toHaveLength(0)
- })
+ it.each(['', ' ', '0', '-1', '2147483648'])(
+ 'fails closed for invalid timeout env %j before SDK tool discovery',
+ async value => {
+ vi.stubEnv('CLERUM_MCP_TOOL_TIMEOUT_MS', value)
+ const c = client()
+
+ await expect(c.connect()).rejects.toThrow(
+ 'CLERUM_MCP_TOOL_TIMEOUT_MS must be a positive safe integer'
+ )
+ expect(sdkState.listToolsCalls).toHaveLength(0)
+ expect(sdkState.callToolCalls).toHaveLength(0)
+ }
+ )
it('allows a lower caller budget to override env max/per-call contradiction', async () => {
vi.stubEnv('CLERUM_MCP_TOOL_TIMEOUT_MS', '3600000')
diff --git a/mcp-host/src/__tests__/messageHandler.test.ts b/mcp-host/src/__tests__/messageHandler.test.ts
index 950a3b281..c9a958336 100644
--- a/mcp-host/src/__tests__/messageHandler.test.ts
+++ b/mcp-host/src/__tests__/messageHandler.test.ts
@@ -512,3 +512,35 @@ describe('IncomingMessageHandler', () => {
})
})
})
+
+describe('interrupted attachment delivery', () => {
+ it.each([false, true])(
+ 'keeps failure status and attachments in sync and async delivery (async=%s)',
+ async asyncMode => {
+ const deps = createMockDeps()
+ const handler = new IncomingMessageHandler(createTestMessage(), deps)
+ const pending = asyncMode ? Promise.resolve(handler.executeAsync()) : handler.execute()
+ const task = deps.messageQueue.dequeue()!
+ expect(task).not.toBeNull()
+ const attachment = {
+ id: 'result',
+ kind: 'image' as const,
+ mimeType: 'image/png',
+ encoding: 'base64' as const,
+ dataBase64: 'eA==',
+ }
+ const error = {
+ code: 'TASK_ITERATION_LIMIT',
+ message: 'Work interrupted',
+ retryable: false,
+ provider: 'openai',
+ }
+ await task.responseCallback!({ error, attachments: [attachment] })
+ const inline = await pending
+ const stored = deps.pendingTaskResults.get(task.id)
+ expect(stored).toMatchObject({ status: 'failed', error, attachments: [attachment] })
+ if (!asyncMode)
+ expect(inline).toMatchObject({ success: false, error, attachments: [attachment] })
+ }
+ )
+})
diff --git a/mcp-host/src/agent/__tests__/coreEventBridge.test.ts b/mcp-host/src/agent/__tests__/coreEventBridge.test.ts
index 27e0b6358..56e2e1bcc 100644
--- a/mcp-host/src/agent/__tests__/coreEventBridge.test.ts
+++ b/mcp-host/src/agent/__tests__/coreEventBridge.test.ts
@@ -356,10 +356,10 @@ describe('Gap 3 — task:completed via core SimpleEventEmitter', () => {
await agent.stop()
})
- it('should emit task:completed through coreEvents on exhaustion', async () => {
+ it('should emit task:failed through coreEvents on exhaustion', async () => {
const coreEvents = agent.getCoreEvents()
const collected: AgentEvent[] = []
- coreEvents.on('task:completed', event => collected.push(event))
+ coreEvents.on('task:failed', event => collected.push(event))
;(runToolUseLoop as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
type: 'exhaustion',
message: 'Max iterations reached',
@@ -372,7 +372,7 @@ describe('Gap 3 — task:completed via core SimpleEventEmitter', () => {
await agent.executeTask(task)
expect(collected.length).toBe(1)
- expect(collected[0].type).toBe('task:completed')
+ expect(collected[0].type).toBe('task:failed')
await agent.stop()
})
@@ -398,7 +398,7 @@ describe('Gap 3 — complete AgentEventType coverage via getCoreEvents()', () =>
const allTypes: AgentEventType[] = [
'state:changed',
'task:started',
- 'task:completed',
+ 'task:failed',
'task:failed',
'tool:called',
'tool:completed',
diff --git a/mcp-host/src/agent/__tests__/stateMachineFailure.test.ts b/mcp-host/src/agent/__tests__/stateMachineFailure.test.ts
index 39216a660..67e1db29e 100644
--- a/mcp-host/src/agent/__tests__/stateMachineFailure.test.ts
+++ b/mcp-host/src/agent/__tests__/stateMachineFailure.test.ts
@@ -1,7 +1,8 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
+import { NoopSafety } from '../../core/safety/__tests__/noopSafety.js'
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { logger } from '../../logger'
import { SseProgressReporter, progressReporterRegistry } from '../../progress/sseProgressReporter'
-import { NoopSafety } from '../../core/safety/__tests__/noopSafety.js'
import { MessageQueue } from '../../queue'
import type { TaskError } from '../../queue/types'
import { AgentStateMachine } from '../stateMachine'
@@ -65,7 +66,7 @@ describe('AgentStateMachine.handleTaskFailure', () => {
queue.enqueue(task)
queue.dequeue()
- const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+ const errSpy = vi.spyOn(logger, 'error').mockImplementation(() => {})
;(
machine as unknown as {
@@ -74,9 +75,8 @@ describe('AgentStateMachine.handleTaskFailure', () => {
).handleTaskFailure(task, testError)
expect(errSpy).toHaveBeenCalledWith(
- expect.stringMatching(
- /code=LLM_INSUFFICIENT_QUOTA retryable=false provider=openai message="out of credit"/
- )
+ { taskId: task.id, code: 'LLM_INSUFFICIENT_QUOTA', retryable: false, provider: 'openai' },
+ 'Task failed'
)
errSpy.mockRestore()
})
diff --git a/mcp-host/src/agent/__tests__/stateMachineLifecycle.test.ts b/mcp-host/src/agent/__tests__/stateMachineLifecycle.test.ts
index 26dba926c..2a81e3c56 100644
--- a/mcp-host/src/agent/__tests__/stateMachineLifecycle.test.ts
+++ b/mcp-host/src/agent/__tests__/stateMachineLifecycle.test.ts
@@ -7,6 +7,7 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { runToolUseLoop } from '../../core/orchestration/toolUseLoop'
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { logger } from '../../logger'
import { MessageQueue } from '../../queue/messageQueue'
import { Task } from '../../queue/types'
import { AgentStateMachine } from '../stateMachine'
@@ -170,7 +171,9 @@ describe('AgentStateMachine — task processing', () => {
await agent.executeTask(task)
expect(task.responseCallback).toHaveBeenCalledWith(
- expect.objectContaining({ response: 'Max iterations reached' })
+ expect.objectContaining({
+ error: expect.objectContaining({ code: 'TASK_ITERATION_LIMIT', retryable: false }),
+ })
)
})
})
@@ -500,7 +503,7 @@ describe('AgentStateMachine — clearPendingApproval retry queue', () => {
// Burn through MAX_ATTEMPTS + 1 attempts; the last one should clear the
// entry (gave up) rather than re-schedule.
- const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+ const errSpy = vi.spyOn(logger, 'error').mockImplementation(() => {})
const max = (agent.constructor as any).CLEAR_RETRY_MAX_ATTEMPTS as number
for (let i = 0; i < max + 1; i++) {
;(agent as any).tryClearPendingApproval('session-Z')
@@ -508,7 +511,47 @@ describe('AgentStateMachine — clearPendingApproval retry queue', () => {
}
expect((agent as any).clearPendingApprovalRetries.has('session-Z')).toBe(false)
// Final attempt logged the "exhausted" message.
- expect(errSpy).toHaveBeenCalledWith(expect.stringMatching(/exhausted.*retries/))
+ expect(errSpy).toHaveBeenCalledWith(
+ expect.objectContaining({ attempts: max }),
+ expect.stringMatching(/exhausted.*retries/)
+ )
errSpy.mockRestore()
})
})
+
+describe('interrupted task artifact delivery', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(runToolUseLoop).mockReset()
+ })
+ it.each([false, true])(
+ 'delivers artifacts once, retaining failure status (callback rejects=%s)',
+ async rejects => {
+ const { agent } = setupAgent()
+ const task = createTestTask('Exhaust with output')
+ const attachment = {
+ id: 'result',
+ kind: 'image' as const,
+ mimeType: 'image/png',
+ encoding: 'base64' as const,
+ dataBase64: 'eA==',
+ }
+ const callback = vi.fn(async () => {
+ if (rejects) throw new Error('client unavailable')
+ })
+ task.responseCallback = callback
+ vi.mocked(runToolUseLoop).mockResolvedValue({
+ type: 'exhaustion',
+ iterations: 1000,
+ message: 'limit',
+ attachments: [attachment],
+ })
+ await agent.executeTask(task)
+ expect(task.status).toBe('failed')
+ expect(callback).toHaveBeenCalledExactlyOnceWith({
+ error: expect.objectContaining({ code: 'TASK_ITERATION_LIMIT' }),
+ attachments: [attachment],
+ })
+ }
+ )
+})
diff --git a/mcp-host/src/agent/__tests__/taskExecutionBudget.test.ts b/mcp-host/src/agent/__tests__/taskExecutionBudget.test.ts
new file mode 100644
index 000000000..1947d877e
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/taskExecutionBudget.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+ TaskExecutionBudget,
+ TaskLimitError,
+ parseTaskExecutionBudget,
+} from '../taskExecutionBudget'
+
+afterEach(() => vi.useRealTimers())
+describe('TaskExecutionBudget', () => {
+ it('retains consumption across approvals and restart, excluding approval wait', async () => {
+ vi.useFakeTimers()
+ let now = 0
+ const first = new TaskExecutionBudget(100, 2, () => now)
+ first.start(new AbortController())
+ first.consumeIteration()
+ now = 40
+ const saved = first.pause()
+ now = 10000
+ const restored = new TaskExecutionBudget(200, 20, () => now)
+ restored.restore(saved)
+ expect(restored.durationMs).toBe(100)
+ expect(restored.maxIterations).toBe(2)
+ const controller = new AbortController()
+ restored.start(controller)
+ restored.consumeIteration()
+ expect(restored.remainingIterations).toBe(0)
+ expect(() => restored.consumeIteration()).toThrow(TaskLimitError)
+ await vi.advanceTimersByTimeAsync(59)
+ expect(controller.signal.aborted).toBe(false)
+ await vi.advanceTimersByTimeAsync(1)
+ expect(controller.signal.reason.code).toBe('TASK_DURATION_LIMIT')
+ restored.pause()
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ it('clears its timer on successful completion', async () => {
+ vi.useFakeTimers()
+ const budget = new TaskExecutionBudget(100, 2)
+ const controller = new AbortController()
+ budget.start(controller)
+ budget.pause()
+ await vi.advanceTimersByTimeAsync(200)
+ expect(controller.signal.aborted).toBe(false)
+ })
+ it('refuses exhausted restored time before work starts', () => {
+ const budget = new TaskExecutionBudget(100, 2)
+ budget.restore({ elapsedActiveMs: 100, iterationsUsed: 1, durationMs: 100, maxIterations: 2 })
+ expect(() => budget.start(new AbortController())).toThrow(TaskLimitError)
+ })
+ it.each([
+ null,
+ {},
+ { elapsedActiveMs: -1, iterationsUsed: 0 },
+ { elapsedActiveMs: 0, iterationsUsed: NaN },
+ ])('rejects invalid durable accounting %s', value => {
+ expect(() => parseTaskExecutionBudget(value)).toThrow('Invalid task execution budget')
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/taskExecutor.test.ts b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
index 0b9433dde..b7a617a22 100644
--- a/mcp-host/src/agent/__tests__/taskExecutor.test.ts
+++ b/mcp-host/src/agent/__tests__/taskExecutor.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { config as appConfig } from '../../config'
import { ConversationManager } from '../../core/conversation/conversation'
import { LlmError, LlmErrorCode } from '../../core/errors'
@@ -1769,3 +1769,307 @@ describe('TaskExecutor Codex presentation wiring', () => {
}
})
})
+
+describe('TaskExecutor effective limits', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(runToolUseLoop).mockReset()
+ vi.mocked(executeSingleTool).mockReset()
+ })
+ it('keeps an iteration budget through approval and cold rehydration', async () => {
+ const task = createTask(),
+ deps = createDeps()
+ deps.config.maxToolCallsPerTask = 2
+ const maxima: number[] = []
+ vi.mocked(runToolUseLoop).mockImplementation(async config => {
+ maxima.push(config.maxIterations)
+ if (config.maxIterations === 0) return { type: 'exhaustion', message: 'limit', iterations: 0 }
+ config.events.emit({ type: 'loop:iteration', data: { iteration: 0 }, timestamp: new Date() })
+ return {
+ type: 'need_approval',
+ approval: {
+ request_id: `r${maxima.length}`,
+ tool_name: 'test',
+ tool_call_id: 'tc',
+ parameters: {},
+ description: 'confirm',
+ context_snapshot: [
+ { role: 'user', content: 'work' },
+ {
+ role: 'assistant',
+ content: '',
+ tool_calls: [{ id: 'tc', name: 'test', arguments: {} }],
+ },
+ ],
+ },
+ }
+ })
+ vi.mocked(executeSingleTool).mockResolvedValue({
+ tool_call_id: 'tc',
+ name: 'test',
+ content: 'done',
+ is_error: false,
+ })
+ const first = new TaskExecutor(task, deps)
+ await first.run()
+ const approval = first.pendingApproval!
+ expect(approval.task_budget?.iterationsUsed).toBe(1)
+ const restored = new TaskExecutor(task, deps)
+ await restored.rehydrateWaitingApproval(first.sessionKey!, approval)
+ await restored.resumeAfterApproval(false)
+ expect(restored.pendingApproval?.task_budget?.iterationsUsed).toBe(2)
+ await restored.resumeAfterApproval(false)
+ expect(maxima).toEqual([2, 1, 0])
+ expect(executeSingleTool).toHaveBeenCalledTimes(2)
+ expect(deps.onComplete).not.toHaveBeenCalled()
+ expect(deps.onFail).toHaveBeenCalledWith(
+ task,
+ expect.objectContaining({ code: 'TASK_ITERATION_LIMIT' })
+ )
+ })
+ it('renews a legacy approval on the same task before executing anything', async () => {
+ const task = createTask(),
+ deps = createDeps()
+ const conv = await deps.conversationManager.getOrCreate('user-1:telegram:test-channel', {
+ userId: 'user-1',
+ })
+ await deps.conversationManager.startTurn(conv, 'work', task.id)
+ const approval = {
+ request_id: 'legacy',
+ tool_name: 'test',
+ tool_call_id: 'tc',
+ parameters: {},
+ description: 'old approval',
+ context_snapshot: [],
+ legacy_budget: true,
+ }
+ await deps.conversationManager.suspendForApproval(conv, approval)
+ const executor = new TaskExecutor(task, deps)
+ await executor.rehydrateWaitingApproval('user-1:telegram:test-channel', approval)
+ await executor.resumeAfterApproval(false)
+ expect(executor.taskId).toBe(task.id)
+ expect(executor.pendingApproval?.request_id).not.toBe('legacy')
+ expect(executor.pendingApproval?.task_budget?.iterationsUsed).toBe(0)
+ expect(executor.executorState).toBe('waiting_approval')
+ expect(executeSingleTool).not.toHaveBeenCalled()
+ expect(runToolUseLoop).not.toHaveBeenCalled()
+ })
+})
+
+describe('TaskExecutor active duration', () => {
+ afterEach(() => vi.useRealTimers())
+ it.each([false, true])(
+ 'fails exactly once during an uncooperative LLM call (persistence failure=%s)',
+ async persistFails => {
+ vi.clearAllMocks()
+ vi.useFakeTimers()
+ const actual = await vi.importActual<typeof import('../../core/orchestration/toolUseLoop')>(
+ '../../core/orchestration/toolUseLoop'
+ )
+ vi.mocked(runToolUseLoop).mockImplementation(actual.runToolUseLoop)
+ const task = createTask(),
+ deps = createDeps()
+ deps.config.maxTaskDuration = 100
+ if (persistFails)
+ vi.spyOn(deps.conversationManager, 'completeTurn').mockRejectedValue(
+ new Error('storage unavailable')
+ )
+ let started!: () => void
+ const dispatched = new Promise<void>(resolve => {
+ started = resolve
+ })
+ vi.mocked(deps.llmProvider.completeSingleTurnWithTools).mockImplementation(async () => {
+ started()
+ return new Promise(() => {}) // Deliberately ignores abort; the task boundary must still stop.
+ })
+ const executor = new TaskExecutor(task, deps)
+ const running = executor.run()
+ await dispatched
+ await vi.advanceTimersByTimeAsync(100)
+ await running
+ expect(executor.executorState).toBe('failed')
+ expect(deps.onFail).toHaveBeenCalledTimes(1)
+ expect(deps.onFail).toHaveBeenCalledWith(
+ task,
+ expect.objectContaining({ code: 'TASK_DURATION_LIMIT' })
+ )
+ expect(deps.onComplete).not.toHaveBeenCalled()
+ const conv = deps.conversationManager.getSessionByKey(executor.sessionKey!)
+ if (!persistFails) expect(conv?.turns.at(-1)?.response).toContain('stopped before completion')
+ await expect(executor.waitForCompletion()).resolves.toBeUndefined()
+ expect(vi.getTimerCount()).toBe(0)
+ }
+ )
+})
+
+describe('TaskExecutor exhaustion and cancellation contracts', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(runToolUseLoop).mockReset()
+ vi.mocked(executeSingleTool).mockReset()
+ })
+ it('preserves the separate cost brake response and accumulated attachments', async () => {
+ const deps = createDeps(),
+ task = createTask()
+ const attachment = createImageAttachment()
+ vi.mocked(runToolUseLoop).mockResolvedValue({
+ type: 'exhaustion',
+ reason: 'task_budget',
+ message: 'Configured budget reached',
+ iterations: 1,
+ attachments: [attachment],
+ })
+ await new TaskExecutor(task, deps).run()
+ expect(task.responseCallback).toHaveBeenCalledWith({
+ response: 'Configured budget reached',
+ attachments: [attachment],
+ })
+ expect(deps.onFail).not.toHaveBeenCalled()
+ })
+ it('does not resurrect a cancelled legacy approval', async () => {
+ const task = createTask(),
+ deps = createDeps()
+ deps.taskLifecycle.register(task)
+ const key = 'user-1:telegram:test-channel'
+ const conv = await deps.conversationManager.getOrCreate(key, { userId: 'user-1' })
+ await deps.conversationManager.startTurn(conv, 'work', task.id)
+ const approval = {
+ request_id: 'legacy-cancel',
+ tool_name: 'test',
+ tool_call_id: 'tc',
+ parameters: {},
+ description: 'old',
+ context_snapshot: [],
+ legacy_budget: true,
+ }
+ await deps.conversationManager.suspendForApproval(conv, approval)
+ const executor = new TaskExecutor(task, deps)
+ await executor.rehydrateWaitingApproval(key, approval)
+ executor.abort()
+ await executor.resumeAfterApproval(false)
+ expect(deps.onApprovalNeeded).not.toHaveBeenCalled()
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executeSingleTool).not.toHaveBeenCalled()
+ await expect(executor.waitForCompletion()).resolves.toBeUndefined()
+ })
+})
+
+describe('adversarial review regressions', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(runToolUseLoop).mockReset()
+ vi.mocked(executeSingleTool).mockReset()
+ })
+ afterEach(() => vi.restoreAllMocks())
+ it.each([false, true])(
+ 'persists interruption when final sanitization crosses deadline (static=%s)',
+ async isStatic => {
+ let now = 0
+ vi.spyOn(performance, 'now').mockImplementation(() => now)
+ const deps = createDeps()
+ deps.config.maxTaskDuration = 10000
+ const task = createTask(isStatic ? 'list workflows' : 'Finish the work')
+ const executor = new TaskExecutor(task, deps)
+ const failTurn = vi.spyOn(deps.conversationManager, 'failTurn')
+ const safety = executor['responseSafety']
+ const sanitize = safety.sanitizeAssistantResponse.bind(safety)
+ vi.spyOn(safety, 'sanitizeAssistantResponse').mockImplementation(content => {
+ const result = sanitize(content)
+ now = 10001 // Cross the boundary synchronously, before the timer callback can run.
+ return result
+ })
+ if (isStatic) {
+ vi.spyOn(executor as any, 'prepareChannelWorkflowCallerContext').mockImplementation(
+ async () => {
+ executor['workflowAccessDeniedResponse'] = 'Access denied'
+ }
+ )
+ }
+ vi.mocked(runToolUseLoop).mockResolvedValue({
+ type: 'response',
+ content: 'Final answer',
+ usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
+ })
+ await executor.run()
+ expect(deps.onFail).toHaveBeenCalledWith(
+ task,
+ expect.objectContaining({ code: 'TASK_DURATION_LIMIT' })
+ )
+ expect(deps.onComplete).not.toHaveBeenCalled()
+ expect(failTurn).not.toHaveBeenCalled()
+ const conversation = deps.conversationManager.getSessionByKey(executor.sessionKey!)
+ expect(conversation?.turns.at(-1)?.response).toContain('stopped before completion')
+ }
+ )
+ it('retains exhaustion attachments and reports the restored effective limit', async () => {
+ const deps = createDeps(),
+ task = createTask(),
+ attachment = createImageAttachment()
+ const executor = new TaskExecutor(task, deps)
+ executor['executionBudget'].restore({
+ elapsedActiveMs: 0,
+ iterationsUsed: 2,
+ durationMs: 300000,
+ maxIterations: 2,
+ })
+ vi.mocked(runToolUseLoop).mockResolvedValue({
+ type: 'exhaustion',
+ iterations: 0,
+ message: 'limit',
+ attachments: [attachment],
+ })
+ await executor.run()
+ expect(deps.onFail).toHaveBeenCalledExactlyOnceWith(
+ task,
+ expect.objectContaining({
+ code: 'TASK_ITERATION_LIMIT',
+ message: expect.stringContaining('after 2 iterations'),
+ }),
+ [attachment]
+ )
+ expect(deps.onComplete).not.toHaveBeenCalled()
+ })
+ it('retains saved artifacts when restored time is already exhausted', async () => {
+ const deps = createDeps(),
+ task = createTask(),
+ attachment = createImageAttachment()
+ const key = 'user-1:telegram:test-channel'
+ const conversation = await deps.conversationManager.getOrCreate(key, { userId: 'user-1' })
+ await deps.conversationManager.startTurn(conversation, 'work', task.id)
+ const approval = {
+ request_id: 'expired-budget',
+ tool_name: 'test',
+ tool_call_id: 'tc',
+ parameters: {},
+ description: 'confirm',
+ context_snapshot: [],
+ attachments: [attachment],
+ completed_results: [
+ {
+ tool_call_id: 'prior',
+ name: 'image',
+ content: 'done',
+ is_error: false,
+ attachments: [attachment],
+ },
+ ],
+ task_budget: {
+ elapsedActiveMs: 300000,
+ iterationsUsed: 1,
+ durationMs: 300000,
+ maxIterations: 10,
+ },
+ }
+ await deps.conversationManager.suspendForApproval(conversation, approval)
+ const executor = new TaskExecutor(task, deps)
+ await executor.rehydrateWaitingApproval(key, approval)
+ await executor.resumeAfterApproval(false)
+ expect(deps.onFail).toHaveBeenCalledExactlyOnceWith(
+ task,
+ expect.objectContaining({ code: 'TASK_DURATION_LIMIT' }),
+ [attachment]
+ )
+ expect(executeSingleTool).not.toHaveBeenCalled()
+ expect(runToolUseLoop).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/agent/stateMachine.ts b/mcp-host/src/agent/stateMachine.ts
index 924be030f..762d5d261 100644
--- a/mcp-host/src/agent/stateMachine.ts
+++ b/mcp-host/src/agent/stateMachine.ts
@@ -30,6 +30,7 @@ import type { SessionSearchService } from '../core/sessionSearch'
import type { SpilloverStorage } from '../core/spillover'
import { createTokenCounter } from '../core/tokenizer'
import type {
+ Attachment,
Conversation,
AgentEventType as CoreAgentEventType,
PendingApproval,
@@ -39,6 +40,7 @@ import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
import { isTerminal } from '../lifecycle/types'
import { SingleTurnProvider } from '../llm'
import type { PromptCache } from '../llm/promptCache'
+import { logger } from '../logger'
import { McpManager } from '../mcp'
import { ensureReporter } from '../progress/sseProgressReporter'
import { MessageQueue, Task } from '../queue'
@@ -287,7 +289,7 @@ export class AgentStateMachine extends EventEmitter {
if (modelName) {
this.modelName = modelName
}
- console.log('[Agent] LLM provider set')
+ logger.info({ component: 'Agent' }, 'LLM provider set')
}
/**
@@ -298,7 +300,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setTaskModelResolver(resolver: TaskModelResolver): void {
this.taskModelResolver = resolver
- console.log('[Agent] Task model resolver set')
+ logger.info({ component: 'Agent' }, 'Task model resolver set')
}
/**
@@ -310,7 +312,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setFailoverSupport(provider: FailoverSupportProvider): void {
this.failoverSupportProvider = provider
- console.log('[Agent] Failover support provider set')
+ logger.info({ component: 'Agent' }, 'Failover support provider set')
}
/**
@@ -362,7 +364,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setMcpManager(manager: McpManager): void {
this.mcpManager = manager
- console.log('[Agent] MCP manager set')
+ logger.info({ component: 'Agent' }, 'MCP manager set')
}
/**
@@ -370,7 +372,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setSessionProcessor(processor: SessionProcessor): void {
this.sessionProcessor = processor
- console.log('[Agent] Session processor set')
+ logger.info({ component: 'Agent' }, 'Session processor set')
}
/**
@@ -378,7 +380,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setCronScheduler(scheduler: CronScheduler): void {
this.cronScheduler = scheduler
- console.log('[Agent] Cron scheduler set')
+ logger.info({ component: 'Agent' }, 'Cron scheduler set')
}
/**
@@ -386,7 +388,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setWorkspaceProvider(provider: ScopedWorkspaceProvider): void {
this.workspaceProvider = provider
- console.log('[Agent] Workspace provider set')
+ logger.info({ component: 'Agent' }, 'Workspace provider set')
}
/**
@@ -396,7 +398,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setSpilloverStorage(storage: SpilloverStorage | undefined): void {
this.spilloverStorage = storage
- console.log(`[Agent] Spillover storage ${storage ? 'set' : 'cleared'}`)
+ logger.info({ configured: Boolean(storage) }, 'Spillover storage configured')
}
/**
@@ -406,7 +408,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setPromptCache(cache: PromptCache | undefined): void {
this.promptCache = cache
- console.log(`[Agent] Prompt cache ${cache ? 'set' : 'cleared'}`)
+ logger.info({ configured: Boolean(cache) }, 'Prompt cache configured')
}
/**
@@ -417,7 +419,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setSessionSearchService(service: SessionSearchService | undefined): void {
this.sessionSearchService = service
- console.log(`[Agent] Session search service ${service ? 'set' : 'cleared'}`)
+ logger.info({ configured: Boolean(service) }, 'Session search configured')
}
/**
@@ -426,7 +428,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setDynamicEnvProvider(provider: () => Record<string, string>): void {
this.dynamicEnvProvider = provider
- console.log('[Agent] Dynamic env provider set')
+ logger.info({ component: 'Agent' }, 'Dynamic env provider set')
}
/**
@@ -435,7 +437,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setSecretEntriesProvider(provider: () => Array<{ name: string; value: string }>): void {
this.secretEntriesProvider = provider
- console.log('[Agent] Secret entries provider set')
+ logger.info({ component: 'Agent' }, 'Secret entries provider set')
}
/**
@@ -446,7 +448,7 @@ export class AgentStateMachine extends EventEmitter {
setUsageReporter(reporter: UsageReporter, staticContext: AdapterStaticContext): void {
this.usageReporter = reporter
this.usageStaticContext = staticContext
- console.log('[Agent] Usage reporter set')
+ logger.info({ component: 'Agent' }, 'Usage reporter set')
}
setGovernedRunReporter(reporter: GovernedRunReporter): void {
@@ -473,7 +475,7 @@ export class AgentStateMachine extends EventEmitter {
): void {
this.budgetClient = client
this.getHostBudgetContext = getHostContext
- console.log('[Agent] Budget check wired')
+ logger.info({ component: 'Agent' }, 'Budget check wired')
}
/**
@@ -533,7 +535,7 @@ export class AgentStateMachine extends EventEmitter {
* sees the friendly message below.
*/
handleBudgetDenied(task: Task, reason?: string): void {
- console.warn(`[Agent] Task ${task.id} denied by budget: ${reason ?? 'budget_exceeded'}`)
+ logger.warn({ taskId: task.id, reason: reason ?? 'budget_exceeded' }, 'Task denied by budget')
this.handleTaskFailure(task, {
code: 'BUDGET_EXCEEDED',
message: "This period's consumption budget has been reached. Please try again later.",
@@ -585,12 +587,12 @@ export class AgentStateMachine extends EventEmitter {
/** Guardrails block from the Host CRD (spec §5). Absent = no guardrails = today. */
setGuardrailsConfig(config: GuardrailsConfig | undefined): void {
this.guardrailsConfig = config
- console.log('[Guardrail] Guardrails config set:', { rules: config?.rules?.length ?? 0 })
+ logger.info({ rules: config?.rules?.length ?? 0 }, 'Guardrails configured')
}
setApprovalConfig(config: ApprovalConfig | undefined): void {
this.approvalConfig = config
- console.log('[Agent] Approval config set:', config?.defaultPolicy || 'none')
+ logger.info({ defaultPolicy: config?.defaultPolicy || 'none' }, 'Approval policy configured')
}
/**
@@ -599,7 +601,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setColdStartLoader(loader: ColdStartLoader): void {
this.coldStartLoader = loader
- console.log('[Agent] Cold-start loader set')
+ logger.info({ component: 'Agent' }, 'Cold-start loader set')
}
private buildApprovalBinding(
@@ -669,7 +671,7 @@ export class AgentStateMachine extends EventEmitter {
*/
setConversationStore(store: ConversationStore): void {
this.conversationManager.setStore(store)
- console.log('[Agent] Conversation store set')
+ logger.info({ component: 'Agent' }, 'Conversation store set')
}
/**
@@ -693,18 +695,18 @@ export class AgentStateMachine extends EventEmitter {
try {
const reaped = await this.coldStartLoader.reapProcessingSessions(now)
if (reaped.length > 0) {
- console.log(`[Agent] Reaped ${reaped.length} processing session(s) on boot`)
+ logger.info({ count: reaped.length }, 'Processing sessions reaped on boot')
}
} catch (err) {
// A reap failure must not block boot; pending approvals still rehydrate.
- console.error('[Agent] Processing reaper failed on boot:', err)
+ logger.error({ err: err }, 'Processing reaper failed on boot:')
}
}
if (typeof this.coldStartLoader.reapExpiredAwaitingApprovalSessions === 'function') {
const reaped = await this.coldStartLoader.reapExpiredAwaitingApprovalSessions(now)
if (reaped.length > 0) {
- console.log(`[Agent] Reaped ${reaped.length} expired approval session(s) on boot`)
+ logger.info({ count: reaped.length }, 'Expired approvals reaped on boot')
}
}
@@ -735,7 +737,7 @@ export class AgentStateMachine extends EventEmitter {
})
}
if (rehydrated.length > 0)
- console.log(`[Agent] Rehydrated ${rehydrated.length} pending approval executor(s)`)
+ logger.info({ count: rehydrated.length }, 'Pending approval executors rehydrated')
}
/**
@@ -891,7 +893,7 @@ export class AgentStateMachine extends EventEmitter {
}
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
- console.error('[Agent] compactSession failed:', err)
+ logger.error({ err: err }, 'compactSession failed:')
return { kind: 'error', message }
} finally {
this.compactionsInFlight.delete(opts.sessionKey)
@@ -985,7 +987,7 @@ export class AgentStateMachine extends EventEmitter {
const msg = task.sourceMessage
const userId = msg?.sender || 'anonymous'
const notificationMsg = this.buildApprovalNotification(approval, userId, msg?.channelType)
- console.log(`[Agent] Tool ${approval.tool_name} needs approval`)
+ logger.info({ toolName: approval.tool_name }, 'Tool requires approval')
this.emitEvent('tool:approval_needed', {
taskId,
toolName: approval.tool_name,
@@ -1016,7 +1018,7 @@ export class AgentStateMachine extends EventEmitter {
const executor = this.activeExecutors.get(entry.taskId)
if (!executor || executor.executorState !== 'waiting_approval') return
- console.warn(`[Agent] Approval timeout for request ${requestId}. Auto-denying.`)
+ logger.warn({ requestId }, 'Approval timed out; denying')
// Clean up coordinator state FIRST so transition subscribers always observe
// consistent state (PR-193 review #2). EventEmitter.emit() is synchronous;
@@ -1044,7 +1046,7 @@ export class AgentStateMachine extends EventEmitter {
// Promise.resolve so legacy synchronous test doubles (which return void)
// still flow through the same path.
Promise.resolve(executor.deny()).catch(err => {
- console.error(`[Agent] executor.deny() raised after timeout:`, err)
+ logger.error({ err: err }, `executor.deny() raised after timeout:`)
})
}
@@ -1119,7 +1121,7 @@ export class AgentStateMachine extends EventEmitter {
// Resume execution (fire and forget).
// Session release happens in onComplete/onFail callbacks.
executor.resumeAfterApproval(alwaysApprove).catch(err => {
- console.error(`[Agent] Resume after approval failed:`, err)
+ logger.error({ err: err }, `Resume after approval failed:`)
})
return { success: true }
@@ -1193,7 +1195,7 @@ export class AgentStateMachine extends EventEmitter {
try {
await Promise.resolve(executor.deny())
} catch (err) {
- console.error(`[Agent] executor.deny() failed:`, err)
+ logger.error({ err: err }, `executor.deny() failed:`)
}
this.activeExecutors.delete(entry.taskId)
this.releaseSessionForTask(executor.sourceTask)
@@ -1206,11 +1208,11 @@ export class AgentStateMachine extends EventEmitter {
*/
start(): void {
if (this.isRunning) {
- console.log('[Agent] Already running')
+ logger.info({ component: 'Agent' }, 'Already running')
return
}
- console.log('[Agent] Starting agent')
+ logger.info({ component: 'Agent' }, 'Starting agent')
this.isRunning = true
// B5 — start the clear-pending-approval retry drain. Every 30s we try
// every entry whose `nextTry` has passed. The interval is `.unref()`'d
@@ -1228,7 +1230,7 @@ export class AgentStateMachine extends EventEmitter {
* Stop the agent (finish current tasks, then stop).
*/
async stop(): Promise<void> {
- console.log('[Agent] Stopping agent')
+ logger.info({ component: 'Agent' }, 'Stopping agent')
this.isRunning = false
// B5 — stop the clear-pending-approval retry drain. Anything still in
@@ -1245,7 +1247,7 @@ export class AgentStateMachine extends EventEmitter {
// for waiting_approval, SSE emission for clients.
const drained = this.lifecycle.drainNonTerminal()
if (drained > 0) {
- console.log(`[Agent] Shutdown drain cancelled ${drained} non-terminal tasks`)
+ logger.info({ count: drained }, 'Shutdown cancelled non-terminal tasks')
}
// Clear all approval timers (drain already cleared the approvalMap entries
@@ -1271,7 +1273,7 @@ export class AgentStateMachine extends EventEmitter {
* Pause the agent (stop processing new tasks).
*/
pause(): void {
- console.log('[Agent] Pausing agent')
+ logger.info({ component: 'Agent' }, 'Pausing agent')
this.isRunning = false
this.setState('paused')
}
@@ -1280,7 +1282,7 @@ export class AgentStateMachine extends EventEmitter {
* Resume the agent.
*/
resume(): void {
- console.log('[Agent] Resuming agent')
+ logger.info({ component: 'Agent' }, 'Resuming agent')
this.isRunning = true
this.setState('idle')
}
@@ -1324,7 +1326,7 @@ export class AgentStateMachine extends EventEmitter {
* Returns true if the task is suspended (awaiting approval), false otherwise.
*/
public async executeTask(task: Task): Promise<boolean> {
- console.log(`[Agent] Dispatching task ${task.id} to executor`)
+ logger.info({ taskId: task.id }, 'Dispatching task')
if (!this.llmProvider) {
this.handleTaskFailure(task, {
@@ -1350,7 +1352,7 @@ export class AgentStateMachine extends EventEmitter {
effectiveContextWindow = resolved.contextWindowTokens
}
} catch (err) {
- console.warn('[Agent] per-task model resolution failed; using Host default:', err)
+ logger.warn({ err: err }, 'per-task model resolution failed; using Host default:')
}
}
@@ -1418,14 +1420,14 @@ export class AgentStateMachine extends EventEmitter {
this.queue.completeTask(t)
this.emitEvent('task:completed', { task: t })
},
- onFail: (t: Task, error: TaskError) => {
+ onFail: (t: Task, error: TaskError, attachments?: Attachment[]) => {
this.enqueueTaskTrace(t, 'run_end', `task:${t.id}:end`, {
status: 'failed',
error_class: error.code,
})
this.activeExecutors.delete(t.id)
this.releaseSessionForTask(t)
- this.handleTaskFailure(t, error)
+ this.handleTaskFailure(t, error, attachments)
},
})
}
@@ -1548,19 +1550,20 @@ export class AgentStateMachine extends EventEmitter {
/**
* Handle task failure — the single delivery point for user-visible errors.
*/
- private handleTaskFailure(task: Task, error: TaskError): void {
- console.error(
- `[Agent] Task ${task.id} failed: ` +
- `code=${error.code} retryable=${error.retryable} provider=${error.provider} ` +
- `message="${error.message}"`
+ private handleTaskFailure(task: Task, error: TaskError, attachments?: Attachment[]): void {
+ logger.error(
+ { taskId: task.id, code: error.code, retryable: error.retryable, provider: error.provider },
+ 'Task failed'
)
// Deliver to user via canonical callback — this is the core bug fix.
// Previously responseCallback was never called on failure.
if (task.responseCallback) {
- task.responseCallback({ error }).catch(cbErr => {
- console.error(`[Agent] responseCallback threw on failure delivery:`, cbErr)
- })
+ task
+ .responseCallback({ error, ...(attachments?.length ? { attachments } : {}) })
+ .catch(cbErr => {
+ logger.error({ err: cbErr }, `responseCallback threw on failure delivery:`)
+ })
}
// §5.3.1 — guarantee a registered SSE reporter BEFORE the terminal transition
@@ -1594,7 +1597,7 @@ export class AgentStateMachine extends EventEmitter {
ensureReporter(task.id, this.lifecycle, new BasicSafety(this.secretEntriesProvider))
}
} catch (err) {
- console.error('[Agent] ensure progress reporter failed', err)
+ logger.error({ err: err }, 'ensure progress reporter failed')
}
// Terminal SSE emission is handled by SseProgressReporter's lifecycle subscription.
@@ -1659,7 +1662,7 @@ export class AgentStateMachine extends EventEmitter {
// run()'s finally block handles activeExecutors.delete after the loop exits.
executor.abort()
} catch (err) {
- console.error('[TaskLifecycle subscriber] cleanup raised', { taskId: ev.taskId, err })
+ logger.error({ taskId: ev.taskId, err }, 'Lifecycle cleanup failed')
// Invariant I11: do NOT re-throw; SseProgressReporter must still fire
}
})
@@ -1696,10 +1699,12 @@ export class AgentStateMachine extends EventEmitter {
const prior = this.clearPendingApprovalRetries.get(sessionKey)
const attempts = (prior?.attempts ?? 0) + 1
if (attempts > AgentStateMachine.CLEAR_RETRY_MAX_ATTEMPTS) {
- console.error(
- `[Agent] clearPendingApproval exhausted ${attempts - 1} retries for sessionKey=${sessionKey}. ` +
- `Last error: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}. ` +
- `The SQLite row is now an orphan; cold-start TTL filter (B7) will eventually drop it.`
+ logger.error(
+ {
+ attempts: attempts - 1,
+ err: lastErr instanceof Error ? lastErr : new Error('Non-error persistence failure'),
+ },
+ 'Approval cleanup exhausted retries; awaiting cold-start recovery'
)
this.clearPendingApprovalRetries.delete(sessionKey)
return
@@ -1710,9 +1715,13 @@ export class AgentStateMachine extends EventEmitter {
)
const nextTry = Date.now() + backoff
this.clearPendingApprovalRetries.set(sessionKey, { attempts, nextTry })
- console.warn(
- `[Agent] clearPendingApproval failed (attempt ${attempts}, retrying in ${backoff}ms): ` +
- `sessionKey=${sessionKey}, err=${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+ logger.warn(
+ {
+ attempts,
+ backoffMs: backoff,
+ err: lastErr instanceof Error ? lastErr : new Error('Non-error persistence failure'),
+ },
+ 'Approval cleanup failed; retry scheduled'
)
}
@@ -1736,7 +1745,7 @@ export class AgentStateMachine extends EventEmitter {
const oldState = this.state
this.state = newState
- console.log(`[Agent] State: ${oldState} -> ${newState}`)
+ logger.info({ oldState, newState }, 'Agent state changed')
this.emitEvent('state:changed', { oldState, newState })
}
diff --git a/mcp-host/src/agent/taskExecutionBudget.ts b/mcp-host/src/agent/taskExecutionBudget.ts
new file mode 100644
index 000000000..9b48ec8f5
--- /dev/null
+++ b/mcp-host/src/agent/taskExecutionBudget.ts
@@ -0,0 +1,116 @@
+import type { TaskExecutionBudgetSnapshot } from '../core/types'
+
+export class TaskLimitError extends Error {
+ constructor(
+ readonly code: 'TASK_DURATION_LIMIT' | 'TASK_ITERATION_LIMIT',
+ message: string
+ ) {
+ super(message)
+ this.name = 'TaskLimitError'
+ }
+}
+
+export function parseTaskExecutionBudget(value: unknown): TaskExecutionBudgetSnapshot {
+ if (!value || typeof value !== 'object') throw new Error('Invalid task execution budget')
+ const snapshot = value as TaskExecutionBudgetSnapshot
+ if (
+ !Number.isFinite(snapshot.elapsedActiveMs) ||
+ snapshot.elapsedActiveMs < 0 ||
+ !Number.isSafeInteger(snapshot.iterationsUsed) ||
+ snapshot.iterationsUsed < 0 ||
+ !Number.isSafeInteger(snapshot.durationMs) ||
+ snapshot.durationMs <= 0 ||
+ snapshot.durationMs > 2_147_483_647 ||
+ !Number.isSafeInteger(snapshot.maxIterations) ||
+ snapshot.maxIterations <= 0
+ ) {
+ throw new Error('Invalid task execution budget')
+ }
+ return {
+ elapsedActiveMs: snapshot.elapsedActiveMs,
+ iterationsUsed: snapshot.iterationsUsed,
+ durationMs: snapshot.durationMs,
+ maxIterations: snapshot.maxIterations,
+ }
+}
+
+/** One active-time and iteration budget, retained across approval suspensions. */
+export class TaskExecutionBudget {
+ private elapsedActiveMs = 0
+ private iterationsUsed = 0
+ private segmentStart: number | undefined
+ private timer: ReturnType<typeof setTimeout> | undefined
+ constructor(
+ public durationMs: number,
+ public maxIterations: number,
+ private readonly clock: () => number = () => performance.now()
+ ) {
+ if (
+ !Number.isSafeInteger(durationMs) ||
+ durationMs <= 0 ||
+ durationMs > 2_147_483_647 ||
+ !Number.isSafeInteger(maxIterations) ||
+ maxIterations <= 0
+ ) {
+ throw new Error('Invalid task execution limits')
+ }
+ }
+ restore(value: unknown): void {
+ if (this.segmentStart !== undefined) throw new Error('Cannot restore an active budget')
+ const snapshot = parseTaskExecutionBudget(value)
+ this.durationMs = Math.min(this.durationMs, snapshot.durationMs)
+ this.maxIterations = Math.min(this.maxIterations, snapshot.maxIterations)
+ this.elapsedActiveMs = snapshot.elapsedActiveMs
+ this.iterationsUsed = snapshot.iterationsUsed
+ }
+ get remainingIterations(): number {
+ return Math.max(0, this.maxIterations - this.iterationsUsed)
+ }
+ private elapsed(): number {
+ return (
+ this.elapsedActiveMs +
+ (this.segmentStart === undefined ? 0 : Math.max(0, this.clock() - this.segmentStart))
+ )
+ }
+ assertTime(): void {
+ if (this.elapsed() >= this.durationMs) throw this.timeoutError()
+ }
+ timeoutError(): TaskLimitError {
+ return new TaskLimitError(
+ 'TASK_DURATION_LIMIT',
+ `Task stopped before completion: active execution reached ${this.durationMs}ms. Continuation requires a new budget.`
+ )
+ }
+ start(controller: AbortController): void {
+ controller.signal.throwIfAborted()
+ this.assertTime()
+ if (this.segmentStart !== undefined) throw new Error('Task budget already active')
+ this.segmentStart = this.clock()
+ this.timer = setTimeout(
+ () => controller.abort(this.timeoutError()),
+ this.durationMs - this.elapsed()
+ )
+ this.timer.unref?.()
+ }
+ consumeIteration(): void {
+ this.assertTime()
+ if (this.remainingIterations === 0)
+ throw new TaskLimitError(
+ 'TASK_ITERATION_LIMIT',
+ 'Task stopped before completion: its iteration budget is exhausted.'
+ )
+ this.iterationsUsed++
+ }
+ pause(): TaskExecutionBudgetSnapshot {
+ this.elapsedActiveMs = this.elapsed()
+ this.segmentStart = undefined
+ clearTimeout(this.timer)
+ this.timer = undefined
+ return {
+ elapsedActiveMs: this.elapsedActiveMs,
+ iterationsUsed: this.iterationsUsed,
+ durationMs: this.durationMs,
+ maxIterations: this.maxIterations,
+ }
+ }
+}
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index d1d5d5ac7..79d2f1c2d 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -5,9 +5,11 @@
* 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 { 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'
@@ -41,6 +43,10 @@ import {
runToolUseLoop,
validateToolLinkages,
} from '../core/orchestration/toolUseLoop'
+import {
+ collectToolAttachments,
+ mergeCollectedAttachments,
+} from '../core/orchestration/toolUseLoopMessages'
import { buildTurnContextBlock } from '../core/orchestration/turnContext'
import { DefaultReasoningFactory } from '../core/reasoning'
import {
@@ -107,6 +113,7 @@ import {
looksLikeWorkflowTriggerSuccess,
workflowAccessDeniedResponseForMessage,
} from './providerWorkflowAccessGate'
+import { TaskExecutionBudget, TaskLimitError } from './taskExecutionBudget'
import { TurnTimingRecorder } from './turnTiming'
import type { AgentConfig, ExecutorFailoverSupport } from './types'
@@ -232,7 +239,7 @@ export interface TaskExecutorDeps {
// Callbacks to coordinator
onApprovalNeeded: (requestId: string, taskId: string, approval: PendingApproval) => void
onComplete: (task: Task) => void
- onFail: (task: Task, error: TaskError) => void
+ onFail: (task: Task, error: TaskError, attachments?: Attachment[]) => void
}
export class TaskExecutor {
@@ -243,6 +250,9 @@ export class TaskExecutor {
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<{
registry: ToolRegistry
loopController: LoopController
@@ -282,6 +292,10 @@ export class TaskExecutor {
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
@@ -348,6 +362,9 @@ export class TaskExecutor {
) {
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')
this.task.traceContext = approval.traceContext ?? this.conversation.traceContext ?? null
this.state = 'waiting_approval'
}
@@ -370,6 +387,7 @@ export class TaskExecutor {
try {
this.state = 'processing'
+ this.executionBudget.start(this.abortController)
this.turnTiming = new TurnTimingRecorder(this.task.createdAt)
// 1. Resolve session key, get/create conversation
@@ -453,7 +471,7 @@ export class TaskExecutor {
// the no-cap path stays identical to before (no baseline, brake disabled).
this.captureTaskTokenBaseline()
- await this.prepareChannelWorkflowCallerContext()
+ await withAbort(() => this.prepareChannelWorkflowCallerContext(), this.abortController.signal)
this.enqueueGovernedRunEvent('run_start', `task:${this.taskId}:start`)
if (this.workflowAccessDeniedResponse && looksLikeWorkflowAccessRequest(userInput)) {
this.logProviderWorkflowAccessDenied('request')
@@ -482,14 +500,45 @@ export class TaskExecutor {
this.resolveCompletion?.()
}
} catch (error) {
+ if (
+ this.abortController.signal.aborted &&
+ !(this.abortController.signal.reason instanceof TaskLimitError)
+ ) {
+ if (this.conversation)
+ await this.handleLoopResult({ type: 'cancelled', reason: 'signal_aborted' })
+ this.resolveCompletion?.()
+ 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'
- this.deps.onFail(this.task, taskError)
+ if (error instanceof TaskLimitError && this.completedAttachments.length > 0) {
+ this.deps.onFail(this.task, taskError, [...this.completedAttachments])
+ } else {
+ this.deps.onFail(this.task, taskError)
+ }
this.resolveCompletion?.()
+ } finally {
+ this.executionBudget.pause()
}
}
@@ -515,7 +564,27 @@ export class TaskExecutor {
return
}
+ const savedApproval = this.conversation.pending_approval
+ 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 = {
@@ -598,7 +667,10 @@ export class TaskExecutor {
// 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 this.buildLoopConfig({ skipContextManager: true })
+ const loopConfig = await withAbort(
+ () => this.buildLoopConfig({ skipContextManager: true }),
+ this.abortController.signal
+ )
const suspendedCall = {
id: approval.tool_call_id,
name: approval.tool_name,
@@ -629,7 +701,10 @@ export class TaskExecutor {
}
const execStart = Date.now()
+ this.executionBudget.assertTime()
const toolResult = await executeSingleTool(suspendedCall, loopConfig)
+ collectToolAttachments([toolResult], this.completedAttachments)
+ this.executionBudget.assertTime()
if (reporter) {
reporter.reportToolComplete({
@@ -739,14 +814,60 @@ export class TaskExecutor {
this.resolveCompletion?.()
}
} 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' })
+ this.resolveCompletion?.()
+ 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'
- this.deps.onFail(this.task, taskError)
+ if (error instanceof TaskLimitError && this.completedAttachments.length > 0) {
+ this.deps.onFail(this.task, taskError, [...this.completedAttachments])
+ } else {
+ this.deps.onFail(this.task, taskError)
+ }
this.resolveCompletion?.()
+ } finally {
+ this.executionBudget.pause()
}
}
@@ -756,6 +877,13 @@ export class TaskExecutor {
* 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,
@@ -899,7 +1027,7 @@ export class TaskExecutor {
this.prependTurnContextBlock(messages)
}
const promptAssemblyStart = Date.now()
- const loopConfig = await this.buildLoopConfig()
+ 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).
@@ -946,6 +1074,15 @@ export class TaskExecutor {
}
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) {
@@ -954,8 +1091,17 @@ export class TaskExecutor {
switch (result.type) {
case 'response':
case 'exhaustion': {
+ if (result.type === 'exhaustion' && result.reason !== 'task_budget')
+ 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 this.guardProviderWorkflowTriggerClaim(rawContent)
+ 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) {
@@ -975,6 +1121,8 @@ export class TaskExecutor {
// 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) {
@@ -993,6 +1141,7 @@ export class TaskExecutor {
}
case 'need_approval': {
+ result.approval.task_budget = this.executionBudget.pause()
// 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
@@ -1005,9 +1154,11 @@ export class TaskExecutor {
result.approval
)
} catch (err) {
- await this.deps.conversationManager.failTurn(this.conversation!)
+ 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)
@@ -1058,6 +1209,8 @@ export class TaskExecutor {
}
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
@@ -1074,6 +1227,8 @@ export class TaskExecutor {
})
}
// 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) {
@@ -1201,7 +1356,10 @@ export class TaskExecutor {
// 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 = maybeWrapHookedLlmPort(effectiveLlmPort, this.deps.guardrailsConfig)
+ const hookedLlmPort = bindTaskSignal(
+ maybeWrapHookedLlmPort(effectiveLlmPort, this.deps.guardrailsConfig),
+ this.abortController.signal
+ )
const metadata: Record<string, unknown> = {}
if (this.task.sourceMessage) {
@@ -1285,11 +1443,13 @@ export class TaskExecutor {
loopController,
contextManager,
progressReporter,
- maxIterations: this.deps.config.maxToolCallsPerTask || 10,
+ maxIterations: this.executionBudget.remainingIterations,
toolTimeout: appConfig.nativeTool.toolTimeout,
toolProgressInterval: appConfig.nativeTool.toolProgressInterval,
})
loopConfig.abortSignal = this.abortController.signal
+ 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).
@@ -1324,6 +1484,7 @@ export class TaskExecutor {
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)
@@ -1938,11 +2099,7 @@ export class TaskExecutor {
private collectAttachments(results: ToolResult[]): Attachment[] {
const attachments: Attachment[] = []
- for (const r of results) {
- if (r.attachments) {
- attachments.push(...r.attachments)
- }
- }
+ collectToolAttachments(results, attachments)
return attachments
}
diff --git a/mcp-host/src/agent/types.ts b/mcp-host/src/agent/types.ts
index 7f41a69b5..0f8ef8679 100644
--- a/mcp-host/src/agent/types.ts
+++ b/mcp-host/src/agent/types.ts
@@ -66,7 +66,7 @@ export interface AgentConfig {
// Maximum time to process a single task (ms)
maxTaskDuration: number
- // Maximum tool calls per task
+ // Maximum LLM/tool iterations per task (each iteration may call multiple tools)
maxToolCallsPerTask: number
// Whether to auto-start processing
@@ -83,10 +83,10 @@ export interface AgentConfig {
* Default agent configuration.
*/
export const DEFAULT_AGENT_CONFIG: AgentConfig = {
- maxTaskDuration: 5 * 60 * 1000, // 5 minutes
- maxToolCallsPerTask: 50,
+ maxTaskDuration: 24 * 60 * 60 * 1000, // 24 hours of active task execution
+ maxToolCallsPerTask: 1000,
autoStart: true,
- taskDelay: 100, // 100ms between tasks
+ taskDelay: 3, // 3ms minimum between task dispatches
approvalTimeout: 0, // 0 = no in-memory auto-deny; the request stays available until resolved. Override via CLERUM_APPROVAL_TIMEOUT
}
diff --git a/mcp-host/src/config.executionLimits.test.ts b/mcp-host/src/config.executionLimits.test.ts
new file mode 100644
index 000000000..559386ba1
--- /dev/null
+++ b/mcp-host/src/config.executionLimits.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveMcpRequestTimeoutMs } from './mcp/requestOptions'
+
+const names = [
+ 'CLERUM_AGENT_TASK_DELAY',
+ 'CLERUM_AGENT_MAX_TASK_DURATION',
+ 'CLERUM_AGENT_MAX_TOOL_CALLS',
+ 'CLERUM_SHELL_TIMEOUT',
+ 'CLERUM_TOOL_TIMEOUT',
+]
+afterEach(() => {
+ vi.unstubAllEnvs()
+ vi.resetModules()
+})
+
+describe('execution limit validation', () => {
+ it.each(names)('rejects an explicitly empty %s', async name => {
+ vi.resetModules()
+ vi.stubEnv(name, '')
+ await expect(import('./config')).rejects.toThrow(name)
+ })
+ it.each(['CLERUM_MCP_TOOL_TIMEOUT_MS', 'CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS'])(
+ 'rejects an explicitly empty %s',
+ name => {
+ vi.stubEnv(name, '')
+ expect(() => resolveMcpRequestTimeoutMs()).toThrow(name)
+ }
+ )
+ it.each(
+ names.flatMap(name => ['abc', '-1', '1.5', '2147483648'].map(value => ({ name, value })))
+ )('rejects $name=$value', async ({ name, value }) => {
+ vi.resetModules()
+ vi.stubEnv(name, value)
+ await expect(import('./config')).rejects.toThrow(name)
+ })
+ it.each(
+ ['CLERUM_MCP_TOOL_TIMEOUT_MS', 'CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS'].flatMap(name =>
+ ['abc', '-1', '1.5', '2147483648'].map(value => ({ name, value }))
+ )
+ )('rejects $name=$value', ({ name, value }) => {
+ vi.stubEnv(name, value)
+ expect(() => resolveMcpRequestTimeoutMs()).toThrow(name)
+ })
+ it('keeps defaults when execution variables are absent', async () => {
+ vi.resetModules()
+ for (const name of [
+ ...names,
+ 'CLERUM_MCP_TOOL_TIMEOUT_MS',
+ 'CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS',
+ ])
+ vi.stubEnv(name, undefined)
+ const { config } = await import('./config')
+ expect(config.agentTaskDelay).toBe(3)
+ expect(config.agentMaxTaskDuration).toBe(86400000)
+ expect(config.agentMaxToolCallsPerTask).toBe(1000)
+ expect(config.nativeTool.shellTimeout).toBe(1500000)
+ expect(config.nativeTool.toolTimeout).toBe(1500000)
+ expect(resolveMcpRequestTimeoutMs()).toBe(1500000)
+ })
+})
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index c0d4a797a..acfb57cea 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -306,6 +306,21 @@ function getEnv(key: string, defaultValue?: string): string | undefined {
return process.env[key] ?? defaultValue
}
+function getExecutionLimit(key: string, defaultValue: number, allowZero = false): number {
+ const raw = getEnv(key)
+ if (raw === undefined) return defaultValue
+ const value = Number(raw)
+ if (
+ !/^\d+$/.test(raw) ||
+ !Number.isSafeInteger(value) ||
+ value < (allowZero ? 0 : 1) ||
+ value > 2_147_483_647
+ ) {
+ throw new Error(`${key} must be a valid bounded integer`)
+ }
+ return value
+}
+
function getEnvBool(key: string, defaultValue: boolean): boolean {
const value = process.env[key]
if (!value) return defaultValue
@@ -714,9 +729,9 @@ export const config: Config = {
),
// Agent configuration
- agentTaskDelay: parseInt(getEnv('CLERUM_AGENT_TASK_DELAY', '100')!, 10),
- agentMaxTaskDuration: parseInt(getEnv('CLERUM_AGENT_MAX_TASK_DURATION', '1800000')!, 10),
- agentMaxToolCallsPerTask: parseInt(getEnv('CLERUM_AGENT_MAX_TOOL_CALLS', '50')!, 10),
+ agentTaskDelay: getExecutionLimit('CLERUM_AGENT_TASK_DELAY', 3, true),
+ agentMaxTaskDuration: getExecutionLimit('CLERUM_AGENT_MAX_TASK_DURATION', 86400000),
+ agentMaxToolCallsPerTask: getExecutionLimit('CLERUM_AGENT_MAX_TOOL_CALLS', 1000),
agentMaxQueueSize: parseInt(getEnv('CLERUM_AGENT_MAX_QUEUE_SIZE', '100')!, 10),
// 0 = disabled (default): an unresolved approval never auto-denies in memory,
// so the request stays available no matter how long the human takes. A
@@ -905,8 +920,8 @@ export const config: Config = {
// Native tool configuration
nativeTool: {
workspacePath: process.env.CLERUM_WORKSPACE_PATH || process.cwd(),
- shellTimeout: parseInt(getEnv('CLERUM_SHELL_TIMEOUT', '600000')!, 10),
- toolTimeout: parseInt(getEnv('CLERUM_TOOL_TIMEOUT', '660000')!, 10),
+ shellTimeout: getExecutionLimit('CLERUM_SHELL_TIMEOUT', 1500000),
+ toolTimeout: getExecutionLimit('CLERUM_TOOL_TIMEOUT', 1500000),
toolProgressInterval: parseInt(getEnv('CLERUM_TOOL_PROGRESS_INTERVAL_MS', '30000')!, 10),
httpAllowlist: (process.env.CLERUM_HTTP_ALLOWLIST || '')
.split(',')
diff --git a/mcp-host/src/core/adapters/__tests__/abortableLlmPort.test.ts b/mcp-host/src/core/adapters/__tests__/abortableLlmPort.test.ts
new file mode 100644
index 000000000..f63481ce1
--- /dev/null
+++ b/mcp-host/src/core/adapters/__tests__/abortableLlmPort.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { LlmPort } from '../../interfaces'
+import { bindTaskSignal } from '../abortableLlmPort'
+
+describe('task-bound LLM calls', () => {
+ it.each(['complete', 'completeWithTools'] as const)(
+ 'aborts %s and ignores late provider completion',
+ async method => {
+ const controller = new AbortController()
+ const requestController = new AbortController()
+ let finish: (value: any) => void = () => {
+ throw new Error('provider not started')
+ }
+ const call = vi.fn(
+ (_request: { signal?: AbortSignal }) =>
+ new Promise<any>(resolve => {
+ finish = resolve
+ })
+ )
+ const inner: LlmPort = { modelName: () => 'test', complete: call, completeWithTools: call }
+ const port = bindTaskSignal(inner, controller.signal)
+ const pending = port[method]({
+ messages: [],
+ tools: [],
+ signal: requestController.signal,
+ } as any).catch(error => error)
+ await Promise.resolve()
+ const forwardedSignal = call.mock.calls[0][0].signal!
+ expect(forwardedSignal).toBeInstanceOf(AbortSignal)
+ expect(forwardedSignal.aborted).toBe(false)
+ const reason = new Error('task duration exceeded')
+ controller.abort(reason)
+ expect(forwardedSignal.aborted).toBe(true)
+ expect(forwardedSignal.reason).toBe(reason)
+ expect(requestController.signal.aborted).toBe(false)
+ expect(await pending).toBe(reason)
+ expect(call.mock.calls.length).toBe(1)
+ finish({ content: 'late result' })
+ expect(await pending).toBe(reason)
+ }
+ )
+})
diff --git a/mcp-host/src/core/adapters/abortableLlmPort.ts b/mcp-host/src/core/adapters/abortableLlmPort.ts
new file mode 100644
index 000000000..f5693ef8c
--- /dev/null
+++ b/mcp-host/src/core/adapters/abortableLlmPort.ts
@@ -0,0 +1,47 @@
+import type { LlmPort } from '../interfaces'
+
+/** A late provider result must not re-enter a task that has already stopped. */
+export function withAbort<T>(operation: () => Promise<T>, signal: AbortSignal): Promise<T> {
+ signal.throwIfAborted()
+ return new Promise<T>((resolve, reject) => {
+ const cleanup = () => signal.removeEventListener('abort', onAbort)
+ const onAbort = () => {
+ cleanup()
+ reject(signal.reason)
+ }
+ signal.addEventListener('abort', onAbort, { once: true })
+ Promise.resolve()
+ .then(() => {
+ signal.throwIfAborted()
+ return operation()
+ })
+ .then(
+ value => {
+ cleanup()
+ resolve(value)
+ },
+ error => {
+ cleanup()
+ reject(error)
+ }
+ )
+ })
+}
+
+/** Reasoning and compaction share the same task cancellation boundary. */
+export function bindTaskSignal(inner: LlmPort, taskSignal: AbortSignal): LlmPort {
+ const signalFor = (signal?: AbortSignal) =>
+ signal ? AbortSignal.any([signal, taskSignal]) : taskSignal
+ return {
+ modelName: () => inner.modelName(),
+ ...(inner.getTokenCounter ? { getTokenCounter: () => inner.getTokenCounter!() } : {}),
+ complete: request => {
+ const signal = signalFor(request.signal)
+ return withAbort(() => inner.complete({ ...request, signal }), signal)
+ },
+ completeWithTools: request => {
+ const signal = signalFor(request.signal)
+ return withAbort(() => inner.completeWithTools({ ...request, signal }), signal)
+ },
+ }
+}
diff --git a/mcp-host/src/core/adapters/toolRegistryAdapter.ts b/mcp-host/src/core/adapters/toolRegistryAdapter.ts
index c382bd6dd..24cac03af 100644
--- a/mcp-host/src/core/adapters/toolRegistryAdapter.ts
+++ b/mcp-host/src/core/adapters/toolRegistryAdapter.ts
@@ -1,7 +1,7 @@
import { serverNameOf } from '../../capabilities/toolCatalogTools'
import { logger } from '../../logger'
import { McpManager } from '../../mcp/manager'
-import { Tool, ToolRegistry } from '../interfaces'
+import { ExecutionContext, Tool, ToolRegistry } from '../interfaces'
import { Attachment, ToolDefinition, ToolOutput, ValidationResult } from '../types'
import {
BoundedJsonError,
@@ -217,7 +217,7 @@ class McpToolAdapter implements Tool {
}
}
- async execute(params: Record<string, unknown>): Promise<ToolOutput> {
+ async execute(params: Record<string, unknown>, context?: ExecutionContext): Promise<ToolOutput> {
const startTime = Date.now()
try {
// An approval may have been suspended with an older adapter/schema.
@@ -244,6 +244,8 @@ class McpToolAdapter implements Tool {
// another user's broker token.
const result = await this.mcpManager.callTool(this.fullName, params, {
userId: this.userId,
+ ...(context?.timeoutMs === undefined ? {} : { timeoutMs: context.timeoutMs }),
+ ...(context?.signal ? { signal: context.signal } : {}),
})
const { textParts, attachments } = extractMcpContent(result.result, this.fullName)
diff --git a/mcp-host/src/core/conversation/conversation.ts b/mcp-host/src/core/conversation/conversation.ts
index 35951b871..528d47bf5 100644
--- a/mcp-host/src/core/conversation/conversation.ts
+++ b/mcp-host/src/core/conversation/conversation.ts
@@ -496,7 +496,11 @@ export class ConversationManager {
* that via `enqueueSync`; this method awaits the ACK before returning.
*/
async suspendForApproval(conversation: Conversation, approval: PendingApproval): Promise<void> {
- if (conversation.state !== ConversationState.Processing) {
+ const renewing =
+ conversation.state === ConversationState.AwaitingApproval &&
+ conversation.pending_approval?.legacy_budget === true &&
+ approval.replaces_request_id === conversation.pending_approval.request_id
+ if (conversation.state !== ConversationState.Processing && !renewing) {
throw new ConversationError(
`Cannot suspend: conversation is ${conversation.state}`,
ConversationErrorCode.InvalidTransition
diff --git a/mcp-host/src/core/conversation/persistence/__tests__/crossPodRestart.test.ts b/mcp-host/src/core/conversation/persistence/__tests__/crossPodRestart.test.ts
index 892304512..0d183081b 100644
--- a/mcp-host/src/core/conversation/persistence/__tests__/crossPodRestart.test.ts
+++ b/mcp-host/src/core/conversation/persistence/__tests__/crossPodRestart.test.ts
@@ -10,6 +10,7 @@ import * as os from 'node:os'
import * as path from 'node:path'
import { AgentStateMachine } from '../../../../agent/stateMachine'
import { TaskLifecycle } from '../../../../lifecycle/taskLifecycle'
+import { logger } from '../../../../logger'
import { MessageQueue } from '../../../../queue/messageQueue'
import type { IncomingMessage } from '../../../../server'
import { ConversationState, type TraceContextV1 } from '../../../types'
@@ -74,6 +75,12 @@ describe('Cross-pod-restart resume — P.3 invariant #3', () => {
parameters: { command: 'rm -rf /' },
description: 'dangerous',
context_snapshot: [],
+ task_budget: {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ },
})
await podA.shutdown()
@@ -139,6 +146,12 @@ describe('Cross-pod-restart resume — P.3 invariant #3', () => {
parameters: {},
description: 'safe',
context_snapshot: [],
+ task_budget: {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ },
})
await managerA.approve(convA, false)
await podA.shutdown()
@@ -171,6 +184,12 @@ describe('Cross-pod-restart resume — P.3 invariant #3', () => {
parameters: {},
description: 'unsafe owner fixture',
context_snapshot: [],
+ task_budget: {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ },
})
pod.worker.db
.prepare('UPDATE sessions SET user_id = ? WHERE id = ?')
@@ -190,17 +209,18 @@ describe('Cross-pod-restart resume — P.3 invariant #3', () => {
agent.setMcpManager({ getAllTools: () => [], callTool: async () => ({}) } as never)
agent.setConversationStore(pod.store)
agent.setColdStartLoader(new SqliteColdStartLoader(pod.store))
- const log = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+ const log = vi.spyOn(logger, 'error').mockImplementation(() => undefined)
try {
await expect(agent.bootstrap()).resolves.toBeUndefined()
expect(agent.getPendingApprovals()).toEqual([])
expect(log).toHaveBeenCalledWith(
- expect.stringContaining('CONV_OWNERSHIP_MISMATCH')
+ expect.objectContaining({ code: 'CONV_OWNERSHIP_MISMATCH' }),
+ 'Pending approval ownership rejected'
)
- await expect(
- manager.getOrCreate(sessionKey, { userId: 'user-1' })
- ).rejects.toMatchObject({ code: 'CONV_OWNERSHIP_MISMATCH' })
+ await expect(manager.getOrCreate(sessionKey, { userId: 'user-1' })).rejects.toMatchObject({
+ code: 'CONV_OWNERSHIP_MISMATCH',
+ })
} finally {
log.mockRestore()
await pod.shutdown()
diff --git a/mcp-host/src/core/conversation/persistence/__tests__/reconstructConnectRequired.test.ts b/mcp-host/src/core/conversation/persistence/__tests__/reconstructConnectRequired.test.ts
index ab9295fab..73d4743cb 100644
--- a/mcp-host/src/core/conversation/persistence/__tests__/reconstructConnectRequired.test.ts
+++ b/mcp-host/src/core/conversation/persistence/__tests__/reconstructConnectRequired.test.ts
@@ -39,6 +39,12 @@ async function roundTrip(approval: PendingApproval): Promise<PendingApproval> {
// persistSuspend requires.
await manager.startTurn(conv, 'do the thing', 'task-1')
+ approval.task_budget = {
+ elapsedActiveMs: 0,
+ iterationsUsed: 1,
+ durationMs: 86400000,
+ maxIterations: 1000,
+ }
await handle.store.persistSuspend(conv, approval)
const s = prepareStatements(handle.worker.db)
diff --git a/mcp-host/src/core/conversation/persistence/__tests__/sqliteConversationStore.test.ts b/mcp-host/src/core/conversation/persistence/__tests__/sqliteConversationStore.test.ts
index aac760426..3a9b03ce1 100644
--- a/mcp-host/src/core/conversation/persistence/__tests__/sqliteConversationStore.test.ts
+++ b/mcp-host/src/core/conversation/persistence/__tests__/sqliteConversationStore.test.ts
@@ -550,6 +550,12 @@ describe('SqliteConversationStore — cold-start rehydration', () => {
await manager.startTurn(conv, 'hi', 'test-task')
await manager.suspendForApproval(conv, {
request_id: 'req-cold',
+ task_budget: {
+ elapsedActiveMs: 40,
+ iterationsUsed: 2,
+ durationMs: 1000,
+ maxIterations: 10,
+ },
tool_name: 'shell_exec',
tool_call_id: 'tc_cold',
parameters: {},
@@ -567,6 +573,12 @@ describe('SqliteConversationStore — cold-start rehydration', () => {
expect(rehydrated).toBeDefined()
expect(rehydrated!.state).toBe(ConversationState.AwaitingApproval)
expect(rehydrated!.pending_approval?.request_id).toBe('req-cold')
+ expect(rehydrated!.pending_approval?.task_budget).toEqual({
+ elapsedActiveMs: 40,
+ iterationsUsed: 2,
+ durationMs: 1000,
+ maxIterations: 10,
+ })
expect(rehydrated!.turns).toHaveLength(1)
expect(rehydrated!.turns[0].user_input).toBe('hi')
} finally {
@@ -1047,6 +1059,12 @@ describe('SqliteConversationStore — active_task_id (D.1)', () => {
await manager.startTurn(conv, 'hola', 'task-reload', traceContext)
await manager.suspendForApproval(conv, {
request_id: 'req-reload',
+ task_budget: {
+ elapsedActiveMs: 40,
+ iterationsUsed: 2,
+ durationMs: 1000,
+ maxIterations: 10,
+ },
tool_name: 'shell_exec',
tool_call_id: 'tc-reload',
parameters: {},
diff --git a/mcp-host/src/core/conversation/persistence/reconstruct.ts b/mcp-host/src/core/conversation/persistence/reconstruct.ts
index 51303dd1e..f83901d15 100644
--- a/mcp-host/src/core/conversation/persistence/reconstruct.ts
+++ b/mcp-host/src/core/conversation/persistence/reconstruct.ts
@@ -1,3 +1,4 @@
+import { parseTaskExecutionBudget } from '../../../agent/taskExecutionBudget'
/**
* Reconstruct a live `Conversation` from rows pulled out of the SQLite store.
*
@@ -139,6 +140,11 @@ export function normalizeConnectReason(
export function reconstructPendingApproval(row: PendingApprovalRow): PendingApproval {
const snapshot = JSON.parse(row.context_snapshot) as ChatMessage[]
return {
+ task_budget:
+ row.task_budget === 'legacy'
+ ? undefined
+ : parseTaskExecutionBudget(JSON.parse(row.task_budget ?? 'null')),
+ legacy_budget: row.task_budget === 'legacy',
request_id: row.request_id,
tool_name: row.tool_name,
parameters: JSON.parse(row.parameters) as Record<string, unknown>,
diff --git a/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts b/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts
index de33ee306..9b7769dda 100644
--- a/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts
+++ b/mcp-host/src/core/conversation/persistence/sqliteConversationStore.ts
@@ -23,6 +23,7 @@ import type {
ReapedSession,
SessionRow,
} from '../../../db/worker/protocol'
+import { logger } from '../../../logger'
import { parseSessionKey } from '../../../session/types'
import { ConversationError, ConversationErrorCode } from '../../errors'
import {
@@ -207,7 +208,7 @@ export class SqliteConversationStore implements ConversationStore {
try {
cb(key, value)
} catch (err) {
- console.error('[SqliteConversationStore] onEvict callback threw:', err)
+ logger.error({ err }, 'Conversation eviction callback failed')
}
}
})
@@ -251,7 +252,7 @@ export class SqliteConversationStore implements ConversationStore {
pin(key: string): void {
if (!this.cache.has(key)) {
- console.warn(`[SqliteConversationStore] pin(${key}): unknown key`)
+ logger.warn({ ...this.cache.stats() }, 'Cannot pin unknown conversation')
return
}
this.cache.pin(key)
@@ -309,10 +310,9 @@ export class SqliteConversationStore implements ConversationStore {
// up, and pinnedCountGauge surfaces the saturation for alerting. The
// root-cause leak is fixed in SqliteColdStartLoader.releaseDropped; this
// is the last-resort backstop.
- console.error(
- `[SqliteConversationStore] cache overflow loading sessionKey=${sessionKey} ` +
- `(pinned=${this.cache.pinnedCount()}/${this.cache.maxSize}); returning uncached`,
- err
+ logger.error(
+ { err, pinnedCount: this.cache.pinnedCount(), maxSize: this.cache.maxSize },
+ 'Conversation cache full; returning uncached'
)
pinnedCountGauge?.set(this.cache.pinnedCount())
return conversation
@@ -520,14 +520,13 @@ export class SqliteConversationStore implements ConversationStore {
'Pending approval session ownership could not be verified',
ConversationErrorCode.OwnershipMismatch
)
- console.error(
- JSON.stringify({
- level: 'error',
- event: 'pending_approval_ownership_rejected',
+ logger.error(
+ {
code: error.code,
requestId: row.approval.request_id,
reason: derivedOwner ? 'owner_mismatch' : 'unverifiable_session_suffix',
- })
+ },
+ 'Pending approval ownership rejected'
)
continue
}
@@ -656,9 +655,7 @@ export class SqliteConversationStore implements ConversationStore {
persistSessionCreate(conv: Conversation, opts: GetOrCreateOptions): void {
const sessionKey = this.sessionKeyById.get(conv.id)
if (!sessionKey) {
- console.warn(
- `[SqliteConversationStore] persistSessionCreate: no sessionKey for conv ${conv.id}`
- )
+ logger.warn({ conversationId: conv.id }, 'Missing session key while persisting conversation')
return
}
const parsed = parseSessionKey(sessionKey)
@@ -1023,6 +1020,7 @@ export class SqliteConversationStore implements ConversationStore {
this.reconcilePinning(sessionKey, conv)
const now = Date.now()
const row: PendingApprovalRow = {
+ task_budget: approval.task_budget ? JSON.stringify(approval.task_budget) : null,
request_id: approval.request_id,
session_id: conv.id,
task_id: conv.activeTaskId,
@@ -1047,11 +1045,12 @@ export class SqliteConversationStore implements ConversationStore {
mcp_server_name: approval.mcpServerName ?? null,
}
await this.persistQueue.enqueueSync(
- { kind: 'insert_pending_approval', payload: row },
- sessionKey
- )
- await this.persistQueue.enqueueSync(
- { kind: 'update_session_state', sessionId: conv.id, state: conv.state },
+ {
+ kind: 'insert_pending_approval',
+ payload: row,
+ replaceRequestId: approval.replaces_request_id,
+ markAwaitingApproval: true,
+ },
sessionKey
)
}
diff --git a/mcp-host/src/core/interfaces.ts b/mcp-host/src/core/interfaces.ts
index 66f53aae0..3799a2f76 100644
--- a/mcp-host/src/core/interfaces.ts
+++ b/mcp-host/src/core/interfaces.ts
@@ -78,6 +78,9 @@ export interface ToolTraceDescriptor {
* `tool_progress` SSE events.
*/
export interface ExecutionContext {
+ /** Execution budget, excluding bounded termination cleanup. */
+ timeoutMs?: number
+ signal?: AbortSignal
/**
* Tool calls this as output becomes available (not required to be line-aligned
* — the ring buffer handles line boundaries).
@@ -107,6 +110,8 @@ export interface Tool {
* Tools that don't opt in get zero runtime overhead from this feature.
*/
supportsProgressOutput?(): boolean
+ /** Local implementation-owned bounded cleanup after execution is stopped. */
+ timeoutCleanupMs?(): number
}
// ─── Channel ────────────────────────────────────────────────
diff --git a/mcp-host/src/core/orchestration/__tests__/toolExecutionTimeout.test.ts b/mcp-host/src/core/orchestration/__tests__/toolExecutionTimeout.test.ts
new file mode 100644
index 000000000..0433dadc3
--- /dev/null
+++ b/mcp-host/src/core/orchestration/__tests__/toolExecutionTimeout.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { tmpdir } from 'node:os'
+import type { Tool } from '../../interfaces'
+import { ShellTool } from '../../tools/shell'
+import { executeWithTimeout } from '../toolExecutionTimeout'
+
+const context = { onOutput: () => {} }
+function tool(overrides: Partial<Tool> = {}): Tool {
+ return {
+ name: () => 'test',
+ description: () => '',
+ parametersSchema: () => ({}),
+ requiresApproval: () => false,
+ requiresSanitization: () => true,
+ execute: vi.fn(async () => ({ content: 'done', is_error: false, duration_ms: 0 })),
+ ...overrides,
+ }
+}
+afterEach(() => vi.useRealTimers())
+describe('tool execution deadline', () => {
+ it('clears deadline timers when execution succeeds', async () => {
+ vi.useFakeTimers()
+ await expect(executeWithTimeout(tool(), {}, context, 100)).resolves.toMatchObject({
+ content: 'done',
+ })
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ it('stops an uncooperative ordinary tool at the execution deadline', async () => {
+ vi.useFakeTimers()
+ // Intentionally never settles to exercise the outer deadline.
+ const pending = executeWithTimeout(
+ tool({ execute: () => new Promise(() => {}) }),
+ {},
+ context,
+ 100
+ ).catch(error => error)
+ await vi.advanceTimersByTimeAsync(100)
+ expect((await pending).code).toBe('TOOL_TIMEOUT')
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ it('allows bounded cleanup after abort but never an unlimited wait', async () => {
+ vi.useFakeTimers()
+ let signal: AbortSignal | undefined
+ const pending = executeWithTimeout(
+ tool({
+ timeoutCleanupMs: () => 20,
+ execute: async (_, ctx) => {
+ signal = ctx?.signal
+ return new Promise(() => {})
+ },
+ }),
+ {},
+ context,
+ 100
+ ).catch(error => error)
+ await vi.advanceTimersByTimeAsync(100)
+ expect(signal?.aborted).toBe(true)
+ expect(vi.getTimerCount()).toBe(1)
+ await vi.advanceTimersByTimeAsync(20)
+ expect((await pending).code).toBe('TOOL_TIMEOUT')
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ it('propagates task cancellation before the tool deadline', async () => {
+ vi.useFakeTimers()
+ const parent = new AbortController()
+ const pending = executeWithTimeout(
+ tool({
+ execute: async (_, ctx) =>
+ new Promise((_, reject) => {
+ ctx!.signal!.addEventListener('abort', () => reject(ctx!.signal!.reason), {
+ once: true,
+ })
+ }),
+ }),
+ {},
+ context,
+ 1000,
+ parent.signal
+ ).catch(error => error)
+ const reason = new Error('task deadline')
+ parent.abort(reason)
+ expect(await pending).toBe(reason)
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ it.each([-1, NaN, Infinity, 2_147_483_647])(
+ 'rejects invalid cleanup allowance %s before execution',
+ async cleanup => {
+ const t = tool({ timeoutCleanupMs: () => cleanup })
+ await expect(executeWithTimeout(t, {}, context, 100)).rejects.toThrow('Invalid tool')
+ expect(t.execute).not.toHaveBeenCalled()
+ }
+ )
+ it('preserves partial shell output when both deadlines are equal', async () => {
+ const shell = new ShellTool(tmpdir(), 100, ['PATH'])
+ const result = await executeWithTimeout(
+ shell,
+ { command: 'printf partial; sleep 60' },
+ context,
+ 100
+ )
+ expect(result.is_error).toBe(true)
+ expect(result.content).toContain('partial')
+ expect(result.content).toContain('100ms timeout')
+ })
+ it('uses the shorter caller deadline with progress reporting disabled', async () => {
+ const shell = new ShellTool(tmpdir(), 60000, ['PATH'])
+ const result = await executeWithTimeout(
+ shell,
+ { command: 'printf partial; sleep 60' },
+ context,
+ 100
+ )
+ expect(result.content).toContain('100ms timeout')
+ expect(result.duration_ms).toBeLessThan(6100)
+ })
+})
diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts
index ceab750dd..7f01e2c13 100644
--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.spillover.test.ts
@@ -187,7 +187,10 @@ describe('executeSingleTool — T1.5 spillover wiring', () => {
} as never,
0
)
- expect(target.execute).toHaveBeenCalledExactlyOnceWith({ field_0: 'selected' }, undefined)
+ expect(target.execute).toHaveBeenCalledExactlyOnceWith(
+ { field_0: 'selected' },
+ expect.objectContaining({ timeoutMs: expect.any(Number), signal: expect.any(AbortSignal) })
+ )
expect(invoked.toolResults[0]).toMatchObject({
tool_call_id: 'business-call',
name: target.name(),
diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts
index c36d53fd3..9919bb320 100644
--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.test.ts
@@ -973,7 +973,10 @@ describe('runToolUseLoop — loop control', () => {
if (result.type === 'response') {
expect(result.content).toBe('Found X')
}
- expect(searchTool.execute).toHaveBeenCalledWith({ q: 'X' }, undefined)
+ expect(searchTool.execute).toHaveBeenCalledWith(
+ { q: 'X' },
+ expect.objectContaining({ timeoutMs: expect.any(Number), signal: expect.any(AbortSignal) })
+ )
})
it('collects tool attachments without leaking base64 into tool messages', async () => {
@@ -2051,6 +2054,7 @@ describe('executeSingleTool — progress watcher', () => {
vi.useFakeTimers()
const reporter = makeReporterMock()
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn(async () => ({ content: 'ok', is_error: false, duration_ms: 1 })),
requiresSanitization: () => false,
// NO supportsProgressOutput
@@ -2069,6 +2073,7 @@ describe('executeSingleTool — progress watcher', () => {
vi.useFakeTimers()
const reporter = makeReporterMock()
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn(async () => ({ content: 'ok', is_error: false, duration_ms: 1 })),
requiresSanitization: () => false,
supportsProgressOutput: () => false,
@@ -2087,6 +2092,7 @@ describe('executeSingleTool — progress watcher', () => {
vi.useFakeTimers()
const reporter = makeReporterMock()
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn(async () => ({ content: 'ok', is_error: false, duration_ms: 1 })),
requiresSanitization: () => false,
supportsProgressOutput: () => true,
@@ -2107,6 +2113,7 @@ describe('executeSingleTool — progress watcher', () => {
// Tool that calls context.onOutput BEFORE resolving — so watcher has dirty data.
let resolveTool: (v: any) => void = () => {}
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn((_args: any, ctx: any) => {
return new Promise<any>(r => {
resolveTool = r
@@ -2146,6 +2153,7 @@ describe('executeSingleTool — progress watcher', () => {
const reporter = makeReporterMock()
let resolveTool: (v: any) => void = () => {}
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn((_args: any, _ctx: any) => {
// Tool produces NO output — ring buffer stays empty.
return new Promise<any>(r => {
@@ -2184,6 +2192,7 @@ describe('executeSingleTool — progress watcher', () => {
vi.useFakeTimers()
const reporter = makeReporterMock()
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn(async () => ({ content: 'done', is_error: false, duration_ms: 1 })),
requiresSanitization: () => false,
supportsProgressOutput: () => true,
@@ -2207,6 +2216,7 @@ describe('executeSingleTool — progress watcher', () => {
const reporter = makeReporterMock()
// Tool that never resolves — triggers Promise.race timeout.
const tool = {
+ name: () => 'shell_exec',
execute: vi.fn(() => new Promise(() => {})),
requiresSanitization: () => false,
supportsProgressOutput: () => true,
@@ -2275,3 +2285,96 @@ describe('tool presentation failure boundary', () => {
expect(reasoning.respondWithTools).not.toHaveBeenCalled()
})
})
+
+describe('interrupted loop artifact collection', () => {
+ it.each(['iteration', 'model', 'batch', 'admission', 'validation'] as const)(
+ 'retains trusted files at %s boundary',
+ async boundary => {
+ const attachment: Attachment = {
+ id: 'report',
+ kind: 'file',
+ mimeType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: 'IyByZXBvcnQ=',
+ filename: 'report.md',
+ sourceTool: 'clerum__generate_markdown',
+ lane: 'internal_generated_artifact',
+ producer: 'mcp-host-internal-tool',
+ artifactFormat: 'md',
+ }
+ const artifactTool = createMockTool('clerum__generate_markdown', {
+ attachments: [attachment],
+ })
+ const controller = new AbortController()
+ const abortTool = createMockTool('stop')
+ vi.mocked(abortTool.execute).mockImplementation(async () => {
+ controller.abort(new Error('task deadline'))
+ return { content: 'interrupted', duration_ms: 0, is_error: true }
+ })
+ const calls = [{ id: 'report-call', name: artifactTool.name(), arguments: {} }]
+ if (boundary === 'batch' || boundary === 'validation')
+ calls.push({ id: 'stop-call', name: abortTool.name(), arguments: {} })
+ const reasoning = createMockReasoning([{ type: 'tool_calls', calls }])
+ reasoning.continueWithToolResults = vi.fn(async () => {
+ controller.abort(new Error('task deadline'))
+ return { type: 'text' as const, content: 'late reply' }
+ })
+ if (boundary === 'validation')
+ abortTool.validateParams = async () => {
+ throw new Error('validation deadline')
+ }
+ const events = new SimpleEventEmitter()
+ if (boundary === 'admission') {
+ const forward = events.emit.bind(events)
+ events.emit = event => {
+ if (event.type === 'loop:iteration' && event.data.iteration === 1)
+ throw new Error('admission deadline')
+ forward(event)
+ }
+ }
+ const config = buildLoopConfig({
+ reasoning,
+ toolRegistry: createMockRegistry([artifactTool, abortTool]),
+ safety: new BasicSafety(),
+ events,
+ conversation: makeFakeConversation(),
+ maxIterations: boundary === 'iteration' ? 1 : 2,
+ })
+ config.abortSignal = controller.signal
+ const collected = vi.fn()
+ config.onAttachments = collected
+ const pending = runToolUseLoop(config, [{ role: 'user', content: 'produce a report' }])
+ if (boundary === 'admission' || boundary === 'validation')
+ await expect(pending).rejects.toThrow(`${boundary} deadline`)
+ else expect((await pending).type).toBe(boundary === 'iteration' ? 'exhaustion' : 'cancelled')
+ expect(collected.mock.calls.flatMap(call => call[0])).toContainEqual(attachment)
+ expect(collected.mock.calls.flatMap(call => call[0]).every(item => item === attachment)).toBe(
+ true
+ )
+ }
+ )
+ it('does not collect file output with untrusted provenance on interruption', async () => {
+ const untrusted: Attachment = {
+ id: 'bad',
+ kind: 'file',
+ mimeType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: 'eA==',
+ filename: 'report.md',
+ }
+ const tool = createMockTool('external__tool', { attachments: [untrusted] })
+ const config = buildLoopConfig({
+ reasoning: createMockReasoning([
+ { type: 'tool_calls', calls: [{ id: 'call', name: tool.name(), arguments: {} }] },
+ ]),
+ toolRegistry: createMockRegistry([tool]),
+ safety: new BasicSafety(),
+ events: new SimpleEventEmitter(),
+ conversation: makeFakeConversation(),
+ maxIterations: 1,
+ })
+ config.onAttachments = vi.fn()
+ await runToolUseLoop(config, [{ role: 'user', content: 'work' }])
+ expect(config.onAttachments).toHaveBeenCalledExactlyOnceWith([])
+ })
+})
diff --git a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.workflowTriggerRecovery.test.ts b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.workflowTriggerRecovery.test.ts
index 36ca82e00..23a85ff75 100644
--- a/mcp-host/src/core/orchestration/__tests__/toolUseLoop.workflowTriggerRecovery.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/toolUseLoop.workflowTriggerRecovery.test.ts
@@ -232,7 +232,7 @@ describe('runToolUseLoop workflow trigger recovery', () => {
name: 'research-summary-workflow',
inputs: { topic: 'the roman empire' },
},
- undefined
+ expect.objectContaining({ timeoutMs: expect.any(Number), signal: expect.any(AbortSignal) })
)
})
diff --git a/mcp-host/src/core/orchestration/loopConfig.ts b/mcp-host/src/core/orchestration/loopConfig.ts
index a4caa80de..f938111a0 100644
--- a/mcp-host/src/core/orchestration/loopConfig.ts
+++ b/mcp-host/src/core/orchestration/loopConfig.ts
@@ -13,7 +13,7 @@ import {
} from '../interfaces'
import { DefaultToolOutputProcessor } from '../safety/toolOutputProcessor'
import type { SpilloverStorage } from '../spillover'
-import { ChatMessage, Conversation, PendingApproval, ToolDefinition } from '../types'
+import { Attachment, ChatMessage, Conversation, PendingApproval, ToolDefinition } from '../types'
/**
* Configuration for the tool-use loop.
@@ -62,6 +62,8 @@ export interface LoopConfig {
// Limits
maxIterations: number
+ /** Retain trusted artifacts at tool completion and loop exit; consumers deduplicate. */
+ onAttachments?: (attachments: Attachment[]) => void
toolTimeout: number // ms per tool execution
toolProgressInterval: number // ms between tool_progress snapshots; 0 disables streaming
diff --git a/mcp-host/src/core/orchestration/toolExecutionTimeout.ts b/mcp-host/src/core/orchestration/toolExecutionTimeout.ts
new file mode 100644
index 000000000..46503f23d
--- /dev/null
+++ b/mcp-host/src/core/orchestration/toolExecutionTimeout.ts
@@ -0,0 +1,61 @@
+import { ToolError, ToolErrorCode } from '../errors'
+import type { ExecutionContext, Tool } from '../interfaces'
+import type { ToolOutput } from '../types'
+
+/** Separate the execution deadline from bounded termination/result collection. */
+export async function executeWithTimeout(
+ tool: Tool,
+ params: Record<string, unknown>,
+ context: ExecutionContext,
+ timeoutMs: number,
+ parentSignal?: AbortSignal
+): Promise<ToolOutput> {
+ const cleanupMs = tool.timeoutCleanupMs?.() ?? 0
+ if (
+ !Number.isSafeInteger(timeoutMs) ||
+ timeoutMs <= 0 ||
+ !Number.isSafeInteger(cleanupMs) ||
+ cleanupMs < 0 ||
+ timeoutMs + cleanupMs > 2_147_483_647
+ ) {
+ throw new Error('Invalid tool execution or cleanup timeout')
+ }
+ parentSignal?.throwIfAborted()
+ const controller = new AbortController()
+ let executionTimer: ReturnType<typeof setTimeout> | undefined
+ let cleanupTimer: ReturnType<typeof setTimeout> | undefined
+ let stopped = false
+ let stop: (reason: unknown) => void
+ const deadline = new Promise<never>((_, reject) => {
+ stop = reason => {
+ if (stopped) return
+ stopped = true
+ controller.abort(reason)
+ if (cleanupMs === 0) reject(reason)
+ else cleanupTimer = setTimeout(() => reject(reason), cleanupMs)
+ }
+ executionTimer = setTimeout(
+ () =>
+ stop(
+ new ToolError(
+ `Tool ${tool.name()} timed out after ${timeoutMs}ms`,
+ tool.name(),
+ ToolErrorCode.Timeout
+ )
+ ),
+ timeoutMs
+ )
+ })
+ const onAbort = () => stop(parentSignal?.reason ?? new Error('Tool execution aborted'))
+ parentSignal?.addEventListener('abort', onAbort, { once: true })
+ try {
+ return await Promise.race([
+ tool.execute(params, { ...context, timeoutMs, signal: controller.signal }),
+ deadline,
+ ])
+ } finally {
+ clearTimeout(executionTimer)
+ clearTimeout(cleanupTimer)
+ parentSignal?.removeEventListener('abort', onAbort)
+ }
+}
diff --git a/mcp-host/src/core/orchestration/toolUseLoop.ts b/mcp-host/src/core/orchestration/toolUseLoop.ts
index e31190f90..605802bad 100644
--- a/mcp-host/src/core/orchestration/toolUseLoop.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoop.ts
@@ -90,358 +90,365 @@ export async function runToolUseLoop(
'Loop started'
)
- for (let iteration = 0; iteration < maxIterations; iteration++) {
- if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
-
- // P2 token budgets (§5.2) — per-task emergency brake. Local, no network:
- // compares THIS task's token delta (current counters − the start-of-task
- // baseline) against the cap from the P1 verdict and exits BEFORE the next
- // LLM call (never interrupts a call in flight). On iteration 0 the delta is
- // 0, so the first call always proceeds. No-op when no cap is configured.
- if (config.taskBrake) {
- const trip = evaluateTaskBrake(config.taskBrake, config.conversation)
- if (trip) return taskBrakeResult(config, iteration, trip, collectedAttachments)
- }
+ try {
+ for (let iteration = 0; iteration < maxIterations; iteration++) {
+ if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
- config.events.emit({
- type: 'loop:iteration',
- data: { iteration, messageCount: messages.length },
- timestamp: new Date(),
- })
+ // P2 token budgets (§5.2) — per-task emergency brake. Local, no network:
+ // compares THIS task's token delta (current counters − the start-of-task
+ // baseline) against the cap from the P1 verdict and exits BEFORE the next
+ // LLM call (never interrupts a call in flight). On iteration 0 the delta is
+ // 0, so the first call always proceeds. No-op when no cap is configured.
+ if (config.taskBrake) {
+ const trip = evaluateTaskBrake(config.taskBrake, config.conversation)
+ if (trip) return taskBrakeResult(config, iteration, trip, collectedAttachments)
+ }
- messages = await manageMessagesForIteration(config, messages, iteration, true)
+ config.events.emit({
+ type: 'loop:iteration',
+ data: { iteration, messageCount: messages.length },
+ timestamp: new Date(),
+ })
- let tools: ToolDefinition[]
- try {
- tools = await loopController.refreshTools(toolRegistry.listDefinitions())
- } catch (error) {
- if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
- // Presentation failures must not dump the entire local catalog into the
- // model request or bypass the controller's approved tool selection.
- return {
- type: 'error',
- error: error instanceof Error ? error : new Error('Tool presentation failed'),
+ messages = await manageMessagesForIteration(config, messages, iteration, true)
+
+ let tools: ToolDefinition[]
+ try {
+ tools = await loopController.refreshTools(toolRegistry.listDefinitions())
+ } catch (error) {
+ if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
+ // Presentation failures must not dump the entire local catalog into the
+ // model request or bypass the controller's approved tool selection.
+ return {
+ type: 'error',
+ error: error instanceof Error ? error : new Error('Tool presentation failed'),
+ }
}
- }
- const context: ReasoningContext = {
- messages,
- available_tools: tools,
- job_description: jobDescription,
- signal: config.abortSignal,
- }
+ const context: ReasoningContext = {
+ messages,
+ available_tools: tools,
+ job_description: jobDescription,
+ signal: config.abortSignal,
+ }
- const { result, continuingFromToolResults } = await callReasoningForIteration(
- config,
- context,
- lastToolResults,
- iteration
- )
- if (continuingFromToolResults) lastToolResults = null
- if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
+ const { result, continuingFromToolResults } = await callReasoningForIteration(
+ config,
+ context,
+ lastToolResults,
+ iteration
+ )
+ if (continuingFromToolResults) lastToolResults = null
+ if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
- switch (result.type) {
- case 'text': {
- if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
+ switch (result.type) {
+ case 'text': {
+ if (config.abortSignal?.aborted) return { type: 'cancelled', reason: 'signal_aborted' }
- const workflowListFallback = continuingFromToolResults
- ? buildWorkflowListFallbackWhenResponseOmitsNames(
- result.content,
- lastCompletedToolResultsForFallback
+ const workflowListFallback = continuingFromToolResults
+ ? buildWorkflowListFallbackWhenResponseOmitsNames(
+ result.content,
+ lastCompletedToolResultsForFallback
+ )
+ : null
+ if (workflowListFallback) {
+ return responseResult(
+ config,
+ iteration,
+ workflowListFallback,
+ totalUsage,
+ collectedAttachments,
+ `[NewCore:Loop] EXIT → workflow_list deterministic fallback, iterations=${iteration + 1}`
)
- : null
- if (workflowListFallback) {
- return responseResult(
- config,
- iteration,
- workflowListFallback,
- totalUsage,
- collectedAttachments,
- `[NewCore:Loop] EXIT → workflow_list deterministic fallback, iterations=${iteration + 1}`
- )
- }
+ }
+
+ const workflowTriggerNonRunFallback = continuingFromToolResults
+ ? buildWorkflowTriggerNonRunFallbackWhenResponseOmitsClarification(
+ result.content,
+ lastCompletedToolResultsForFallback
+ )
+ : null
+ if (workflowTriggerNonRunFallback) {
+ return responseResult(
+ config,
+ iteration,
+ workflowTriggerNonRunFallback,
+ totalUsage,
+ collectedAttachments,
+ `[NewCore:Loop] EXIT → workflow_trigger non-run deterministic fallback, iterations=${iteration + 1}`
+ )
+ }
+
+ const completedWorkflowListThisTurn =
+ Array.isArray(lastCompletedToolResultsForFallback) &&
+ lastCompletedToolResultsForFallback.some(result => result.name === 'workflow_list')
+ if (
+ continuingFromToolResults &&
+ !workflowTriggerAfterListTextResponseRecovered &&
+ !hasWorkflowTriggerResultForCurrentUserTurn(messages) &&
+ completedWorkflowListThisTurn &&
+ shouldRecoverWorkflowTriggerTextResponse(userRequestText, result.content)
+ ) {
+ workflowTriggerAfterListTextResponseRecovered = true
+ logger.info(
+ { component: 'Loop', iteration },
+ 'recovering workflow trigger text response after workflow_list'
+ )
+ messages.push({ role: 'assistant', content: result.content })
+ messages.push({
+ role: 'user',
+ content:
+ 'The previous assistant response listed or described workflows but did not trigger the requested workflow. The user asked to run a named workflow recipe and provided any business inputs in the original message. Call workflow_trigger for that workflow with those inputs when it is available, or use workflow tools to prove it is not available. Do not only summarize workflow_list.',
+ })
+ continue
+ }
- const workflowTriggerNonRunFallback = continuingFromToolResults
- ? buildWorkflowTriggerNonRunFallbackWhenResponseOmitsClarification(
+ if (
+ !continuingFromToolResults &&
+ !emptyResponseAfterToolResultsRecovered &&
+ !emptyInitialResponseRecovered &&
+ !workflowListTextResponseRecovered &&
+ isWorkflowListIntent(userRequestText) &&
+ tools.some(tool => tool.name === 'workflow_list') &&
+ !hasToolResultForCurrentUserTurn(messages) &&
+ !hasWorkflowListResultForCurrentUserTurn(messages)
+ ) {
+ workflowListTextResponseRecovered = true
+ logger.info(
+ { component: 'Loop', iteration },
+ 'recovering workflow list text response without tool call'
+ )
+ messages.push({ role: 'assistant', content: result.content })
+ messages.push({
+ role: 'user',
+ content:
+ 'The previous assistant response answered a workflow recipe list request without calling workflow_list. Use workflow_list now and answer only from its current results. Do not reuse prior conversation workflow names.',
+ })
+ continue
+ }
+
+ if (
+ !continuingFromToolResults &&
+ !workflowTriggerTextResponseRecovered &&
+ !hasWorkflowTriggerResultForCurrentUserTurn(messages) &&
+ shouldRecoverWorkflowTriggerTextResponse(userRequestText, result.content)
+ ) {
+ workflowTriggerTextResponseRecovered = true
+ logger.info(
+ { component: 'Loop', iteration },
+ 'recovering workflow trigger text response without tool call'
+ )
+ messages.push({ role: 'assistant', content: result.content })
+ messages.push({
+ role: 'user',
+ content:
+ 'The previous assistant response did not trigger the requested workflow. The user asked to trigger a workflow recipe by name. Use workflow_trigger for the requested workflow and target when it is available, or use the workflow tools to prove that it is not available. Do not create or report a workflow run without workflow_trigger.',
+ })
+ continue
+ }
+
+ if (
+ !continuingFromToolResults &&
+ !workflowArtifactTextResponseRecovered &&
+ shouldRecoverWorkflowArtifactTextResponse(userRequestText)
+ ) {
+ workflowArtifactTextResponseRecovered = true
+ logger.info(
+ { component: 'Loop', iteration },
+ 'recovering workflow artifact text response without tool call'
+ )
+ messages.push({ role: 'assistant', content: result.content })
+ messages.push({
+ role: 'user',
+ content:
+ 'The previous assistant response did not retrieve the requested workflow result artifact. The user asked for an existing workflow result artifact by name. Use workflow_result for the named workflow, or use the workflow tools to prove that it is unavailable. Do not invent artifact URLs, proof values, or run outputs.',
+ })
+ continue
+ }
+
+ if (loopController.shouldAccept(result.content, iteration)) {
+ return responseResult(
+ config,
+ iteration,
result.content,
- lastCompletedToolResultsForFallback
+ totalUsage,
+ collectedAttachments,
+ `[NewCore:Loop] EXIT → response (text, ${result.content.length} chars), iterations=${iteration + 1}`
)
- : null
- if (workflowTriggerNonRunFallback) {
- return responseResult(
- config,
- iteration,
- workflowTriggerNonRunFallback,
- totalUsage,
- collectedAttachments,
- `[NewCore:Loop] EXIT → workflow_trigger non-run deterministic fallback, iterations=${iteration + 1}`
- )
- }
+ }
- const completedWorkflowListThisTurn =
- Array.isArray(lastCompletedToolResultsForFallback) &&
- lastCompletedToolResultsForFallback.some(result => result.name === 'workflow_list')
- if (
- continuingFromToolResults &&
- !workflowTriggerAfterListTextResponseRecovered &&
- !hasWorkflowTriggerResultForCurrentUserTurn(messages) &&
- completedWorkflowListThisTurn &&
- shouldRecoverWorkflowTriggerTextResponse(userRequestText, result.content)
- ) {
- workflowTriggerAfterListTextResponseRecovered = true
- logger.info(
- { component: 'Loop', iteration },
- 'recovering workflow trigger text response after workflow_list'
- )
- messages.push({ role: 'assistant', content: result.content })
- messages.push({
- role: 'user',
- content:
- 'The previous assistant response listed or described workflows but did not trigger the requested workflow. The user asked to run a named workflow recipe and provided any business inputs in the original message. Call workflow_trigger for that workflow with those inputs when it is available, or use workflow tools to prove it is not available. Do not only summarize workflow_list.',
- })
+ const nudgeMsg = loopController.onTextRejected(result.content, iteration)
+ if (nudgeMsg) messages.push({ role: 'assistant', content: result.content }, nudgeMsg)
continue
}
- if (
- !continuingFromToolResults &&
- !emptyResponseAfterToolResultsRecovered &&
- !emptyInitialResponseRecovered &&
- !workflowListTextResponseRecovered &&
- isWorkflowListIntent(userRequestText) &&
- tools.some(tool => tool.name === 'workflow_list') &&
- !hasToolResultForCurrentUserTurn(messages) &&
- !hasWorkflowListResultForCurrentUserTurn(messages)
- ) {
- workflowListTextResponseRecovered = true
- logger.info(
- { component: 'Loop', iteration },
- 'recovering workflow list text response without tool call'
- )
- messages.push({ role: 'assistant', content: result.content })
- messages.push({
- role: 'user',
- content:
- 'The previous assistant response answered a workflow recipe list request without calling workflow_list. Use workflow_list now and answer only from its current results. Do not reuse prior conversation workflow names.',
- })
- continue
- }
+ case 'tool_calls': {
+ const toolNames = result.calls.map(c => c.name)
+ logger.info({ component: 'Loop', iteration, toolNames }, 'Tool calls selected')
- if (
- !continuingFromToolResults &&
- !workflowTriggerTextResponseRecovered &&
- !hasWorkflowTriggerResultForCurrentUserTurn(messages) &&
- shouldRecoverWorkflowTriggerTextResponse(userRequestText, result.content)
- ) {
- workflowTriggerTextResponseRecovered = true
- logger.info(
- { component: 'Loop', iteration },
- 'recovering workflow trigger text response without tool call'
- )
- messages.push({ role: 'assistant', content: result.content })
- messages.push({
- role: 'user',
- content:
- 'The previous assistant response did not trigger the requested workflow. The user asked to trigger a workflow recipe by name. Use workflow_trigger for the requested workflow and target when it is available, or use the workflow tools to prove that it is not available. Do not create or report a workflow run without workflow_trigger.',
- })
- continue
- }
+ if (
+ isWorkflowListIntent(userRequestText) &&
+ result.calls.some(call => call.name === 'workflow_trigger')
+ ) {
+ const workflowListFallback = buildWorkflowToolSuccessFallbackResponse(
+ lastCompletedToolResultsForFallback
+ )
+ if (workflowListFallback) {
+ return responseResult(
+ config,
+ iteration,
+ workflowListFallback,
+ totalUsage,
+ collectedAttachments,
+ `[NewCore:Loop] EXIT → workflow_list deterministic fallback before mistaken trigger, iterations=${iteration + 1}`
+ )
+ }
+
+ messages.push({
+ role: 'user',
+ content:
+ 'The user asked to list workflow recipes, not trigger one. Do not call workflow_trigger for workflow availability questions. Use workflow_list and answer only from its results.',
+ })
+ continue
+ }
+
+ if (
+ !workflowArtifactIntentRecovered &&
+ isWorkflowArtifactIntent(userRequestText) &&
+ result.calls.some(call => call.name === 'workflow_trigger')
+ ) {
+ workflowArtifactIntentRecovered = true
+ messages.push({
+ role: 'user',
+ content:
+ 'The previous tool choice would trigger a workflow, but the user asked for an existing workflow result artifact. Do not call workflow_trigger for result, artifact, output, or download requests. Use workflow_result for the named workflow.',
+ })
+ continue
+ }
- if (
- !continuingFromToolResults &&
- !workflowArtifactTextResponseRecovered &&
- shouldRecoverWorkflowArtifactTextResponse(userRequestText)
- ) {
- workflowArtifactTextResponseRecovered = true
- logger.info(
- { component: 'Loop', iteration },
- 'recovering workflow artifact text response without tool call'
- )
- messages.push({ role: 'assistant', content: result.content })
messages.push({
- role: 'user',
- content:
- 'The previous assistant response did not retrieve the requested workflow result artifact. The user asked for an existing workflow result artifact by name. Use workflow_result for the named workflow, or use the workflow tools to prove that it is unavailable. Do not invent artifact URLs, proof values, or run outputs.',
+ role: 'assistant',
+ content: result.content ?? '',
+ tool_calls: result.calls,
})
- continue
- }
- if (loopController.shouldAccept(result.content, iteration)) {
- return responseResult(
+ const { toolResults, pendingApproval, cancelled } = await executeToolCalls(
+ result.calls,
config,
iteration,
+ messages,
result.content,
- totalUsage,
- collectedAttachments,
- `[NewCore:Loop] EXIT → response (text, ${result.content.length} chars), iterations=${iteration + 1}`
+ result.usage
)
- }
+ if (cancelled) {
+ appendToolResults(messages, toolResults, collectedAttachments)
+ return { type: 'cancelled', reason: 'signal_aborted' }
+ }
+ if (pendingApproval) {
+ if (collectedAttachments.length > 0) {
+ pendingApproval.attachments = [
+ ...(pendingApproval.attachments ?? []),
+ ...collectedAttachments,
+ ]
+ }
+ return { type: 'need_approval', approval: pendingApproval }
+ }
- const nudgeMsg = loopController.onTextRejected(result.content, iteration)
- if (nudgeMsg) messages.push({ role: 'assistant', content: result.content }, nudgeMsg)
- continue
- }
+ const workflowFallbackResults = toolResults.filter(
+ tr => tr.is_error !== true && isWorkflowSuccessFallbackToolName(tr.name)
+ )
+ if (workflowFallbackResults.length > 0) {
+ lastCompletedToolResultsForFallback = workflowFallbackResults
+ }
- case 'tool_calls': {
- const toolNames = result.calls.map(c => c.name)
- logger.info({ component: 'Loop', iteration, toolNames }, 'Tool calls selected')
+ const workflowTriggerImmediateFallback =
+ buildWorkflowTriggerImmediateFallbackResponse(toolResults)
+ if (workflowTriggerImmediateFallback) {
+ return responseResult(
+ config,
+ iteration,
+ workflowTriggerImmediateFallback,
+ totalUsage,
+ collectedAttachments,
+ `[NewCore:Loop] EXIT → workflow_trigger deterministic fallback, iterations=${iteration + 1}`
+ )
+ }
- if (
- isWorkflowListIntent(userRequestText) &&
- result.calls.some(call => call.name === 'workflow_trigger')
- ) {
- const workflowListFallback = buildWorkflowToolSuccessFallbackResponse(
- lastCompletedToolResultsForFallback
- )
- if (workflowListFallback) {
+ const workflowToolFailureResponse = buildWorkflowToolFailureResponse(toolResults)
+ if (workflowToolFailureResponse) {
return responseResult(
config,
iteration,
- workflowListFallback,
+ workflowToolFailureResponse,
totalUsage,
collectedAttachments,
- `[NewCore:Loop] EXIT → workflow_list deterministic fallback before mistaken trigger, iterations=${iteration + 1}`
+ `[NewCore:Loop] EXIT → workflow tool failure response, iterations=${iteration + 1}`
)
}
- messages.push({
- role: 'user',
- content:
- 'The user asked to list workflow recipes, not trigger one. Do not call workflow_trigger for workflow availability questions. Use workflow_list and answer only from its results.',
- })
+ appendToolResults(messages, toolResults, collectedAttachments)
+ lastToolResults = toolResults
+ messages = await manageMessagesForIteration(config, messages, iteration)
+ validateToolLinkages(messages)
continue
}
- if (
- !workflowArtifactIntentRecovered &&
- isWorkflowArtifactIntent(userRequestText) &&
- result.calls.some(call => call.name === 'workflow_trigger')
- ) {
- workflowArtifactIntentRecovered = true
- messages.push({
- role: 'user',
- content:
- 'The previous tool choice would trigger a workflow, but the user asked for an existing workflow result artifact. Do not call workflow_trigger for result, artifact, output, or download requests. Use workflow_result for the named workflow.',
+ case 'need_approval':
+ logger.info({ component: 'Loop', iterations: iteration + 1 }, 'Loop requires approval')
+ return { type: 'need_approval', approval: result.approval }
+ case 'error': {
+ const recovery = handleLoopErrorRecovery({
+ error: result.error,
+ continuingFromToolResults,
+ emptyResponseAfterToolResultsRecovered,
+ emptyInitialResponseRecovered,
+ workflowTriggerTextResponseRecovered,
+ lastCompletedToolResultsForFallback,
+ messages,
+ iteration,
+ userRequestText,
})
- continue
- }
- messages.push({
- role: 'assistant',
- content: result.content ?? '',
- tool_calls: result.calls,
- })
-
- const { toolResults, pendingApproval, cancelled } = await executeToolCalls(
- result.calls,
- config,
- iteration,
- messages,
- result.content,
- result.usage
- )
- if (cancelled) return { type: 'cancelled', reason: 'signal_aborted' }
- if (pendingApproval) {
- if (collectedAttachments.length > 0) {
- pendingApproval.attachments = [
- ...(pendingApproval.attachments ?? []),
- ...collectedAttachments,
- ]
+ if (recovery.type === 'continue') {
+ emptyResponseAfterToolResultsRecovered =
+ recovery.emptyResponseAfterToolResultsRecovered ??
+ emptyResponseAfterToolResultsRecovered
+ emptyInitialResponseRecovered =
+ recovery.emptyInitialResponseRecovered ?? emptyInitialResponseRecovered
+ workflowTriggerTextResponseRecovered =
+ recovery.workflowTriggerTextResponseRecovered ?? workflowTriggerTextResponseRecovered
+ messages = recovery.messages
+ logger.info({ component: 'Loop', iteration }, 'recovering from LLM error')
+ continue
}
- return { type: 'need_approval', approval: pendingApproval }
- }
-
- const workflowFallbackResults = toolResults.filter(
- tr => tr.is_error !== true && isWorkflowSuccessFallbackToolName(tr.name)
- )
- if (workflowFallbackResults.length > 0) {
- lastCompletedToolResultsForFallback = workflowFallbackResults
- }
- const workflowTriggerImmediateFallback =
- buildWorkflowTriggerImmediateFallbackResponse(toolResults)
- if (workflowTriggerImmediateFallback) {
- return responseResult(
- config,
- iteration,
- workflowTriggerImmediateFallback,
- totalUsage,
- collectedAttachments,
- `[NewCore:Loop] EXIT → workflow_trigger deterministic fallback, iterations=${iteration + 1}`
- )
- }
-
- const workflowToolFailureResponse = buildWorkflowToolFailureResponse(toolResults)
- if (workflowToolFailureResponse) {
- return responseResult(
- config,
- iteration,
- workflowToolFailureResponse,
- totalUsage,
- collectedAttachments,
- `[NewCore:Loop] EXIT → workflow tool failure response, iterations=${iteration + 1}`
- )
- }
-
- appendToolResults(messages, toolResults, collectedAttachments)
- lastToolResults = toolResults
- messages = await manageMessagesForIteration(config, messages, iteration)
- validateToolLinkages(messages)
- continue
- }
-
- case 'need_approval':
- logger.info({ component: 'Loop', iterations: iteration + 1 }, 'Loop requires approval')
- return { type: 'need_approval', approval: result.approval }
- case 'error': {
- const recovery = handleLoopErrorRecovery({
- error: result.error,
- continuingFromToolResults,
- emptyResponseAfterToolResultsRecovered,
- emptyInitialResponseRecovered,
- workflowTriggerTextResponseRecovered,
- lastCompletedToolResultsForFallback,
- messages,
- iteration,
- userRequestText,
- })
-
- if (recovery.type === 'continue') {
- emptyResponseAfterToolResultsRecovered =
- recovery.emptyResponseAfterToolResultsRecovered ??
- emptyResponseAfterToolResultsRecovered
- emptyInitialResponseRecovered =
- recovery.emptyInitialResponseRecovered ?? emptyInitialResponseRecovered
- workflowTriggerTextResponseRecovered =
- recovery.workflowTriggerTextResponseRecovered ?? workflowTriggerTextResponseRecovered
- messages = recovery.messages
- logger.info({ component: 'Loop', iteration }, 'recovering from LLM error')
- continue
- }
+ if (recovery.type === 'response') {
+ return responseResult(
+ config,
+ iteration,
+ recovery.content,
+ totalUsage,
+ collectedAttachments,
+ recovery.logMessage
+ )
+ }
- if (recovery.type === 'response') {
- return responseResult(
- config,
- iteration,
- recovery.content,
- totalUsage,
- collectedAttachments,
- recovery.logMessage
+ logger.error(
+ { component: 'Loop', iterations: iteration + 1, err: result.error },
+ 'Loop failed'
)
+ return { type: 'error', error: result.error }
}
-
- logger.error(
- { component: 'Loop', iterations: iteration + 1, err: result.error },
- 'Loop failed'
- )
- return { type: 'error', error: result.error }
}
}
- }
- return exhaustionResult(
- config,
- maxIterations,
- loopController.onExhaustion(maxIterations),
- collectedAttachments
- )
+ return exhaustionResult(
+ config,
+ maxIterations,
+ loopController.onExhaustion(maxIterations),
+ collectedAttachments
+ )
+ } finally {
+ config.onAttachments?.(collectedAttachments)
+ }
}
diff --git a/mcp-host/src/core/orchestration/toolUseLoopMessages.ts b/mcp-host/src/core/orchestration/toolUseLoopMessages.ts
index bed917236..4ddf20ece 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopMessages.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopMessages.ts
@@ -36,6 +36,31 @@ function appendCollectedAttachment(
return true
}
+/** Reuse the same provenance and deduplication rules for interrupted work. */
+export function collectToolAttachments(
+ results: ToolResult[],
+ collected: Attachment[]
+): Attachment[] {
+ const added: Attachment[] = []
+ for (const result of results) {
+ for (const attachment of result.attachments ?? []) {
+ if (
+ shouldCollectAttachment(result, attachment) &&
+ appendCollectedAttachment(collected, attachment)
+ )
+ added.push(attachment)
+ }
+ }
+ return added
+}
+
+export function mergeCollectedAttachments(
+ collected: Attachment[],
+ attachments: Attachment[]
+): void {
+ for (const attachment of attachments) appendCollectedAttachment(collected, attachment)
+}
+
export function appendToolResults(
messages: ChatMessage[],
toolResults: ToolResult[],
@@ -43,10 +68,9 @@ export function appendToolResults(
): void {
const pendingImages: MessageContentPart[] = []
for (const tr of toolResults) {
- const trustedAttachments = tr.attachments?.filter(att => shouldCollectAttachment(tr, att)) ?? []
+ const trustedAttachments = collectToolAttachments([tr], collectedAttachments)
if (trustedAttachments.length) {
for (const att of trustedAttachments) {
- if (!appendCollectedAttachment(collectedAttachments, att)) continue
if (att.kind !== 'image') continue
if (att.mimeType !== 'image/jpeg' && att.mimeType !== 'image/png') continue
pendingImages.push({
diff --git a/mcp-host/src/core/orchestration/toolUseLoopRuntime.ts b/mcp-host/src/core/orchestration/toolUseLoopRuntime.ts
index 3e1d7fb61..2145831a6 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopRuntime.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopRuntime.ts
@@ -1,4 +1,5 @@
import type { TaskBrakeTrip } from '../../budget/taskBrake'
+import { logger } from '../../logger'
import { clerumCompactionTotal } from '../extensions/contextManager'
import type {
Attachment,
@@ -47,9 +48,7 @@ export async function manageMessagesForIteration(
const managed = await config.contextManager.manage(messages, config.conversation)
if (managed.length < beforeCount) {
if (logCompaction) {
- console.log(
- `[ContextManager] context:compacted — before=${beforeCount}, after=${managed.length}, dropped=${beforeCount - managed.length}, iter=${iteration}`
- )
+ logger.debug({ beforeCount, afterCount: managed.length, iteration }, 'Context compacted')
}
config.events.emit({
type: 'context:compacted',
@@ -89,12 +88,13 @@ export async function callReasoningForIteration(
const continuingFromToolResults = Boolean(lastToolResults)
const callReasoning = async (): Promise<RespondResult> => {
if (lastToolResults) {
- console.log(
- `[NewCore:Loop] iter=${iteration} → continueWithToolResults (${lastToolResults.length} results)`
+ logger.debug(
+ { iteration, resultCount: lastToolResults.length },
+ 'Continuing with tool results'
)
return config.reasoning.continueWithToolResults(context, lastToolResults)
}
- console.log(`[NewCore:Loop] iter=${iteration} → respondWithTools`)
+ logger.debug({ iteration }, 'Requesting model response')
return config.reasoning.respondWithTools(context)
}
@@ -104,9 +104,7 @@ export async function callReasoningForIteration(
isRetryableLlmTransportError(result.error) &&
!config.abortSignal?.aborted
) {
- console.log(
- `[NewCore:Loop] iter=${iteration} → retrying retryable LLM transport error once: ${result.error.message}`
- )
+ logger.warn({ iteration, err: result.error }, 'Retrying model transport failure')
await delay(LLM_TRANSPORT_RETRY_DELAY_MS, config.abortSignal)
if (!config.abortSignal?.aborted) {
result = await callReasoning()
@@ -150,7 +148,7 @@ export function responseResult(
attachments: Attachment[],
logMessage: string
): LoopResult {
- console.log(logMessage)
+ logger.debug({ message: logMessage }, 'Loop response')
config.events.emit({
type: 'loop:completed',
data: { iteration, resultType: 'response' },
@@ -187,8 +185,9 @@ export function taskBrakeResult(
trip: TaskBrakeTrip,
attachments: Attachment[]
): LoopResult {
- console.log(
- `[NewCore:Loop] EXIT → task budget brake (${trip.unit}: spent=${trip.spent} > limit=${trip.limit}), iterations=${iteration}`
+ logger.info(
+ { unit: trip.unit, spent: trip.spent, limit: trip.limit, iteration },
+ 'Task budget brake reached'
)
config.events.emit({
type: 'loop:completed',
@@ -197,6 +196,7 @@ export function taskBrakeResult(
})
return {
type: 'exhaustion',
+ reason: 'task_budget',
message: TASK_BUDGET_BRAKE_MESSAGE,
iterations: iteration,
attachments: attachments.length > 0 ? attachments : undefined,
@@ -209,7 +209,7 @@ export function exhaustionResult(
message: string,
attachments: Attachment[]
): LoopResult {
- console.log(`[NewCore:Loop] EXIT → exhaustion, iterations=${maxIterations}`)
+ logger.info({ iterations: maxIterations }, 'Loop iteration limit reached')
config.events.emit({
type: 'loop:completed',
data: { iteration: maxIterations, resultType: 'exhaustion' },
@@ -217,6 +217,7 @@ export function exhaustionResult(
})
return {
type: 'exhaustion',
+ reason: 'iteration_limit',
message,
iterations: maxIterations,
attachments: attachments.length > 0 ? attachments : undefined,
diff --git a/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts b/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts
index 97c77b6be..c0bfc2bc6 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopSingleTool.ts
@@ -1,14 +1,16 @@
+import { logger } from '../../logger'
import {
extractToolIntent,
getDisplayName,
sanitizeError,
} from '../../progress/intentExtraction.js'
import type { ToolCallTokens } from '../../progress/types.js'
-import { ToolError, ToolErrorCode } from '../errors'
+import { ToolError } from '../errors'
import type { ExecutionContext } from '../interfaces'
import { RingBuffer } from '../tools/ringBuffer'
import type { TokenUsage, ToolCall, ToolResult } from '../types'
import type { LoopConfig } from './loopConfig'
+import { executeWithTimeout } from './toolExecutionTimeout'
import { buildOutputPreview, extractInputPreview } from './toolUseLoopPreviews'
export async function executeSingleTool(
@@ -24,6 +26,7 @@ export async function executeSingleTool(
| 'toolProgressInterval'
| 'spilloverStorage'
| 'taskId'
+ | 'abortSignal'
>,
iteration?: number
): Promise<ToolResult> {
@@ -65,7 +68,7 @@ export async function executeSingleTool(
})
let ringBuffer: RingBuffer | null = null
- let executionContext: ExecutionContext | undefined
+ const executionContext: ExecutionContext = { onOutput: chunk => ringBuffer?.append(chunk) }
let watcherId: NodeJS.Timeout | null = null
const watcherStartedAt = Date.now()
@@ -83,7 +86,6 @@ export async function executeSingleTool(
if (wantsWatcher) {
ringBuffer = new RingBuffer(64 * 1024)
const buf = ringBuffer
- executionContext = { onOutput: (chunk: string) => buf.append(chunk) }
watcherId = setInterval(() => {
try {
const snapshot = buf.snapshot()
@@ -106,25 +108,16 @@ export async function executeSingleTool(
try {
const execStart = Date.now()
- const output = await Promise.race([
- tool.execute(call.arguments, executionContext),
- new Promise<never>((_, reject) =>
- setTimeout(
- () =>
- reject(
- new ToolError(
- `Tool ${call.name} timed out after ${toolTimeout}ms`,
- call.name,
- ToolErrorCode.Timeout
- )
- ),
- toolTimeout
- )
- ),
- ])
-
- console.log(
- `[NewCore:Loop] exec ${call.name} → ${Date.now() - execStart}ms, ${output.is_error ? 'error' : 'ok'}`
+ const output = await executeWithTimeout(
+ tool,
+ call.arguments,
+ executionContext,
+ toolTimeout,
+ config.abortSignal
+ )
+ logger.debug(
+ { toolName: call.name, durationMs: Date.now() - execStart, isError: output.is_error },
+ 'Tool execution finished'
)
let wrappedContent: string
@@ -204,9 +197,7 @@ export async function executeSingleTool(
} catch (err) {
// Spillover is an optimization; persistence failure must NOT lose the
// tool result. Log and fall through with the inline content.
- console.error(
- `[NewCore:Loop] spillover persist failed for ${call.name}: ${(err as Error).message}`
- )
+ logger.error({ toolName: call.name, err }, 'Spillover persistence failed')
}
}
@@ -224,7 +215,7 @@ export async function executeSingleTool(
const errorMessage =
err instanceof ToolError ? err.message : `Tool execution failed: ${(err as Error).message}`
- console.log(`[NewCore:Loop] exec ${call.name} → FAILED: ${errorMessage}`)
+ logger.error({ toolName: call.name, err }, 'Tool execution failed')
return {
tool_call_id: call.id,
diff --git a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
index 26052d950..2d143948e 100644
--- a/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
+++ b/mcp-host/src/core/orchestration/toolUseLoopToolBatch.ts
@@ -10,8 +10,16 @@ import {
recordDecision,
resolveToolIdentityFromRegistry,
} from '../guardrails'
-import type { ChatMessage, PendingApproval, TokenUsage, ToolCall, ToolResult } from '../types'
+import type {
+ Attachment,
+ ChatMessage,
+ PendingApproval,
+ TokenUsage,
+ ToolCall,
+ ToolResult,
+} from '../types'
import type { LoopConfig } from './loopConfig'
+import { collectToolAttachments } from './toolUseLoopMessages'
import { executeSingleTool, reportToolComplete, reportToolStart } from './toolUseLoopSingleTool'
import { isWorkflowTriggerNotFoundToolResult } from './toolUseLoopWorkflowTriggerFallbacks'
@@ -416,6 +424,12 @@ export async function executeToolCalls(
}
}
+ // Retain policy-processed output before a subsequent tool can throw.
+ if (config.onAttachments && toolResult.attachments?.length) {
+ const attachments: Attachment[] = []
+ collectToolAttachments([toolResult], attachments)
+ if (attachments.length) config.onAttachments(attachments)
+ }
if (config.abortSignal?.aborted) {
toolResults.push(toolResult)
return { toolResults, cancelled: true }
diff --git a/mcp-host/src/core/tools/__tests__/shellProcessCleanup.test.ts b/mcp-host/src/core/tools/__tests__/shellProcessCleanup.test.ts
new file mode 100644
index 000000000..b5dc047ad
--- /dev/null
+++ b/mcp-host/src/core/tools/__tests__/shellProcessCleanup.test.ts
@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import { PassThrough } from 'node:stream'
+import { ShellTool } from '../shell'
+
+vi.mock('child_process', () => ({ spawn: vi.fn() }))
+afterEach(() => {
+ vi.restoreAllMocks()
+ vi.useRealTimers()
+})
+describe('ShellTool process-group cleanup', () => {
+ it('terminates remaining group members before clearing escalation on leader close', async () => {
+ vi.useFakeTimers()
+ // Hermetic child/process-group model: no subprocess or signal is sent.
+ const child = Object.assign(new EventEmitter(), {
+ pid: 424242,
+ killed: false,
+ stdout: new PassThrough(),
+ stderr: new PassThrough(),
+ kill: vi.fn(),
+ })
+ vi.mocked(spawn).mockReturnValue(child as any)
+ const kill = vi.spyOn(process, 'kill').mockReturnValue(true)
+ const pending = new ShellTool('/tmp', 100, []).execute({ command: 'test command' })
+ child.stdout.write('partial output')
+ await vi.advanceTimersByTimeAsync(100)
+ expect(kill).toHaveBeenCalledWith(-424242, 'SIGTERM')
+ child.emit('close', null)
+ const result = await pending
+ expect(kill).toHaveBeenCalledWith(-424242, 'SIGKILL')
+ expect(result.content).toContain('partial output')
+ expect(vi.getTimerCount()).toBe(0)
+ child.stdout.destroy()
+ child.stderr.destroy()
+ })
+})
diff --git a/mcp-host/src/core/tools/shell.ts b/mcp-host/src/core/tools/shell.ts
index 97c9c6329..15cf3daf8 100644
--- a/mcp-host/src/core/tools/shell.ts
+++ b/mcp-host/src/core/tools/shell.ts
@@ -1,5 +1,6 @@
import { spawn } from 'child_process'
import { ALL_PROVIDERS, LlmProvider, PROVIDERS } from '../../llm/registryCore'
+import { ToolError, ToolErrorCode } from '../errors'
import { ExecutionContext, Tool } from '../interfaces'
import { ToolOutput } from '../types'
@@ -88,7 +89,14 @@ export class ShellTool implements Tool {
return true
}
+ timeoutCleanupMs(): number {
+ // Termination has an existing 5s SIGKILL grace; allow 1s for close/output delivery.
+ return ShellTool.SIGKILL_GRACE_MS + 1000
+ }
+
async execute(params: Record<string, unknown>, context?: ExecutionContext): Promise<ToolOutput> {
+ context?.signal?.throwIfAborted()
+ const timeout = Math.min(this.timeout, context?.timeoutMs ?? this.timeout)
const startTime = Date.now()
const command = params.command as string
@@ -150,8 +158,9 @@ export class ShellTool implements Tool {
const stdoutBuf: string[] = []
const stderrBuf: string[] = []
let totalBytes = 0
- let killed: 'timeout' | 'maxbuffer' | null = null
+ let killed: 'timeout' | 'maxbuffer' | 'cancelled' | null = null
let resolved = false
+ let killTimer: ReturnType<typeof setTimeout> | undefined
const resolveOnce = (out: ToolOutput) => {
if (resolved) return
@@ -176,7 +185,7 @@ export class ShellTool implements Tool {
} else {
child.kill('SIGTERM')
}
- const killTimer = setTimeout(() => {
+ killTimer = setTimeout(() => {
if (canGroupKill) {
try {
process.kill(-(pid as number), 'SIGKILL')
@@ -211,10 +220,37 @@ export class ShellTool implements Tool {
killed = 'timeout'
forceKill()
}
- }, this.timeout)
+ }, timeout)
- child.on('close', exitCode => {
+ const onAbort = () => {
+ if (!killed && !resolved) {
+ killed =
+ context?.signal?.reason instanceof ToolError &&
+ context.signal.reason.code === ToolErrorCode.Timeout
+ ? 'timeout'
+ : 'cancelled'
+ forceKill()
+ }
+ }
+ context?.signal?.addEventListener('abort', onAbort, { once: true })
+ if (context?.signal?.aborted) onAbort()
+ const cleanup = () => {
clearTimeout(timer)
+ clearTimeout(killTimer)
+ context?.signal?.removeEventListener('abort', onAbort)
+ }
+ child.on('close', exitCode => {
+ // Leader/stdio close does not prove descendants exited. Complete group
+ // termination now before dropping escalation, rather than leaving a
+ // delayed signal that could target a reused process-group identifier.
+ if (killed && typeof child.pid === 'number' && child.pid > 0) {
+ try {
+ process.kill(-child.pid, 'SIGKILL')
+ } catch {
+ /* Group already gone. */
+ }
+ }
+ cleanup()
const stdout = stdoutBuf.join('')
const stderr = stderrBuf.join('')
const body =
@@ -224,7 +260,15 @@ export class ShellTool implements Tool {
if (killed === 'timeout') {
resolveOnce({
- content: `${body}\n\n[Command killed after ${this.timeout}ms timeout — partial output above]`,
+ content: `${body}\n\n[Command killed after ${timeout}ms timeout — partial output above]`,
+ duration_ms: Date.now() - startTime,
+ is_error: true,
+ })
+ return
+ }
+ if (killed === 'cancelled') {
+ resolveOnce({
+ content: `${body}\n\n[Command cancelled — partial output above]`,
duration_ms: Date.now() - startTime,
is_error: true,
})
@@ -254,7 +298,7 @@ export class ShellTool implements Tool {
})
child.on('error', err => {
- clearTimeout(timer)
+ cleanup()
resolveOnce({
content: `Command failed to start: ${err.message}`,
duration_ms: Date.now() - startTime,
diff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.ts
index 8a9a60da0..25fd01aac 100644
--- a/mcp-host/src/core/types.ts
+++ b/mcp-host/src/core/types.ts
@@ -492,7 +492,19 @@ export interface TurnToolCall {
spillover_ref?: string
}
+export interface TaskExecutionBudgetSnapshot {
+ elapsedActiveMs: number
+ iterationsUsed: number
+ durationMs: number
+ maxIterations: number
+}
+
export interface PendingApproval {
+ task_budget?: TaskExecutionBudgetSnapshot
+ /** Set only by reconstruction of migration-marked legacy rows. */
+ legacy_budget?: boolean
+ /** Internal atomic replacement instruction; not persisted in the snapshot. */
+ replaces_request_id?: string
request_id: string
tool_name: string
/** Producer-owned governed replay classification; never inferred by Control UI. */
@@ -533,7 +545,13 @@ export type LoopResult =
| { type: 'response'; content: string; usage: TokenUsage; attachments?: Attachment[] }
| { type: 'need_approval'; approval: PendingApproval }
| { type: 'error'; error: Error }
- | { type: 'exhaustion'; message: string; iterations: number; attachments?: Attachment[] }
+ | {
+ type: 'exhaustion'
+ reason?: 'iteration_limit' | 'task_budget'
+ message: string
+ iterations: number
+ attachments?: Attachment[]
+ }
| { type: 'cancelled'; reason?: string }
export type AgentEventType =
diff --git a/mcp-host/src/db/migrations/014-pending-approval-task-budget.ts b/mcp-host/src/db/migrations/014-pending-approval-task-budget.ts
new file mode 100644
index 000000000..0fc91d11c
--- /dev/null
+++ b/mcp-host/src/db/migrations/014-pending-approval-task-budget.ts
@@ -0,0 +1,19 @@
+import type { Database } from 'better-sqlite3'
+
+export const name = '014-pending-approval-task-budget'
+function hasColumn(db: Database): boolean {
+ return (db.prepare('PRAGMA table_info(pending_approvals)').all() as Array<{ name: string }>).some(
+ row => row.name === 'task_budget'
+ )
+}
+export function up(db: Database): void {
+ if (!hasColumn(db)) {
+ // Only rows present at migration are eligible for explicit fresh-budget approval.
+ db.exec(
+ "ALTER TABLE pending_approvals ADD COLUMN task_budget TEXT; UPDATE pending_approvals SET task_budget = 'legacy';"
+ )
+ }
+}
+export function down(db: Database): void {
+ if (hasColumn(db)) db.exec('ALTER TABLE pending_approvals DROP COLUMN task_budget;')
+}
diff --git a/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts b/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
index 5d45ca4b7..f091bbced 100644
--- a/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
+++ b/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
@@ -75,6 +75,7 @@ describe('migration 008 — active trace context', () => {
'011-session-summary-user-activity-index',
'012-session-ownership-backfill',
'013-pending-approval-connect',
+ '014-pending-approval-task-budget',
],
pending: [],
})
diff --git a/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts b/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts
new file mode 100644
index 000000000..ba2adea50
--- /dev/null
+++ b/mcp-host/src/db/migrations/__tests__/014-pending-approval-task-budget.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import Database from 'better-sqlite3'
+import * as migration from '../014-pending-approval-task-budget'
+import { reconstructPendingApproval } from '../../../core/conversation/persistence/reconstruct'
+import { createDispatcher, dispatch } from '../../worker/dispatcher'
+import type { PendingApprovalRow } from '../../worker/protocol'
+import { migrations } from '../index'
+
+function fixture() {
+ const db = new Database(':memory:')
+ for (const m of migrations) {
+ if (m.name === migration.name) break
+ m.up(db)
+ }
+ db.prepare(
+ "INSERT INTO sessions(id,session_key,source,started_at,state,active_task_id) VALUES ('s','u:rpc:a:c','rpc',0,'awaiting_approval','task')"
+ ).run()
+ db.prepare(
+ `INSERT INTO pending_approvals(request_id,session_id,task_id,tool_name,tool_call_id,parameters,description,context_snapshot,source_message,registered_at,expires_at)
+ VALUES ('old','s','task','test','tc','{}','confirm','[]','{"content":"work"}',0,9999999999)`
+ ).run()
+ migration.up(db)
+ return db
+}
+describe('durable task budget migration and renewal', () => {
+ it('marks old rows once, preserves new budgets on repeated migration, and supports rollback', () => {
+ const db = fixture()
+ try {
+ const row = db.prepare('SELECT * FROM pending_approvals').get() as PendingApprovalRow
+ expect(reconstructPendingApproval(row).legacy_budget).toBe(true)
+ db.prepare('UPDATE pending_approvals SET task_budget=?').run(
+ JSON.stringify({
+ elapsedActiveMs: 10,
+ iterationsUsed: 1,
+ durationMs: 100,
+ maxIterations: 3,
+ })
+ )
+ migration.up(db)
+ expect(
+ reconstructPendingApproval(
+ db.prepare('SELECT * FROM pending_approvals').get() as PendingApprovalRow
+ ).task_budget?.iterationsUsed
+ ).toBe(1)
+ migration.down(db)
+ expect(
+ (db.prepare('PRAGMA table_info(pending_approvals)').all() as Array<{ name: string }>).some(
+ c => c.name === 'task_budget'
+ )
+ ).toBe(false)
+ } finally {
+ db.close()
+ }
+ })
+ it('atomically replaces a legacy approval, retaining old state if insertion fails', async () => {
+ const db = fixture()
+ try {
+ const deps = createDispatcher(db)
+ const old = db.prepare('SELECT * FROM pending_approvals').get() as PendingApprovalRow
+ const budget = { elapsedActiveMs: 0, iterationsUsed: 0, durationMs: 100, maxIterations: 3 }
+ const row = {
+ ...old,
+ request_id: 'new',
+ source_message: null,
+ task_budget: JSON.stringify(budget),
+ }
+ db.exec(
+ "CREATE TRIGGER reject_new BEFORE INSERT ON pending_approvals WHEN NEW.request_id='new' BEGIN SELECT RAISE(ABORT,'test failure'); END;"
+ )
+ await expect(
+ dispatch({ kind: 'insert_pending_approval', payload: row, replaceRequestId: 'old' }, deps)
+ ).rejects.toThrow('test failure')
+ expect(db.prepare('SELECT request_id FROM pending_approvals').get()).toEqual({
+ request_id: 'old',
+ })
+ db.exec('DROP TRIGGER reject_new')
+ await dispatch(
+ { kind: 'insert_pending_approval', payload: row, replaceRequestId: 'old' },
+ deps
+ )
+ const saved = db.prepare('SELECT * FROM pending_approvals').get() as PendingApprovalRow
+ expect(saved.request_id).toBe('new')
+ expect(saved.task_id).toBe('task')
+ expect(saved.source_message).toBe(old.source_message)
+ expect(reconstructPendingApproval(saved).task_budget).toEqual(budget)
+ expect(reconstructPendingApproval(saved).legacy_budget).toBe(false)
+ expect(db.prepare('SELECT state,active_task_id FROM sessions').get()).toEqual({
+ state: 'awaiting_approval',
+ active_task_id: 'task',
+ })
+ } finally {
+ db.close()
+ }
+ })
+ it.each(['', null, '{}', 'null'])(
+ 'rejects malformed or missing post-migration accounting: %s',
+ value => {
+ const db = fixture()
+ try {
+ const old = db.prepare('SELECT * FROM pending_approvals').get() as PendingApprovalRow
+ expect(() => reconstructPendingApproval({ ...old, task_budget: value })).toThrow()
+ } finally {
+ db.close()
+ }
+ }
+ )
+})
diff --git a/mcp-host/src/db/migrations/index.ts b/mcp-host/src/db/migrations/index.ts
index 5b788294e..22fae9d0a 100644
--- a/mcp-host/src/db/migrations/index.ts
+++ b/mcp-host/src/db/migrations/index.ts
@@ -11,6 +11,7 @@ import * as materializedSessionSummaries from './010-materialized-session-summar
import * as sessionSummaryUserActivityIndex from './011-session-summary-user-activity-index'
import * as sessionOwnershipBackfill from './012-session-ownership-backfill'
import * as pendingApprovalConnect from './013-pending-approval-connect'
+import * as pendingApprovalTaskBudget from './014-pending-approval-task-budget'
/**
* Ordered list of migrations. New migrations append; never reorder or rename.
@@ -35,4 +36,5 @@ export const migrations: Array<{
sessionSummaryUserActivityIndex,
sessionOwnershipBackfill,
pendingApprovalConnect,
+ pendingApprovalTaskBudget,
]
diff --git a/mcp-host/src/db/statements.ts b/mcp-host/src/db/statements.ts
index c025c6bcb..c1a70846c 100644
--- a/mcp-host/src/db/statements.ts
+++ b/mcp-host/src/db/statements.ts
@@ -409,15 +409,16 @@ export function prepareStatements(db: Database): PreparedStatements {
request_id, session_id, task_id, tool_name, tool_call_id,
parameters, description, context_snapshot, completed_results,
intent_summary, source_message, registered_at, expires_at, trace_context,
- reason, mcp_server_name
+ reason, mcp_server_name, task_budget
) VALUES (
@request_id, @session_id, @task_id, @tool_name, @tool_call_id,
@parameters, @description, @context_snapshot, @completed_results,
@intent_summary, @source_message, @registered_at, @expires_at, @trace_context,
- @reason, @mcp_server_name
+ @reason, @mcp_server_name, @task_budget
)
ON CONFLICT(request_id) DO UPDATE SET
task_id = excluded.task_id,
+ task_budget = excluded.task_budget,
context_snapshot = excluded.context_snapshot,
completed_results = excluded.completed_results,
trace_context = excluded.trace_context,
diff --git a/mcp-host/src/db/worker/dispatcher.ts b/mcp-host/src/db/worker/dispatcher.ts
index de6895de2..0c0e9ec21 100644
--- a/mcp-host/src/db/worker/dispatcher.ts
+++ b/mcp-host/src/db/worker/dispatcher.ts
@@ -574,7 +574,34 @@ export async function dispatch(op: WorkerOp, deps: DispatcherDeps): Promise<unkn
case 'insert_pending_approval':
return withBusyRetry(() => {
const tx = db.transaction((row: PendingApprovalRow) => {
- s.insertPendingApproval.run(row)
+ let sourceMessage = row.source_message
+ if (op.replaceRequestId) {
+ const previous = db
+ .prepare('SELECT * FROM pending_approvals WHERE request_id = ?')
+ .get(op.replaceRequestId) as PendingApprovalRow | undefined
+ if (
+ !previous ||
+ previous.session_id !== row.session_id ||
+ previous.task_id !== row.task_id ||
+ previous.task_budget !== 'legacy'
+ ) {
+ throw new Error('Approval renewal binding mismatch')
+ }
+ sourceMessage = previous.source_message
+ db.prepare('DELETE FROM pending_approvals WHERE request_id = ?').run(
+ op.replaceRequestId
+ )
+ }
+ s.insertPendingApproval.run({
+ ...row,
+ source_message: sourceMessage,
+ task_budget: row.task_budget ?? null,
+ })
+ if (op.markAwaitingApproval)
+ db.prepare('UPDATE sessions SET state = ? WHERE id = ?').run(
+ 'awaiting_approval',
+ row.session_id
+ )
})
tx.immediate(op.payload)
return { ok: true }
diff --git a/mcp-host/src/db/worker/protocol.ts b/mcp-host/src/db/worker/protocol.ts
index 63857137c..8c75a9bfa 100644
--- a/mcp-host/src/db/worker/protocol.ts
+++ b/mcp-host/src/db/worker/protocol.ts
@@ -82,6 +82,8 @@ export interface MessageRow {
}
export interface PendingApprovalRow {
+ /** Nullable for approvals created before migration 014. */
+ task_budget?: string | null
request_id: string
session_id: string
task_id: string
@@ -257,7 +259,12 @@ export type WorkerOp =
title?: string
}
| { kind: 'replace_messages'; sessionId: string; messages: MessageRow[] }
- | { kind: 'insert_pending_approval'; payload: PendingApprovalRow }
+ | {
+ kind: 'insert_pending_approval'
+ payload: PendingApprovalRow
+ replaceRequestId?: string
+ markAwaitingApproval?: boolean
+ }
| { kind: 'delete_pending_approval'; requestId: string }
| { kind: 'load_active_session'; sessionKey: string }
| {
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index ace4ce076..4693e547d 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -1758,6 +1758,7 @@ async function initializeAgent(): Promise<void> {
const maxConcurrent = parseInt(process.env.CLERUM_MAX_CONCURRENT_SESSIONS || '3', 10)
sessionProcessor = new SessionProcessor({
maxConcurrent,
+ taskDelayMs: config.agentTaskDelay,
executor: async (task: Task) => {
return agent!.executeTask(task)
},
diff --git a/mcp-host/src/mcp/requestOptions.ts b/mcp-host/src/mcp/requestOptions.ts
index 83fe9ed6b..013d8fa32 100644
--- a/mcp-host/src/mcp/requestOptions.ts
+++ b/mcp-host/src/mcp/requestOptions.ts
@@ -1,5 +1,5 @@
-const DEFAULT_MCP_TOOL_TIMEOUT_MS = 3_600_000
-const DEFAULT_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS = 3_600_000
+const DEFAULT_MCP_TOOL_TIMEOUT_MS = 1_500_000
+const DEFAULT_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS = 1_500_000
const MCP_TOOL_TIMEOUT_ENV = 'CLERUM_MCP_TOOL_TIMEOUT_MS'
const MCP_TOOL_MAX_TOTAL_TIMEOUT_ENV = 'CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS'
@@ -21,10 +21,10 @@ export interface McpSdkRequestOptions {
function readPositiveSafeIntegerEnv(name: string, defaultValue: number): number {
const raw = process.env[name]
- if (raw === undefined || raw === '') return defaultValue
+ if (raw === undefined) return defaultValue
if (!/^\d+$/.test(raw)) throw new Error(`${name} must be a positive safe integer`)
const value = Number.parseInt(raw, 10)
- if (!Number.isSafeInteger(value) || value < 1) {
+ if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647) {
throw new Error(`${name} must be a positive safe integer`)
}
return value
@@ -48,7 +48,11 @@ export function resolveMcpRequestTimeoutMs(callerTimeoutMs?: number): number {
)
}
if (callerTimeoutMs !== undefined) {
- if (!Number.isSafeInteger(callerTimeoutMs) || callerTimeoutMs < 1) {
+ if (
+ !Number.isSafeInteger(callerTimeoutMs) ||
+ callerTimeoutMs < 1 ||
+ callerTimeoutMs > 2_147_483_647
+ ) {
throw new Error('caller MCP timeout must be a positive safe integer')
}
return Math.min(configuredTimeoutMs, configuredMaxTotalTimeoutMs, callerTimeoutMs)
diff --git a/mcp-host/src/messageHandler.ts b/mcp-host/src/messageHandler.ts
index c29fd344a..7910568f6 100644
--- a/mcp-host/src/messageHandler.ts
+++ b/mcp-host/src/messageHandler.ts
@@ -2,6 +2,7 @@ import { AgentStateMachine } from './agent'
import { LlmErrorCode } from './core/errors'
import type { Attachment } from './core/types'
import type { TaskLifecycle } from './lifecycle/taskLifecycle'
+import { logger } from './logger'
import { MessageQueue, Task, TaskResponsePayload } from './queue'
import type { TaskError, TaskStatus } from './queue'
import { ResultStore } from './resultStore'
@@ -156,7 +157,7 @@ export class IncomingMessageHandler {
// SessionProcessor, so register here to satisfy Invariant I12.
this.deps.taskLifecycle.register(this.task)
}
- console.log(`[Main] Message queued as task ${this.task.id}`)
+ logger.info({ taskId: this.task.id }, 'Message queued')
// Dispatch to SessionProcessor if available
if (this.deps.sessionProcessor) {
@@ -199,10 +200,9 @@ export class IncomingMessageHandler {
this.task.responseCallback = async payload => {
const attachments = this.deps.sanitizeAttachments(payload.attachments)
const status: PendingTaskEntry['status'] = payload.error ? 'failed' : 'completed'
- console.log(
- `[Main] Storing async result for task ${this.task.id} (status=${status}, attachments=${
- attachments?.length ?? 0
- })`
+ logger.info(
+ { taskId: this.task.id, status, attachmentCount: attachments?.length ?? 0 },
+ 'Storing async result'
)
this.deps.pendingTaskResults.set(this.task.id, {
status,
@@ -224,7 +224,7 @@ export class IncomingMessageHandler {
const onApproval = (event: { data: unknown }) => {
const data = event.data as Record<string, unknown>
if (data.taskId !== this.task.id) return
- console.log(`[Main] Storing async approval notification for task ${this.task.id}`)
+ logger.info({ taskId: this.task.id }, 'Storing async approval notification')
this.deps.pendingTaskResults.set(this.task.id, {
status: 'waiting_approval',
model: this.deps.getModel(),
@@ -253,9 +253,9 @@ export class IncomingMessageHandler {
const onApprovalConsumed = (event: { data: unknown }) => {
const data = event.data as Record<string, unknown>
if (data.taskId !== this.task.id) return
- console.log(
- `[Main] Clearing stale approval entry for task ${this.task.id} ` +
- `(request: ${data.requestId})`
+ logger.info(
+ { taskId: this.task.id, requestId: data.requestId },
+ 'Clearing stale approval entry'
)
this.deps.pendingTaskResults.delete(this.task.id)
}
@@ -281,7 +281,7 @@ export class IncomingMessageHandler {
this.deps.messageQueue.on('task:failed', onFinalFailure)
}
- console.log(`[Main] Message queued as async task ${this.task.id}`)
+ logger.info({ taskId: this.task.id }, 'Message queued asynchronously')
// Dispatch to SessionProcessor if available
if (this.deps.sessionProcessor) {
@@ -320,10 +320,9 @@ export class IncomingMessageHandler {
priorStatus: TaskStatus
}): MessageResponse {
const { reason, priorTaskId, priorStatus } = admission
- console.warn(
- `[Main] duplicate delivery suppressed (${reason}) — message ` +
- `${this.message.channelType}:${this.message.channelId}:${this.message.messageId} ` +
- `is already task ${priorTaskId} (status=${priorStatus}); no new execution started`
+ logger.warn(
+ { taskId: this.task.id, reason, priorTaskId, priorStatus },
+ 'Duplicate delivery suppressed'
)
const record = this.deps.taskLifecycle.get(priorTaskId)
if (priorStatus === 'completed') {
@@ -394,6 +393,7 @@ export class IncomingMessageHandler {
this.resolve({
success: false,
error: payload.error,
+ ...(attachments?.length ? { attachments } : {}),
model: this.deps.getModel(),
})
} else {
@@ -406,7 +406,7 @@ export class IncomingMessageHandler {
})
}
} else {
- console.log(`[Main] Storing post-approval result for task ${this.task.id}`)
+ logger.info({ taskId: this.task.id }, 'Storing post-approval result')
// Compute the terminal status from the payload (parity with the sync
// branch above and executeAsync): a post-approval turn can FAIL, and
// hardcoding 'completed' here made the poll report success:false with
@@ -435,7 +435,7 @@ export class IncomingMessageHandler {
if (!this.resolved) {
this.resolved = true
- console.log(`[Main] Returning approval notification for task ${this.task.id}`)
+ logger.info({ taskId: this.task.id }, 'Returning approval notification')
this.resolve({
success: true,
status: 'waiting_approval',
@@ -449,8 +449,9 @@ export class IncomingMessageHandler {
model: this.deps.getModel(),
})
} else {
- console.log(
- `[Main] Storing approval notification for task ${this.task.id} (request: ${data.requestId})`
+ logger.info(
+ { taskId: this.task.id, requestId: data.requestId },
+ 'Storing approval notification'
)
this.deps.pendingTaskResults.set(this.task.id, {
status: 'waiting_approval',
@@ -480,9 +481,9 @@ export class IncomingMessageHandler {
this.onApprovalConsumed = (event: { data: unknown }) => {
const data = event.data as Record<string, unknown>
if (data.taskId !== this.task.id) return
- console.log(
- `[Main] Clearing stale approval entry for task ${this.task.id} ` +
- `(request: ${data.requestId})`
+ logger.info(
+ { taskId: this.task.id, requestId: data.requestId },
+ 'Clearing stale approval entry'
)
this.deps.pendingTaskResults.delete(this.task.id)
}
diff --git a/mcp-host/src/session/__tests__/budgetCheck.test.ts b/mcp-host/src/session/__tests__/budgetCheck.test.ts
index 971dc35ce..8096eb8b8 100644
--- a/mcp-host/src/session/__tests__/budgetCheck.test.ts
+++ b/mcp-host/src/session/__tests__/budgetCheck.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it, vi } from 'vitest'
import type { BudgetVerdict } from '../../budget/types'
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { logger } from '../../logger'
import type { Task } from '../../queue/types'
import { SessionProcessor } from '../sessionProcessor'
@@ -141,7 +142,7 @@ describe('SessionProcessor — P1 token budget check', () => {
],
}
const checkTaskBudget = vi.fn().mockResolvedValue(verdict)
- const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const warn = vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
const sp = new SessionProcessor({ maxConcurrent: 1, executor, lifecycle: lc, checkTaskBudget })
const task = registered(lc, mkTask('t1'))
@@ -151,8 +152,8 @@ describe('SessionProcessor — P1 token budget check', () => {
expect(executor).toHaveBeenCalledWith(task)
expect(warn).toHaveBeenCalledWith(
- '[SessionProcessor] budget_unpriced_usage',
- expect.objectContaining({ taskId: 't1', source: 'internal', pairs: verdict.unpriced })
+ expect.objectContaining({ taskId: 't1', source: 'internal', pairs: verdict.unpriced }),
+ 'Unpriced task usage'
)
warn.mockRestore()
})
@@ -161,7 +162,7 @@ describe('SessionProcessor — P1 token budget check', () => {
const lc = new TaskLifecycle()
const executor = vi.fn().mockResolvedValue(false)
const checkTaskBudget = vi.fn().mockResolvedValue({ allowed: true })
- const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const warn = vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
const sp = new SessionProcessor({ maxConcurrent: 1, executor, lifecycle: lc, checkTaskBudget })
const task = registered(lc, mkTask('t1'))
@@ -180,7 +181,7 @@ describe('SessionProcessor — P1 token budget check', () => {
const lc = new TaskLifecycle()
const executor = vi.fn().mockResolvedValue(false)
const checkTaskBudget = vi.fn().mockResolvedValue({ allowed: true, unpriced: [] })
- const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const warn = vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
const sp = new SessionProcessor({ maxConcurrent: 1, executor, lifecycle: lc, checkTaskBudget })
const task = registered(lc, mkTask('t1'))
@@ -199,7 +200,7 @@ describe('SessionProcessor — P1 token budget check', () => {
const lc = new TaskLifecycle()
const executor = vi.fn().mockResolvedValue(false)
const checkTaskBudget = vi.fn().mockRejectedValue(new Error('boom'))
- const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const warn = vi.spyOn(logger, 'warn').mockImplementation(() => undefined)
const sp = new SessionProcessor({ maxConcurrent: 1, executor, lifecycle: lc, checkTaskBudget })
const task = registered(lc, mkTask('t1'))
diff --git a/mcp-host/src/session/__tests__/sessionProcessor.test.ts b/mcp-host/src/session/__tests__/sessionProcessor.test.ts
index 57cc1b839..7925740d1 100644
--- a/mcp-host/src/session/__tests__/sessionProcessor.test.ts
+++ b/mcp-host/src/session/__tests__/sessionProcessor.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
import type { Task } from '../../queue/types'
import { SessionProcessor } from '../sessionProcessor'
@@ -189,3 +189,57 @@ describe('SessionProcessor', () => {
expect(processor.pendingSessionCount).toBe(0)
})
})
+
+describe('SessionProcessor dispatch spacing', () => {
+ afterEach(() => vi.useRealTimers())
+ it('spaces dispatches without blocking concurrency or resetting the pending timer', async () => {
+ vi.useFakeTimers()
+ const lifecycle = new TaskLifecycle()
+ const started: string[] = []
+ const processor = new SessionProcessor({
+ maxConcurrent: 3,
+ taskDelayMs: 100,
+ lifecycle,
+ executor: async task => {
+ started.push(task.id)
+ return false
+ },
+ })
+ for (const id of ['a', 'b']) {
+ const task = createTask(id)
+ lifecycle.register(task)
+ processor.enqueue(id, task)
+ }
+ expect(started).toEqual(['a'])
+ await vi.advanceTimersByTimeAsync(50)
+ const task = createTask('c')
+ lifecycle.register(task)
+ processor.enqueue('c', task)
+ await vi.advanceTimersByTimeAsync(50)
+ expect(started).toEqual(['a', 'b'])
+ await vi.advanceTimersByTimeAsync(100)
+ expect(started).toEqual(['a', 'b', 'c'])
+ expect(vi.getTimerCount()).toBe(0)
+ })
+ it('does not dispatch a task cancelled during the delay', async () => {
+ vi.useFakeTimers()
+ const lifecycle = new TaskLifecycle()
+ const execute = vi.fn(async () => false)
+ const processor = new SessionProcessor({
+ maxConcurrent: 2,
+ taskDelayMs: 100,
+ lifecycle,
+ executor: execute,
+ })
+ const a = createTask('a'),
+ b = createTask('b')
+ lifecycle.register(a)
+ lifecycle.register(b)
+ processor.enqueue('a', a)
+ processor.enqueue('b', b)
+ lifecycle.transition(b.id, 'cancelled', 'user_requested')
+ await vi.advanceTimersByTimeAsync(100)
+ expect(execute).toHaveBeenCalledTimes(1)
+ expect(vi.getTimerCount()).toBe(0)
+ })
+})
diff --git a/mcp-host/src/session/sessionProcessor.ts b/mcp-host/src/session/sessionProcessor.ts
index 96e15f0fb..b0a23126b 100644
--- a/mcp-host/src/session/sessionProcessor.ts
+++ b/mcp-host/src/session/sessionProcessor.ts
@@ -1,10 +1,13 @@
import { EventEmitter } from 'events'
import type { BudgetVerdict } from '../budget/types'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle'
+import { logger } from '../logger'
import type { Task } from '../queue/types'
export interface SessionProcessorConfig {
maxConcurrent: number
+ /** Minimum interval between task dispatches, not between tool iterations. */
+ taskDelayMs?: number
/**
* Execute a task. Returns true if the session should stay locked
* (e.g., task is awaiting approval), false if the session is free.
@@ -42,10 +45,16 @@ export class SessionProcessor extends EventEmitter {
private activeSessions = new Set<string>()
private suspendedSessions = new Set<string>()
private config: SessionProcessorConfig
+ private nextDispatchAt = 0
+ private dispatchTimer: ReturnType<typeof setTimeout> | undefined
constructor(config: SessionProcessorConfig) {
super()
this.config = config
+ const delay = config.taskDelayMs ?? 0
+ if (!Number.isSafeInteger(delay) || delay < 0 || delay > 2_147_483_647) {
+ throw new Error('Invalid task dispatch delay')
+ }
}
get activeCount(): number {
@@ -91,6 +100,15 @@ export class SessionProcessor extends EventEmitter {
return
}
+ const remainingDelay = this.nextDispatchAt - Date.now()
+ if (remainingDelay > 0) {
+ if (!this.dispatchTimer)
+ this.dispatchTimer = setTimeout(() => {
+ this.dispatchTimer = undefined
+ this.tryProcessNext()
+ }, remainingDelay)
+ return
+ }
const queue = this.sessionQueues.get(readySession)!
const task = queue.shift()!
@@ -110,6 +128,7 @@ export class SessionProcessor extends EventEmitter {
return
}
+ this.nextDispatchAt = Date.now() + (this.config.taskDelayMs ?? 0)
this.activeSessions.add(readySession)
this.emit('task:started', { sessionKey: readySession, task })
@@ -117,6 +136,7 @@ export class SessionProcessor extends EventEmitter {
// synchronously — no await happens before dispatch, so behavior matches the
// pre-budget path exactly.
void this.dispatchWithBudgetCheck(readySession, task)
+ this.tryProcessNext()
}
/**
@@ -133,10 +153,7 @@ export class SessionProcessor extends EventEmitter {
} catch (err) {
// Defense in depth — the callback is already fail-open, but a budget
// check must never block a task on an unexpected throw (§0.2).
- console.warn('[SessionProcessor] budget check threw; failing open', {
- taskId: task.id,
- error: err instanceof Error ? err.message : String(err),
- })
+ logger.warn({ taskId: task.id, err }, 'Task budget check failed open')
verdict = { allowed: true }
}
// Informational ops signal (does NOT affect allow/deny). control-api
@@ -163,11 +180,10 @@ export class SessionProcessor extends EventEmitter {
*/
private logUnpricedUsage(task: Task, verdict: BudgetVerdict): void {
if (!verdict.unpriced?.length) return
- console.warn('[SessionProcessor] budget_unpriced_usage', {
- taskId: task.id,
- source: task.source,
- pairs: verdict.unpriced,
- })
+ logger.warn(
+ { taskId: task.id, source: task.source, pairs: verdict.unpriced },
+ 'Unpriced task usage'
+ )
}
/**
@@ -210,7 +226,7 @@ export class SessionProcessor extends EventEmitter {
.catch(error => {
this.activeSessions.delete(sessionKey)
// TaskLifecycle is now authoritative — removed task.status === 'cancelled' band-aid (spec §4.3)
- console.error(`[SessionProcessor] Task ${task.id} failed in session ${sessionKey}:`, error)
+ logger.error({ taskId: task.id, err: error }, 'Session task failed')
this.emit('task:failed', { sessionKey, task, error })
this.tryProcessNext()
})
diff --git a/mcp-host/test/fixtures/kubernetes-unit.yaml b/mcp-host/test/fixtures/kubernetes-unit.yaml
new file mode 100644
index 000000000..9ba151d71
--- /dev/null
+++ b/mcp-host/test/fixtures/kubernetes-unit.yaml
@@ -0,0 +1,16 @@
+# Unit-test client construction only. No live cluster.
+apiVersion: v1
+kind: Config
+current-context: unit-fixture
+clusters:
+ - name: unit-fixture
+ cluster:
+ server: http://127.0.0.1:9
+contexts:
+ - name: unit-fixture
+ context:
+ cluster: unit-fixture
+ user: unit-fixture
+users:
+ - name: unit-fixture
+ user: {}
diff --git a/mcp-host/vitest.config.ts b/mcp-host/vitest.config.ts
index dd7f38af0..898541254 100644
--- a/mcp-host/vitest.config.ts
+++ b/mcp-host/vitest.config.ts
@@ -1,9 +1,13 @@
import { defineConfig } from 'vitest/config'
+import { fileURLToPath } from 'node:url'
export default defineConfig({
test: {
- // Explicitly scope to this package's src/ directory so vitest does not
- // scan sibling packages when invoked from a parent directory.
+ // Client construction in unit tests uses a fixture, never a live context.
+ env: {
+ KUBECONFIG: fileURLToPath(new URL('./test/fixtures/kubernetes-unit.yaml', import.meta.url)),
+ },
+ // Keep package tests independent of sibling packages.
include: ['src/**/*.test.ts', 'src/**/__tests__/**/*.test.ts'],
exclude: ['dist/**', 'node_modules/**'],
},