agentfootprint 10.3.1 → 10.5.0

package/dist/esm/core/Agent.js

@@ -147,7 +147,7 @@ import { InvalidRunInputError, normalizeRunInput } from './runInput.js';
 import { clockOf } from '../time/rows.js';
 import { draftClock, readRunTime, readTimeOptions, } from '../time/clock.js';
 import { buildOutputRetryStage } from './agent/stages/outputRetry.js';
-import { RunnerBase, makeRunId, withRunSignalInEnv } from './RunnerBase.js';
+import { RunnerBase, makeRunId, runSignalOf } from './RunnerBase.js';
 import { clampIterations, validateMemoryIdUniqueness, validateToolNameUniqueness, } from './agent/validators.js';
 import { buildRouteDeciderStage } from './agent/stages/route.js';
 import { withAnswerValidation } from './agent/stages/answerValidation.js';
@@ -163,6 +163,8 @@ import { isRefused, rulesOf } from '../tools/declare.js';
 import { honestyLayersOf, readInputsLayerOption, } from './agent/honesty/armed.js';
 import { answerFoldReads } from './agent/honesty/mounts.js';
 import { readsMessageFrom } from './messageFrom.js';
+import { memberIdentityIn, memberRequestIn, readsParentRun } from './memberRun.js';
+import { requestOf } from './requestOfRun.js';
 import { carriesArgumentView } from './toolShownArgs.js';
 import { assertMaxToolResultChars } from './agent/toolResultCap.js';
 import { buildAgentChart } from './agent/buildAgentChart.js';
@@ -366,6 +368,13 @@ export class Agent extends 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. */
@@ -635,6 +644,8 @@ export class Agent extends RunnerBase {
      *  Set before the executor is built and cleared in `finally`, so a run that
      *  throws does not leave the agent permanently refusing. */
     inFlightRunId;
+    /** The scopes this agent's OWN executors made — see the `isOwnRun` seed dep. */
+    ownScopes = new WeakSet();
     /** The question a person still owes this agent an answer to. Set when a run
      *  ends paused, cleared by `resume()`, `abandonPause()`, or a run that
      *  completes. Read by the `run()` guard — see `PendingQuestionError`. */
@@ -846,6 +857,9 @@ export class Agent extends RunnerBase {
             // the marker only to a runner that reads it.
             readsMessageFrom(this);
         }
+        // A member runs for the run that mounted it: a composition hands it that
+        // run as `parentRun` (`core/memberRun.ts`).
+        readsParentRun(this);
         if (opts.argumentAskContext !== undefined)
             this.argumentAskContext = opts.argumentAskContext;
         if (opts.toolChoice !== undefined)
@@ -1572,6 +1586,8 @@ export class Agent extends RunnerBase {
         // not at the resume of a pause it would have made impossible to resume.
         assertIdentityShape(runInput.identity, 'Agent.run');
         assertIdentityShape(options?.identity, 'Agent.run');
+        // The incoming request, sealed — refused here when `requestContext` did not build it.
+        const runRequest = 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)
@@ -1580,7 +1596,9 @@ export class Agent extends 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 = 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.
@@ -1613,7 +1631,7 @@ export class Agent extends 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
@@ -1642,6 +1660,9 @@ export class Agent extends 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 = runSignalOf(engineOptions);
         try {
             const result = await executor.run({
                 input: {
@@ -1660,7 +1681,7 @@ export class Agent extends 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')
@@ -1757,6 +1778,8 @@ export class Agent extends 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.
@@ -1921,6 +1944,10 @@ export class Agent extends 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.
+        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
@@ -2112,6 +2139,9 @@ export class Agent extends RunnerBase {
         assertIdentityShape(options?.identity, 'Agent.resume');
         if (options?.redact !== undefined)
             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 = 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.
         requireVerificationOnResume(checkpoint.sharedState ?? {}, false);
@@ -2127,7 +2157,7 @@ export class Agent extends 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 = withRunSignalInEnv(withoutTime(options));
+        options = withoutTime(options);
         const gate = pauseDemandsDecision(checkpoint.pauseData);
         if (gate && !isCheckInDecision(input))
             throw new DecisionRequiredError(gate, input);
@@ -2238,7 +2268,7 @@ export class Agent extends 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.
@@ -2273,8 +2303,11 @@ export class Agent extends RunnerBase {
                     runRedaction: carriedRunPolicy(leg.policy),
                 },
             };
+        // A resume arms its own run signal and deadline (`runSignalOf`), released in
+        // the `finally` below.
+        const runSignal = 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;
@@ -2292,6 +2325,7 @@ export class Agent extends 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
@@ -2897,8 +2931,9 @@ export class Agent extends RunnerBase {
         return 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.
     /**
@@ -2923,8 +2958,10 @@ export class Agent extends RunnerBase {
         const skillIds = this.injections.filter((i) => i.flavor === 'skill').map((i) => i.id);
         if (!checker || skillIds.length === 0)
             return undefined;
-        return async () => {
-            const identity = this.lastRunIdentity;
+        return async (scope) => {
+            // The caller of THIS run: the instance's caller on its own run, the
+            // member's run (never the instance's last caller) on a mount.
+            const identity = this.ownScopes.has(scope) ? this.lastRunIdentity : memberIdentityIn(scope);
             const hidden = [];
             for (const id of skillIds) {
                 let allowed = false;
@@ -3038,7 +3075,7 @@ export class Agent extends 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();
@@ -3098,11 +3135,26 @@ export class Agent extends RunnerBase {
         // commitValues (#13c-B, commit-log value encoding) and writeProvenance
         // (#P1, per-write read provenance — the exact-dataflow debugging dial).
         const spec = this.getSpec();
+        // Every scope THIS executor makes is marked as the agent's own, so a stage
+        // can tell its own run from a mount in another runner's executor
+        // (`memberRun.ts`) — per scope, never by instance state.
+        const scopeFactory = redaction.scopeFactoryFor(spec);
+        const ownScopes = this.ownScopes;
+        const scopeRequests = this.scopeRequests;
         const executor = new FlowChartExecutor(spec, {
             readTracking: this.readTracking,
             commitValues: this.commitValues,
             writeProvenance: this.writeProvenance,
-            scopeFactory: redaction.scopeFactoryFor(spec),
+            scopeFactory: (...args) => {
+                const scope = scopeFactory(...args);
+                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;
+            },
         });
         redaction.applyTo(executor);
         // Enable structured narrative so `getLastNarrativeEntries()` can
@@ -4059,7 +4111,14 @@ export class Agent extends RunnerBase {
             // The time layer's clock: the draft `run()` read (refusing a run with no
             // zone), stamped by seed as the turn's one `clock` row. Absent → the
             // deps object seed always had.
-            ...(this.timeOptions !== undefined && { timeClock: () => this.seedClockDraft() }),
+            // The caller's clock belongs to the agent's OWN run: a member (another
+            // runner's executor) gets the builder's fallback, never a concurrent
+            // direct caller's `time` (`memberRun.ts`).
+            ...(this.timeOptions !== undefined && {
+                timeClock: (scope) => this.ownScopes.has(scope)
+                    ? this.seedClockDraft()
+                    : draftClock(undefined, this.timeOptions ?? {}),
+            }),
             // The time layer's reader: seed reads the person's words once per turn,
             // after the clock. Absent → nothing is read.
             ...(this.timeOptions?.reader !== undefined &&
@@ -4070,6 +4129,9 @@ export class Agent extends 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;
             },
@@ -4140,6 +4202,10 @@ export class Agent extends RunnerBase {
             // the same reason the runId is: the chart is built once, and this
             // changes every run.
             getCurrentSessionId: () => this.currentRunContext?.sessionId,
+            // Whether this stage runs in THIS agent's own executor, or inside another
+            // runner's (a composition, a chart a caller built) — where the accessors
+            // above describe some other run (`memberRun.ts`). Asked per scope.
+            isOwnRun: (scope) => this.ownScopes.has(scope),
             // WHICH TURN THIS IS (9.6.0). Only memories that WRITE the conversation
             // are consulted: they are the ones whose entry ids are turn-stamped, and
             // a corpus (`.rag(...)`, which reads under its own namespace) has no
@@ -4331,8 +4397,15 @@ export class Agent extends 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 = buildInjectionEngineSubflow({
             injections: this.injections,
+            ...(hiddenSkillIdsForEngine && { hiddenSkillIds: hiddenSkillIdsForEngine }),
             ...(this.skillGraphNextSkill && { nextSkill: this.skillGraphNextSkill }),
             ...(this.skillGraphExplainNextSkill && {
                 explainNextSkill: this.skillGraphExplainNextSkill,
@@ -4446,10 +4519,10 @@ export class Agent extends RunnerBase {
             notServed: 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` ·
@@ -4459,7 +4532,6 @@ export class Agent extends 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
@@ -4529,7 +4601,6 @@ export class Agent extends 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 }),
@@ -4890,6 +4961,12 @@ export class Agent extends 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) : 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).
@@ -4906,6 +4983,11 @@ export class Agent extends 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 && {
@@ -4976,12 +5058,16 @@ export class Agent extends RunnerBase {
             // tier one is lazy on top of that — an agent whose tools hold no sessions
             // never allocates it.
             currentRun: () => this.toolRunFacts(),
+            isOwnRun: (scope) => this.ownScopes.has(scope),
             answeredAsk: () => this.answeredAsk,
             // The time layer: each dispatched call files its `call` row, and the
             // resume door compares a resume's passed `time` with the kept clock.
             ...(this.timeOptions !== undefined && {
                 time: {
-                    takePassedOnResume: () => {
+                    takePassedOnResume: (scope) => {
+                        // Only the agent's own resumed leg takes it — never a member's.
+                        if (!this.ownScopes.has(scope))
+                            return undefined;
                         const passed = this.resumePassedTime;
                         this.resumePassedTime = undefined;
                         return passed;