@assemblyline-agents/runtime 2.0.0 → 3.0.0

package/dist/tool-execution.js

@@ -1,13 +1,13 @@
-import { boundModelOutput, normalizeApprovalPolicy, sandboxFilesystemContractMetadata } from "@assemblyline-agents/core";
-import { ASK_QUESTION_TOOL_NAME, CORE_HARNESS_TOOL_NAMES, isBuiltInToolName, LOAD_SKILL_TOOL_NAME, runtimeToolsForManifest, TOOL_CALL_TOOL_NAME, TOOL_DESCRIBE_TOOL_NAME, TOOL_SEARCH_TOOL_NAME } from "./builtin-tools.js";
-import { createConnectionRegistryForRunImpl, deferredLocalTools, executeConnectionSearchTool, executeConnectionTool, executeLoadSkillTool, executeToolDescribeTool, executeToolSearchTool, failRuntimeHandledTool } from "./builtin-tool-executors.js";
-import { CONNECTION_SEARCH_TOOL_NAME, parseQualifiedName } from "./connections.js";
+import { boundModelOutput, DELEGATE_TOOL_NAME, normalizeApprovalPolicy, sandboxFilesystemContractMetadata } from "@assemblyline-agents/core";
+import { HISTORY_SEARCH_TOOL_NAME, FILES_MOUNT_TOOL_NAME, FILES_SEARCH_TOOL_NAME, LOAD_SKILL_TOOL_NAME, PAIR_TOOL_NAME, runtimeToolsForSurface, TOOL_SEARCH_TOOL_NAME, WORKSPACE_CHECKPOINT_CREATE_TOOL_NAME, WORKSPACE_CHECKPOINT_LIST_TOOL_NAME, WORKSPACE_CHECKPOINT_RESTORE_TOOL_NAME, WORKSPACE_FORK_TOOL_NAME, WORKSPACE_SEARCH_TOOL_NAME, WORKSPACE_STATUS_TOOL_NAME } from "./builtin-tools.js";
+import { createConnectionRegistryForRunImpl, executeConnectionSearchTool, executeConnectionTool, executeHistorySearchTool, executeLoadSkillTool, executePairTool, executeToolSearchTool, failRuntimeHandledTool, recordRuntimeHandledToolStart } from "./builtin-tool-executors.js";
+import { CONNECTION_SEARCH_TOOL_NAME, isConnectionConfigurationError, parseQualifiedName } from "./connections.js";
 import { resolvePositiveIntegerEnv } from "./env-config.js";
 import { harnessPauseOutcome } from "./harness-continuation.js";
 import { evalRunOptionsForRun } from "./eval-run-options.js";
 import { isJsonObject, previewString, redactedToolInput, safeJson } from "./json-util.js";
+import { runUsesChannelReplyForHumanInput } from "./human-input-routing.js";
 import { prepareToolModelOutput } from "./model-media.js";
-import { failRun } from "./run-outcome.js";
 import { sandboxWriteByteLength } from "./resource-projection-util.js";
 import { stringValue, timestamp, toolRequiresSandbox } from "./runtime-util.js";
 import { applyCoreToolPolicy, filterVisibleToolSet } from "./security.js";
@@ -16,10 +16,13 @@ export function visibleToolSetImpl(host, defaultToolNames, activeSkills) {
     void activeSkills;
     return filterVisibleToolSet(defaultToolNames, host.coreToolPolicy);
 }
-export async function modelToolsImpl(host, activeToolNames, connectionRegistry, discoveredConnectionTools = new Map()) {
+export async function modelToolsImpl(host, run, activeToolNames, connectionRegistry, discoveredConnectionTools = new Map(), options = {}) {
     const tools = [];
-    for (const tool of runtimeToolsForManifest(host.manifest)) {
-        if (!activeToolNames.has(tool.name))
+    const surface = host.surfaceForRun(run);
+    for (const tool of runtimeToolsForSurface(surface.tools)) {
+        const active = activeToolNames.has(tool.name);
+        const deferred = options.includeDeferred === true && tool.visibility === "deferred";
+        if (!active && !deferred)
             continue;
         const policyTool = applyCoreToolPolicy(tool, host.coreToolPolicy);
         if (!policyTool)
@@ -30,17 +33,21 @@ export async function modelToolsImpl(host, activeToolNames, connectionRegistry,
             description: definition.description ?? policyTool.description,
             inputSchema: definition.inputSchema ?? policyTool.inputSchema
         };
-        // Statically pause-capable tools must serialize their batch: approval
-        // gates park the run before executing, ask_question always pauses, and
-        // the deferred-tool bridge can hit any of those through the tool it
-        // routes to.
-        if (policyTool.name === ASK_QUESTION_TOOL_NAME ||
-            policyTool.name === TOOL_CALL_TOOL_NAME ||
-            normalizeApprovalPolicy(policyTool.needsApproval).mode === "always") {
+        // Approval-gated tools park the run and therefore serialize their batch.
+        if (normalizeApprovalPolicy(policyTool.needsApproval).mode === "always") {
             descriptor.execution = "sequential";
         }
+        if (!active) {
+            descriptor.deferLoading = true;
+            options.exposedDeferredToolNames?.add(policyTool.name);
+        }
         tools.push(descriptor);
     }
+    // connection_search is not part of the built-in tool catalog, so it cannot
+    // be selected by authored setup() (capability validation rejects unknown
+    // names) and this branch stays dormant today. tool_search is the model's
+    // discovery surface for connection tools, and the core `pair` tool is the
+    // discovery-independent binding path.
     if (connectionRegistry?.hasLiveConnections() && activeToolNames.has(CONNECTION_SEARCH_TOOL_NAME)) {
         tools.push({
             name: CONNECTION_SEARCH_TOOL_NAME,
@@ -66,30 +73,74 @@ export async function modelToolsImpl(host, activeToolNames, connectionRegistry,
             }
         });
     }
+    if (options.includeDeferred && connectionRegistry?.hasLiveConnections()) {
+        const catalog = await connectionRegistry.search({ keywords: "", limit: Number.MAX_SAFE_INTEGER });
+        for (const result of catalog) {
+            if (!result.qualifiedName || !result.tool || !result.inputSchema)
+                continue;
+            const metadata = {
+                connection: result.connection,
+                name: result.tool,
+                qualifiedName: result.qualifiedName,
+                description: result.description,
+                inputSchema: result.inputSchema
+            };
+            if (result.outputSchema)
+                metadata.outputSchema = result.outputSchema;
+            discoveredConnectionTools.set(result.qualifiedName, metadata);
+        }
+    }
     for (const [qualifiedName, metadata] of discoveredConnectionTools) {
-        if (!activeToolNames.has(qualifiedName))
+        const active = activeToolNames.has(qualifiedName);
+        if (!active && !options.includeDeferred)
             continue;
-        tools.push({
+        const descriptor = {
             name: qualifiedName,
             description: metadata.description,
             inputSchema: metadata.inputSchema,
+            external: {
+                namespace: metadata.connection,
+                name: metadata.name
+            },
             // Connection tools can pause for authorization at any call.
             execution: "sequential"
-        });
+        };
+        if (!active) {
+            descriptor.deferLoading = true;
+            options.exposedDeferredToolNames?.add(qualifiedName);
+        }
+        tools.push(descriptor);
     }
-    for (const subagent of host.manifest.subagents) {
-        if (!activeToolNames.has(`delegate_${subagent.name}`))
-            continue;
+    const selectedSubagentNames = new Set(Array.isArray(run.input.agentSubagents)
+        ? run.input.agentSubagents.filter((name) => typeof name === "string")
+        : []);
+    const selectedSubagents = surface.subagents
+        .filter((subagent) => selectedSubagentNames.has(subagent.name))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (activeToolNames.has(DELEGATE_TOOL_NAME) && selectedSubagents.length > 0) {
+        const directory = selectedSubagents
+            .map((subagent) => `${subagent.name}: ${subagent.description}`)
+            .join("\n");
         tools.push({
-            name: `delegate_${subagent.name}`,
-            description: subagent.description,
+            name: DELEGATE_TOOL_NAME,
+            description: `Delegate one self-contained task to an enabled immediate child. The child has no parent transcript, so include needed context and usable file paths; review its result before replying. Available agents:\n${directory}`,
             inputSchema: {
                 type: "object",
                 properties: {
-                    task: { type: "string" },
-                    expectedOutput: { type: "string" },
-                    constraints: { type: "array", items: { type: "string" } }
+                    agent: {
+                        type: "string",
+                        enum: selectedSubagents.map((subagent) => subagent.name),
+                        description: "Exact child-agent name from the available-agent directory."
+                    },
+                    task: { type: "string", description: "Self-contained objective and required context." },
+                    expectedOutput: { type: "string", description: "Required result or artifact." },
+                    constraints: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Limits, authority, and confidentiality requirements."
+                    }
                 },
+                required: ["agent", "task"],
                 additionalProperties: true
             }
         });
@@ -97,126 +148,142 @@ export async function modelToolsImpl(host, activeToolNames, connectionRegistry,
     return tools;
 }
 export async function harnessExecuteToolImpl(host, call, state) {
-    const { toolCallId, name, input: params } = call;
-    if (name === LOAD_SKILL_TOOL_NAME) {
-        const outcome = await executeLoadSkillTool(host, state.run(), {
-            sandboxHandle: state.sandboxHandle,
-            allowedSkills: state.activeSkills
-        }, params, `tool:${state.run().id}:${name}:${toolCallId}`);
-        state.setRun(outcome.run);
-        return harnessResult(outcome.modelOutput, host.env);
-    }
-    if (name === TOOL_SEARCH_TOOL_NAME) {
-        const outcome = await executeToolSearchTool(host, state.run(), {
-            connectionRegistry: state.connectionRegistry,
-            discoveredConnectionTools: state.discoveredConnectionTools
-        }, params, `tool:${state.run().id}:${name}:${toolCallId}`);
-        state.setRun(outcome.run);
-        return harnessResult(outcome.modelOutput, host.env);
-    }
-    if (name === TOOL_DESCRIBE_TOOL_NAME) {
-        const outcome = await executeToolDescribeTool(host, state.run(), {
-            connectionRegistry: state.connectionRegistry,
-            discoveredConnectionTools: state.discoveredConnectionTools
-        }, params, `tool:${state.run().id}:${name}:${toolCallId}`);
-        state.setRun(outcome.run);
-        return harnessResult(outcome.modelOutput, host.env);
+    // Tool calls may already be queued in a provider response when the operator
+    // cancels. Re-read the durable run before every tool boundary so no new side
+    // effect starts after cancellation became visible to the operator.
+    const durableRun = await host.state.getRun(state.run().id);
+    if (durableRun?.status === "cancelled" || durableRun?.controlIntent === "cancel") {
+        if (durableRun)
+            state.setRun(durableRun);
+        return harnessResult({ cancelled: true }, host.env);
     }
-    if (name === TOOL_CALL_TOOL_NAME) {
-        const outcome = await executeToolCallBridge(host, state.run(), {
-            sandboxHandle: state.sandboxHandle,
-            connectionRegistry: state.connectionRegistry,
-            discoveredConnectionTools: state.discoveredConnectionTools
-        }, params, `tool:${state.run().id}:deferred:${toolCallId}`);
+    const { toolCallId, name, input: params } = call;
+    const boundaryIdempotencyKey = `tool:${state.run().id}:${name}:${toolCallId}`;
+    try {
+        if (!state.defaultToolNames.has(name) && !state.exposedDeferredToolNames.has(name)) {
+            await host.state.appendEvent(state.run().id, "tool.unavailable", {
+                toolName: name,
+                reason: "not_enabled_for_run"
+            });
+            throw new Error(`Tool ${name} is not enabled for this run.`);
+        }
+        if (state.exposedDeferredToolNames.has(name))
+            state.defaultToolNames.add(name);
+        if (name === LOAD_SKILL_TOOL_NAME) {
+            const outcome = await executeLoadSkillTool(host, state.run(), {
+                sandboxHandle: state.sandboxHandle,
+                allowedSkills: state.activeSkills
+            }, params, `tool:${state.run().id}:${name}:${toolCallId}`);
+            state.setRun(outcome.run);
+            return harnessResult(outcome.modelOutput, host.env);
+        }
+        if (name === TOOL_SEARCH_TOOL_NAME) {
+            const outcome = await executeToolSearchTool(host, state.run(), {
+                connectionRegistry: state.connectionRegistry,
+                discoveredConnectionTools: state.discoveredConnectionTools,
+                activeToolNames: state.defaultToolNames
+            }, params, `tool:${state.run().id}:${name}:${toolCallId}`);
+            state.setRun(outcome.run);
+            return harnessResult(outcome.modelOutput, host.env);
+        }
+        if (name === DELEGATE_TOOL_NAME) {
+            if (!isJsonObject(params))
+                throw new Error(`${DELEGATE_TOOL_NAME} requires an object input.`);
+            const subagentName = stringValue(params.agent);
+            if (!subagentName)
+                throw new Error(`${DELEGATE_TOOL_NAME} requires agent.`);
+            if (!stringValue(params.task))
+                throw new Error(`${DELEGATE_TOOL_NAME} requires a non-empty task.`);
+            const task = { ...params };
+            delete task.agent;
+            const timeline = await host.runSubagent(state.run().id, subagentName, task);
+            return harnessResult({
+                runId: timeline.run.id,
+                status: timeline.run.status,
+                events: timeline.events.map((event) => ({ type: event.type, data: event.data })).slice(-8)
+            }, host.env);
+        }
+        if (name === PAIR_TOOL_NAME) {
+            const outcome = await executePairTool(host, state.run(), state.connectionRegistry, params, `tool:${state.run().id}:${name}:${toolCallId}`);
+            state.setRun(outcome.run);
+            return harnessResult(outcome.modelOutput, host.env);
+        }
+        if (name === CONNECTION_SEARCH_TOOL_NAME) {
+            const outcome = await executeConnectionSearchTool(host, state.run(), state.connectionRegistry, params, `tool:${state.run().id}:${name}:${toolCallId}`);
+            state.setRun(outcome.run);
+            for (const result of outcome.results) {
+                if (result.qualifiedName && result.tool && result.inputSchema) {
+                    const metadata = {
+                        connection: result.connection,
+                        name: result.tool,
+                        qualifiedName: result.qualifiedName,
+                        description: result.description,
+                        inputSchema: result.inputSchema
+                    };
+                    if (result.outputSchema)
+                        metadata.outputSchema = result.outputSchema;
+                    state.discoveredConnectionTools.set(result.qualifiedName, metadata);
+                    state.defaultToolNames.add(result.qualifiedName);
+                }
+            }
+            return harnessResult(outcome.results, host.env);
+        }
+        if (parseQualifiedName(name)) {
+            const outcome = await executeConnectionTool(host, state.run(), state.connectionRegistry, name, params, false, `tool:${state.run().id}:${name}:${toolCallId}`, "return");
+            state.setRun(outcome.run);
+            if (outcome.waitingForApproval || outcome.waitingForConnection) {
+                const waiting = { run: outcome.run };
+                if (outcome.waitingForApproval !== undefined)
+                    waiting.waitingForApproval = outcome.waitingForApproval;
+                if (outcome.waitingForConnection !== undefined)
+                    waiting.waitingForConnection = outcome.waitingForConnection;
+                waiting.toolCallId = toolCallId;
+                waiting.toolName = name;
+                if (outcome.authorizationSessionId)
+                    waiting.authorizationSessionId = outcome.authorizationSessionId;
+                state.setPause(waiting);
+                return harnessPauseOutcome(waiting);
+            }
+            return harnessResult(outcome.modelOutput ?? {}, host.env);
+        }
+        const compiledTool = runtimeToolsForSurface(host.surfaceForRun(state.run()).tools).find((candidate) => candidate.name === name);
+        if (!compiledTool) {
+            await host.state.appendEvent(state.run().id, "tool.unavailable", { toolName: name });
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        const outcome = await executeToolImpl(host, state.run(), compiledTool, params, state.sandboxHandle, false, `tool:${state.run().id}:${compiledTool.name}:${toolCallId}`, call.signal);
         state.setRun(outcome.run);
-        if (outcome.waitingForApproval || outcome.waitingForInput || outcome.waitingForConnection) {
+        if (outcome.waitingForApproval || outcome.waitingForInput) {
             const waiting = { run: outcome.run };
             if (outcome.waitingForApproval !== undefined)
                 waiting.waitingForApproval = outcome.waitingForApproval;
             if (outcome.waitingForInput !== undefined)
                 waiting.waitingForInput = outcome.waitingForInput;
-            if (outcome.waitingForConnection !== undefined)
-                waiting.waitingForConnection = outcome.waitingForConnection;
             if (outcome.toolCallId)
                 waiting.toolCallId = outcome.toolCallId;
             if (outcome.toolName)
                 waiting.toolName = outcome.toolName;
-            if (outcome.authorizationSessionId)
-                waiting.authorizationSessionId = outcome.authorizationSessionId;
-            state.setPause(waiting);
-            return harnessPauseOutcome(waiting);
-        }
-        return harnessResult(outcome.modelOutput ?? {}, host.env);
-    }
-    if (name.startsWith("delegate_")) {
-        const subagentName = name.slice("delegate_".length);
-        const task = isJsonObject(params) ? params : { task: String(params ?? "") };
-        const timeline = await host.runSubagent(state.run().id, subagentName, task);
-        return harnessResult({
-            runId: timeline.run.id,
-            status: timeline.run.status,
-            events: timeline.events.map((event) => ({ type: event.type, data: event.data })).slice(-8)
-        }, host.env);
-    }
-    if (name === CONNECTION_SEARCH_TOOL_NAME) {
-        const outcome = await executeConnectionSearchTool(host, state.run(), state.connectionRegistry, params, `tool:${state.run().id}:${name}:${toolCallId}`);
-        state.setRun(outcome.run);
-        for (const result of outcome.results) {
-            if (result.qualifiedName && result.tool && result.inputSchema) {
-                const metadata = {
-                    connection: result.connection,
-                    name: result.tool,
-                    qualifiedName: result.qualifiedName,
-                    description: result.description,
-                    inputSchema: result.inputSchema
-                };
-                if (result.outputSchema)
-                    metadata.outputSchema = result.outputSchema;
-                state.discoveredConnectionTools.set(result.qualifiedName, metadata);
-                state.defaultToolNames.add(result.qualifiedName);
-            }
-        }
-        return harnessResult(outcome.results, host.env);
-    }
-    if (parseQualifiedName(name)) {
-        const outcome = await executeConnectionTool(host, state.run(), state.connectionRegistry, name, params, false, `tool:${state.run().id}:${name}:${toolCallId}`);
-        state.setRun(outcome.run);
-        if (outcome.waitingForApproval || outcome.waitingForConnection) {
-            const waiting = { run: outcome.run };
-            if (outcome.waitingForApproval !== undefined)
-                waiting.waitingForApproval = outcome.waitingForApproval;
-            if (outcome.waitingForConnection !== undefined)
-                waiting.waitingForConnection = outcome.waitingForConnection;
-            waiting.toolCallId = toolCallId;
-            waiting.toolName = name;
-            if (outcome.authorizationSessionId)
-                waiting.authorizationSessionId = outcome.authorizationSessionId;
             state.setPause(waiting);
             return harnessPauseOutcome(waiting);
         }
         return harnessResult(outcome.modelOutput ?? {}, host.env);
     }
-    const compiledTool = runtimeToolsForManifest(host.manifest).find((candidate) => candidate.name === name);
-    if (!compiledTool) {
-        await host.state.appendEvent(state.run().id, "tool.unavailable", { toolName: name });
-        return harnessResult({ error: `Unknown tool: ${name}` }, host.env);
-    }
-    const outcome = await executeToolImpl(host, state.run(), compiledTool, params, state.sandboxHandle, false, `tool:${state.run().id}:${compiledTool.name}:${toolCallId}`);
-    state.setRun(outcome.run);
-    if (outcome.waitingForApproval || outcome.waitingForInput) {
-        const waiting = { run: outcome.run };
-        if (outcome.waitingForApproval !== undefined)
-            waiting.waitingForApproval = outcome.waitingForApproval;
-        if (outcome.waitingForInput !== undefined)
-            waiting.waitingForInput = outcome.waitingForInput;
-        if (outcome.toolCallId)
-            waiting.toolCallId = outcome.toolCallId;
-        if (outcome.toolName)
-            waiting.toolName = outcome.toolName;
-        state.setPause(waiting);
-        return harnessPauseOutcome(waiting);
+    catch (error) {
+        // One shared model-tool boundary catches failures that occur before a
+        // specialized executor can normalize them (sandbox acquisition, deferred
+        // activation preflight, connection approval resolution, delegation, or
+        // future dispatch branches). State persistence failures still escape naturally:
+        // if we cannot durably record this failure, the run cannot safely continue.
+        const run = state.run();
+        const existing = (await host.state.listToolCalls(run.id))
+            .filter((candidate) => candidate.idempotencyKey === boundaryIdempotencyKey
+            || candidate.idempotencyKey.startsWith(`${boundaryIdempotencyKey}:`))
+            .at(-1);
+        const toolCall = existing ?? await recordRuntimeHandledToolStart(host, run, name, params, boundaryIdempotencyKey);
+        const failure = await failRuntimeHandledTool(host, run, toolCall, toolCall.toolName, error, isConnectionConfigurationError(error) ? { failureKind: "configuration_error" } : undefined);
+        state.setRun(failure.run);
+        return harnessResult(failure.modelOutput, host.env);
     }
-    return harnessResult(outcome.modelOutput ?? {}, host.env);
 }
 function harnessResult(output, env) {
     const prepared = prepareToolModelOutput(output, env);
@@ -224,31 +291,14 @@ function harnessResult(output, env) {
         return { kind: "result", output: prepared.output };
     return { kind: "result", output: prepared.output, media: prepared.media };
 }
-async function executeToolCallBridge(host, run, state, input, idempotencyKey, approved = false) {
-    const raw = isJsonObject(input) ? input : {};
-    const name = stringValue(raw.name);
-    const args = isJsonObject(raw.arguments) ? raw.arguments : isJsonObject(raw.input) ? raw.input : {};
-    if (!name)
-        throw new Error("tool_call requires name.");
-    if (CORE_HARNESS_TOOL_NAMES.includes(name)) {
-        throw new Error(`Core harness tool ${name} is already directly visible; call it directly.`);
-    }
-    if (parseQualifiedName(name)) {
-        return executeConnectionTool(host, run, state.connectionRegistry, name, args, approved, `${idempotencyKey}:${name}`);
-    }
-    const compiledTool = deferredLocalTools(host).find((tool) => tool.name === name);
-    if (!compiledTool)
-        throw new Error(`Deferred tool not found: ${name}`);
-    const outcome = await executeToolImpl(host, run, compiledTool, args, state.sandboxHandle, approved, `${idempotencyKey}:${name}`);
-    return { ...outcome, toolName: compiledTool.name };
-}
 export function selectToolImpl(host, options) {
     if (options.toolName) {
-        return runtimeToolsForManifest(host.manifest).find((tool) => tool.name === options.toolName);
+        const surface = options.existingRun ? host.surfaceForRun(options.existingRun) : undefined;
+        return runtimeToolsForSurface((surface?.tools ?? host.manifest.tools)).find((tool) => tool.name === options.toolName);
     }
     return undefined;
 }
-export async function executeToolImpl(host, run, tool, input, sandboxHandle, approved, idempotencyKey = `tool:${run.id}:${tool.name}`) {
+export async function executeToolImpl(host, run, tool, input, sandboxHandle, approved, idempotencyKey = `tool:${run.id}:${tool.name}`, signal) {
     const policyTool = applyCoreToolPolicy(tool, host.coreToolPolicy);
     if (!policyTool) {
         await host.state.appendEvent(run.id, "tool.call_requested", { toolName: tool.name, input: redactedToolInput(input) });
@@ -256,37 +306,30 @@ export async function executeToolImpl(host, run, tool, input, sandboxHandle, app
             runId: run.id,
             toolName: tool.name,
             status: "requested",
-            input: redactedToolInput(input),
+            input: safeJson(input),
             idempotencyKey
         });
-        return failRuntimeHandledTool(host, run, toolCall, tool.name, `Core tool ${tool.name} is disabled by the OpenEve core tool policy.`);
+        return failRuntimeHandledTool(host, run, toolCall, tool.name, `Core tool ${tool.name} is disabled by the Assembly Line core tool policy.`);
     }
     tool = policyTool;
     if (tool.name === TOOL_SEARCH_TOOL_NAME) {
         return executeToolSearchTool(host, run, {
             connectionRegistry: createConnectionRegistryForRunImpl(host, run, "local"),
-            discoveredConnectionTools: new Map()
+            discoveredConnectionTools: new Map(),
+            activeToolNames: new Set()
         }, input, idempotencyKey);
     }
-    if (tool.name === TOOL_DESCRIBE_TOOL_NAME) {
-        return executeToolDescribeTool(host, run, {
-            connectionRegistry: createConnectionRegistryForRunImpl(host, run, "local"),
-            discoveredConnectionTools: new Map()
-        }, input, idempotencyKey);
-    }
-    if (tool.name === TOOL_CALL_TOOL_NAME) {
-        return executeToolCallBridge(host, run, {
-            sandboxHandle,
-            connectionRegistry: createConnectionRegistryForRunImpl(host, run, "local", sandboxHandle),
-            discoveredConnectionTools: new Map()
-        }, input, idempotencyKey, approved);
+    if (tool.name === HISTORY_SEARCH_TOOL_NAME) {
+        return executeHistorySearchTool(host, run, input, idempotencyKey);
     }
     await host.state.appendEvent(run.id, "tool.call_requested", { toolName: tool.name, input: redactedToolInput(input) });
     let toolCall = await host.state.createToolCall({
         runId: run.id,
         toolName: tool.name,
         status: "requested",
-        input: redactedToolInput(input),
+        // Raw, not redacted: approval resume re-executes this persisted input.
+        // Redaction happens at outward read boundaries (redactedToolCallRecord).
+        input: safeJson(input),
         idempotencyKey
     });
     const approval = normalizeApprovalPolicy(tool.needsApproval);
@@ -303,7 +346,7 @@ export async function executeToolImpl(host, run, tool, input, sandboxHandle, app
             toolName: tool.name,
             source: "eval"
         });
-        return executeToolWithRecordImpl(host, run, tool, toolCall, input, sandboxHandle, true);
+        return executeToolWithRecordImpl(host, run, tool, toolCall, input, sandboxHandle, true, signal);
     }
     if (approval.mode === "always" && !approved) {
         toolCall = await host.state.updateToolCall(toolCall.id, { status: "waiting_for_approval" });
@@ -320,22 +363,34 @@ export async function executeToolImpl(host, run, tool, input, sandboxHandle, app
         });
         return { run: waitingRun, waitingForApproval: true, toolCallId: toolCall.id, toolName: tool.name };
     }
-    return executeToolWithRecordImpl(host, run, tool, toolCall, input, sandboxHandle, approved);
+    return executeToolWithRecordImpl(host, run, tool, toolCall, input, sandboxHandle, approved, signal);
 }
-export async function executeToolWithRecordImpl(host, run, tool, toolCall, input, sandboxHandle, approvedToolCall = false) {
+export async function executeToolWithRecordImpl(host, run, tool, toolCall, input, sandboxHandle, approvedToolCall = false, signal) {
     await host.state.updateToolCall(toolCall.id, { status: "running" });
     await host.state.appendEvent(run.id, "tool.execution_started", { toolCallId: toolCall.id, toolName: tool.name });
     const toolSpanStartedAt = timestamp();
-    if (toolRequiresSandbox(tool)) {
-        await sandboxHandle.get();
-    }
-    const ctx = createToolContext(host, run, sandboxHandle, approvedToolCall);
     try {
-        const definition = await host.loadTool(tool, run);
-        if (!definition.execute)
+        const workspaceTool = WORKSPACE_TOOL_NAMES.has(tool.name);
+        const definition = workspaceTool ? undefined : await host.loadTool(tool, run);
+        if (!workspaceTool && !definition?.execute)
             throw new Error(`Tool ${tool.name} does not export execute().`);
-        const result = await withToolTimeout(Promise.resolve(definition.execute(input, ctx)), definition.timeoutMs ?? host.toolTimeoutMs, tool.name);
-        const modelOutput = definition.toModelOutput ? await definition.toModelOutput(result) : boundModelOutput(result, host.toolOutputMaxChars);
+        const executed = await withToolTimeout(async () => {
+            // Acquisition, provider reconnect, filesystem hydration, credential
+            // projection, authored execution, and output conversion share one
+            // deadline. A sandbox provider can no longer wedge the tool boundary
+            // before its timer starts.
+            if (toolRequiresSandbox(tool))
+                await sandboxHandle.get();
+            const ctx = createToolContext(host, run, sandboxHandle, approvedToolCall);
+            const result = workspaceTool
+                ? await host.executeWorkspaceTool(run, tool.name, input, sandboxHandle)
+                : await Promise.resolve(definition.execute(input, ctx));
+            const modelOutput = definition?.toModelOutput
+                ? await definition.toModelOutput(result)
+                : boundModelOutput(result, host.toolOutputMaxChars);
+            return { result, modelOutput };
+        }, definition?.timeoutMs ?? host.toolTimeoutMs, tool.name, signal);
+        const { result, modelOutput } = executed;
         await host.state.updateToolCall(toolCall.id, {
             status: "completed",
             result: safeJson(result),
@@ -368,7 +423,57 @@ export async function executeToolWithRecordImpl(host, run, tool, toolCall, input
         return { run: await host.state.getRun(run.id) ?? run, modelOutput };
     }
     catch (error) {
+        if (error instanceof ToolOperationInterruptedError && !sandboxHandle.current()) {
+            sandboxHandle.abandonAcquisition();
+        }
         if (error instanceof HumanInputRequired) {
+            if (runUsesChannelReplyForHumanInput(run)) {
+                const message = "This run accepts human input through its active channel, not by pausing the run.";
+                const modelOutput = {
+                    error: message,
+                    question: error.question,
+                    options: safeJson(error.options ?? {}),
+                    action: "Ask the question as your final response. The user's next channel message will continue the conversation.",
+                    failure: {
+                        kind: "channel_reply_required",
+                        runCanContinue: true
+                    }
+                };
+                await host.state.updateToolCall(toolCall.id, {
+                    status: "failed",
+                    error: message,
+                    modelOutput
+                });
+                await host.state.appendEvent(run.id, "tool.execution_failed", {
+                    toolCallId: toolCall.id,
+                    toolName: tool.name,
+                    error: message,
+                    failureKind: "channel_reply_required",
+                    recoverable: true
+                });
+                await host.state.appendEvent(run.id, "human_input.redirected_to_channel", {
+                    toolCallId: toolCall.id,
+                    toolName: tool.name,
+                    question: error.question,
+                    options: error.options ?? {}
+                });
+                await host.emitSpan("ai.toolCall", toolSpanStartedAt, host.runSpanAttributes(run, {
+                    toolCallId: toolCall.id,
+                    toolName: tool.name,
+                    status: "failed",
+                    error: message,
+                    ...host.toolContentAttributes(input, modelOutput)
+                }), {
+                    parentSpanId: host.turnSpanId(run.id),
+                    status: "error"
+                });
+                await host.emitSpan("assembly-line.tool", toolSpanStartedAt, {
+                    runId: run.id,
+                    toolName: tool.name,
+                    status: "failed"
+                });
+                return { run: await host.state.getRun(run.id) ?? run, modelOutput };
+            }
             await host.state.updateToolCall(toolCall.id, { status: "waiting_for_approval", error: error.message });
             const waitingRun = await host.state.updateRun(run.id, { status: "waiting_for_input" });
             await host.state.appendEvent(run.id, "human_input.requested", {
@@ -392,27 +497,14 @@ export async function executeToolWithRecordImpl(host, run, tool, toolCall, input
             });
             return { run: waitingRun, waitingForInput: true, toolCallId: toolCall.id, toolName: tool.name };
         }
-        // Core sandbox tools (read/write/edit/delete/list/grep/bash) operate on a
-        // filesystem: "not found", "empty", and non-zero exit are normal,
-        // recoverable conditions, not run-ending crashes. Their errors are a
-        // RESULT for the model to reason over (create the dir, try another path,
-        // report gracefully) — exactly what lets an autonomous agent survive an
-        // empty /workspace or a first-run state file that doesn't exist yet.
-        // Authored tools throwing is a stronger signal (the agent's own code
-        // broke) and remains a run failure, so routine/trigger failure detection
-        // is unchanged. Terminal conditions (human input, approval, connection
-        // auth) are explicit cases above and never reach here.
+        // Every durably recordable model-invoked tool failure is returned to the
+        // model. RecoverableToolError classifies correctable input, but ordinary
+        // tool and infrastructure errors are also visible so the model can choose
+        // another action or explain the failure. State persistence failures still
+        // escape because continuing without a durable record is unsafe.
         const message = error instanceof Error ? error.message : String(error);
-        await host.state.updateToolCall(toolCall.id, { status: "failed", error: message });
-        await host.state.appendEvent(run.id, "tool.execution_failed", { toolCallId: toolCall.id, toolName: tool.name, error: message });
-        const recoverable = isBuiltInToolName(tool.name);
-        const nextRun = recoverable
-            ? await host.state.getRun(run.id) ?? run
-            : await failRun({ state: host.state }, run.id, {
-                reason: "tool.execution_failed",
-                error: message,
-                data: { toolCallId: toolCall.id, toolName: tool.name }
-            });
+        const failure = await failRuntimeHandledTool(host, run, toolCall, tool.name, error);
+        const nextRun = failure.run;
         await host.emitSpan("ai.toolCall", toolSpanStartedAt, host.runSpanAttributes(nextRun, {
             toolCallId: toolCall.id,
             toolName: tool.name,
@@ -428,44 +520,66 @@ export async function executeToolWithRecordImpl(host, run, tool, toolCall, input
             toolName: tool.name,
             status: "failed"
         });
-        return { run: nextRun, modelOutput: { error: message } };
+        return { run: nextRun, modelOutput: failure.modelOutput };
     }
 }
+const WORKSPACE_TOOL_NAMES = new Set([
+    FILES_SEARCH_TOOL_NAME,
+    FILES_MOUNT_TOOL_NAME,
+    WORKSPACE_SEARCH_TOOL_NAME,
+    WORKSPACE_STATUS_TOOL_NAME,
+    WORKSPACE_CHECKPOINT_CREATE_TOOL_NAME,
+    WORKSPACE_CHECKPOINT_LIST_TOOL_NAME,
+    WORKSPACE_CHECKPOINT_RESTORE_TOOL_NAME,
+    WORKSPACE_FORK_TOOL_NAME
+]);
 const DEFAULT_SHELL_TIMEOUT_MS = 30_000;
 const DEFAULT_SHELL_TIMEOUT_MAX_MS = 600_000;
-/** Clamp a (possibly model-supplied) shell timeout to [1s, OPENEVE_BASH_TIMEOUT_MAX_MS]; 0/negative/NaN fall to the default. */
+/** Clamp a (possibly model-supplied) shell timeout to [1s, ASSEMBLY_LINE_BASH_TIMEOUT_MAX_MS]; 0/negative/NaN fall to the default. */
 export function clampShellTimeoutMs(requested, env) {
-    const max = resolvePositiveIntegerEnv(env.OPENEVE_BASH_TIMEOUT_MAX_MS, DEFAULT_SHELL_TIMEOUT_MAX_MS);
+    const max = resolvePositiveIntegerEnv(env.ASSEMBLY_LINE_BASH_TIMEOUT_MAX_MS, DEFAULT_SHELL_TIMEOUT_MAX_MS);
     if (typeof requested !== "number" || !Number.isFinite(requested) || requested <= 0) {
         return Math.min(DEFAULT_SHELL_TIMEOUT_MS, max);
     }
     return Math.min(Math.max(Math.floor(requested), 1_000), max);
 }
-/**
- * Race a tool `execute` against its deadline. The promise is not cancelled —
- * the tool call fails (and flows through the recoverable/authored
- * classification) but the underlying work is not forcibly stopped.
- */
-function withToolTimeout(promise, timeoutMs, toolName) {
-    if (timeoutMs <= 0)
-        return promise;
+class ToolOperationInterruptedError extends Error {
+}
+/** Bound the complete runtime tool boundary and release its caller on cancel. */
+function withToolTimeout(operation, timeoutMs, toolName, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(new ToolOperationInterruptedError(`Tool ${toolName} was cancelled.`));
+    }
+    const pending = Promise.resolve().then(operation);
+    if (timeoutMs <= 0 && !signal)
+        return pending;
     return new Promise((resolve, reject) => {
-        // Ref'd on purpose: while a hung tool is the only pending work, an
-        // unref'd timer would drain the event loop before the deadline fires.
-        const timer = setTimeout(() => {
-            reject(new Error(`Tool ${toolName} timed out after ${timeoutMs}ms.`));
-        }, timeoutMs);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => finish(() => {
+            reject(new ToolOperationInterruptedError(`Tool ${toolName} was cancelled.`));
+        });
+        const timer = timeoutMs > 0 ? setTimeout(() => finish(() => {
+            reject(new ToolOperationInterruptedError(`Tool ${toolName} timed out after ${timeoutMs}ms.`));
+        }), timeoutMs) : undefined;
+        signal?.addEventListener("abort", onAbort, { once: true });
+        pending.then((value) => {
+            finish(() => resolve(value));
         }, (error) => {
-            clearTimeout(timer);
-            reject(error instanceof Error ? error : new Error(String(error)));
+            finish(() => reject(error instanceof Error ? error : new Error(String(error))));
         });
     });
 }
 export function wrapSandboxImpl(host, runId, session) {
-    return {
+    const wrapped = {
         ...session,
         readFile: async (path) => {
             const contents = await session.readFile(path);
@@ -505,6 +619,14 @@ export function wrapSandboxImpl(host, runId, session) {
             return result;
         }
     };
+    if (session.readFileBytes) {
+        wrapped.readFileBytes = async (path) => {
+            const contents = await session.readFileBytes(path);
+            await host.state.appendEvent(runId, "sandbox.file_read", { path, bytes: contents.byteLength });
+            return contents;
+        };
+    }
+    return wrapped;
 }
 async function ensureSandboxSyncObligation(host, runId, session, reason, metadata = {}) {
     const run = await host.state.getRun(runId);
@@ -512,6 +634,31 @@ async function ensureSandboxSyncObligation(host, runId, session, reason, metadat
         throw new Error(`Run not found for sandbox sync obligation: ${runId}`);
     const sessionKey = host.sandboxSessionKey(run);
     const existing = await host.state.getSandboxSession(sessionKey);
+    const workspaceId = stringValue(existing?.manifest.workspaceId)?.trim();
+    const baseVersionId = existing?.manifest.baseVersionId;
+    const hasBaseVersionId = baseVersionId === null || typeof baseVersionId === "string";
+    if (!workspaceId || !hasBaseVersionId) {
+        const missing = [
+            ...(!workspaceId ? ["workspaceId"] : []),
+            ...(!hasBaseVersionId ? ["baseVersionId"] : [])
+        ];
+        const error = `Sandbox is not fully hydrated; refusing ${reason} before creating an invalid sync obligation (missing ${missing.join(", ")}).`;
+        await host.state.appendEvent(runId, "sandbox.sync_obligation_rejected", {
+            sandboxId: session.id,
+            sessionKey,
+            reason,
+            missing,
+            metadata
+        });
+        throw new Error(error);
+    }
+    const sessionManifest = {
+        ...existing?.manifest,
+        roots: ["/memory", "/skills", "/workspace"],
+        sandboxRoot: session.root,
+        ...sandboxFilesystemContractMetadata(session.provider === "local" ? "emulated" : "physical")
+    };
+    const syncManifest = { ...sessionManifest, sessionRecordKey: sessionKey };
     const syncJob = await host.state.enqueueSandboxSyncJob({
         runId,
         sandboxId: session.id,
@@ -519,13 +666,7 @@ async function ensureSandboxSyncObligation(host, runId, session, reason, metadat
         idempotencyKey: `sandbox-sync:${runId}:${session.id}`,
         reason,
         maxAttempts: host.sandboxSyncMaxAttempts,
-        manifest: {
-            ...(existing?.manifest ?? {}),
-            roots: ["/memory", "/skills", "/workspace"],
-            sandboxRoot: session.root,
-            sessionKey,
-            ...sandboxFilesystemContractMetadata(session.provider === "local" ? "emulated" : "physical")
-        },
+        manifest: syncManifest,
         metadata
     });
     await host.state.updateSandboxSession(sessionKey, {
@@ -535,13 +676,7 @@ async function ensureSandboxSyncObligation(host, runId, session, reason, metadat
         dirty: true,
         lastSeenAt: timestamp(),
         syncJobId: syncJob.id,
-        manifest: {
-            ...(existing?.manifest ?? {}),
-            roots: ["/memory", "/skills", "/workspace"],
-            sandboxRoot: session.root,
-            sessionKey,
-            ...sandboxFilesystemContractMetadata(session.provider === "local" ? "emulated" : "physical")
-        }
+        manifest: sessionManifest
     }).catch(async () => {
         await host.state.upsertSandboxSession({
             sessionKey,
@@ -552,12 +687,7 @@ async function ensureSandboxSyncObligation(host, runId, session, reason, metadat
             dirty: true,
             lastSeenAt: timestamp(),
             syncJobId: syncJob.id,
-            manifest: {
-                roots: ["/memory", "/skills", "/workspace"],
-                sandboxRoot: session.root,
-                sessionKey,
-                ...sandboxFilesystemContractMetadata(session.provider === "local" ? "emulated" : "physical")
-            }
+            manifest: sessionManifest
         });
     });
     await host.state.appendEvent(runId, "sandbox.sync_obligation", {