agentfootprint 9.21.0 → 9.22.0

package/AGENTS.md

@@ -475,7 +475,7 @@ Resilience decorators live on the `agentfootprint/resilience` subpath
 (not the main barrel). Each preserves the `LLMProvider` interface and
 stacks freely.
 
-### Observability — 89 typed events across 21 domains
+### Observability — 90 typed events across 21 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CLAUDE.md

@@ -60,7 +60,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Embedder fingerprint** (8.9.0) → `Embedder.id` (optional; every shipped embedder sets one, and NONE include dims — the store appends `@<dims>` itself, so an id carrying its own size double-stamps) + `indexDocuments` defaulting `embedderId` to it + `SqliteVectorStore.reconcileFingerprint` (the only comparison site). Rule: dimensions ALWAYS decide, model ids decide only when BOTH sides named themselves — refusing on an absent name would block the majority of callers who never pass `embedderId`.
 - **Retrieval record** (8.8.0) → FOUR stages write one object in sequence: `loadRelevant` (candidates+scores+threshold verdicts) → `pickByBudget` (re-marks admitted→over-budget/over-max-entries) → `formatDefault` (`promptFragment` + `promptPosition`) → the read mount's outputMapper lifts it to root as `retrievalEvidence_<id>`. `memoryRecallInjections` then splits ONE recall into one ActiveInjection PER CHUNK — guarded by a byte-equality check (`fragments.join('\n\n') === systemContent`) that falls back to the single injection rather than change the prompt. `rank` (score order) and `promptPosition` (picker order) are DIFFERENT and both load-bearing: joining fragments in rank order reproduces the right bytes in a sequence the model never saw.
 - **AgentState** → all 8 stages/ files, both builders' mappers, memory-wire STRING-TYPED keys ('runIdentity'/'turnNumber'/… buildAgentChart.ts:177-180 — not refactor-safe), finalizeResult's `reliabilityFail*`/`policyHalt*` reads (rename silently kills the typed errors).
-- **events/** → 89 typed events across 21 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
+- **events/** → 90 typed events across 21 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
 - **adapters/types.ts LLMMessage/LLMRequest** → 62 importers: tool_use round-trip (toolCalls.ts:115-135), wire assembly (callLLM.ts:150-160), providers, cache strategies, security/extractSequence, reliability loop.
 - **Cache** → strategy registration is a MODULE SIDE EFFECT (src/index.ts:15-17); an entry point skipping that import silently falls back to NoOp. Resolved once per Agent at construction (Agent.ts:347).
 - **Injection engine eval semantics** → Evaluate stage cursor keystone (buildInjectionEngineSubflow.ts:214-222), Route stage MIRRORS slot filters (keep in sync with buildSystemPromptSlot), read_skill gate (toolCalls.ts:747). The gate's allowed set is TWO kinds of id (8.4.0): a HOP (`deps.allowedSkillIds` = `graph.reachableSkills(cursor)` — activates AND moves the cursor) ∪ an OPEN skill (`deps.openSkillIds` = `Agent.openSkillIds()`, Agent.ts:1052 — a registered skill whose trigger is `llm-activated` AND that the graph declares no incoming edge to; activates, never moves the cursor). Both clauses are load-bearing: the trigger test is "read_skill can really activate this", the edge test keeps a bare model edge `.route(a,m)` from-gated. **8.5.0** extends the SAME trigger test three ways: a decision `tree()` returns `[]` from `reachableSkills` (leaves compile to `rule` triggers, so a pick could only be accepted then dropped — the gate refuses with a tree-specific message, `deps.skillGraphIsTree`, derived in AgentBuilder from `graph.nodes.some(kind==='predicate')`); `surfaceMode:'tool-only'` is refused at agent build for any skill whose trigger is not `llm-activated` (skillBodyDelivery.ts — the read_skill tool result is the only channel that mode has, and the graph never calls read_skill); and `read_skill`'s DESCRIPTION is rebuilt per iteration from `reachableSkills(cursor) ∪ open` (Agent.readSkillOfferFor → buildToolsSlot's `readSkillFor`). **The read_skill ENUM must stay the full catalog** — `toolArgValidation` defaults to `'enforce'` and runs at toolCalls.ts:570, BEFORE the gate at :765, and sets `error = true` which the gate skips; narrowing the enum silently retires the teaching refusal, `skill.rejected`, routeRecorder's rejection hops and the rejected-cap governor.

package/README.md

@@ -879,6 +879,7 @@ The flowchart, recorders, and tests don't change between dev and prod.
 
 **Operability**
 - Provider-agnostic prompt caching — declarative per-injection, per-iteration marker recomputation
+- Artifacts (the claim check) — tools check data into a governed store (`ctx.artifacts`; in-memory / file / SQLite) and the model routes ~26-char tickets instead of hauling payloads: `wants` resolves ref arguments at dispatch with teaching refusals, the placement threshold (`artifacts: { store, placement }`) auto-refs oversized tool results, and the auto-attached `present` tool hands a ref to the screen with a durable description snapshot — every mint / resolve / refusal / presentation a typed event
 - Human-in-the-loop pause / resume — a tool calls `pauseHere(...)` (or `askHuman(...)`); `isPaused(result)` hands you a JSON-serializable checkpoint, and `agent.resume(checkpoint, input)` continues hours later on a different server
 - Resilience primitives — `withRetry`, `withFallback`, `withCircuitBreaker`, `.outputFallback`, `agent.resumeOnError`
 - 60+ typed observability events — `agent` · `composition` · `context` · `stream` · `tools` · `skill` · `memory` · `cache` · `cost` · `permission` · `eval` · `embedding` · `pause` · `error` · `fallback` · `resilience` · `reliability` · `risk`

package/ai-instructions/claude-code/SKILL.md

@@ -379,7 +379,7 @@ if (isPaused(result)) {
 }
 ```
 
-## Observability — 89 typed events × 21 domains
+## Observability — 90 typed events × 21 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/dist/artifacts/capability.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/artifacts/capability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/artifacts/capability.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/index.js

@@ -4,12 +4,14 @@
  *
  * The claim-check store: shapes + the five-verb port (`types`), the ref
  * grammar (`naming`), the payload laws (`payload`), the eviction law
- * (`retention`), the shared put pipeline (`minting`), three adapters, and
- * the `ctx.artifacts` capability (`capability`). See README.md in this
- * folder for the one-job map and the import direction.
+ * (`retention`), the shared put pipeline (`minting`), three adapters, the
+ * `ctx.artifacts` capability (`capability`) — and the Phase-2 data legs:
+ * ref arguments at dispatch (`wants`), the hand-to-the-screen verb
+ * (`present`), and the placement threshold (`placement`). See README.md in
+ * this folder for the one-job map and the import direction.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unconfiguredArtifacts = exports.bindArtifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
+exports.placedToolResult = exports.placedResultKind = exports.isPlacedToolResult = exports.assertArtifactPlacement = exports.presentArtifact = exports.PRESENT_TOOL_NAME = exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = exports.unconfiguredArtifacts = exports.bindArtifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "ArtifactIntegrityError", { enumerable: true, get: function () { return types_js_1.ArtifactIntegrityError; } });
 Object.defineProperty(exports, "InvalidArtifactError", { enumerable: true, get: function () { return types_js_1.InvalidArtifactError; } });
@@ -30,4 +32,16 @@ Object.defineProperty(exports, "UnreadableArtifactStoreError", { enumerable: tru
 var capability_js_1 = require("./capability.js");
 Object.defineProperty(exports, "bindArtifacts", { enumerable: true, get: function () { return capability_js_1.bindArtifacts; } });
 Object.defineProperty(exports, "unconfiguredArtifacts", { enumerable: true, get: function () { return capability_js_1.unconfiguredArtifacts; } });
+var wants_js_1 = require("./wants.js");
+Object.defineProperty(exports, "assertToolWants", { enumerable: true, get: function () { return wants_js_1.assertToolWants; } });
+Object.defineProperty(exports, "resolveToolWants", { enumerable: true, get: function () { return wants_js_1.resolveToolWants; } });
+Object.defineProperty(exports, "wantsNeedsStoreRefusal", { enumerable: true, get: function () { return wants_js_1.wantsNeedsStoreRefusal; } });
+var present_js_1 = require("./present.js");
+Object.defineProperty(exports, "PRESENT_TOOL_NAME", { enumerable: true, get: function () { return present_js_1.PRESENT_TOOL_NAME; } });
+Object.defineProperty(exports, "presentArtifact", { enumerable: true, get: function () { return present_js_1.presentArtifact; } });
+var placement_js_1 = require("./placement.js");
+Object.defineProperty(exports, "assertArtifactPlacement", { enumerable: true, get: function () { return placement_js_1.assertArtifactPlacement; } });
+Object.defineProperty(exports, "isPlacedToolResult", { enumerable: true, get: function () { return placement_js_1.isPlacedToolResult; } });
+Object.defineProperty(exports, "placedResultKind", { enumerable: true, get: function () { return placement_js_1.placedResultKind; } });
+Object.defineProperty(exports, "placedToolResult", { enumerable: true, get: function () { return placement_js_1.placedToolResult; } });
 //# sourceMappingURL=index.js.map

package/dist/artifacts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,uCAgBoB;AAflB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAcvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,uCAgBoB;AAflB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAcvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA;AASvB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AAKxB,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,6GAAA,eAAe,OAAA;AAKjB,+CAOwB;AANtB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAClB,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA"}

package/dist/artifacts/placement.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * artifacts/placement — the placement threshold (Phase 2, Leg 3).
+ *
+ * An OPTIONAL operator dial on the agent's artifacts wiring:
+ * `Agent.create({ artifacts: { store, placement: { maxInlineChars: N } } })`.
+ * A tool result whose finalized text exceeds the threshold is checked into
+ * the store (kind `tool-result/<toolName>`) and the model receives the claim
+ * ticket instead — a SHORT substitute naming ref + meta + how to consume it.
+ * The whole 879,073-token failure class, retired by configuration.
+ *
+ * PRECEDENCE with the other two ceilings, stated once and owned here:
+ *   1. the tool's own `resultCeiling` (the AUTHOR's refusal) is judged FIRST,
+ *      at the execute boundary — a refused result is a short teaching
+ *      sentence, so placement never sees the payload at all;
+ *   2. placement (the OPERATOR's ref-ing) is judged next, on what the
+ *      after-tool governance chain let through — a rule that already
+ *      summarized a huge result is measured on what it produced;
+ *   3. the agent-level `maxToolResultChars` truncation net runs LAST — with
+ *      placement on it measures the ticket, so it should now rarely fire.
+ *
+ * A placed result is a TICKET, not a refusal: declared effects are still
+ * judged and procedure steps advance normally — the result ARRIVED; it just
+ * travels by reference. The decision is never silent: the mint lands as
+ * `agentfootprint.artifacts.minted` (origin joining it to the tool call) and
+ * the substitution states itself in the result the model reads.
+ *
+ * This module is the PURE half — the dial shape, its build-time refusals,
+ * the measure rule (shared with both ceilings: strings as-is, everything
+ * else `safeStringify`d by the caller), and the substitute composer. The
+ * dispatch layer owns the mint and the events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placedToolResult = exports.isPlacedToolResult = exports.placedResultKind = exports.assertArtifactPlacement = void 0;
+/**
+ * Refuse a placement dial this library cannot honor, where it is configured
+ * — never at the first oversized result of the first run.
+ */
+function assertArtifactPlacement(site, placement) {
+    if (placement === undefined)
+        return;
+    const value = placement.maxInlineChars;
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${site}: artifacts.placement.maxInlineChars must be a positive whole number of ` +
+            `characters, and ${String(value)} is not one. It is the threshold over which a tool ` +
+            `result is checked into the artifact store and the model reads the claim ticket ` +
+            `instead. To turn placement OFF, omit \`placement\` — absent means results are never ` +
+            `measured and never placed, exactly as before.`);
+    }
+}
+exports.assertArtifactPlacement = assertArtifactPlacement;
+/** The kind vocabulary a placement mint declares: `tool-result/<toolName>`.
+ *  Honest — it says exactly what the payload is and which tool produced it —
+ *  and it is what a `wants` declaration or a `present` call names to consume
+ *  the placed result. */
+function placedResultKind(toolName) {
+    return `tool-result/${toolName}`;
+}
+exports.placedResultKind = placedResultKind;
+/** Type guard for consumers reading `tool_end.result` or a tool message. */
+function isPlacedToolResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.placed === true &&
+        typeof value.ref === 'string' &&
+        typeof value.reason === 'string');
+}
+exports.isPlacedToolResult = isPlacedToolResult;
+/** Compose the ticket from the mint the dispatch layer performed. */
+function placedToolResult(toolName, meta, sizeChars, maxInlineChars) {
+    return {
+        placed: true,
+        ref: meta.ref,
+        kind: meta.kind,
+        mediaType: meta.mediaType,
+        bytes: meta.bytes,
+        reason: `${toolName} returned ${sizeChars} chars, over the ${maxInlineChars}-char placement ` +
+            `threshold, so the full result was stored as artifact '${meta.ref}' ` +
+            `(${meta.kind}) instead of entering this conversation. Route the ref: pass the ` +
+            `string '${meta.ref}' to a tool whose argument wants '${meta.kind}', or call ` +
+            `present({ ref: '${meta.ref}', as: … }) to hand it to the screen. Do not retype or ` +
+            `summarize content you have not read.`,
+    };
+}
+exports.placedToolResult = placedToolResult;
+//# sourceMappingURL=placement.js.map

package/dist/artifacts/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../src/artifacts/placement.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAeH;;;GAGG;AACH,SAAgB,uBAAuB,CACrC,IAAY,EACZ,SAAwC;IAExC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO;IACpC,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,0EAA0E;YAC/E,mBAAmB,MAAM,CAAC,KAAK,CAAC,qDAAqD;YACrF,iFAAiF;YACjF,sFAAsF;YACtF,+CAA+C,CAClD,CAAC;IACJ,CAAC;AACH,CAAC;AAfD,0DAeC;AAED;;;yBAGyB;AACzB,SAAgB,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,eAAe,QAAQ,EAAE,CAAC;AACnC,CAAC;AAFD,4CAEC;AAqBD,4EAA4E;AAC5E,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA8B,CAAC,MAAM,KAAK,IAAI;QAC/C,OAAQ,KAA2B,CAAC,GAAG,KAAK,QAAQ;QACpD,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC;AARD,gDAQC;AAED,qEAAqE;AACrE,SAAgB,gBAAgB,CAC9B,QAAgB,EAChB,IAAkB,EAClB,SAAiB,EACjB,cAAsB;IAEtB,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EACJ,GAAG,QAAQ,aAAa,SAAS,oBAAoB,cAAc,kBAAkB;YACrF,yDAAyD,IAAI,CAAC,GAAG,IAAI;YACrE,IAAI,IAAI,CAAC,IAAI,mEAAmE;YAChF,WAAW,IAAI,CAAC,GAAG,qCAAqC,IAAI,CAAC,IAAI,aAAa;YAC9E,mBAAmB,IAAI,CAAC,GAAG,yDAAyD;YACpF,sCAAsC;KACzC,CAAC;AACJ,CAAC;AApBD,4CAoBC"}

package/dist/artifacts/present.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * artifacts/present — the hand-to-the-screen verb (Phase 2, Leg 2).
+ *
+ * `present({ ref, as, label? })` is how the model finishes an analytics
+ * answer WITHOUT serializing what the screen will show: it names the ticket
+ * (`ref`), the consumer vocabulary for how to render it (`as: 'bar-chart'`,
+ * `'table'`, …), and optionally the human title. The framework `head`s the
+ * ref under the run's own scope and the RESULT carries a DESCRIPTION
+ * SNAPSHOT — `{ kind, mediaType, bytes, label }` — so the claim ticket
+ * describes the parcel: a conversation reloaded after the artifact expired
+ * can still render an honest placeholder from history alone ("Chart —
+ * 'Q3 sales by region' (bar-chart, 41 KB) — expired; re-run to regenerate"),
+ * because the snapshot lives INSIDE the tool result, the one thing provider
+ * message history keeps typed and durable. Never a blank pane.
+ *
+ * `as` is deliberately NOT validated against a component registry — that
+ * registry is a later phase (the frontend leg); until then the value is
+ * stored as data and travels on the `artifacts.presented` event exactly as
+ * spoken.
+ *
+ * This module is the PURE half — the tool's name/schema constants, the
+ * snapshot shape, and the resolution over the five-verb port. The tool SHELL
+ * (a placeholder whose result the agent loop overwrites — the `skip_step`
+ * pattern) lives in core, which is also where the typed
+ * `agentfootprint.artifacts.presented` event is emitted. Core wires
+ * artifacts; never the reverse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presentArtifact = exports.PRESENT_TOOL_NAME = void 0;
+/**
+ * The reserved name of the auto-attached tool. Reserved ONLY when a store is
+ * attached (the `read_skill` seam): a storeless agent may keep its own
+ * `present`, because the framework attaches nothing there.
+ */
+exports.PRESENT_TOOL_NAME = 'present';
+/** How many live refs a miss refusal lists. A lesson, not a catalog. */
+const PRESENT_LIST_LIMIT = 10;
+/** `art_h7Kq… [chart/spec · 41210 bytes · 'Q3 sales']` — one listed ref. */
+function describeRef(meta) {
+    return `${meta.ref} [${meta.kind} · ${meta.bytes} bytes${meta.label !== undefined ? ` · '${meta.label}'` : ''}]`;
+}
+/**
+ * Resolve one `present` call over the port — ONE law for every dispatch
+ * door. `head`, never `get`: presenting is the render-by-ref decision, and
+ * the screen pays for the bytes later, under its own identity.
+ */
+async function presentArtifact(store, scope, args) {
+    const ref = args.ref;
+    const as = args.as;
+    if (typeof ref !== 'string' || ref.trim().length === 0) {
+        return {
+            ok: false,
+            refusal: `present needs \`ref\` — the art_… ticket of the artifact to hand to the screen. ` +
+                `Store the data first (a tool that mints, or the placement threshold), then present ` +
+                `its ref.`,
+        };
+    }
+    if (typeof as !== 'string' || as.trim().length === 0) {
+        return {
+            ok: false,
+            refusal: `present needs \`as\` — the consumer vocabulary for how the screen should render ` +
+                `'${ref}' (e.g. 'bar-chart', 'table', 'image'). Say what it is; the screen picks ` +
+                `the renderer.`,
+        };
+    }
+    const meta = await store.head(scope, ref);
+    if (meta === null) {
+        const page = await store.list(scope, { limit: PRESENT_LIST_LIMIT });
+        const listing = page.artifacts.length === 0
+            ? `Nothing is live in this run's scope right now — store the data first, then present ` +
+                `its ref.`
+            : `Live refs in scope: ${page.artifacts.map(describeRef).join(', ')}.`;
+        return {
+            ok: false,
+            missedRef: ref,
+            refusal: `present('${ref}') found nothing under that ref in this run's scope — expired, ` +
+                `swept, or never stored here. Nothing was presented. ${listing}`,
+        };
+    }
+    const label = typeof args.label === 'string' && args.label.trim().length > 0 ? args.label : meta.label;
+    return {
+        ok: true,
+        result: {
+            presented: true,
+            ref: meta.ref,
+            as,
+            snapshot: {
+                kind: meta.kind,
+                mediaType: meta.mediaType,
+                bytes: meta.bytes,
+                ...(label !== undefined && { label }),
+            },
+        },
+    };
+}
+exports.presentArtifact = presentArtifact;
+//# sourceMappingURL=present.js.map

package/dist/artifacts/present.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"present.js","sourceRoot":"","sources":["../../src/artifacts/present.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAIH;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAyC3C,wEAAwE;AACxE,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,SAAS,WAAW,CAAC,IAAkB;IACrC,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,KAAK,SAC9C,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EACpD,GAAG,CAAC;AACN,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,KAAoB,EACpB,IAAuC;IAEvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACnB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,kFAAkF;gBAClF,qFAAqF;gBACrF,UAAU;SACb,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,kFAAkF;gBAClF,IAAI,GAAG,2EAA2E;gBAClF,eAAe;SAClB,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACpE,MAAM,OAAO,GACX,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YACzB,CAAC,CAAC,qFAAqF;gBACrF,UAAU;YACZ,CAAC,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAC3E,OAAO;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,GAAG;YACd,OAAO,EACL,YAAY,GAAG,iEAAiE;gBAChF,uDAAuD,OAAO,EAAE;SACnE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IAC3F,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE;YACN,SAAS,EAAE,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,EAAE;YACF,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;aACtC;SACF;KACF,CAAC;AACJ,CAAC;AAzDD,0CAyDC"}

package/dist/artifacts/wants.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * artifacts/wants — ref ARGUMENTS at dispatch (Phase 2, Leg 1).
+ *
+ * A tool declares `wants: { dataset: 'dataset/rows' }` and the FRAMEWORK
+ * resolves the ref before `execute`: the model speaks the ~26-char ticket as
+ * the argument, dispatch redeems it under the run's own scope and kind-checks
+ * the meta, and the handler receives the RESOLVED DATA (plus the meta on
+ * `ctx.wanted`). A stale, unknown, or wrong-kind ref NEVER reaches the tool —
+ * the model reads a teaching refusal that lists the live refs of the wanted
+ * kind in scope (the innerRunRecords law: correct by naming what CAN resolve).
+ *
+ * The declare-and-push precedent, verb for verb: `needs` resolves a credential
+ * before execute and injects `ctx.credential`; `wants` resolves data before
+ * execute and injects it into the args. Both fail closed; neither lets the
+ * model fabricate what the framework could not deliver.
+ *
+ * This module is the PURE half — validation at `defineTool` time and
+ * resolution over the five-verb port. It never imports `core/`: the
+ * tool-dispatch layer composes the scope, adapts the outcome onto the typed
+ * `agentfootprint.artifacts.*` events (`op: 'dispatch'`), and refuses the
+ * call. Core wires artifacts; never the reverse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = void 0;
+const types_js_1 = require("./types.js");
+/**
+ * Refuse a `wants` declaration this library cannot honor, at definition time
+ * — naming the tool and the fix, never at the first dispatch of the first
+ * run. Checks, per declared argument:
+ *   • the kind is a non-empty string (a blank kind can never match a mint);
+ *   • when the tool's `inputSchema` declares `properties`, the argument
+ *     exists there (a wants-arg the model is never offered can never be
+ *     filled);
+ *   • when that property declares a `type`, it is `'string'` — the model
+ *     passes the REF, never the bytes, so any other type is a schema that
+ *     asks the model to inline what this feature exists to keep out.
+ */
+function assertToolWants(toolName, wants, inputSchema) {
+    if (wants === undefined)
+        return;
+    const entries = Object.entries(wants);
+    if (entries.length === 0) {
+        throw new Error(`defineTool: tool '${toolName}' declares wants: {} — an empty declaration resolves ` +
+            `nothing and reads as one that does. Name at least one argument ` +
+            `(e.g. wants: { dataset: 'dataset/rows' }), or omit \`wants\` — absent means no ` +
+            `argument is resolved, exactly as before.`);
+    }
+    const properties = inputSchema !== undefined &&
+        typeof inputSchema.properties === 'object' &&
+        inputSchema.properties !== null
+        ? inputSchema.properties
+        : undefined;
+    for (const [argName, kind] of entries) {
+        if (typeof kind !== 'string' || kind.trim().length === 0) {
+            throw new Error(`defineTool: tool '${toolName}' declares wants.${argName} = ${JSON.stringify(kind)}, ` +
+                `which is not an artifact kind. The value is the consumer vocabulary the resolved ` +
+                `artifact's meta.kind must equal exactly (e.g. 'dataset/rows').`);
+        }
+        if (properties !== undefined && !(argName in properties)) {
+            throw new Error(`defineTool: tool '${toolName}' declares wants.${argName}, but inputSchema.properties ` +
+                `has no '${argName}' — the model is never offered that argument, so no ref could ` +
+                `ever arrive to resolve. Add it to inputSchema (type: 'string' — the model passes ` +
+                `the art_… ref), or drop it from \`wants\`.`);
+        }
+        const property = properties?.[argName];
+        const declaredType = typeof property === 'object' && property !== null
+            ? property.type
+            : undefined;
+        if (declaredType !== undefined && declaredType !== 'string') {
+            throw new Error(`defineTool: tool '${toolName}' declares wants.${argName}, but inputSchema declares ` +
+                `that argument as type '${String(declaredType)}'. A wants-argument is spoken as the ` +
+                `ref STRING (the model routes the ticket, never the bytes) — declare it ` +
+                `{ type: 'string' }.`);
+        }
+    }
+}
+exports.assertToolWants = assertToolWants;
+/** How many live refs a refusal lists, and how many rows the listing pages
+ *  through to find them. Bounded — a refusal is a lesson, not a catalog. */
+const LIVE_REF_LIST_LIMIT = 10;
+const LIVE_REF_SCAN_LIMIT = 200;
+/** The live refs of `kind` in scope, newest first, bounded — what a refusal
+ *  names so the model can correct instead of retrying the same dead ref. */
+async function liveRefsOfKind(store, scope, kind) {
+    const found = [];
+    let cursor;
+    let scanned = 0;
+    // Page cap beside the row cap: a misbehaving BYO store that returns empty
+    // pages with a never-advancing cursor must not spin this loop forever — the
+    // row-based SCAN_LIMIT only advances when pages carry rows.
+    let pages = 0;
+    do {
+        const page = await store.list(scope, { ...(cursor !== undefined && { cursor }) });
+        for (const meta of page.artifacts) {
+            scanned += 1;
+            if (meta.kind === kind)
+                found.push(meta);
+            if (found.length >= LIVE_REF_LIST_LIMIT || scanned >= LIVE_REF_SCAN_LIMIT)
+                return found;
+        }
+        cursor = page.cursor === cursor ? undefined : page.cursor;
+        pages += 1;
+    } while (cursor !== undefined && pages < 50);
+    return found;
+}
+/** `art_h7Kq… ('Q3 rows', 6100 bytes)` — one listed live ref. */
+function describeLiveRef(meta) {
+    return `${meta.ref}${meta.label !== undefined ? ` ('${meta.label}', ${meta.bytes} bytes)` : ` (${meta.bytes} bytes)`}`;
+}
+/** The correcting clause: what CAN resolve, or the honest "nothing can". */
+function liveRefsClause(kind, live) {
+    if (live.length === 0) {
+        return (`No live '${kind}' artifacts exist in this run's scope right now — produce one first ` +
+            `(a tool that stores '${kind}', or re-run the step that minted it).`);
+    }
+    return `Live '${kind}' refs in scope: ${live
+        .map(describeLiveRef)
+        .join(', ')}. Pass one of these.`;
+}
+/**
+ * Resolve one tool's declared `wants` against the run's scope — the whole
+ * Leg-1 law in one place, shared by every dispatch door.
+ *
+ * Per declared argument that is PRESENT in the call args (an absent optional
+ * argument is the model choosing not to pass one — nothing to resolve):
+ *   • a non-string value is refused (`invalid-input`) — the argument is
+ *     spoken as the ref string, never the bytes;
+ *   • a ref that does not resolve in scope is refused
+ *     (`missing-or-expired`), listing the live refs of the wanted kind;
+ *   • a ref whose meta.kind differs from the declaration is refused
+ *     (`kind-mismatch`), naming both kinds and listing what would fit;
+ *   • a stored payload failing its digest re-check is refused
+ *     (`digest-mismatch`) — corrupt bytes never reach the tool as if whole.
+ *
+ * ALL declared args are judged before answering, so one refusal teaches the
+ * whole correction rather than one argument per retry loop.
+ */
+async function resolveToolWants(store, scope, toolName, wants, args) {
+    const refusals = [];
+    const wanted = {};
+    const resolvedList = [];
+    const nextArgs = { ...args };
+    for (const [argName, kind] of Object.entries(wants)) {
+        if (!(argName in args) || args[argName] === undefined)
+            continue;
+        const spoken = args[argName];
+        if (typeof spoken !== 'string' || spoken.trim().length === 0) {
+            const live = await liveRefsOfKind(store, scope, kind);
+            refusals.push({
+                argName,
+                kind,
+                reason: 'invalid-input',
+                detail: `'${argName}' must be an artifact ref STRING (an art_… ticket), not ` +
+                    `${Array.isArray(spoken) ? 'an array' : `a ${typeof spoken}`} — this tool declares ` +
+                    `it wants '${kind}' there and the framework resolves the ref for you; never inline ` +
+                    `the data. ${liveRefsClause(kind, live)}`,
+            });
+            continue;
+        }
+        let record;
+        try {
+            record = await store.get(scope, spoken);
+        }
+        catch (err) {
+            if (err instanceof types_js_1.ArtifactIntegrityError) {
+                refusals.push({
+                    argName,
+                    kind,
+                    reason: 'digest-mismatch',
+                    ref: spoken,
+                    detail: `'${argName}' = ${spoken} failed its integrity re-check — the stored payload no ` +
+                        `longer matches its minted digest, and corrupt bytes are never delivered as ` +
+                        `whole. Re-create the artifact from its source, then pass the new ref.`,
+                });
+                continue;
+            }
+            throw err;
+        }
+        if (record === null) {
+            const live = await liveRefsOfKind(store, scope, kind);
+            refusals.push({
+                argName,
+                kind,
+                reason: 'missing-or-expired',
+                ref: spoken,
+                detail: `'${argName}' = ${spoken} does not resolve in this run's scope — expired, swept, ` +
+                    `or never stored here. ${liveRefsClause(kind, live)}`,
+            });
+            continue;
+        }
+        if (record.meta.kind !== kind) {
+            const live = await liveRefsOfKind(store, scope, kind);
+            refusals.push({
+                argName,
+                kind,
+                reason: 'kind-mismatch',
+                ref: spoken,
+                detail: `'${argName}' = ${spoken} resolves, but it is '${record.meta.kind}' and this ` +
+                    `argument wants '${kind}' — the wrong parcel for this ticket window. ` +
+                    `${liveRefsClause(kind, live)}`,
+            });
+            continue;
+        }
+        nextArgs[argName] = record.data;
+        wanted[argName] = record.meta;
+        resolvedList.push({ argName, meta: record.meta });
+    }
+    if (refusals.length > 0) {
+        return {
+            ok: false,
+            refusals,
+            refusal: `Tool '${toolName}' was not executed — its declared artifact argument` +
+                `${refusals.length > 1 ? 's' : ''} did not resolve. ` +
+                refusals.map((r) => r.detail).join(' '),
+        };
+    }
+    return { ok: true, args: nextArgs, wanted, resolved: resolvedList };
+}
+exports.resolveToolWants = resolveToolWants;
+/**
+ * The teaching refusal for a `wants`-declaring tool dispatched where NO
+ * artifact store is attached — fail-closed, naming the config fix, because
+ * running the tool with the raw ref string where it expects resolved data
+ * would be accepted-and-silently-wrong. (Agent dispatch refuses this at
+ * BUILD for statically registered tools; this sentence serves the doors
+ * that only meet the tool at dispatch — provider-served tools, `mcpServe`.)
+ */
+function wantsNeedsStoreRefusal(toolName, wants) {
+    const declared = Object.entries(wants)
+        .map(([arg, kind]) => `${arg}: '${kind}'`)
+        .join(', ');
+    return (`Tool '${toolName}' declares artifact arguments (wants: { ${declared} }) but no artifact ` +
+        `store is attached here, so its refs cannot be resolved and the tool was not executed. ` +
+        `This is configuration, not something to retry: attach a store ` +
+        `(Agent.create({ ..., artifacts }) — inMemoryArtifacts(), fileArtifacts({ directory }), ` +
+        `or sqliteArtifacts({ file })), or serve this tool from an agent that has one.`);
+}
+exports.wantsNeedsStoreRefusal = wantsNeedsStoreRefusal;
+//# sourceMappingURL=wants.js.map

package/dist/artifacts/wants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wants.js","sourceRoot":"","sources":["../../src/artifacts/wants.ts"],"names":[],"mappings":"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"}