agentfootprint 10.4.0 → 10.5.0

package/dist/core/Agent.js

@@ -190,6 +190,7 @@ const armed_js_1 = require("./agent/honesty/armed.js");
 const mounts_js_1 = require("./agent/honesty/mounts.js");
 const messageFrom_js_1 = require("./messageFrom.js");
 const memberRun_js_1 = require("./memberRun.js");
+const requestOfRun_js_1 = require("./requestOfRun.js");
 const toolShownArgs_js_1 = require("./toolShownArgs.js");
 const toolResultCap_js_1 = require("./agent/toolResultCap.js");
 const buildAgentChart_js_1 = require("./agent/buildAgentChart.js");
@@ -393,6 +394,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *  chart mounted in a composition) never stamps a clock nobody declared for
      *  it (`seedClockDraft`). */
     runClockDraft;
+    /** The incoming request each of this agent's OWN scopes serves — recorded
+     *  by the executor that made the scope (`createExecutor`), so a scope keeps
+     *  ITS run's request for as long as it lives: a stage still running after
+     *  its run was aborted can never be served the next run's request. A stage
+     *  mounted in another runner's executor reads its run's request by link
+     *  (`memberRun.ts`). Never written to scope. */
+    scopeRequests = new WeakMap();
     /** The `time` the CURRENT resume passed, as read — TAKEN once by the first
      *  ToolCalls pass of the resumed leg (`ToolCallsHandlerDeps.time`), and
      *  cleared when `run()` or `resume()` ends. */
@@ -1604,6 +1612,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // not at the resume of a pause it would have made impossible to resume.
         (0, callerIdentity_js_1.assertIdentityShape)(runInput.identity, 'Agent.run');
         (0, callerIdentity_js_1.assertIdentityShape)(options?.identity, 'Agent.run');
+        // The incoming request, sealed — refused here when `requestContext` did not build it.
+        const runRequest = (0, requestOfRun_js_1.requestOf)(options, 'Agent.run');
         // A policy handed down for this run is refused here, before anything moves,
         // by the same check `Agent.create({ redact })` gets.
         if (options?.redact !== undefined)
@@ -1612,7 +1622,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // starts — a run with no zone anywhere runs with its zone UNKNOWN (G15),
         // never on the server's zone.
         const clockDraft = this.clockDraftFor(runInput.time ?? options?.time, 'Agent.run');
-        const engineOptions = (0, RunnerBase_js_1.withRunSignalInEnv)(withoutTime(options));
+        // The engine's options; the run's signal (and its deadline) is armed just
+        // before the run starts and released in its `finally` (`runSignalOf`).
+        const engineOptions = withoutTime(options);
         // Timing next, and before the executor exists: both of these refuse a call
         // that would have SUCCEEDED into corrupted per-instance state or an
         // orphaned human question. See ./conversation.ts for why they are throws.
@@ -1645,7 +1657,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // declared at file end via hoisting)
         this.answeredAsk = undefined;
         this.resumePassedTime = undefined;
-        const executor = this.createExecutor(engineOptions);
+        const executor = this.createExecutor(engineOptions, runRequest);
         this.inFlightRunId = this.currentRunContext.runId;
         // One disposition ledger per run (9.60.0) — registration mirrors what
         // this agent's configuration makes applicable; dev posture runs the
@@ -1674,6 +1686,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // Set here, beside the `try` whose `finally` clears it, so no exit path
         // can leave it behind for a turn this `run()` did not start.
         this.runClockDraft = clockDraft;
+        // Armed here, beside the `try` whose `finally` releases it: no refused
+        // call above can leave a deadline running.
+        const runSignal = (0, RunnerBase_js_1.runSignalOf)(engineOptions);
         try {
             const result = await executor.run({
                 input: {
@@ -1692,7 +1707,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 // budget — give it headroom (×2 + 10 covers double-hop loop shapes).
                 // Consumer-provided options win.
                 maxIterations: this.maxIterations * 2 + 10,
-                ...(engineOptions ?? {}),
+                ...(runSignal.options ?? {}),
             });
             const finalized = this.finalizeResult(executor, result);
             if (typeof finalized === 'string')
@@ -1789,6 +1804,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             throw cause;
         }
         finally {
+            // The run's deadline and signal links end with the run (`runSignalOf`).
+            runSignal.release();
             // The time layer's per-run inputs end with the run: a stale draft would
             // be stamped by the next seed this agent did not start (a composition
             // mounting its chart) as if the app had declared it.
@@ -1953,6 +1970,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // else's conversation.
         this.assertNotRunning('Agent.resumeOnError');
         this.assertNoPendingQuestion('Agent.resumeOnError');
+        // A request `run()` would refuse is refused HERE, before the side channel
+        // below is armed — a refusal after it would leave the restored history for
+        // the next, unrelated run.
+        (0, requestOfRun_js_1.requestOf)(options, 'Agent.resumeOnError');
         // Stash the checkpointed history on the side channel; the seed function
         // reads + clears it before scope.history initializes. No message is
         // appended — the failing run's message is already the last user turn in
@@ -2144,6 +2165,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         (0, callerIdentity_js_1.assertIdentityShape)(options?.identity, 'Agent.resume');
         if (options?.redact !== undefined)
             (0, policy_js_1.assertRedactionPolicy)(options.redact, 'Agent.resume');
+        // The incoming request is the RESUMING caller's — never the paused one's:
+        // a checkpoint carries no request, and a resume without one serves none.
+        const resumeRequest = (0, requestOfRun_js_1.requestOf)(options, 'Agent.resume');
         // Native guard lands with the new checkpoint protocol, before its runtime
         // opt-in is mounted. Until then no Agent is armed to consume this carrier.
         (0, verificationCheckpoint_js_1.requireVerificationOnResume)(checkpoint.sharedState ?? {}, false);
@@ -2159,7 +2183,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // moves; it is never applied — the paused turn's clock is kept, and a
         // differing value is recorded by the ToolCalls resume door.
         const passedTime = this.passedTimeFor(options?.time, 'Agent.resume');
-        options = (0, RunnerBase_js_1.withRunSignalInEnv)(withoutTime(options));
+        options = withoutTime(options);
         const gate = (0, pause_js_1.pauseDemandsDecision)(checkpoint.pauseData);
         if (gate && !(0, checkin_js_1.isCheckInDecision)(input))
             throw new pause_js_1.DecisionRequiredError(gate, input);
@@ -2270,7 +2294,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // (and only when) it completes.
         const recording = this.startRunRecording();
         this.answeredAsk = answeredAsk;
-        const executor = this.createExecutor(resumeOptions);
+        const executor = this.createExecutor(resumeOptions, resumeRequest);
         // The leg's WHOLE policy rides its own state too (`runRedaction`), so a
         // later pause carries what this leg was covered by — names the resume
         // added included — and a third leg is never less covered than this one.
@@ -2305,8 +2329,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                     runRedaction: (0, conversation_js_2.carriedRunPolicy)(leg.policy),
                 },
             };
+        // A resume arms its own run signal and deadline (`runSignalOf`), released in
+        // the `finally` below.
+        const runSignal = (0, RunnerBase_js_1.runSignalOf)(resumeOptions);
         try {
-            const result = await executor.resume(legCheckpoint, input, resumeOptions);
+            const result = await executor.resume(legCheckpoint, input, runSignal.options);
             const finalized = this.finalizeResult(executor, result);
             if (typeof finalized === 'string')
                 this.lastRunAnswer = finalized;
@@ -2324,6 +2351,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             throw cause;
         }
         finally {
+            runSignal.release();
             // A resume's passed `time` ends with the resume (the fresh-run path's terms).
             this.resumePassedTime = undefined;
             // Same terms as the fresh-run path: rows on every exit, before the
@@ -2929,8 +2957,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         return (0, types_js_2.checkerGoverns)(this.permissionChecker, 'skill_read');
     }
     // FOLD (resolver) · computes "which skill ids may this caller be told about".
-    // The OWNER of the published fact is src/core/slots/buildToolsSlot.ts · discoverStage, which
-    // resolves it once per iteration and publishes it on scope; every model-facing composer reads THAT.
+    // The OWNER of the published fact is src/injection-engine/buildInjectionEngineSubflow.ts · hiddenSkillIdsOf
+    // (the engine's Gather stage), which resolves it once per iteration, before the cursor and the
+    // evaluator decide, and publishes it on scope; every model-facing composer reads THAT.
     // Second caller: the turn router (stages/routeTurn.ts · resolveHidden) resolves it again, with different
     // failure semantics, and publishes nothing — two sweeps of one policy question per turn.
     /**
@@ -3072,7 +3101,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             `not in this release. Use { strategy: 'instruct', retries: N } on this provider — it ` +
             `works on every wire — or run the native strategy on a provider that declares it.`);
     }
-    createExecutor(runOptions) {
+    createExecutor(runOptions, request) {
         this.assertDeliverableRoles();
         this.assertForcedToolChoiceSupported();
         this.assertNativeOutputSchemaSupported();
@@ -3137,14 +3166,19 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // (`memberRun.ts`) — per scope, never by instance state.
         const scopeFactory = redaction.scopeFactoryFor(spec);
         const ownScopes = this.ownScopes;
+        const scopeRequests = this.scopeRequests;
         const executor = new footprintjs_1.FlowChartExecutor(spec, {
             readTracking: this.readTracking,
             commitValues: this.commitValues,
             writeProvenance: this.writeProvenance,
             scopeFactory: (...args) => {
                 const scope = scopeFactory(...args);
-                if (scope !== null && typeof scope === 'object')
+                if (scope !== null && typeof scope === 'object') {
                     ownScopes.add(scope);
+                    // THIS executor's request, bound to the scope for its whole life.
+                    if (request !== undefined)
+                        scopeRequests.set(scope, request);
+                }
                 return scope;
             },
         });
@@ -4121,6 +4155,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // on ruled tools, and the run's `messageFrom` constant is written — only
             // under the arm (refused at build without the inputs layer).
             ...(this.argumentSourcesArmed === true && { argumentSources: true }),
+            // The answer check's tool-call ledger — value-conditional, so an agent
+            // without `answerValidation` hands seed the deps it always did.
+            ...(this.answerValidationConfig !== undefined && { toolCallLedger: true }),
             get consumePendingResumeFindingsLedger() {
                 return ledgerRestoreArmed ? consumeResumeLedger : undefined;
             },
@@ -4386,8 +4423,15 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // never drift from the verdicts. Open ids are fixed after build, so they
         // are computed once, exactly as the offer builder does.
         const openForReachable = this.skillGraphReachable ? this.openSkillIds() : [];
+        // Per-role skill visibility (9.11.0). The RESOLVER is handed to the
+        // Injection Engine, the fact's one owner: its Gather stage resolves the
+        // ids once per iteration, BEFORE anything decides, so the cursor and the
+        // evaluator refuse a hidden skill on every activation path; the mount
+        // publishes them on scope for every model-facing composer after it.
+        const hiddenSkillIdsForEngine = this.hiddenSkillIdsNow();
         const injectionEngineSubflow = (0, buildInjectionEngineSubflow_js_1.buildInjectionEngineSubflow)({
             injections: this.injections,
+            ...(hiddenSkillIdsForEngine && { hiddenSkillIds: hiddenSkillIdsForEngine }),
             ...(this.skillGraphNextSkill && { nextSkill: this.skillGraphNextSkill }),
             ...(this.skillGraphExplainNextSkill && {
                 explainNextSkill: this.skillGraphExplainNextSkill,
@@ -4501,10 +4545,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             notServed: toolCalls_js_1.notServedResult,
         });
         const readSkillFor = this.readSkillOfferFor();
-        // Per-role skill visibility. The RESOLVER is handed to the tools slot, which
-        // is the fact's one owner: it resolves the ids once per iteration and
-        // publishes them on scope (`buildToolsSlot.ts` · `discoverStage`). Since 9.86.0 the
-        // description is NOT the only reader — the read_skill gate's refusals, the
+        // Per-role skill visibility. The Injection Engine resolves the ids once per
+        // iteration and publishes them on scope (`buildInjectionEngineSubflow.ts` ·
+        // `hiddenSkillIdsOf`); the tools slot reads that published set through its
+        // mount. Since 9.86.0 the description is NOT the only reader — the read_skill gate's refusals, the
         // `skill.rejected` payload, the propose-transition refusal and the dispatch
         // roster all filter through that published set
         // (`stages/toolCalls.ts` · "── Skill-graph read_skill GATE" the gate, `toolCalls.ts` ·
@@ -4514,7 +4558,6 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // the self-call notice's move offer through them; the notice no longer names
         // a destination at all (see `selfCallNotice`), so there is nothing left to
         // filter and the cache went with the clause that needed it.
-        const hiddenSkillIds = this.hiddenSkillIdsNow();
         // Registration-time owner stamps (9.60.0) — the identity edges the
         // integrity checks read. Built once per chart from the registry.
         const toolOwners = new Map(registry
@@ -4584,7 +4627,6 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             toolClaimants,
             servedTools,
             ...(readSkillFor && { readSkillFor }),
-            ...(hiddenSkillIds && { hiddenSkillIds }),
             ...(budget?.tools !== undefined && { budgetCap: budget.tools }),
             // Steps (9.18.0): per-step narrowing + banner + the skip_step offer.
             ...(stepPlanFor !== undefined && { stepPlanFor }),
@@ -4945,6 +4987,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             toolClaimants,
             ...(permissionChecker && { permissionChecker }),
             ...(credentialProvider && { credentialProvider }),
+            // The request a call's credential is read for: this agent's own run's,
+            // or — on a mount — the run its link names (`memberRun.ts`). An accessor,
+            // because the chart is built once and the request is per run.
+            ...(credentialProvider && {
+                currentRequest: (scope) => this.ownScopes.has(scope) ? this.scopeRequests.get(scope) : (0, memberRun_js_1.memberRequestIn)(scope),
+            }),
             // The claim-check store (9.21.0). Absent → not one new line runs in
             // dispatch: `ctx.artifacts` is the fail-closed teacher and no artifact
             // event can fire (zero-cost-when-unused).
@@ -4961,6 +5009,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // the VALUE-conditional pattern, so an agent on the default hands the
             // handler exactly the deps object it always did.
             ...(this.repeatedCallNudge === false && { repeatedCallNudge: false }),
+            // The answer check's tool-call ledger (`context.toolCalls`) — kept ONLY
+            // when `answerValidation` is configured, so no other agent's record changes.
+            ...(this.answerValidationConfig !== undefined && {
+                toolCallLedger: { maxCalls: this.answerValidationConfig.limits.maxToolCalls },
+            }),
             // Skill-graph read_skill gate: bound the model's read_skill jumps to the
             // reachable set from the current cursor. Undefined → gate off (back-compat).
             ...(this.skillGraphReachable && {