@assemblyline-agents/runtime 1.0.0 → 3.0.0

package/dist/builtin-tool-executors.js

@@ -1,37 +1,71 @@
-import { isConnectionAuthorizationRequiredError, shellQuote } from "@assemblyline-agents/core";
-import { CORE_HARNESS_TOOL_NAMES, LOAD_SKILL_TOOL_NAME, runtimeToolsForManifest, TOOL_DESCRIBE_TOOL_NAME, TOOL_SEARCH_TOOL_NAME } from "./builtin-tools.js";
+import { isConnectionAuthorizationRequiredError, isRecoverableToolError, shellQuote } from "@assemblyline-agents/core";
+import { HISTORY_SEARCH_TOOL_NAME, LOAD_SKILL_TOOL_NAME, PAIR_TOOL_NAME, runtimeToolsForSurface, TOOL_SEARCH_TOOL_NAME } from "./builtin-tools.js";
 import { connectionSearchResultForModel, normalizeDeferredToolSearchInput } from "./capability-catalog.js";
-import { CONNECTION_SEARCH_TOOL_NAME, parseQualifiedName, RuntimeConnectionRegistry } from "./connections.js";
+import { CONNECTION_SEARCH_TOOL_NAME, isConnectionConfigurationError, parseQualifiedName, RuntimeConnectionRegistry } from "./connections.js";
 import { evalRunOptionsForRun } from "./eval-run-options.js";
-import { isJsonObject, redactedToolInput, safeJson } from "./json-util.js";
-import { failRun } from "./run-outcome.js";
-import { skillNameFromSkillPath } from "./resource-projection-util.js";
+import { isJsonObject, previewString, redactedToolInput, safeJson } from "./json-util.js";
+import { normalizeResourcePath, skillNameFromSkillPath } from "./resource-projection-util.js";
 import { normalizeConnectionApproval, stringValue } from "./runtime-util.js";
+import { audienceFromRun, principalKey } from "./audience.js";
+import { applyCoreToolPolicy } from "./security.js";
 import { parseSkillBody } from "./self-improvement.js";
+import { initiatorFromRun, principalFromRun } from "./principals.js";
+import { authorizationRequiredModelOutput } from "./model-visible-interrupts.js";
 /**
  * Runtime-handled tool executors: the builtin skill/discovery tools
- * (load_skill, tool_search, tool_describe), the deferred local tool catalog,
- * the tool-call bookkeeping those paths share, and the connection tool
- * executors together with the connection-registry factories they run against.
+ * (load_skill and tool_search), the deferred tool catalog, the tool-call
+ * bookkeeping those paths share, and the connection tool executors together
+ * with the connection-registry factories they run against.
  * None of these route through an authored tool definition, so their records
  * are written here rather than by executeToolWithRecord in
  * ./tool-execution.js. Imports only the {@link ToolExecutionHost} type from
  * ./tool-execution.js, so the value-level module graph stays acyclic.
  */
-export async function skillLoadDetailsImpl(host, skillName) {
-    await host.ensureSkillsSeeded();
-    const skill = await host.skillStore.get(host.skillScope(), skillName);
-    if (!skill || skill.pending)
+/** Cap on inventory entries returned by load_skill; the full tree stays reachable via list/grep. */
+const LOAD_SKILL_RESOURCE_INVENTORY_LIMIT = 150;
+export async function skillLoadDetailsImpl(host, run, skillName) {
+    await host.ensureSkillsSeeded(run);
+    const skill = await host.skillStore.get(host.skillScopeForRun(run), skillName);
+    if (!skill || skill.pending || skill.archived)
         throw new Error(`Skill not found: ${skillName}`);
     const parsed = parseSkillBody(skill.body);
-    return {
+    const surfacePath = host.surfaceForRun(run).path;
+    const entryPath = host.skillBundleIndex.entrypointPathForSkill(skill.name, surfacePath);
+    const bundle = host.skillBundleIndex.bundleForSkill(skill.name, surfacePath);
+    const closure = host.skillBundleIndex
+        .resourceClosureForSkill(skill.name, surfacePath)
+        .filter((resource) => resource.runtimePath !== entryPath);
+    const details = {
         name: skill.name,
         description: parsed.description || `Skill ${skill.name}`,
         declaredTools: parsed.allowedTools,
         instructions: parsed.instructions,
         origin: skill.origin,
-        path: `/skills/${skill.name}/SKILL.md`
+        path: entryPath,
+        resources: closure
+            .slice(0, LOAD_SKILL_RESOURCE_INVENTORY_LIMIT)
+            .map((resource) => ({ path: resource.runtimePath, size: resource.size, contentType: resource.contentType })),
+        resourceCount: closure.length,
+        resourceBytes: closure.reduce((total, resource) => total + resource.size, 0)
     };
+    if (bundle) {
+        details.bundle = {
+            id: bundle.id,
+            kind: bundle.kind,
+            ...(bundle.plugin ? { plugin: { name: bundle.plugin.name, ...(bundle.plugin.version ? { version: bundle.plugin.version } : {}) } } : {})
+        };
+    }
+    return details;
+}
+/** Resolve a load_skill `path` input: canonical entrypoint paths first, then the legacy shapes. */
+function skillNameFromLoadInput(host, requested) {
+    try {
+        return host.skillBundleIndex.skillNameForEntrypointPath(normalizeResourcePath(requested))
+            ?? skillNameFromSkillPath(requested);
+    }
+    catch {
+        return skillNameFromSkillPath(requested);
+    }
 }
 export function createConnectionRegistryImpl(host, channel, turn) {
     const session = { channel };
@@ -41,18 +75,24 @@ export function createConnectionRegistryImpl(host, channel, turn) {
         session.userId = turn.userId;
     if (turn?.metadata)
         session.metadata = turn.metadata;
+    if (turn?.principal)
+        session.principal = turn.principal;
+    if (turn?.initiator)
+        session.initiator = turn.initiator;
     return new RuntimeConnectionRegistry({
         connections: host.mergedConnections(),
         env: host.env,
         fetch: host.fetch,
         session,
+        audience: turn?.audience ?? { private: true },
+        agentId: host.manifest.agent.id ?? host.manifest.agentRevision,
         grantStore: host.connectionGrantStore,
         authorizationSessionStore: host.connectionAuthorizationSessionStore,
         ...(host.connectionCallbackBaseUrl ? { callbackBaseUrl: host.connectionCallbackBaseUrl } : {}),
         loadDefinition: async (connection) => host.loadConnectionDefinition(connection)
     });
 }
-export function createConnectionRegistryForRunImpl(host, run, fallbackChannel, sandboxHandle) {
+export function createConnectionRegistryForRunImpl(host, run, fallbackChannel, sandboxHandle, selectedConnections) {
     const session = {
         channel: typeof run.input.channel === "string" ? run.input.channel : fallbackChannel
     };
@@ -62,17 +102,26 @@ export function createConnectionRegistryForRunImpl(host, run, fallbackChannel, s
         session.userId = run.input.userId;
     if (isJsonObject(run.input.metadata))
         session.metadata = run.input.metadata;
-    const subagentName = typeof run.input.subagent === "string" ? run.input.subagent : undefined;
-    const scopedConnectionNames = subagentName
-        ? new Set(host.manifest.subagents.find((subagent) => subagent.name === subagentName)?.connections ?? [])
-        : undefined;
+    const principal = principalFromRun(run);
+    const initiator = initiatorFromRun(run);
+    if (principal)
+        session.principal = principal;
+    if (initiator)
+        session.initiator = initiator;
+    const surface = host.surfaceForRun(run);
+    const subagentConnectionNames = surface.path !== "root" ? new Set(surface.connections) : undefined;
+    const scopedConnectionNames = selectedConnections && subagentConnectionNames
+        ? new Set([...selectedConnections].filter((name) => subagentConnectionNames.has(name)))
+        : selectedConnections ?? subagentConnectionNames;
     return new RuntimeConnectionRegistry({
-        connections: scopedConnectionNames
+        connections: (scopedConnectionNames
             ? host.mergedConnections().filter((connection) => scopedConnectionNames.has(connection.name))
-            : host.mergedConnections(),
+            : host.mergedConnections()),
         env: host.env,
         fetch: host.fetch,
         session,
+        audience: audienceFromRun(run),
+        agentId: host.manifest.agent.id ?? host.manifest.agentRevision,
         grantStore: host.connectionGrantStore,
         authorizationSessionStore: host.connectionAuthorizationSessionStore,
         ...(host.connectionCallbackBaseUrl ? { callbackBaseUrl: host.connectionCallbackBaseUrl } : {}),
@@ -108,11 +157,16 @@ export async function beginConnectionAuthorizationImpl(host, connectionName, ses
         resolverSession.conversationId = session.conversationId;
     if (session.userId)
         resolverSession.userId = session.userId;
+    if (session.principal)
+        resolverSession.principal = session.principal;
+    if (session.initiator)
+        resolverSession.initiator = session.initiator;
     const registry = new RuntimeConnectionRegistry({
         connections: host.mergedConnections(),
         env: host.env,
         fetch: host.fetch,
         session: resolverSession,
+        agentId: host.manifest.agent.id ?? host.manifest.agentRevision,
         grantStore: host.connectionGrantStore,
         authorizationSessionStore: host.connectionAuthorizationSessionStore,
         ...(host.connectionCallbackBaseUrl ? { callbackBaseUrl: host.connectionCallbackBaseUrl } : {}),
@@ -126,6 +180,7 @@ export function createConnectionRegistryForSessionImpl(host, session) {
         env: host.env,
         fetch: host.fetch,
         session: session.session,
+        agentId: host.manifest.agent.id ?? host.manifest.agentRevision,
         grantStore: host.connectionGrantStore,
         authorizationSessionStore: host.connectionAuthorizationSessionStore,
         ...(host.connectionCallbackBaseUrl ? { callbackBaseUrl: host.connectionCallbackBaseUrl } : {}),
@@ -135,12 +190,17 @@ export function createConnectionRegistryForSessionImpl(host, session) {
 export async function executeLoadSkillTool(host, run, state, input, idempotencyKey) {
     const raw = isJsonObject(input) ? input : {};
     const requested = stringValue(raw.name) || stringValue(raw.skillName) || stringValue(raw.path);
-    const skillName = requested ? skillNameFromSkillPath(requested) ?? requested : "";
+    const skillName = requested
+        ? skillNameFromLoadInput(host, requested) ?? requested
+        : "";
     const toolCall = await recordRuntimeHandledToolStart(host, run, LOAD_SKILL_TOOL_NAME, input, idempotencyKey);
     try {
         if (!skillName)
             throw new Error("load_skill requires name.");
-        const loaded = await skillLoadDetailsImpl(host, skillName);
+        if (!state.allowedSkills.has(skillName)) {
+            throw new Error(`Skill ${skillName} is not enabled by the current agent capability snapshot.`);
+        }
+        const loaded = await skillLoadDetailsImpl(host, run, skillName);
         let sandboxProjected = false;
         const activeSandbox = state.sandboxHandle.current();
         if (activeSandbox) {
@@ -166,24 +226,109 @@ export async function executeLoadSkillTool(host, run, state, input, idempotencyK
         };
         if (loaded.declaredTools.length > 0)
             output.declaredTools = loaded.declaredTools;
+        if (loaded.bundle)
+            output.bundle = safeJson(loaded.bundle);
+        if (loaded.resourceCount > 0) {
+            output.resources = loaded.resources.map((resource) => safeJson(resource));
+            output.resourceCount = loaded.resourceCount;
+            output.resourceBytes = loaded.resourceBytes;
+            if (loaded.resourceCount > loaded.resources.length) {
+                output.resourceInventoryTruncated = true;
+            }
+        }
         await completeRuntimeHandledTool(host, run, toolCall, LOAD_SKILL_TOOL_NAME, output);
         await host.state.appendEvent(run.id, "skill.loaded", {
             skill: loaded.name,
             origin: loaded.origin,
             path: loaded.path,
+            ...(loaded.bundle ? { bundle: loaded.bundle.id } : {}),
+            resourceCount: loaded.resourceCount,
             sandboxProjected
         });
         return { run: await host.state.getRun(run.id) ?? run, modelOutput: output, skillName: loaded.name };
     }
     catch (error) {
-        return failRuntimeHandledTool(host, run, toolCall, LOAD_SKILL_TOOL_NAME, error, { recoverable: true });
+        return failRuntimeHandledTool(host, run, toolCall, LOAD_SKILL_TOOL_NAME, error);
+    }
+}
+export async function executeHistorySearchTool(host, run, input, idempotencyKey) {
+    const raw = isJsonObject(input) ? input : {};
+    const query = stringValue(raw.query);
+    const scope = stringValue(raw.scope) || "current_conversation";
+    const rawLimit = typeof raw.limit === "number" && Number.isFinite(raw.limit) ? Math.floor(raw.limit) : 8;
+    const limit = Math.min(50, Math.max(1, rawLimit));
+    const toolCall = await recordRuntimeHandledToolStart(host, run, HISTORY_SEARCH_TOOL_NAME, input, idempotencyKey);
+    try {
+        if (!query)
+            throw new Error("history_search requires query.");
+        if (!["current_conversation", "current_channel", "my_conversations"].includes(scope)) {
+            throw new Error(`Unsupported history_search scope: ${scope}`);
+        }
+        const search = {
+            agentScope: host.memoryScopeForRun(run).agentScope,
+            query,
+            limit
+        };
+        if (scope === "current_conversation") {
+            const conversationId = stringValue(run.input.conversationId);
+            if (!conversationId)
+                throw new Error("history_search current_conversation requires an active conversation.");
+            search.conversationId = conversationId;
+        }
+        else if (scope === "current_channel") {
+            const metadata = isJsonObject(run.input.metadata) ? run.input.metadata : {};
+            const source = isJsonObject(metadata.source) ? metadata.source : undefined;
+            const provider = stringValue(source?.provider);
+            const workspaceId = stringValue(source?.workspaceId);
+            const channelId = stringValue(source?.channelId);
+            if (!provider || !workspaceId || !channelId) {
+                throw new Error("history_search current_channel is unavailable because this turn has no attributed channel scope.");
+            }
+            const channel = stringValue(run.input.channel);
+            if (channel)
+                search.channel = channel;
+            search.source = { provider, workspaceId, channelId };
+        }
+        else {
+            if (!audienceFromRun(run).private) {
+                throw new Error("history_search my_conversations is unavailable in a shared conversation.");
+            }
+            const principal = principalFromRun(run);
+            const subject = principal ? principalKey(principal) : stringValue(run.input.userId);
+            if (!subject)
+                throw new Error("history_search my_conversations requires an authenticated conversation subject.");
+            search.subject = subject;
+        }
+        const results = await host.state.searchMessages(search);
+        const output = {
+            query,
+            scope,
+            matches: results.map((result) => {
+                const contentSource = isJsonObject(result.message.content.source) ? result.message.content.source : undefined;
+                const conversationSource = isJsonObject(result.conversationMetadata.source) ? result.conversationMetadata.source : undefined;
+                return {
+                    messageId: result.message.id,
+                    conversationId: result.message.conversationId,
+                    role: result.message.role,
+                    text: previewString(stringValue(result.message.content.text), 1_200),
+                    createdAt: result.message.createdAt,
+                    score: result.score,
+                    source: safeJson(contentSource ?? conversationSource ?? {})
+                };
+            })
+        };
+        await completeRuntimeHandledTool(host, run, toolCall, HISTORY_SEARCH_TOOL_NAME, output);
+        return { run: await host.state.getRun(run.id) ?? run, modelOutput: output };
+    }
+    catch (error) {
+        return failRuntimeHandledTool(host, run, toolCall, HISTORY_SEARCH_TOOL_NAME, error);
     }
 }
 export async function executeToolSearchTool(host, run, state, input, idempotencyKey) {
     const request = normalizeDeferredToolSearchInput(input);
     const toolCall = await recordRuntimeHandledToolStart(host, run, TOOL_SEARCH_TOOL_NAME, input, idempotencyKey);
     try {
-        const local = await searchDeferredLocalTools(host, request.query, request.limit);
+        const local = searchDeferredTools(host, run, request.query, request.limit);
         const connectionResults = state.connectionRegistry.hasLiveConnections()
             ? await state.connectionRegistry.search({
                 keywords: request.query,
@@ -195,7 +340,16 @@ export async function executeToolSearchTool(host, run, state, input, idempotency
                 toolName: TOOL_SEARCH_TOOL_NAME
             })
             : [];
-        for (const result of connectionResults) {
+        const connectionFailures = connectionResults.filter((result) => result.error && result.needsAuthorization !== true);
+        const connectionStatuses = connectionResults.filter((result) => result.needsAuthorization === true);
+        const connectionMatches = connectionResults.filter((result) => !result.error);
+        const actionableConnectionMatches = connectionMatches.filter((result) => result.qualifiedName && result.tool && result.inputSchema);
+        if (connectionFailures.length > 0 && local.length === 0 && actionableConnectionMatches.length === 0) {
+            throw new Error(`Deferred connection tool discovery failed: ${connectionFailures
+                .map((result) => `${result.connection}: ${result.error}`)
+                .join("; ")}`);
+        }
+        for (const result of actionableConnectionMatches) {
             if (!result.qualifiedName || !result.tool || !result.inputSchema)
                 continue;
             const metadata = {
@@ -208,10 +362,18 @@ export async function executeToolSearchTool(host, run, state, input, idempotency
             if (result.outputSchema)
                 metadata.outputSchema = result.outputSchema;
             state.discoveredConnectionTools.set(result.qualifiedName, metadata);
+            state.activeToolNames.add(result.qualifiedName);
         }
+        for (const tool of local)
+            state.activeToolNames.add(tool.name);
+        const activated = [
+            ...local.map((tool) => tool.name),
+            ...actionableConnectionMatches.flatMap((result) => result.qualifiedName ? [result.qualifiedName] : [])
+        ];
         const output = {
             query: request.query,
-            totalAvailable: deferredLocalTools(host).length + connectionResults.length,
+            totalAvailable: deferredTools(host, run).length + connectionMatches.length,
+            activated,
             matches: [
                 ...local.map((tool) => ({
                     name: tool.name,
@@ -220,84 +382,33 @@ export async function executeToolSearchTool(host, run, state, input, idempotency
                     tags: tool.tags ?? [],
                     aliases: tool.aliases ?? []
                 })),
-                ...connectionResults.map(connectionSearchResultForModel)
+                ...connectionMatches.map(connectionSearchResultForModel)
             ].slice(0, request.limit)
         };
-        await completeRuntimeHandledTool(host, run, toolCall, TOOL_SEARCH_TOOL_NAME, output);
-        return { run: await host.state.getRun(run.id) ?? run, modelOutput: output };
-    }
-    catch (error) {
-        return failRuntimeHandledTool(host, run, toolCall, TOOL_SEARCH_TOOL_NAME, error, { recoverable: true });
-    }
-}
-export async function executeToolDescribeTool(host, run, state, input, idempotencyKey) {
-    const raw = isJsonObject(input) ? input : {};
-    const name = stringValue(raw.name);
-    const toolCall = await recordRuntimeHandledToolStart(host, run, TOOL_DESCRIBE_TOOL_NAME, input, idempotencyKey);
-    try {
-        if (!name)
-            throw new Error("tool_describe requires name.");
-        const local = deferredLocalTools(host).find((tool) => tool.name === name);
-        if (local) {
-            const definition = await host.loadTool(local);
-            const output = {
-                name: local.name,
-                kind: "tool",
-                description: definition.description ?? local.description,
-                inputSchema: safeJson(definition.inputSchema ?? local.inputSchema),
-                outputSchema: safeJson(definition.outputSchema ?? local.outputSchema ?? {})
-            };
-            await completeRuntimeHandledTool(host, run, toolCall, TOOL_DESCRIBE_TOOL_NAME, output);
-            return { run: await host.state.getRun(run.id) ?? run, modelOutput: output };
+        if (connectionStatuses.length > 0) {
+            output.connectionStatuses = connectionStatuses.map(connectionSearchResultForModel);
         }
-        let connection = state.discoveredConnectionTools.get(name);
-        if (!connection && parseQualifiedName(name) && state.connectionRegistry.hasLiveConnections()) {
-            const parsed = parseQualifiedName(name);
-            const results = parsed
-                ? await state.connectionRegistry.search({ keywords: parsed.toolName, connection: parsed.connectionName, limit: 10 }, {
-                    runId: run.id,
-                    toolCallId: toolCall.id,
-                    toolName: TOOL_DESCRIBE_TOOL_NAME
-                })
-                : [];
-            const result = results.find((candidate) => candidate.qualifiedName === name);
-            if (result?.qualifiedName && result.tool && result.inputSchema) {
-                connection = {
-                    connection: result.connection,
-                    name: result.tool,
-                    qualifiedName: result.qualifiedName,
-                    description: result.description,
-                    inputSchema: result.inputSchema,
-                    ...(result.outputSchema ? { outputSchema: result.outputSchema } : {})
-                };
-                state.discoveredConnectionTools.set(name, connection);
-            }
+        if (connectionFailures.length > 0) {
+            output.connectionErrors = connectionFailures.map(connectionSearchResultForModel);
         }
-        if (!connection)
-            throw new Error(`Deferred tool not found: ${name}`);
-        const output = {
-            name: connection.qualifiedName,
-            kind: "connection_tool",
-            connection: connection.connection,
-            description: connection.description,
-            inputSchema: safeJson(connection.inputSchema),
-            outputSchema: safeJson(connection.outputSchema ?? {})
-        };
-        await completeRuntimeHandledTool(host, run, toolCall, TOOL_DESCRIBE_TOOL_NAME, output);
+        await completeRuntimeHandledTool(host, run, toolCall, TOOL_SEARCH_TOOL_NAME, output);
         return { run: await host.state.getRun(run.id) ?? run, modelOutput: output };
     }
     catch (error) {
-        return failRuntimeHandledTool(host, run, toolCall, TOOL_DESCRIBE_TOOL_NAME, error, { recoverable: true });
+        return failRuntimeHandledTool(host, run, toolCall, TOOL_SEARCH_TOOL_NAME, error);
     }
 }
-export function deferredLocalTools(host) {
-    return runtimeToolsForManifest(host.manifest)
-        .filter((tool) => !CORE_HARNESS_TOOL_NAMES.includes(tool.name))
-        .filter((tool) => tool.visibility !== "hidden");
+export function deferredTools(host, run) {
+    return runtimeToolsForSurface(host.surfaceForRun(run).tools)
+        .filter((tool) => tool.visibility === "deferred")
+        .flatMap((tool) => {
+        const policyTool = applyCoreToolPolicy(tool, host.coreToolPolicy);
+        return policyTool ? [policyTool] : [];
+    });
 }
-async function searchDeferredLocalTools(host, query, limit) {
+function searchDeferredTools(host, run, query, limit) {
     const lower = query.toLowerCase();
-    return deferredLocalTools(host)
+    return deferredTools(host, run)
         .map((tool) => ({
         tool,
         haystack: [
@@ -312,13 +423,14 @@ async function searchDeferredLocalTools(host, query, limit) {
         .map((entry) => entry.tool)
         .slice(0, limit);
 }
-async function recordRuntimeHandledToolStart(host, run, toolName, input, idempotencyKey) {
+export async function recordRuntimeHandledToolStart(host, run, toolName, input, idempotencyKey) {
     await host.state.appendEvent(run.id, "tool.call_requested", { toolName, input: redactedToolInput(input) });
     let toolCall = await host.state.createToolCall({
         runId: run.id,
         toolName,
         status: "requested",
-        input: redactedToolInput(input),
+        // Raw, not redacted: resume paths re-execute persisted tool-call input.
+        input: safeJson(input),
         idempotencyKey
     });
     toolCall = await host.state.updateToolCall(toolCall.id, { status: "running" });
@@ -337,21 +449,86 @@ async function completeRuntimeHandledTool(host, run, toolCall, toolName, output)
         modelOutput: safeJson(output)
     });
 }
+/**
+ * Finalize a durably recordable model-invoked tool failure. Tool failures are
+ * model results, not run failures; callers only throw when durable state cannot
+ * be written and continuing would therefore be unsafe.
+ */
 export async function failRuntimeHandledTool(host, run, toolCall, toolName, error, options) {
     const message = error instanceof Error ? error.message : String(error);
+    const failureKind = options?.failureKind
+        ?? (isRecoverableToolError(error) ? "invalid_input" : "execution_error");
+    const modelOutput = {
+        error: message,
+        failure: {
+            kind: failureKind,
+            runCanContinue: true
+        }
+    };
     await host.state.updateToolCall(toolCall.id, { status: "failed", error: message });
-    await host.state.appendEvent(run.id, "tool.execution_failed", { toolCallId: toolCall.id, toolName, error: message });
-    if (options?.recoverable) {
-        // Model-invoked discovery tools: return the error to the model to reason
-        // over rather than irreversibly failing the whole run.
-        return { run, modelOutput: { error: message } };
-    }
-    const failedRun = await failRun({ state: host.state }, run.id, {
-        reason: "tool.execution_failed",
+    await host.state.appendEvent(run.id, "tool.execution_failed", {
+        toolCallId: toolCall.id,
+        toolName,
         error: message,
-        data: { toolCallId: toolCall.id, toolName }
+        failureKind,
+        recoverable: true
     });
-    return { run: failedRun, modelOutput: { error: message } };
+    return { run: await host.state.getRun(run.id) ?? run, modelOutput };
+}
+/** Event appended whenever a pair call cannot proceed for a connection. */
+export const CONNECTION_PAIRING_UNAVAILABLE_EVENT = "connection.pairing_unavailable";
+/**
+ * The core `pair` tool: redeem a user-pasted one-time binding packet against a
+ * live connection, host-side. Unlike the synthetic `<connection>__pair`
+ * discovery tool this executor never requires prior discovery, and when no
+ * connection can pair it reports the per-connection resolve failures instead
+ * of a generic "not exposed" dead end. Errors are recoverable: the model
+ * relays the cause to the user rather than failing the run.
+ */
+export async function executePairTool(host, run, registry, input, idempotencyKey) {
+    const toolCall = await recordRuntimeHandledToolStart(host, run, PAIR_TOOL_NAME, input, idempotencyKey);
+    try {
+        const raw = isJsonObject(input) ? input : {};
+        const secret = typeof raw.secret === "string" ? raw.secret.trim() : "";
+        const requested = typeof raw.connection === "string" ? raw.connection.trim() : "";
+        if (!secret)
+            throw new Error("pair requires the full pasted packet or claim code as `secret`.");
+        const status = await registry.pairingStatus();
+        const target = requested || (status.pairable.length === 1 ? status.pairable[0] : "");
+        if (!target) {
+            if (status.pairable.length > 1) {
+                throw new Error(`Multiple connections support pairing (${status.pairable.join(", ")}); pass the intended one as \`connection\`.`);
+            }
+            throw await pairingUnavailableError(host, run, status.unavailable);
+        }
+        if (!status.pairable.includes(target)) {
+            const failure = status.unavailable.find((item) => item.connection === target);
+            if (failure)
+                throw await pairingUnavailableError(host, run, [failure]);
+        }
+        // Redemption re-validates the target (registered, private-surface access,
+        // pairing support) and reports the precise refusal to the model.
+        const result = await registry.redeemPairingCode(target, secret);
+        const output = { connected: true, connection: result.connection, message: result.message };
+        await completeRuntimeHandledTool(host, run, toolCall, PAIR_TOOL_NAME, output);
+        return { run: await host.state.getRun(run.id) ?? run, modelOutput: output };
+    }
+    catch (error) {
+        return failRuntimeHandledTool(host, run, toolCall, PAIR_TOOL_NAME, error);
+    }
+}
+// Persist why pairing is impossible before the error reaches the model, so an
+// operator can see the cause in the event log even if the conversation moves on.
+async function pairingUnavailableError(host, run, unavailable) {
+    for (const item of unavailable) {
+        await host.state.appendEvent(run.id, CONNECTION_PAIRING_UNAVAILABLE_EVENT, {
+            connection: item.connection,
+            reason: item.reason
+        });
+    }
+    if (unavailable.length === 0)
+        return new Error("No live connection supports pairing.");
+    return new Error(`No connection can pair right now: ${unavailable.map((item) => `${item.connection}: ${item.reason}`).join("; ")}`);
 }
 export async function executeConnectionSearchTool(host, run, registry, input, idempotencyKey) {
     await host.state.appendEvent(run.id, "tool.call_requested", { toolName: CONNECTION_SEARCH_TOOL_NAME, input: redactedToolInput(input) });
@@ -359,7 +536,8 @@ export async function executeConnectionSearchTool(host, run, registry, input, id
         runId: run.id,
         toolName: CONNECTION_SEARCH_TOOL_NAME,
         status: "requested",
-        input: redactedToolInput(input),
+        // Raw, not redacted: resume paths re-execute persisted tool-call input.
+        input: safeJson(input),
         idempotencyKey
     });
     await host.state.updateToolCall(toolCall.id, { status: "running" });
@@ -394,17 +572,24 @@ export async function executeConnectionSearchTool(host, run, registry, input, id
         // Recoverable: model-invoked discovery, so return the error, don't fail the run.
         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: CONNECTION_SEARCH_TOOL_NAME, error: message });
+        await host.state.appendEvent(run.id, "tool.execution_failed", {
+            toolCallId: toolCall.id,
+            toolName: CONNECTION_SEARCH_TOOL_NAME,
+            error: message,
+            failureKind: "execution_error",
+            recoverable: true
+        });
         return { run: await host.state.getRun(run.id) ?? run, results: [{ connection: "connection_search", description: "Connection search failed.", error: message }] };
     }
 }
-export async function executeConnectionTool(host, run, registry, toolName, input, approved, idempotencyKey) {
+export async function executeConnectionTool(host, run, registry, toolName, input, approved, idempotencyKey, authorizationBehavior = "pause") {
     await host.state.appendEvent(run.id, "tool.call_requested", { toolName, input: redactedToolInput(input) });
     let toolCall = await host.state.createToolCall({
         runId: run.id,
         toolName,
         status: "requested",
-        input: redactedToolInput(input),
+        // Raw, not redacted: connection-auth resume re-executes this input.
+        input: safeJson(input),
         idempotencyKey
     });
     const parsed = parseQualifiedName(toolName);
@@ -425,7 +610,7 @@ export async function executeConnectionTool(host, run, registry, toolName, input
             toolName,
             source: "eval"
         });
-        return executeConnectionToolWithRecordImpl(host, run, registry, toolName, toolCall, input);
+        return executeConnectionToolWithRecordImpl(host, run, registry, toolName, toolCall, input, authorizationBehavior);
     }
     if (approval.mode !== "never" && !approved) {
         toolCall = await host.state.updateToolCall(toolCall.id, { status: "waiting_for_approval" });
@@ -442,9 +627,9 @@ export async function executeConnectionTool(host, run, registry, toolName, input
         });
         return { run: waitingRun, waitingForApproval: true, toolCallId: toolCall.id, toolName };
     }
-    return executeConnectionToolWithRecordImpl(host, run, registry, toolName, toolCall, input);
+    return executeConnectionToolWithRecordImpl(host, run, registry, toolName, toolCall, input, authorizationBehavior);
 }
-export async function executeConnectionToolWithRecordImpl(host, run, registry, toolName, toolCall, input) {
+export async function executeConnectionToolWithRecordImpl(host, run, registry, toolName, toolCall, input, authorizationBehavior = "pause") {
     await host.state.updateToolCall(toolCall.id, { status: "running" });
     await host.state.appendEvent(run.id, "tool.execution_started", { toolCallId: toolCall.id, toolName });
     try {
@@ -472,9 +657,13 @@ export async function executeConnectionToolWithRecordImpl(host, run, registry, t
     }
     catch (error) {
         if (isConnectionAuthorizationRequiredError(error)) {
-            await host.state.updateToolCall(toolCall.id, { status: "failed", error: error.message });
-            const waitingRun = await host.state.updateRun(run.id, { status: "waiting_for_connection" });
             const authorizationSessionId = isJsonObject(error.challenge) && typeof error.challenge.sessionId === "string" ? error.challenge.sessionId : undefined;
+            const modelOutput = authorizationRequiredModelOutput(error);
+            await host.state.updateToolCall(toolCall.id, {
+                status: "failed",
+                error: error.message,
+                modelOutput
+            });
             await host.state.appendEvent(run.id, "authorization.required", {
                 toolCallId: toolCall.id,
                 toolName,
@@ -482,20 +671,39 @@ export async function executeConnectionToolWithRecordImpl(host, run, registry, t
                 reason: error.reason,
                 challenge: safeJson(error.challenge ?? {})
             });
+            if (authorizationBehavior === "return") {
+                await host.state.appendEvent(run.id, "authorization.returned_to_model", {
+                    toolCallId: toolCall.id,
+                    toolName,
+                    connectionName: error.connectionName,
+                    recoverable: true
+                });
+                return {
+                    run: await host.state.getRun(run.id) ?? run,
+                    modelOutput,
+                    toolCallId: toolCall.id,
+                    toolName
+                };
+            }
+            const waitingRun = await host.state.updateRun(run.id, { status: "waiting_for_connection" });
             const out = { run: waitingRun, waitingForConnection: true, toolCallId: toolCall.id, toolName };
             if (authorizationSessionId)
                 out.authorizationSessionId = authorizationSessionId;
             return out;
         }
-        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, error: message });
-        const failedRun = await failRun({ state: host.state }, run.id, {
-            reason: "connection.tool_failed",
-            error: message,
-            data: { toolCallId: toolCall.id, toolName }
+        // Every connection failure that reached a model-invoked tool boundary is
+        // returned through the normal result channel. The model may correct its
+        // arguments, choose another connection, or explain configuration trouble
+        // to the user. Authorization remains the explicit pause path above.
+        const failure = await failRuntimeHandledTool(host, run, toolCall, toolName, error, {
+            failureKind: isConnectionConfigurationError(error) ? "configuration_error" : "execution_error"
         });
-        return { run: failedRun, modelOutput: { error: message }, toolCallId: toolCall.id, toolName };
+        return {
+            run: failure.run,
+            modelOutput: failure.modelOutput,
+            toolCallId: toolCall.id,
+            toolName
+        };
     }
 }
 //# sourceMappingURL=builtin-tool-executors.js.map