agentfootprint 10.3.1 → 10.5.0

package/dist/esm/core/agent/stages/toolCalls.d.ts

@@ -57,6 +57,7 @@ import { type SkillTargetClass } from '../../../injection-engine/skillGraph.js';
 import { type SpokenIds } from '../../../lib/spokenIds.js';
 import type { ToolProvider } from '../../../tools/toolProvider.js';
 import type { CredentialProvider } from '../../../identity/types.js';
+import { type RequestContext } from '../../../identity/requestContext.js';
 import type { ArtifactStore } from '../../../artifacts/types.js';
 import { type ArtifactPlacement } from '../../../artifacts/placement.js';
 import type { AuthorizationRequiredMode } from '../../../identity/consent.js';
@@ -291,6 +292,16 @@ export interface ToolCallsHandlerDeps {
      *  declared `needs` is resolved BEFORE execute and injected as `ctx.credential`;
      *  `ctx.credentials` exposes it for the pull escape hatch. */
     readonly credentialProvider?: CredentialProvider;
+    /**
+     * The incoming request a call made in `scope` serves — the agent's own run's
+     * for its own scopes, the run a composition's link names on a mount, and
+     * `undefined` where no run carries one. Every credential call made in that
+     * scope (declared `needs`, the pull path, inner `ctx.tools` calls) carries
+     * it as `CredentialRequest.request` and nothing else (`bindRequest`), so a
+     * request-sourced credential can never serve another run. Absent → no call
+     * carries a request.
+     */
+    readonly currentRequest?: (scope: object) => RequestContext | undefined;
     /**
      * The claim-check store (9.21.0). When present, every dispatch binds it to
      * the run's scope (`scope.runIdentity` — the tuple memory scopes on) as
@@ -340,6 +351,16 @@ export interface ToolCallsHandlerDeps {
      * just authorised would be the framework arguing with the human.
      */
     readonly repeatedCallNudge?: boolean;
+    /**
+     * Keep this run's tool-call ledger (`AgentState.toolCallLedger`) for an
+     * `answerValidation` check: name, call id and outcome per `stream.tool_end`
+     * bracket, at most `maxCalls`. Threaded ONLY on an agent with
+     * `answerValidation` — absent, no bracket writes anything, and the agent
+     * commits exactly the keys it always did.
+     */
+    readonly toolCallLedger?: {
+        readonly maxCalls: number;
+    };
     /**
      * Skill-graph read_skill GATE (`graph.reachableSkills`). When present, a
      * `read_skill('id')` whose `id` is not reachable from the current cursor is
@@ -503,6 +524,16 @@ export interface ToolCallsHandlerDeps {
      *
      * @internal
      */
+    /**
+     * Is this stage running in the agent's OWN executor? Asked of the scope
+     * (`stages/seed.ts` · `isOwnRun`): a stage in another runner's executor — a
+     * composition member — reads its run facts from `scope.memberRun`, never
+     * from {@link currentRun}, which describes the instance's own last run.
+     * Absent → the agent's own run.
+     *
+     * @internal
+     */
+    readonly isOwnRun?: (scope: object) => boolean;
     readonly currentRun?: () => {
         readonly runContext?: import('../../../bridge/eventMeta.js').RunContext;
         readonly runId: string;
@@ -535,7 +566,7 @@ export interface ToolCallsHandlerDeps {
      * @internal
      */
     readonly time?: {
-        readonly takePassedOnResume: () => ReadRunTime | undefined;
+        readonly takePassedOnResume: (scope: object) => ReadRunTime | undefined;
         readonly appZone?: ZoneName;
         /**
          * Present exactly under `.time({ reader })` (step T6b): the batch ask asks

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

@@ -55,6 +55,7 @@ import { checkerGoverns } from '../../../provider-contract/types.js';
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
 import { policyInForce } from '../../../redaction/runRedaction.js';
 import { bindToolSecurityEvents } from '../toolSecurityEvents.js';
+import { appendToolCall, startToolCall, toolOutcomeOf, } from '../../../answer-validation/toolLedger.js';
 import { extractSequence } from '../../../security/extractSequence.js';
 import { skillTarget } from '../../../security/skillTarget.js';
 import { menuOutstanding } from '../../../injection-engine/routingPolicy.js';
@@ -64,6 +65,7 @@ import { selfCallNotice, selfSkillTools } from '../selfCallNotice.js';
 import { parkedMemberIds } from '../../../maps/engagement/types.js';
 import { spoken } from '../../../lib/spokenIds.js';
 import { unconfiguredCredentialProvider } from '../../../identity/types.js';
+import { bindRequest } from '../../../identity/requestContext.js';
 import { bindArtifacts, unconfiguredArtifacts, } from '../../../artifacts/capability.js';
 import { resolveToolWants, wantsNeedsStoreRefusal } from '../../../artifacts/wants.js';
 import { PRESENT_TOOL_NAME, presentArtifact } from '../../../artifacts/present.js';
@@ -77,6 +79,7 @@ import { changedArgKeys, shownArgsOf } from '../../toolShownArgs.js';
 import { toolBytesOf } from '../../../lib/toolBytes.js';
 import { buildToolResolver } from './toolResolver.js';
 import { agentToolDispatch } from '../toolDispatch.js';
+import { runOfLink } from '../../memberRun.js';
 import { runToolChain, runToolAfterChain } from '../../../tools/runChain.js';
 import { recordDecisions } from '../middleware/ledger.js';
 import { ownsReservedArgument, splitFindings } from '../findings/reserved.js';
@@ -775,8 +778,13 @@ export function buildToolCallsHandler(deps) {
     const onAuthorizationRequired = deps.onAuthorizationRequired ?? 'pause';
     // Fail-closed: when no provider is attached, `ctx.credentials` is a provider
     // that THROWS on use (never undefined) — so a tool can't silently no-op.
-    const credentials = deps.credentialProvider ?? unconfiguredCredentialProvider();
+    const baseCredentials = deps.credentialProvider ?? unconfiguredCredentialProvider();
     const hasCredentials = deps.credentialProvider !== undefined;
+    // The provider a call in `scope` is handed: bound to THAT run's request
+    // (or to none), whatever the call itself presents — and only for the one
+    // service the tool DECLARES. A tool reaches a request credential through its
+    // own `needs`, never another service's through the pull path.
+    const credentialsIn = (scope, service) => bindRequest(baseCredentials, deps.currentRequest?.(scope), service);
     // The repeated-call counters (9.26.0), run-keyed and OFF tracked scope — an
     // empty Map here, and not one byte written anywhere a reader can see until a
     // tool actually lands. See `../repeatedCall.ts` for why they are not state.
@@ -1614,8 +1622,60 @@ export function buildToolCallsHandler(deps) {
      * which is a composition's run when this agent is mounted in one — never
      * off the agent's last standalone run.
      */
+    /**
+     * The run facts this dispatch serves. A composition MEMBER's come from the
+     * run it is mounted in (`scope.memberRun`, `core/memberRun.ts`): the
+     * instance's own (`deps.currentRun`) describe some other run — its last
+     * standalone caller, or none — and must never reach this run's tools.
+     */
+    const runFactsOf = (scope) => {
+        // Decided WITHOUT reading the state, so the agent's own runs record
+        // exactly what they always did.
+        if (deps.isOwnRun?.(scope) !== false)
+            return deps.currentRun?.();
+        // A composition's run is looked up by its link — never read off the
+        // record in state. Only a chart a caller built (no link) carries its own.
+        const memberRun = scope.memberRun;
+        const run = memberRun?.link === '' ? memberRun : runOfLink(memberRun?.link);
+        return {
+            runId: run?.runId ?? '',
+            ...(run?.identity !== undefined && { identity: run.identity }),
+        };
+    };
+    /**
+     * THE one door for a `stream.tool_end` bracket in this handler. Every
+     * dispatch path here closes a call through it, so the run's tool-call ledger (when `answerValidation` keeps
+     * one) lists exactly the brackets the stream reported — never arguments,
+     * never results. `ran` is whether the tool's own code ran: a call a person
+     * declined or a rule refused without an `error` is listed `not-run`, never `ok`.
+     */
+    const emitToolEnd = (scope, toolName, payload, ran, declaredStatus = payload.status) => {
+        typedEmit(scope, 'agentfootprint.stream.tool_end', payload);
+        const ledger = deps.toolCallLedger;
+        if (ledger === undefined)
+            return;
+        const prior = scope.toolCallLedger;
+        const next = appendToolCall(prior, { name: toolName, callId: payload.toolCallId, outcome: toolOutcomeOf(payload, ran) }, ledger.maxCalls, 
+        // A tool that declared `pending` returned before its own work settled —
+        // read off what the TOOL declared, before a ceiling or contract refusal
+        // rewrote the bracket's status.
+        declaredStatus !== 'pending' && payload.status !== 'pending');
+        if (next !== prior)
+            scope.toolCallLedger = next;
+    };
+    /** `emitToolEnd`'s twin: the call is open in the ledger until its `tool_end` lands. */
+    const emitToolStart = (scope, payload) => {
+        typedEmit(scope, 'agentfootprint.stream.tool_start', payload);
+        const ledger = deps.toolCallLedger;
+        if (ledger === undefined)
+            return;
+        const prior = scope.toolCallLedger;
+        const next = startToolCall(prior, payload.toolCallId, ledger.maxCalls);
+        if (next !== prior)
+            scope.toolCallLedger = next;
+    };
     const sessionContext = (scope, toolName, toolCallId) => {
-        const facts = deps.currentRun?.();
+        const facts = runFactsOf(scope);
         const redact = policyInForce(scope);
         return {
             ...(facts?.runId !== undefined && { runId: facts.runId }),
@@ -1736,7 +1796,7 @@ export function buildToolCallsHandler(deps) {
      * runIdentity read happens — a storeless agent's trace stays byte-identical.
      */
     const toolArtifacts = (scope, toolName, toolCallId) => {
-        const bindRun = deps.currentRun?.();
+        const bindRun = runFactsOf(scope);
         const emitFact = (type, payload) => {
             const madeIn = bindRun?.runContext;
             const emitForRun = deps.emitForRun;
@@ -1845,7 +1905,7 @@ export function buildToolCallsHandler(deps) {
                     iteration: call.iteration,
                     ...(signal && { signal }),
                     ...(redact !== undefined && { redact }),
-                    credentials: reportingCredentials(credentials, bindToolSecurityEvents(scope, { toolCallId: innerId, iteration: call.iteration }), name),
+                    credentials: reportingCredentials(credentialsIn(scope, registryByName.get(name)?.needs?.credential), bindToolSecurityEvents(scope, { toolCallId: innerId, iteration: call.iteration }), name),
                     hasCredentials,
                     artifacts: unconfiguredArtifacts(),
                     hasArtifacts: false,
@@ -2417,19 +2477,19 @@ export function buildToolCallsHandler(deps) {
      */
     const bracketSettled = (scope, settlement) => {
         for (const { call, result } of settlement.settled) {
-            typedEmit(scope, 'agentfootprint.stream.tool_start', {
+            emitToolStart(scope, {
                 toolName: call.name,
                 toolCallId: call.id,
                 args: peelCall(call).args,
                 parallelCount: settlement.size,
                 notDispatched: notDispatchedMarker(settlement.paused),
             });
-            typedEmit(scope, 'agentfootprint.stream.tool_end', {
+            emitToolEnd(scope, call.name, {
                 toolCallId: call.id,
                 result,
                 durationMs: 0,
                 notDispatched: notDispatchedMarker(settlement.paused),
-            });
+            }, false);
         }
     };
     // Resolve a tool's declared credential (declare-and-push) and execute it,
@@ -2475,7 +2535,7 @@ export function buildToolCallsHandler(deps) {
                 ...(need.mode && { mode: need.mode }),
             });
             try {
-                const cred = await credentials.getCredential({
+                const cred = await credentialsIn(scope, need.credential).getCredential({
                     service: need.credential,
                     ...(need.scopes && { scopes: need.scopes }),
                     ...(need.mode && { mode: need.mode }),
@@ -2545,7 +2605,7 @@ export function buildToolCallsHandler(deps) {
                 iteration,
                 ...(callTime !== undefined && { time: callTime }),
                 ...(env.signal && { signal: env.signal }),
-                credentials: reportingCredentials(credentials, emitSecurity, toolName),
+                credentials: reportingCredentials(credentialsIn(scope, tool.needs?.credential), emitSecurity, toolName),
                 hasCredentials,
                 ...(resolvedCredential && { credential: resolvedCredential }),
                 ...toolArtifacts(scope, toolName, toolCallId),
@@ -2746,7 +2806,7 @@ export function buildToolCallsHandler(deps) {
                 const { askBeforeDispatch } = await import('./argumentAsk.js');
                 const asked = askBeforeDispatch(scope, resolutions, {
                     toolOf: (toolName) => resolveTool(toolName).tool,
-                    runId: () => deps.currentRun?.().runId,
+                    runId: () => runFactsOf(scope)?.runId,
                     ...(deps.argumentAskContext !== undefined && { hostContext: deps.argumentAskContext }),
                     ...(deps.time !== undefined && {
                         time: {
@@ -2896,7 +2956,7 @@ export function buildToolCallsHandler(deps) {
                 if (towers !== undefined) {
                     recordFindings(scope, contingentRowsOf(groundedArgumentValues(args, towers.gate, towers.corpus, towers.exempt), towers.corpus, towers.standingOf, { toolCallId: tc.id }, iteration), turnStampOf(scope));
                 }
-                typedEmit(scope, 'agentfootprint.stream.tool_start', {
+                emitToolStart(scope, {
                     toolName: tc.name,
                     toolCallId: tc.id,
                     args,
@@ -3463,7 +3523,7 @@ export function buildToolCallsHandler(deps) {
                             ...(need.mode && { mode: need.mode }),
                         });
                         try {
-                            const cred = await credentials.getCredential({
+                            const cred = await credentialsIn(scope, need.credential).getCredential({
                                 service: need.credential,
                                 ...(need.scopes && { scopes: need.scopes }),
                                 ...(need.mode && { mode: need.mode }),
@@ -3592,7 +3652,7 @@ export function buildToolCallsHandler(deps) {
                                 iteration,
                                 ...(callTime !== undefined && { time: callTime }),
                                 ...(env.signal && { signal: env.signal }),
-                                credentials: reportingCredentials(credentials, emitSecurity, tc.name),
+                                credentials: reportingCredentials(credentialsIn(scope, tool.needs?.credential), emitSecurity, tc.name),
                                 hasCredentials,
                                 ...(resolvedCredential && { credential: resolvedCredential }),
                                 ...toolArtifacts(scope, tc.name, tc.id),
@@ -3771,7 +3831,7 @@ export function buildToolCallsHandler(deps) {
                                         : declared ?? validateInputDeclaration(declaration);
                                     const awaitingInput = stamped === undefined
                                         ? undefined
-                                        : stampInputRequest(stamped, `${deps.currentRun?.().runId ?? scope.turnStartMs}:${tc.id}`, {
+                                        : stampInputRequest(stamped, `${runFactsOf(scope)?.runId ?? scope.turnStartMs}:${tc.id}`, {
                                             originalRequest: scope.userMessage,
                                             toolCallId: tc.id,
                                             ...(scope.currentSkillId !== undefined && {
@@ -4119,7 +4179,7 @@ export function buildToolCallsHandler(deps) {
                 const capped = capResults(tc.name, placedValues);
                 const modelResult = capped.modelResult;
                 const durationMs = Date.now() - startMs;
-                typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                emitToolEnd(scope, tc.name, {
                     toolCallId: tc.id,
                     result: capped.result,
                     durationMs,
@@ -4137,7 +4197,7 @@ export function buildToolCallsHandler(deps) {
                     ...(modelResult !== capped.result && { modelResult }),
                     ...(executed && changedKeys.length > 0 && { changedArgKeys: changedKeys }),
                     ...(denied && { notExecuted: true }),
-                });
+                }, executed, toolEnvelope?.status);
                 let resultStr = typeof modelResult === 'string' ? modelResult : safeStringify(modelResult);
                 // The tool's OWN answer, before any framework suffix joins it — what
                 // the repeated-call ledger fingerprints. Fingerprinting the decorated
@@ -4209,7 +4269,7 @@ export function buildToolCallsHandler(deps) {
                     // byte-identical to the release before this one. `currentRun()` is
                     // the same accessor `ctx.runId` is composed from — one answer to
                     // "which run is this", not a second spelling of it.
-                    const runKey = deps.currentRun?.().runId ?? UNSCOPED_RUN;
+                    const runKey = runFactsOf(scope)?.runId ?? UNSCOPED_RUN;
                     // `repeatedWhen: 'arguments'` (9.62.0) — read off the RESOLVED tool,
                     // never off the call: only the tool's own definition knows whether
                     // its result is signal or a stamp (a fresh version/timestamp/cursor
@@ -4672,7 +4732,7 @@ export function buildToolCallsHandler(deps) {
                     ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
                 await judgeLanded(scope, deps.findingsJudge, toolRan, { toolName, result: askResultStr, toolCallId }, iteration, turnStampOf(scope));
-                typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                emitToolEnd(scope, toolName, {
                     toolCallId,
                     result: askCapped.result,
                     durationMs: Date.now() - startMs,
@@ -4681,7 +4741,7 @@ export function buildToolCallsHandler(deps) {
                     ...(askCapped.modelResult !== askCapped.result && {
                         modelResult: askCapped.modelResult,
                     }),
-                });
+                }, toolRan);
                 bracketSettled(scope, askSettlement);
                 typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
@@ -4826,7 +4886,7 @@ export function buildToolCallsHandler(deps) {
                     ...(resumeEnvelope?.status !== undefined && { status: resumeEnvelope.status }),
                 });
                 await judgeLanded(scope, deps.findingsJudge, toolRan, { toolName, result: decisionResultStr, toolCallId }, iteration, turnStampOf(scope));
-                typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                emitToolEnd(scope, toolName, {
                     toolCallId,
                     result: decisionCapped.result,
                     durationMs: Date.now() - startMs,
@@ -4835,7 +4895,7 @@ export function buildToolCallsHandler(deps) {
                     ...(decisionCapped.modelResult !== decisionCapped.result && {
                         modelResult: decisionCapped.modelResult,
                     }),
-                });
+                }, toolRan);
                 bracketSettled(scope, decisionSettlement);
                 typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
@@ -4942,7 +5002,7 @@ export function buildToolCallsHandler(deps) {
                     ...(consentEnvelope?.status !== undefined && { status: consentEnvelope.status }),
                 });
                 await judgeLanded(scope, deps.findingsJudge, dispatched.executed === true, { toolName, result: consentResultStr, toolCallId }, iteration, turnStampOf(scope));
-                typedEmit(scope, 'agentfootprint.stream.tool_end', {
+                emitToolEnd(scope, toolName, {
                     toolCallId,
                     result: consentCapped.result,
                     durationMs: Date.now() - startMs,
@@ -4951,7 +5011,7 @@ export function buildToolCallsHandler(deps) {
                     ...(consentCapped.modelResult !== consentCapped.result && {
                         modelResult: consentCapped.modelResult,
                     }),
-                });
+                }, dispatched.executed === true);
                 bracketSettled(scope, consentSettlement);
                 typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                     turnIndex: 0,
@@ -5055,7 +5115,7 @@ export function buildToolCallsHandler(deps) {
             // The person's answer IS the tool's result (the handler's contract
             // above), so it ran by definition.
             await judgeLanded(scope, deps.findingsJudge, true, { toolName, result: resultStr, toolCallId }, iteration, turnStampOf(scope));
-            typedEmit(scope, 'agentfootprint.stream.tool_end', {
+            emitToolEnd(scope, toolName, {
                 toolCallId,
                 // The REAL value the pause returned, not what a rule let the model read
                 // — the same split the other four paths keep. Capped when a ceiling is
@@ -5065,7 +5125,7 @@ export function buildToolCallsHandler(deps) {
                 ...(pauseCapped.modelResult !== pauseCapped.result && {
                     modelResult: pauseCapped.modelResult,
                 }),
-            });
+            }, true);
             bracketSettled(scope, pauseSettlement);
             typedEmit(scope, 'agentfootprint.agent.iteration_end', {
                 turnIndex: 0,