agentfootprint 9.136.0 → 9.138.0

package/dist/esm/core/agent/stages/toolCalls.js

@@ -53,6 +53,7 @@ import { codeRunsOf } from '../../codeRunnerTool.js';
 import { isDevMode } from 'footprintjs';
 import { checkerGoverns } from '../../../adapters/types.js';
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { bindToolSecurityEvents } from '../toolSecurityEvents.js';
 import { extractSequence } from '../../../security/extractSequence.js';
 import { skillTarget } from '../../../security/skillTarget.js';
 import { menuOutstanding } from '../../../lib/injection-engine/routingPolicy.js';
@@ -136,7 +137,7 @@ function errorClassOf(err) {
  * It is a decorator, not a replacement: the same `id`, the same result, the
  * same throw. It only makes a noise on the way past.
  */
-function reportingCredentials(provider, scope, toolName) {
+function reportingCredentials(provider, emitSecurity, toolName) {
     return {
         id: provider.id,
         async getCredential(req) {
@@ -144,7 +145,7 @@ function reportingCredentials(provider, scope, toolName) {
                 return await provider.getCredential(req);
             }
             catch (err) {
-                typedEmit(scope, 'agentfootprint.credential.failed', {
+                emitSecurity('agentfootprint.credential.failed', {
                     service: req.service,
                     reason: err instanceof Error ? err.message : String(err),
                     tool: toolName,
@@ -744,6 +745,28 @@ const madeInRun = (bindRun) => bindRun?.runContext?.runId;
 export function buildToolCallsHandler(deps) {
     const { registryByName, externalToolProvider, providerToolCache, servedTools, toolClaimants, permissionChecker, } = deps;
     const toolArgValidation = deps.toolArgValidation ?? 'enforce';
+    /**
+     * One admission rule for initial and resumed dispatch. Judge against the
+     * wire schema after middleware, before artifact resolution or credentials.
+     * Approval of an ask does not establish schema validity, and a remaining
+     * middleware link may have changed the paused arguments. Credential-consent
+     * checkpoints holding resolved wants data are not converted back to refs.
+     */
+    const argumentRefusal = (scope, tool, args, call) => {
+        if (toolArgValidation === 'off')
+            return undefined;
+        const verdict = validateToolArgs(args, tool.schema.inputSchema);
+        if (verdict.ok)
+            return undefined;
+        typedEmit(scope, 'agentfootprint.validation.args_invalid', {
+            ...call,
+            issues: verdict.issues,
+            enforced: toolArgValidation === 'enforce',
+        });
+        return toolArgValidation === 'enforce'
+            ? formatToolArgIssues(call.toolName, verdict.issues)
+            : undefined;
+    };
     // 8.6.0 — default `'pause'`. Consent is work waiting on a person, and every
     // other place this library needs a person stops the run and asks the caller.
     const onAuthorizationRequired = deps.onAuthorizationRequired ?? 'pause';
@@ -1809,7 +1832,7 @@ export function buildToolCallsHandler(deps) {
                     toolCallId: innerId,
                     iteration: call.iteration,
                     ...(signal && { signal }),
-                    credentials: reportingCredentials(credentials, scope, name),
+                    credentials: reportingCredentials(credentials, bindToolSecurityEvents(scope, { toolCallId: innerId, iteration: call.iteration }), name),
                     hasCredentials,
                     artifacts: unconfiguredArtifacts(),
                     hasArtifacts: false,
@@ -2405,6 +2428,7 @@ export function buildToolCallsHandler(deps) {
     // resume can't re-pause (resume returns void), so that is surfaced as an error.
     const resolveCredentialAndExecute = async (scope, resolved, toolName, args, toolCallId, iteration, env) => {
         const tool = resolved.tool;
+        const emitSecurity = bindToolSecurityEvents(scope, { toolCallId, iteration });
         // The two refusals share one door here too (9.92.0): a name nothing holds,
         // and a name whose offered party cannot answer on this resume.
         if (!tool) {
@@ -2413,6 +2437,9 @@ export function buildToolCallsHandler(deps) {
                 error: true,
             };
         }
+        const invalidArgs = argumentRefusal(scope, tool, args, { toolName, toolCallId, iteration });
+        if (invalidArgs !== undefined)
+            return { result: invalidArgs, error: true };
         noteOffWire(scope, resolved, { toolName, toolCallId, iteration });
         // Declared artifact arguments (9.22.0) — the same resolution the batch
         // loop applies, at this door: a resumed call's refs are judged exactly
@@ -2430,7 +2457,7 @@ export function buildToolCallsHandler(deps) {
         let resolvedCredential;
         const need = tool.needs;
         if (need) {
-            typedEmit(scope, 'agentfootprint.credential.requested', {
+            emitSecurity('agentfootprint.credential.requested', {
                 service: need.credential,
                 ...(need.mode && { mode: need.mode }),
             });
@@ -2448,7 +2475,7 @@ export function buildToolCallsHandler(deps) {
                 });
                 if (cred.status === 'issued') {
                     resolvedCredential = cred.credential;
-                    typedEmit(scope, 'agentfootprint.credential.acquired', {
+                    emitSecurity('agentfootprint.credential.acquired', {
                         service: need.credential,
                         kind: cred.credential.kind,
                         ...(cred.expiresAt !== undefined && { expiresAt: cred.expiresAt }),
@@ -2457,7 +2484,7 @@ export function buildToolCallsHandler(deps) {
                     deps.clearConsentOutstanding?.(need.credential);
                 }
                 else {
-                    typedEmit(scope, 'agentfootprint.credential.authorization_required', {
+                    emitSecurity('agentfootprint.credential.authorization_required', {
                         service: need.credential,
                         sessionId: cred.sessionId,
                     });
@@ -2480,7 +2507,7 @@ export function buildToolCallsHandler(deps) {
             }
             catch (credErr) {
                 const reason = credErr instanceof Error ? credErr.message : String(credErr);
-                typedEmit(scope, 'agentfootprint.credential.failed', {
+                emitSecurity('agentfootprint.credential.failed', {
                     service: need.credential,
                     reason,
                     tool: toolName,
@@ -2505,7 +2532,7 @@ export function buildToolCallsHandler(deps) {
                 iteration,
                 ...(callTime !== undefined && { time: callTime }),
                 ...(env.signal && { signal: env.signal }),
-                credentials: reportingCredentials(credentials, scope, toolName),
+                credentials: reportingCredentials(credentials, emitSecurity, toolName),
                 hasCredentials,
                 ...(resolvedCredential && { credential: resolvedCredential }),
                 ...toolArtifacts(scope, toolName, toolCallId),
@@ -2827,6 +2854,7 @@ export function buildToolCallsHandler(deps) {
             const runIdentity = scope.runIdentity;
             const env = scope.$getEnv();
             for (const tc of toolCalls) {
+                const emitSecurity = bindToolSecurityEvents(scope, { toolCallId: tc.id, iteration });
                 const resolved = resolveTool(tc.name);
                 const tool = resolved.tool;
                 // ── THE PEEL (9.101.0, `.findings()`) — the FIRST read of `tc.args`
@@ -2932,7 +2960,7 @@ export function buildToolCallsHandler(deps) {
                             ...(runIdentity && { identity: runIdentity }),
                             ...(env.signal && { signal: env.signal }),
                         });
-                        typedEmit(scope, 'agentfootprint.permission.check', {
+                        emitSecurity('agentfootprint.permission.check', {
                             capability: 'tool_call',
                             actor: 'agent',
                             target: tc.name,
@@ -2992,7 +3020,7 @@ export function buildToolCallsHandler(deps) {
                         // not belong in a transcript.
                         denied = true;
                         const msg = permErr instanceof Error ? permErr.message : String(permErr);
-                        typedEmit(scope, 'agentfootprint.permission.check', {
+                        emitSecurity('agentfootprint.permission.check', {
                             capability: 'tool_call',
                             actor: 'agent',
                             target: tc.name,
@@ -3029,7 +3057,7 @@ export function buildToolCallsHandler(deps) {
                             ...(runIdentity && { identity: runIdentity }),
                             ...(env.signal && { signal: env.signal }),
                         });
-                        typedEmit(scope, 'agentfootprint.permission.check', {
+                        emitSecurity('agentfootprint.permission.check', {
                             capability,
                             actor: 'agent',
                             target,
@@ -3060,7 +3088,7 @@ export function buildToolCallsHandler(deps) {
                         // whole: an operator's outage text reads as weather to a model.
                         denied = true;
                         const msg = permErr instanceof Error ? permErr.message : String(permErr);
-                        typedEmit(scope, 'agentfootprint.permission.check', {
+                        emitSecurity('agentfootprint.permission.check', {
                             capability,
                             actor: 'agent',
                             target,
@@ -3217,21 +3245,16 @@ export function buildToolCallsHandler(deps) {
                 // tools (their inputSchema is the contract the LLM was shown).
                 // (`argsRejected` is declared above the middleware chain: the inputs
                 // layer's refusals land in the same shape, before the chain.)
-                if (!denied && !argsRejected && tool && toolArgValidation !== 'off') {
-                    const verdict = validateToolArgs(callArgs, tool.schema.inputSchema);
-                    if (!verdict.ok) {
-                        typedEmit(scope, 'agentfootprint.validation.args_invalid', {
-                            toolName: tc.name,
-                            toolCallId: tc.id,
-                            iteration,
-                            issues: verdict.issues,
-                            enforced: toolArgValidation === 'enforce',
-                        });
-                        if (toolArgValidation === 'enforce') {
-                            argsRejected = true;
-                            error = true;
-                            result = formatToolArgIssues(tc.name, verdict.issues);
-                        }
+                if (!denied && !argsRejected && tool) {
+                    const invalidArgs = argumentRefusal(scope, tool, callArgs, {
+                        toolName: tc.name,
+                        toolCallId: tc.id,
+                        iteration,
+                    });
+                    if (invalidArgs !== undefined) {
+                        argsRejected = true;
+                        error = true;
+                        result = invalidArgs;
                     }
                 }
                 // ── Skill-activation gate (9.11.0) ───────────────────────────────
@@ -3407,7 +3430,7 @@ export function buildToolCallsHandler(deps) {
                     let credentialBlocked = false;
                     const need = wantsBlocked ? undefined : tool?.needs;
                     if (need) {
-                        typedEmit(scope, 'agentfootprint.credential.requested', {
+                        emitSecurity('agentfootprint.credential.requested', {
                             service: need.credential,
                             ...(need.mode && { mode: need.mode }),
                         });
@@ -3425,7 +3448,7 @@ export function buildToolCallsHandler(deps) {
                             });
                             if (cred.status === 'issued') {
                                 resolvedCredential = cred.credential;
-                                typedEmit(scope, 'agentfootprint.credential.acquired', {
+                                emitSecurity('agentfootprint.credential.acquired', {
                                     service: need.credential,
                                     kind: cred.credential.kind,
                                     ...(cred.expiresAt !== undefined && { expiresAt: cred.expiresAt }),
@@ -3439,7 +3462,7 @@ export function buildToolCallsHandler(deps) {
                                 // wrong was the tool-result string below, which carried the URL
                                 // to the one party that cannot click it and to every channel
                                 // built to preserve tool output.
-                                typedEmit(scope, 'agentfootprint.credential.authorization_required', {
+                                emitSecurity('agentfootprint.credential.authorization_required', {
                                     service: need.credential,
                                     sessionId: cred.sessionId,
                                 });
@@ -3505,7 +3528,7 @@ export function buildToolCallsHandler(deps) {
                             credentialBlocked = true;
                             error = true;
                             const reason = credErr instanceof Error ? credErr.message : String(credErr);
-                            typedEmit(scope, 'agentfootprint.credential.failed', {
+                            emitSecurity('agentfootprint.credential.failed', {
                                 service: need.credential,
                                 reason,
                                 tool: tc.name,
@@ -3541,7 +3564,7 @@ export function buildToolCallsHandler(deps) {
                                 iteration,
                                 ...(callTime !== undefined && { time: callTime }),
                                 ...(env.signal && { signal: env.signal }),
-                                credentials: reportingCredentials(credentials, scope, tc.name),
+                                credentials: reportingCredentials(credentials, emitSecurity, tc.name),
                                 hasCredentials,
                                 ...(resolvedCredential && { credential: resolvedCredential }),
                                 ...toolArtifacts(scope, tc.name, tc.id),
@@ -4137,14 +4160,13 @@ export function buildToolCallsHandler(deps) {
                 // a ceiling refusal each already teach their own lesson, and stacking
                 // a second one would bury it.
                 //
-                // ONE tool-dispatch door, deliberately. Verified by search, not
-                // assumed: `tool.execute(...)` is invoked from exactly four places in
-                // this library — this batch loop; `resolveCredentialAndExecute`
-                // above (the check-in RESUME door, same file); `mcp/mcpServe.ts`
-                // (serving a tool to an external MCP client); and
-                // `trace-toolpack/traceToolpack.ts` (offline replay against a
-                // recorded run). Only this one, the main ReAct loop, gets the nudge.
-                // The other three never see a live multi-turn conversation the way
+                // Only this batch-loop dispatch gets the nudge. The other dispatch
+                // owners are `resolveCredentialAndExecute` above (resume),
+                // `../toolDispatch.ts` · `agentToolDispatch` (inner calls),
+                // `lib/mcp/mcpServe.ts` (external MCP clients), and
+                // `lib/trace-toolpack/traceToolpack.ts` · `callTraceTool` (offline).
+                // Inner calls are the outer call's work, not another model turn.
+                // The other doors never see a live multi-turn conversation the way
                 // this loop does — a resumed check-in is a single call with no
                 // "again" to notice, an MCP-served call has no ledger to be a run's
                 // (the caller IS the loop, elsewhere), and a trace replay is judging
@@ -4279,11 +4301,10 @@ export function buildToolCallsHandler(deps) {
                 // remaining parallel-call siblings (intentional — once a halt
                 // fires, no further tool dispatches should occur this turn).
                 if (haltContext) {
-                    typedEmit(scope, 'agentfootprint.permission.halt', {
+                    emitSecurity('agentfootprint.permission.halt', {
                         target: tc.name,
                         reason: haltContext.reason,
                         tellLLM: haltContext.tellLLM,
-                        iteration,
                         sequenceLength: extractSequence(newHistory, iteration).length,
                         ...(haltContext.checkerId !== undefined && { checkerId: haltContext.checkerId }),
                     });