agentfootprint 10.5.1 → 10.6.1

package/CAPABILITIES.md

@@ -40,6 +40,7 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | identifying which same-name tool call a permission check or credential event describes — captured at dispatch, including resume and inner pull failures; qualify with run identity, missing fields stay unknown | `ToolCallEventIdentity` + `bindToolSecurityEvents` | `src/core/agent/toolSecurityEvents.ts` | 9.137.0 |
 | guiding an evidence repair to ask for missing context without inventing values | `recoveryInstruction` + `EvidenceRecoveryContext` | `src/core/agent/evidence/` | 9.96.0 |
 | checking a typed final answer against scoped evidence before streaming or memory delivery — optional host-authored checks with enforce/observe modes, canonical JSON and bounded read-only artifacts | `answerValidation` + `AnswerValidationError` | `src/answer-validation/` | 9.95.0 |
+| blocking a declared claim when its required relationship evidence is missing or unresolved, while independently checked measurements remain usable — host-owned policies over Foottrace requirement records, composed with output middleware and enforcing answer validation | `checkClaimRequirements` + `ClaimRequirementPolicy` + `ClaimRequirementAssessment` | `src/answer-validation/requirements.ts` | 10.6.0 |
 | an output guard that sees which tools ran — fail the run when the answer presents code but no code-execution tool ran; this run's tool calls (name, call id, outcome ok/error/not-run; never arguments or results) handed to the enforce check, per run, bounded | `AnswerValidationContext.toolCalls` + `AnswerToolCallsView` + `limits.maxToolCalls` | `src/answer-validation/toolLedger.ts` | 10.5.0 |
 | turning a written operational procedure (a runbook, a triage playbook) into ONE agent tool whose every answer is EVIDENCE — coverage folded up from the inner tools it calls, rule name+version, verdict rows with GENERATED meanings, and the recorded walk as an artifact ticket, never bytes | `runbookAsTool` — dials: `procedure` (factory, invoked per call with `ctx.tools`) + `resultKind` (`'verdict/*'` arms the rowset projection; anything else ships spine + the chart's `report`) + `rules {name, version}` (default absent ⇒ `rule_version: 'undeclared'`) + `verdicts {decider, maxRows}` (default 50; `verdict_meanings` = statically declared branches + this run's rule labels + the DEFAULT branch's label, which reaches evidence only when the chart calls `decide(s, rules, {branch, label})` — fp ≥9.16.1, the default is chosen by NO rule so nothing else can name it, and inside a generated fan-out branch the static walk is blind too; an undeclared or blank label stays ABSENT from the map, never invented from a branch id, and there is deliberately NO caller-supplied meanings map) + `presentation` (`'prose'` default = ship `table` + `VERDICT_RENDER_NOTE` "output it VERBATIM"; `'panel'` = the HOST renders the rowset, so NO `table` key at all + `PANEL_RENDER_NOTE` "the rows are already on the reader's screen — do not reproduce them"; the rowset half is byte-identical across modes, `table` stays RESERVED in both, an unknown value THROWS at definition) + `walk {cap, recording}` (cap default 500; over-cap ⇒ control-flow projection, declared · `recording: true` or `{label, maxBytes}`, default OFF — ALSO files the inner chart's own `{snapshot, events, structure}` under `recording/run` and puts its ref on the spine as `walk.recording_ref`, because the ROW projection cannot be drawn; snapshot read from the REDACTED mirror so one `redact` means the same for both; over `maxBytes` (`DEFAULT_RECORDING_MAX_BYTES` = 5,000,000) it is REFUSED not truncated; every absence — no store / over size / unserializable / store threw — is STATED in `walk.recording_note`, and the four `recording_*` fields are absent entirely when the dial is off) + `composedOf` (drift-checked at agent BUILD) + kept `recorders`/`keepRecord`/`keepRecordLimit`/`redact`; reserved state keys `verdicts`/`coverage`/`report` (the `report` bag lands BESIDE the spine, never over it — a report field spelling `af_coverage`/`af_provenance`/`rule_version`/`walk`/`report_note` or a live projection key is discarded and NAMED in `result.report_note`; precedence is explicit in `report.ts`, never spread order); inner `absent()` passes through VERBATIM unless the call said `allowAbsent`; walk kind `recording/chart-walk` + `walk_segment` discriminant | `src/core/runbook/` | 9.76.0, recording 9.79.0 |
 | speaking MCP from a BROWSER — the SDK is browser-clean (its client + streamableHttp bundle at `platform:'browser'` with zero `node:` edges and never pull in `client/stdio.js`); the one barrier was that `lazyRequire` gets CALLED there, so the fix is to let the caller supply what the loader would have found | `mcpClient({ sdk })` (`McpSdk` = the two SDK modules you imported statically; the library STILL builds the transport, so headers/fetch/gateway vending/`retryOnThrottle`/`_meta` all keep working) · `mcpClient({ connection })` (`McpConnection` = listTools/callTool/close, deliberately NO `connect` — you already did; the only arm that reaches the SDK's `jsonSchemaValidator`, i.e. CSP) + `McpConnectionOptions`; `refuseConflictingOptions` REFUSES at construction every option a transport would have consumed, naming where it moved (a knob naming a behaviour that no longer happens is the defect class); `transportUrl` resolves a relative `url` against `globalThis.location.href` (absolute takes the identical branch, Node refuses by name); `sdkLoadFailure` classifies the seven load sites so a browser is never told to install a package it has (resolution failure ⇒ the site's own absent-package message, which names the `sdk` hook); `retryingFetch` + `ThrottleFetch` promoted out of `@internal` so the connection arm keeps its 429 handling. stdio keeps `lazyRequire` FOREVER — it spawns a subprocess. ZERO packaging change: no subpath, no `browser` condition (TypeScript is blind to it), peer stays optional (no literal dynamic `import()`). Fenced by `test/mcp/browserGraph.test.ts` | `src/mcp/` | 9.81.0 |

package/dist/answer-validation/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toolOutcomeOf = exports.toolCallsView = exports.startToolCall = exports.ledgerAtCheck = exports.incompleteToolCalls = exports.appendToolCall = exports.executeAnswerValidation = exports.resolveAnswerValidation = exports.AnswerValidationError = void 0;
+exports.toolOutcomeOf = exports.toolCallsView = exports.startToolCall = exports.ledgerAtCheck = exports.incompleteToolCalls = exports.appendToolCall = exports.checkClaimRequirements = exports.executeAnswerValidation = exports.resolveAnswerValidation = exports.AnswerValidationError = void 0;
 /** Explicit, bounded validation of schema-accepted JSON answers. */
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "AnswerValidationError", { enumerable: true, get: function () { return types_js_1.AnswerValidationError; } });
 var validate_js_1 = require("./validate.js");
 Object.defineProperty(exports, "resolveAnswerValidation", { enumerable: true, get: function () { return validate_js_1.resolveAnswerValidation; } });
 Object.defineProperty(exports, "executeAnswerValidation", { enumerable: true, get: function () { return validate_js_1.executeAnswerValidation; } });
+var requirements_js_1 = require("./requirements.js");
+Object.defineProperty(exports, "checkClaimRequirements", { enumerable: true, get: function () { return requirements_js_1.checkClaimRequirements; } });
 var toolLedger_js_1 = require("./toolLedger.js");
 Object.defineProperty(exports, "appendToolCall", { enumerable: true, get: function () { return toolLedger_js_1.appendToolCall; } });
 Object.defineProperty(exports, "incompleteToolCalls", { enumerable: true, get: function () { return toolLedger_js_1.incompleteToolCalls; } });

package/dist/answer-validation/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/answer-validation/index.ts"],"names":[],"mappings":";;;AAAA,oEAAoE;AACpE,uCAcoB;AAblB,iHAAA,qBAAqB,OAAA;AAcvB,6CAAiF;AAAxE,sHAAA,uBAAuB,OAAA;AAAE,sHAAA,uBAAuB,OAAA;AACzD,iDAQyB;AAPvB,+GAAA,cAAc,OAAA;AACd,oHAAA,mBAAmB,OAAA;AACnB,8GAAA,aAAa,OAAA;AACb,8GAAA,aAAa,OAAA;AACb,8GAAA,aAAa,OAAA;AACb,8GAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/answer-validation/index.ts"],"names":[],"mappings":";;;AAAA,oEAAoE;AACpE,uCAcoB;AAblB,iHAAA,qBAAqB,OAAA;AAcvB,6CAAiF;AAAxE,sHAAA,uBAAuB,OAAA;AAAE,sHAAA,uBAAuB,OAAA;AACzD,qDAI2B;AAHzB,yHAAA,sBAAsB,OAAA;AAIxB,iDAQyB;AAPvB,+GAAA,cAAc,OAAA;AACd,oHAAA,mBAAmB,OAAA;AACnB,8GAAA,aAAa,OAAA;AACb,8GAAA,aAAa,OAAA;AACb,8GAAA,aAAa,OAAA;AACb,8GAAA,aAAa,OAAA"}

package/dist/answer-validation/requirements.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkClaimRequirements = void 0;
+/** Pure prerequisite checks over caller-authenticated producer reports. No IO or value comparison. */
+const foottrace_1 = require("foottrace");
+const boundedJson_js_1 = require("../lib/boundedJson.js");
+const POLICY_BYTES = 16 * 1024;
+const CHECK_ID_CHARACTERS = 128;
+function ref(value, maximum = foottrace_1.REQUIREMENT_RESULT_LIMITS.name) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maximum ||
+        /\s/u.test(value))
+        throw new Error('Invalid reference.');
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || (code >= 127 && code <= 159))
+            throw new Error('Invalid reference.');
+    }
+    return value;
+}
+/** Fixed diagnostics: never retain a hostile value or the exception raised while inspecting it. */
+function readPolicy(value) {
+    try {
+        const source = (0, boundedJson_js_1.ownData)(value, ['claimRef', 'findingRef', 'windowRef', 'requirementRefs']);
+        if (!Array.isArray(source.requirementRefs))
+            throw new Error();
+        const length = Object.getOwnPropertyDescriptor(source.requirementRefs, 'length')
+            ?.value;
+        if (typeof length !== 'number' || length < 1 || length > foottrace_1.REQUIREMENT_RESULT_LIMITS.refs)
+            throw new Error();
+        const copied = (0, boundedJson_js_1.ownData)((0, boundedJson_js_1.copyJson)(source, POLICY_BYTES, true));
+        const copiedRefs = copied.requirementRefs;
+        // Preflight limits the read; only the detached copy supplies admitted policy facts.
+        if (!Array.isArray(copiedRefs) ||
+            copiedRefs.length < 1 ||
+            copiedRefs.length > foottrace_1.REQUIREMENT_RESULT_LIMITS.refs)
+            throw new Error();
+        const requirementRefs = copiedRefs.map((item) => ref(item));
+        if (new Set(requirementRefs).size !== requirementRefs.length)
+            throw new Error();
+        return Object.freeze({
+            claimRef: ref(copied.claimRef, CHECK_ID_CHARACTERS),
+            findingRef: ref(copied.findingRef),
+            windowRef: ref(copied.windowRef),
+            requirementRefs: Object.freeze(requirementRefs),
+        });
+    }
+    catch {
+        throw Object.assign(new TypeError('Invalid claim requirement policy.'), {
+            code: 'ERR_CLAIM_REQUIREMENT_POLICY',
+        });
+    }
+}
+function assessment(claimRef, resultRefs, reason) {
+    return Object.freeze({
+        check: Object.freeze({
+            id: claimRef,
+            disposition: reason === undefined ? 'checked-pass' : 'unreachable',
+            ...(reason === undefined ? {} : { reason }),
+        }),
+        requirementResultRefs: Object.freeze([...resultRefs]),
+    });
+}
+/**
+ * Check every expected prerequisite for one exact claim/finding/window binding.
+ * Any same-scope unresolved report affecting this claim denies it, including an
+ * extra obligation; a satisfied report never overrides that denial. Missing
+ * expected obligations are unreachable, not a successful empty check.
+ *
+ * The host must authenticate the producer and current query/run/scope, authorize
+ * receipt access and establish domain validity BEFORE supplying results. The
+ * public Foottrace reader admits structure only; neither it nor this helper
+ * verifies provenance, freshness, a claim's value, or permission to disclose it.
+ * Use the returned check only when the candidate actually asserts this claim.
+ * Requirement result IDs are selectors, never artifact evidence references.
+ *
+ * A malformed host policy throws code ERR_CLAIM_REQUIREMENT_POLICY. Malformed
+ * receipt sets produce unreachable/invalid-data without exposing parser errors.
+ */
+function checkClaimRequirements(policy, results) {
+    const expected = readPolicy(policy);
+    let admitted;
+    try {
+        admitted = (0, foottrace_1.readRequirementResults)(results);
+    }
+    catch {
+        return assessment(expected.claimRef, [], 'invalid-data');
+    }
+    const affected = admitted.filter((result) => result.affects.includes(expected.claimRef));
+    const applicable = affected
+        .filter((result) => result.findingRef === expected.findingRef && result.windowRef === expected.windowRef)
+        .sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+    const resultRefs = applicable.map((result) => result.id);
+    const unresolved = applicable.find((result) => result.state === 'unresolved');
+    if (unresolved?.state === 'unresolved')
+        return assessment(expected.claimRef, resultRefs, unresolved.reason);
+    for (const requirementRef of expected.requirementRefs) {
+        if (!applicable.some((result) => result.requirementRef === requirementRef)) {
+            const foreign = affected.some((result) => result.requirementRef === requirementRef);
+            return assessment(expected.claimRef, resultRefs, foreign ? 'incompatible' : 'not-collected');
+        }
+    }
+    return assessment(expected.claimRef, resultRefs);
+}
+exports.checkClaimRequirements = checkClaimRequirements;
+//# sourceMappingURL=requirements.js.map

package/dist/answer-validation/requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.js","sourceRoot":"","sources":["../../src/answer-validation/requirements.ts"],"names":[],"mappings":";;;AAAA,sGAAsG;AACtG,yCAImB;AACnB,0DAA0D;AAoB1D,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC;AAC/B,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,SAAS,GAAG,CAAC,KAAc,EAAE,UAAkB,qCAAyB,CAAC,IAAI;IAC3E,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,KAAK,CAAC;QAClB,KAAK,CAAC,MAAM,GAAG,OAAO;QACtB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;QAEjB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,IAAI,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mGAAmG;AACnG,SAAS,UAAU,CAAC,KAA6B;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,wBAAO,EAAC,KAAK,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;QAC1F,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,wBAAwB,CAAC,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC;YAC9E,EAAE,KAAgB,CAAC;QACrB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,qCAAyB,CAAC,IAAI;YACrF,MAAM,IAAI,KAAK,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,IAAA,wBAAO,EAAC,IAAA,yBAAQ,EAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC;QAC1C,oFAAoF;QACpF,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;YAC1B,UAAU,CAAC,MAAM,GAAG,CAAC;YACrB,UAAU,CAAC,MAAM,GAAG,qCAAyB,CAAC,IAAI;YAElD,MAAM,IAAI,KAAK,EAAE,CAAC;QACpB,MAAM,eAAe,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,IAAI,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QAChF,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,mBAAmB,CAAC;YACnD,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC;YAClC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;YAChC,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;SAChD,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,mCAAmC,CAAC,EAAE;YACtE,IAAI,EAAE,8BAAuC;SAC9C,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CACjB,QAAgB,EAChB,UAA6B,EAC7B,MAA0B;IAE1B,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;YACnB,EAAE,EAAE,QAAQ;YACZ,WAAW,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa;YAClE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;SAC5C,CAAC;QACF,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC;KACtD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,sBAAsB,CACpC,MAA8B,EAC9B,OAAgB;IAEhB,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,QAAmD,CAAC;IACxD,IAAI,CAAC;QACH,QAAQ,GAAG,IAAA,kCAAsB,EAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,cAAc,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzF,MAAM,UAAU,GAAG,QAAQ;SACxB,MAAM,CACL,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS,CACvF;SACA,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC;IAC9E,IAAI,UAAU,EAAE,KAAK,KAAK,YAAY;QACpC,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACtE,KAAK,MAAM,cAAc,IAAI,QAAQ,CAAC,eAAe,EAAE,CAAC;QACtD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,KAAK,cAAc,CAAC,EAAE,CAAC;YAC3E,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,KAAK,cAAc,CAAC,CAAC;YACpF,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AACnD,CAAC;AA7BD,wDA6BC"}

package/dist/core/Agent.js

@@ -4701,8 +4701,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(argumentSources && { argumentSources: true }),
             ...((this.answerValidationConfig !== undefined || governsOutput) && {
                 suppressDraftTokens: true,
+                withholdDraftContent: true,
             }),
-            ...(governsOutput && { withholdDraftContent: true }),
             // Tool choice by classifier (9.105.0): the outcome row after the reply.
             ...(this.toolChoiceOptions !== undefined && { toolChoice: true }),
             // The declared ontology (9.106.0): the piece served from the run