agentfootprint 9.84.0 → 9.86.0

package/dist/types/lib/saidByPerson.d.ts

@@ -6,20 +6,24 @@
  *          imports, no state, no clock.
  * Role:    Leaf. Several layers ask the same question and must not answer it
  *          differently: the window's refusal engine (`currentRequest.ts`,
- *          which will not let a strategy drop the request), the four authors
+ *          which will not let a strategy drop the request), the six authors
  *          of library-written user turns (`window/notice.ts`,
- *          `window/summarize.ts`, `outputEnforcement.ts`, `evidence/gate.ts`
- *          — they own the sentences and take the markers from here), and —
- *          since 9.84.0 — a rule author reading `InjectionContext.history`
- *          (`saidByPerson(ctx)`).
+ *          `window/summarize.ts`, `outputEnforcement.ts`, `evidence/gate.ts`,
+ *          `stages/wrapUp.ts`, and `skillSteps.ts` for the nudge
+ *          `stages/stepNudge.ts` appends — they own the sentences and take
+ *          the markers from here), and — since 9.84.0 — a rule author reading
+ *          `InjectionContext.history` (`saidByPerson(ctx)`).
  * Emits:   N/A.
  *
  * ## Why this is a leaf and not a private helper
  *
- * This library writes FIVE kinds of `role: 'user'` message that nobody said:
+ * This library writes SEVEN kinds of `role: 'user'` message that nobody said:
  * a compaction frame, a drop notice, a schema-check correction, an
- * evidence-check correction, and a message an Injection delivered. The window
- * layer knew two of them and the marker; the evidence layer knew the other two
+ * evidence-check correction, a budget wrap-up instruction, a stepped-skill
+ * nudge, and a message an Injection delivered. Six of the seven are read off
+ * the OPENING they carry ({@link LIBRARY_AUTHORED_PREFIXES}); the delivered
+ * one carries an `injectedBy` marker instead. The window layer knew two of the
+ * openings and the marker; the evidence layer knew two more
  * (`evidence/frames.ts`); neither list was reachable from the routing layer at
  * all — the skill-graph fence forbids it from importing the agent loop, and
  * rightly. So a predicate reading `history` could filter some of the classes
@@ -32,12 +36,27 @@
  * wrote. That is a fixable bug in one place only: the rule has to be one
  * implementation both sides import, not two that agree until they do not.
  *
- * The markers move here with it, as a LIST rather than four constants in four
- * files. A prefix is what the recognizer matches AND what the writer emits;
- * separating those is how a prefix silently stops being recognized, and a
- * sixth authored frame that lands anywhere else is a hole nobody will see
- * until a rule fires on it. Adding one means adding it to
- * {@link LIBRARY_AUTHORED_PREFIXES}, and every reader is fixed at once.
+ * The two frames added in 9.86.0 are the same bug found again, and found by
+ * counting rather than by reading: 9.84.0 registered four openings and wrote
+ * "five classes" in prose, while the tree already had SEVEN producers of a
+ * user-role message that reach `scope.history`. The budget wrap-up
+ * (`stages/wrapUp.ts`) carried an unprefixed sentence containing "Do not
+ * request tools", and the stepped-skill nudge (`stages/stepNudge.ts`) carries
+ * a skill id and every unrun step's TOOL NAME — so both were credited to a
+ * person, a `saidByPerson(ctx).some(m => m.content.includes(…))` rule matched
+ * on them, and the window could anchor its refusal on the wrap-up frame.
+ *
+ * The markers live here, as a LIST rather than one constant per writing file.
+ * A prefix is what the recognizer matches AND what the writer emits;
+ * separating those is how a prefix silently stops being recognized, and an
+ * authored frame that lands anywhere else is a hole nobody will see until a
+ * rule fires on it. Adding one means adding it to
+ * {@link LIBRARY_AUTHORED_PREFIXES}, and every reader is fixed at once —
+ * which is why the count is no longer asserted in prose alone:
+ * `test/lib/injection-engine/userTurnProducers.test.ts` WALKS the tree for
+ * every `role: 'user'` construction site and fails, with the file and line, on
+ * one that is neither registered here, nor a person's own turn, nor
+ * wire-only.
  */
 /**
  * The fields authorship is decided from — structural, so both
@@ -65,6 +84,14 @@ export declare const SCHEMA_CHECK_FRAME_PREFIX = "[schema check";
 /** Opening of the authored frame the evidence gate writes. Stable — tests,
  *  docs and readers match on it. Written by `buildEvidenceCorrection`. */
 export declare const EVIDENCE_CHECK_FRAME_PREFIX = "[evidence check";
+/** Opening of the authored instruction the out-of-budget WRAP-UP call carries.
+ *  Stable — tests and readers match on it. Written by `wrapUpStage`
+ *  (`WRAP_UP_INSTRUCTION`). */
+export declare const WRAP_UP_FRAME_PREFIX = "[budget exhausted";
+/** Opening of the authored frame the stepped-skill NUDGE carries. Stable —
+ *  tests and readers match on it. Written by `nudgeTeachingMessage`, appended
+ *  by `buildStepNudgeStage`. */
+export declare const STEP_NUDGE_FRAME_PREFIX = "[steps unrun";
 /**
  * Every opening this library puts on a `role: 'user'` message it wrote itself.
  *
@@ -76,7 +103,13 @@ export declare const EVIDENCE_CHECK_FRAME_PREFIX = "[evidence check";
  *
  * The two correction frames both QUOTE untrusted text after their label (a
  * validator's error, the model's own flagged values), which is exactly why
- * they are matched by PREFIX and never by anything further in.
+ * they are matched by PREFIX and never by anything further in. The nudge is
+ * the same shape for a different reason: its body is a list of a skill's own
+ * step notes and tool names, which is exactly the text a rule watches for.
+ *
+ * The list is frozen because it is a registry, not a scratch array: a consumer
+ * holds the same object this library's own readers hold, and a `push` into it
+ * would change what every reader calls a person's message.
  */
 export declare const LIBRARY_AUTHORED_PREFIXES: readonly string[];
 /** True when this user-role message opens with a frame this library authored. */

package/dist/types/lib/saidByPerson.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"saidByPerson.d.ts","sourceRoot":"","sources":["../../../src/lib/saidByPerson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;yDACyD;AACzD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AAErD;6DAC6D;AAC7D,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D;uEACuE;AACvE,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;0EAC0E;AAC1E,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAKtD,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAMhF;AAED,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAOxE"}
+{"version":3,"file":"saidByPerson.d.ts","sourceRoot":"","sources":["../../../src/lib/saidByPerson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;yDACyD;AACzD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AAErD;6DAC6D;AAC7D,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D;uEACuE;AACvE,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;0EAC0E;AAC1E,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAE7D;;+BAE+B;AAC/B,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;gCAEgC;AAChC,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAOrD,CAAC;AAEH,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAMhF;AAED,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAEtE;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAOxE"}

package/dist/types/lib/spokenIds.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A set a model-facing sentence is allowed to NAME, after the role filter has
+ * run over it (9.86.0) — and the one fact a filtered list cannot be written
+ * without.
+ *
+ * ── OMIT, NEVER DENY ────────────────────────────────────────────────────
+ *
+ * A narrowing may take a name off a sentence. It may not turn that name's
+ * absence into a claim that the thing is gone: the graph, the dispatch map and
+ * the menu are all still holding it, and a model told "no skill was reachable"
+ * stops asking for the one it may not be told about. Omission costs nothing and
+ * is always true; the negative sentence is a denial of what the run holds.
+ *
+ * Every composer took plain arrays and branched on `length > 0`, so "the set
+ * was empty" and "the filter emptied it" produced the SAME sentence — one
+ * shape, two facts, in three separate places. `held` is that missing fact, and
+ * it is REQUIRED rather than optional on purpose: the compiler now asks every
+ * caller the question the call sites each forgot to answer.
+ *
+ * ── WHY THIS IS A LEAF AND NOT A HELPER IN THE GATE ─────────────────────
+ *
+ * It lived in `core/agent/stages/toolCalls.ts`, which put it on the wrong side
+ * of the skill-graph fence: `read_skill`'s DESCRIPTION is composed inside
+ * `src/lib/injection-engine/`, which may not import the agent loop, so the one
+ * surface the model reads to CHOOSE a skill could not use the fact its own
+ * refusals were being repaired with — and it went on printing "Nothing is
+ * reachable from here" over a graph whose only hop the role filter had removed.
+ * The same reason `src/lib/saidByPerson.ts` is a leaf: the writer and the
+ * recogniser share one rule, so they cannot drift.
+ *
+ * @example
+ * ```ts
+ * const hidden = new Set(['beta']);
+ * const hops = spoken(['beta'], (id) => !hidden.has(id));
+ * // → { named: [], held: true } — the clause is DROPPED, not negated.
+ * ```
+ */
+export interface SpokenIds {
+    /** The members this sentence may name — what survived the filter. */
+    readonly named: readonly string[];
+    /** Did the UNFILTERED set hold anything? `true` with an empty `named` is the
+     *  filtered-to-empty case: the clause is omitted rather than negated. */
+    readonly held: boolean;
+}
+/**
+ * Apply the role filter to one set and keep both halves (9.86.0).
+ *
+ * `mayName` is the caller's visibility predicate — skill ids test membership of
+ * `scope.hiddenSkillIds`, tool names test whether every skill declaring them is
+ * hidden. Both questions have one answer shape, and this is it.
+ */
+export declare function spoken(all: readonly string[], mayName: (id: string) => boolean): SpokenIds;
+//# sourceMappingURL=spokenIds.d.ts.map

package/dist/types/lib/spokenIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spokenIds.d.ts","sourceRoot":"","sources":["../../../src/lib/spokenIds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;6EACyE;IACzE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,SAAS,CAE1F"}

package/dist/types/lib/trace-toolpack/traceToolpack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traceToolpack.d.ts","sourceRoot":"","sources":["../../../../src/lib/trace-toolpack/traceToolpack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AASH,OAAO,EAAc,KAAK,IAAI,EAA6B,MAAM,qBAAqB,CAAC;AAcvF,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAuQpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,sBAAsB,EACjC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,EAAE,CA0BR;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,kMAYnB,CAAC;AAypEX;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,MAAM,CAAC,CASjB"}
+{"version":3,"file":"traceToolpack.d.ts","sourceRoot":"","sources":["../../../../src/lib/trace-toolpack/traceToolpack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AASH,OAAO,EAAc,KAAK,IAAI,EAA6B,MAAM,qBAAqB,CAAC;AAcvF,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAuQpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,sBAAsB,EACjC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,EAAE,CA0BR;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,kMAYnB,CAAC;AAgqEX;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,MAAM,CAAC,CASjB"}

package/dist/types/maps/engagement/parkCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parkCard.d.ts","sourceRoot":"","sources":["../../../../src/maps/engagement/parkCard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAmC,MAAM,YAAY,CAAC;AAkBjG;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,aAAa,GAAG,SAAS,GACpC,MAAM,GAAG,SAAS,CA8BpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,8BAA8B,CAAC"}
+{"version":3,"file":"parkCard.d.ts","sourceRoot":"","sources":["../../../../src/maps/engagement/parkCard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAmC,MAAM,YAAY,CAAC;AAkBjG;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,aAAa,GAAG,SAAS,GACpC,MAAM,GAAG,SAAS,CAoCpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,8BAA8B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "9.84.0",
+  "version": "9.86.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",