agentfootprint 9.86.0 → 9.87.1

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

@@ -171,6 +171,9 @@ export function atMountedCursor(args) {
     }) === 'self';
     return stay && args.parked?.has(args.target) !== true;
 }
+// LENS · tool-result · persistent-history
+// reads: the dispatchable roster ← `toolCalls.ts` · dispatchRoster: registry ∪ provider cache, filtered through scope.hiddenSkillIds
+// law: may omit, never deny; every clause anchored to the call it was composed on.
 /**
  * What a call to a name nothing can dispatch gets back (9.86.0).
  *
@@ -224,6 +227,11 @@ export function unknownToolResult(toolName, dispatchable) {
         ? head
         : `${head} No tool name resolved to an implementation on that call.`;
 }
+// LENS · tool-result · persistent-history
+// reads: hops/open ← deps.allowedSkillIds + deps.openSkillIds, each through scope.hiddenSkillIds via spoken()
+//        target class ← skillGraph.ts · classifySkillTarget, carried in, not re-derived
+//        menu/turnStartedBy ← scope.turnRoute (the routing verdict, whole, not a boolean)
+// law: may omit, never deny; every clause anchored to the call it was composed on.
 /**
  * THE ONE COMPOSER of every `read_skill` refusal (9.86.0) — reachability,
  * posture and tree, from one set of inputs.
@@ -271,7 +279,7 @@ export function unknownToolResult(toolName, dispatchable) {
  * composers rather than re-deriving what it says.
  */
 export function composeReadSkillRefusal(args) {
-    const { requestedId, targetClass, cursorId, hops, openIds, isTree, posture, menuOffered, routedDecisively, } = args;
+    const { requestedId, targetClass, cursorId, hops, openIds, isTree, posture, menuOffered, turnStartedBy, cursorWithheld, } = args;
     const head = `read_skill("${requestedId}") was not granted on that call: `;
     // Open skills are the one list every arm may name: they are admitted from
     // every cursor and no posture governs them (the posture arm below is reached
@@ -302,10 +310,23 @@ export function composeReadSkillRefusal(args) {
             return (`${head}this graph's 'guard' posture admits a routing pick only from the menu the ` +
                 `framework offered, and '${requestedId}' was not admitted on that call.${openClause}`);
         }
+        // What the gate KNOWS about why no menu was outstanding is `TurnRoute.by`,
+        // and each value is a different finished fact. Nothing is asserted about
+        // how the cursor came to be where it was beyond that — the old tail,
+        // "Declared routes moved the cursor instead.", was composed for every
+        // value and was true of none of them in particular.
+        const startClause = turnStartedBy === 'entry' || turnStartedBy === 'intent'
+            ? " — the turn's start had already been resolved decisively"
+            : turnStartedBy === 'continuity'
+                ? ' — the cursor had been carried over from the previous turn'
+                : turnStartedBy === 'menu'
+                    ? ' — the menu had already been resolved by an earlier pick'
+                    : turnStartedBy === 'decider'
+                        ? " — the menu had been resolved by the configured decider before the turn's first call"
+                        : '';
         return (`${head}this graph's 'guard' posture admits a routing pick only while the framework ` +
             `has declared ambiguity, and no menu was outstanding when that call was made` +
-            `${routedDecisively === true ? " — the turn's start had already been resolved decisively" : ''}` +
-            `. Declared routes moved the cursor instead.${openClause}`);
+            `${startClause}.${openClause}`);
     }
     if (isTree === true) {
         return (`${head}this map is a decision tree. A tree routes by predicate on every iteration ` +
@@ -316,7 +337,14 @@ export function composeReadSkillRefusal(args) {
     // this arm — 'self' is answered by the notice, 'hop' and 'open' are admitted
     // — and it is carried rather than re-derived so the sentence and the verdict
     // read the same classification.
-    const from = cursorId !== undefined ? `'${cursorId}'` : "the turn's start";
+    // Three anchors, not two: a named cursor, a cursor this caller may not be
+    // told the name of, and a genuine cold start. The middle one used to print
+    // the raw id — the one name the description's own law withholds.
+    const from = cursorId !== undefined
+        ? `'${cursorId}'`
+        : cursorWithheld === true
+            ? 'the skill the cursor stood in'
+            : "the turn's start";
     // The gate reaches this arm only with `'unreachable'`; the weaker sentence is
     // for a caller that refused an admissible class for a reason of its own, and
     // it is deliberately not an invented explanation of one.
@@ -435,6 +463,9 @@ export function buildToolCallsHandler(deps) {
                 : capToolResult(values.modelResult, { toolName, maxChars: max }).value,
         };
     };
+    // LENS · tool-result · persistent-history
+    // reads: the tool's own declared resultCeiling / resultColumns ← ../resultCeiling.ts · applyResultCeiling, one owner of the measurement and the sentence
+    // law: may omit, never deny; every clause anchored to the call it was composed on.
     /**
      * The tool's OWN refusing ceiling (9.20.0) — ONE implementation for every
      * dispatch door, applied at the execute boundary the moment the handler's
@@ -775,6 +806,10 @@ export function buildToolCallsHandler(deps) {
         const step = currentStepOf(ptr, plan);
         return step ? { ptr, plan, step } : undefined;
     };
+    // LENS · tool-result · persistent-history
+    // reads: the advanced pointer ← pointerOf(scope.stepPointer), under `toolCalls.ts` · "── Step-procedure boundary (9.18.0)"; the sentence ← ../../lib/injection-engine/skillSteps.ts
+    // note: it overwrites the placeholder BEFORE the after-tool moment, so the record carries the authoritative words.
+    // law: may omit, never deny; every clause anchored to the call it was composed on.
     /**
      * `skip_step` bookkeeping — returns the AUTHORITATIVE result that
      * replaces the tool's placeholder (both channels, the read_skill-refusal
@@ -925,6 +960,11 @@ export function buildToolCallsHandler(deps) {
                 }
                 const currentSkillId = scope.currentSkillId;
                 const hops = deps.allowedSkillIds(currentSkillId);
+                const targetClass = classifySkillTarget({
+                    ...(currentSkillId !== undefined && { cursor: currentSkillId }),
+                    target,
+                    hops,
+                });
                 // ── A PROPOSAL TO THE CURSOR'S OWN SKILL IS A STAY (9.86.0) ──────
                 // `makeReachableSkills` filters the cursor out of its own successor
                 // set — right for a MOVE, and this judge read it as "not reachable"
@@ -937,11 +977,47 @@ export function buildToolCallsHandler(deps) {
                 // The event carries the existing `'accepted'` outcome plus an
                 // ADDITIVE `stay: true`, deliberately not a new enum member: an
                 // exhaustive switch over `outcome` in a consumer must keep compiling.
-                if (classifySkillTarget({
-                    ...(currentSkillId !== undefined && { cursor: currentSkillId }),
-                    target,
-                    hops,
-                }) === 'self') {
+                //
+                // A STAY COMPETES FOR THE SLOT LIKE ANY OTHER ACCEPTED PROPOSAL
+                // (9.86.1). The batch law is "first ACCEPTED proposal wins, later
+                // proposals to OTHER targets are superseded", and a stay is accepted
+                // — so a stay judged first holds the slot (with nothing written to
+                // `pendingToolTransition`, because a stay moves nothing) and a later
+                // sibling proposing a hop is `'superseded'` and lands in the
+                // `route_conflict` losers, exactly as two conflicting hops do. Before
+                // this the stay `continue`d past the bookkeeping, so the tool that
+                // judged its data first lost to whichever sibling came second, with
+                // two `'accepted'` events in one batch and no conflict on the record.
+                // The same law in the other order: a stay proposed AFTER an accepted
+                // hop is superseded by it, not accepted beside it.
+                if (targetClass === 'self') {
+                    if (state.winner !== undefined && state.winner.targetSkillId !== target) {
+                        state.losers.push({
+                            toolCallId: call.toolCallId,
+                            toolName: call.toolName,
+                            target,
+                        });
+                        typedEmit(scope, 'agentfootprint.tools.effect', {
+                            kind: 'propose-transition',
+                            outcome: 'superseded',
+                            toolName: call.toolName,
+                            toolCallId: call.toolCallId,
+                            iteration: call.iteration,
+                            targetSkillId: target,
+                            reason: effect.reason,
+                            supersededBy: 'earlier-proposal',
+                        });
+                        continue;
+                    }
+                    if (state.winner === undefined) {
+                        state.winner = {
+                            targetSkillId: target,
+                            toolName: call.toolName,
+                            toolCallId: call.toolCallId,
+                            reason: effect.reason,
+                            iteration: call.iteration,
+                        };
+                    }
                     typedEmit(scope, 'agentfootprint.tools.effect', {
                         kind: 'propose-transition',
                         outcome: 'accepted',
@@ -954,10 +1030,25 @@ export function buildToolCallsHandler(deps) {
                     });
                     continue;
                 }
-                if (!hops.includes(target)) {
+                if (targetClass === 'unreachable') {
+                    // ── THE REFUSAL SPEAKS WITH THE FILTERED SETS (9.86.1) ──────────
+                    // This sentence is appended to the tool result the model reads and
+                    // rides the `tools.effect` payload, and it named the raw hop set and
+                    // the raw cursor — the leak the `read_skill` refusals closed one
+                    // function up. Same filter, same law: the hidden set the tools slot
+                    // resolved for this iteration, and OMIT, NEVER DENY — a hop set the
+                    // filter emptied composes no reachable clause rather than an empty
+                    // one. Admission is still judged on the raw `hops`.
+                    const hiddenIds = new Set(scope.hiddenSkillIds ?? []);
+                    const mayName = (id) => !hiddenIds.has(id);
+                    const reachable = spoken(hops, mayName);
+                    const from = currentSkillId === undefined
+                        ? 'the turn start'
+                        : mayName(currentSkillId)
+                            ? `'${currentSkillId}'`
+                            : 'the skill the cursor stood in';
                     refuse('propose-transition', `propose-transition → '${target}' was refused: '${target}' is not reachable from ` +
-                        `${currentSkillId !== undefined ? `'${currentSkillId}'` : 'the turn start'} per ` +
-                        `the graph's own law${hops.length > 0 ? ` (reachable: ${hops.join(', ')})` : ''}. The graph decides — a proposal is evidence, never authority.`, { targetSkillId: target, reason: effect.reason });
+                        `${from} per the graph's own law${reachable.named.length > 0 ? ` (reachable: ${reachable.named.join(', ')})` : ''}. The graph decides — a proposal is evidence, never authority.`, { targetSkillId: target, reason: effect.reason });
                     continue;
                 }
                 if (state.winner !== undefined && state.winner.targetSkillId !== target) {
@@ -1437,6 +1528,9 @@ export function buildToolCallsHandler(deps) {
     // which owns the scope, the store and the emit channel — OVERWRITES its
     // result with the description snapshot (or the teaching refusal), so
     // governance rules and the caps compose over what the model will read.
+    // LENS · tool-result · persistent-history
+    // reads: the artifact's description snapshot ← the ArtifactStore port (src/artifacts/present.ts, the owner of head/list)
+    // law: may omit, never deny; every clause anchored to the call it was composed on.
     const applyPresent = async (scope, call) => {
         const store = deps.artifactStore;
         if (store === undefined) {
@@ -1617,6 +1711,9 @@ export function buildToolCallsHandler(deps) {
     const parkedNow = (scope) => deps.engagementPlan === undefined
         ? undefined
         : parkedMemberIds(deps.engagementPlan, scope.mapEngagement);
+    // FOLD · the one owner of "which tool names this caller may be told exist" for one iteration
+    // consumers read this and never re-derive it: `toolCalls.ts` · unknownToolResult, called at both dispatch doors
+    // detached: yes — a fresh SpokenIds; the named half leaves through spoken().
     /**
      * Every name `lookupTool` would resolve, in resolution order, through the
      * role filter (9.86.0) — the roster `unknownToolResult` names.
@@ -2097,6 +2194,12 @@ export function buildToolCallsHandler(deps) {
                             ...(decision.rationale !== undefined && { rationale: decision.rationale }),
                             ...(decision.reason !== undefined && { reason: decision.reason }),
                         });
+                        // LENS · tool-result · persistent-history
+                        // reads: the checker's own words ← decision.tellLLM ?? decision.rationale (an AUTHORITY omission: the rule space is never named)
+                        // known gap: the generic fallback anchors a per-call refusal to the whole run and is on the record as
+                        // unrepaired in test/modelFacingScan.test.ts · `LEDGER`, under this file's own key.
+                        // Do not widen it here without that test.
+                        // law: may omit, never deny; every clause anchored to the call it was composed on.
                         if (decision.result === 'deny') {
                             denied = true;
                             // Deny default keeps the existing v2.4 shape (carries
@@ -2779,6 +2882,15 @@ export function buildToolCallsHandler(deps) {
                         // "nothing reachable may be named", and it used to assert the first.
                         const hopsSpoken = spoken(hops, mayName);
                         const openSpoken = spoken(openAll, mayName);
+                        // The cursor through the SAME filter (9.86.1). The description
+                        // withholds a hidden cursor's name and every refusal below printed
+                        // it raw in two clauses; `cursorWithheld` keeps the sentence's
+                        // anchor honest ("the skill the cursor stood in") without the id.
+                        const cursorSpoken = currentSkillId === undefined
+                            ? {}
+                            : mayName(currentSkillId)
+                                ? { cursorId: currentSkillId }
+                                : { cursorWithheld: true };
                         const hopsNamed = hopsSpoken.named;
                         const openNamed = openSpoken.named;
                         // The ONE owner of "is this target the cursor?" — the same function
@@ -2896,7 +3008,7 @@ export function buildToolCallsHandler(deps) {
                             result = composeReadSkillRefusal({
                                 requestedId: reqId,
                                 targetClass,
-                                ...(currentSkillId !== undefined && { cursorId: currentSkillId }),
+                                ...cursorSpoken,
                                 hops: hopsSpoken,
                                 openIds: openSpoken,
                                 ...(deps.skillGraphIsTree === true && { isTree: true }),
@@ -2933,7 +3045,7 @@ export function buildToolCallsHandler(deps) {
                                 result = composeReadSkillRefusal({
                                     requestedId: reqId,
                                     targetClass,
-                                    ...(currentSkillId !== undefined && { cursorId: currentSkillId }),
+                                    ...cursorSpoken,
                                     // No hop is named under a posture, and the graph's hop set
                                     // is not this arm's subject — `held: false` is the honest
                                     // shape, not a claim that nothing was reachable (this arm
@@ -2942,9 +3054,9 @@ export function buildToolCallsHandler(deps) {
                                     openIds: openSpoken,
                                     posture: deps.skillStrictness,
                                     ...(menuNamed !== undefined && { menuOffered: menuNamed }),
-                                    ...((turnRoute?.by === 'intent' || turnRoute?.by === 'entry') && {
-                                        routedDecisively: true,
-                                    }),
+                                    // The whole verdict, not a boolean derived from two of its
+                                    // six values: the composer says one past fact per value.
+                                    ...(turnRoute !== undefined && { turnStartedBy: turnRoute.by }),
                                 });
                                 typedEmit(scope, 'agentfootprint.skill.rejected', {
                                     requestedId: reqId,
@@ -3390,10 +3502,14 @@ export function buildToolCallsHandler(deps) {
                         // silently invents a decision, for the same reason it never silently
                         // drops one.
                         error = true;
+                        // A past fact about the resumed call, not a forecast about the
+                        // turn (9.86.1): "cannot be retried this turn … Answer without it,
+                        // or finish" was a prediction plus a standing order on a result
+                        // that is re-read on every later call.
                         result =
-                            `tool '${toolName}' was not executed and cannot be retried this turn: it declares ` +
-                                `its own checkIn consent gate, that gate trips for these arguments, and a resumed ` +
-                                `dispatch has no second checkpoint to ask on. Answer without it, or finish. (To ` +
+                            `tool '${toolName}' was not executed on that call, and the resumed dispatch had ` +
+                                `no second checkpoint to retry it on: it declares its own checkIn consent gate, ` +
+                                `and that gate tripped for those arguments. (To ` +
                                 `the agent's author: the middleware '${askedBy}' and the tool's checkIn ask ` +
                                 `different questions — one is the rule's, one is the tool's with the evidence ` +
                                 `pack attached — so approving one is not answering the other. Keep one gate for ` +