agentfootprint-lens 0.32.0 → 0.34.0

package/README.md

@@ -358,6 +358,84 @@ The headless half is on `agentfootprint-lens/core` — `defaultSelection`,
 
 ---
 
+## Render an artifact by its ref
+
+agentfootprint 9.21–9.23 taught tools to check large results into an **artifact
+store** and hand the model a ~30-token claim ticket (`art_…`) instead of the
+bytes; the model finishes with `present({ ref, as, label })`. The lens is the
+screen's half of that handshake: it **redeems the ref and renders a component
+the app registered for the artifact's kind** — ids + props, never markup the
+model wrote. The model can say *what* to show; only your registry says *how*.
+
+```tsx
+import {
+  ArtifactPane,
+  httpArtifactResolver,
+  presentedFromEvents,
+  registerArtifactComponent,
+} from 'agentfootprint-lens';
+
+// 1. Teach Lens your kinds, once at startup. ('dataset/rows' already ships.)
+registerArtifactComponent({
+  kind: 'chart/spec',
+  component: ({ meta, data }) => <MyBarChart title={meta.label} spec={data} />,
+});
+
+// 2. Point a resolver at the served agent — the SAME invoke path the
+//    conversation posts to. Session identity rides every redemption.
+const resolver = httpArtifactResolver({ url: '/invoke', sessionId });
+
+// 3. Render every artifact the run presented. On history reload, walk the
+//    stored transcript instead: readPresentedResult(toolMessage.content).
+{presentedFromEvents(recording.events).map((call) => (
+  <ArtifactPane key={call.toolCallId ?? call.ref} presented={call} resolver={resolver} />
+))}
+```
+
+`<ArtifactPane>` heads the ref first (the render decision), then gets the
+payload and mounts the registered component. A kind nothing is registered for
+falls back to an honest **metadata card** — ticket facts, a bounded payload
+preview, copy/download — plus one line naming the `registerArtifactComponent`
+call that closes the gap. Never a blank pane.
+
+### When the artifact is gone
+
+Refs expire — TTL, retention budgets, a restarted store. The `present` result
+carries a **description snapshot** at speak time, so a reloaded conversation
+can still say what stood there, from history alone:
+
+> Chart — "Q3 sales by region" (bar-chart, 41.0 KB) — expired; re-run to regenerate.
+
+That placeholder needs **no store round-trip beyond the failed head** — this is
+the spreadsheet's `#REF!`, taught manners. Missing, expired and
+another-session's ref all answer one indistinguishable not-found by design (a
+leaked ref probes nothing), and the pane renders the same stated absence for
+all three. A resolution *door* failure (no store attached, wire down) is a
+different sentence: the pane shows the server's own teaching refusal, verbatim.
+
+### The two resolvers
+
+```ts
+import { httpArtifactResolver, storeArtifactResolver } from 'agentfootprint-lens/core';
+
+// Over a served agent's wire ops (standingAgent / httpHost / nodeHost, or the
+// managed-runtime dialect): POST { op: 'artifact-head' | 'artifact-get', ref,
+// sessionId } to the invoke path. `userId`, extra `headers` and a custom
+// `fetch` are options.
+const overHttp = httpArtifactResolver({ url: 'https://host/invoke', sessionId: 's-1' });
+
+// Over a directly passed store, for same-process demos and tests. The scope is
+// REQUIRED — refs only resolve under the identity they were minted in.
+const inProcess = storeArtifactResolver({ store, scope: { conversationId } });
+```
+
+Both return `{ status: 'live' | 'absent' | 'failed' }` outcomes instead of
+throwing, so a pane can branch. In the EventStream, the whole artifact
+lifecycle — minted, resolved, expired, refused, presented — already reads as
+prose via the default humanizer.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -522,6 +600,19 @@ file through your own endpoint. Needs agentfootprint 9.9+; on anything older it
 renders a version hint instead of itself. See
 [Report a bug with this run](#report-a-bug-with-this-run).
 
+### `<ArtifactPane>` — render by ref, with `#REF!` taught manners
+
+Takes one `present` call (`presented`) and an `ArtifactResolver` (`resolver`);
+heads the ref, then renders the component registered for the artifact's kind
+(`registerArtifactComponent({ kind, component })`) with `{ meta, data,
+presented }` as props. `'dataset/rows'` ships as a built-in table; every
+unregistered kind falls back to `<ArtifactMetaCard>` with the gap stated. An
+expired/missing ref renders its placeholder from the speak-time snapshot alone.
+The headless half — `httpArtifactResolver`, `storeArtifactResolver`,
+`presentedFromEvents`, `readPresentedResult`, `artifactPlaceholder` — is on
+`agentfootprint-lens/core`. See
+[Render an artifact by its ref](#render-an-artifact-by-its-ref).
+
 ### Headless core
 
 `agentfootprint-lens/core` is React-free: `LensRecorder`, `ChangeNotifier`,

package/dist/{chunk-QBSH233H.js → chunk-ZSOYNKUI.js}

@@ -1552,8 +1552,254 @@ import {
   renderCommentary,
   selectCommentaryKey
 } from "agentfootprint";
+
+// src/core/humanizeRouting.ts
+function fmtScore(n) {
+  return String(Number(n.toFixed(2)));
+}
+function fmtShare(n) {
+  return `${Math.round(n * 100)}%`;
+}
+function quoteList(ids) {
+  return ids.join(", ");
+}
+function q(id) {
+  return id === void 0 ? void 0 : `"${id}"`;
+}
+function movement(p) {
+  const { from, to } = p;
+  if (to !== void 0 && from !== void 0) {
+    return from === to ? `Stayed in ${q(to)}` : `Moved from ${q(from)} to ${q(to)}`;
+  }
+  if (to !== void 0) return `Turn started in ${q(to)}`;
+  if (from !== void 0) return `Stayed in ${q(from)}`;
+  return "The turn was routed";
+}
+function droppedResumeNote(p) {
+  const d = p.droppedResume;
+  if (!d) return "";
+  return ` The conversation's saved place (${q(d.id)}) no longer exists in this deployment.`;
+}
+function humanizeTurnRouted(p) {
+  switch (p.by) {
+    case "entry":
+    case "rule":
+      return `${movement(p)} \u2014 a rule matched (tier 1).${droppedResumeNote(p)}`;
+    case "intent": {
+      const winner = p.scores?.[0];
+      const ruRow = p.runnerUp && p.scores ? p.scores.find((s) => s.id === p.runnerUp.id) : void 0;
+      let clause = " \u2014 intent";
+      if (winner) {
+        clause += ` scored ${fmtScore(winner.score)}`;
+        if (ruRow) clause += ` vs ${fmtScore(ruRow.score)} for runner-up ${q(ruRow.id)}`;
+        else if (p.runnerUp)
+          clause += `, ${fmtScore(p.runnerUp.gap)} ahead of ${q(p.runnerUp.id)}`;
+      } else {
+        clause += " matched";
+      }
+      const scorer = p.scorer ? ` (${p.scorer} scorer)` : "";
+      return `${movement(p)}${clause}${scorer}.${droppedResumeNote(p)}`;
+    }
+    case "continuity": {
+      const nearTie = p.decisive === false && p.scores && p.scores.length >= 2;
+      if (nearTie) {
+        const [a, b] = p.scores;
+        const where2 = p.to ?? p.from;
+        const tail = where2 !== void 0 ? `; continuing in ${q(where2)}` : "";
+        return `Stayed \u2014 near-tie between ${q(a.id)} (${fmtShare(a.relevance)}) and ${q(b.id)} (${fmtShare(b.relevance)})${tail}.${droppedResumeNote(p)}`;
+      }
+      const where = p.to ?? p.from;
+      const head = where !== void 0 ? `Stayed in ${q(where)}` : "Stayed";
+      return `${head} \u2014 treated as a continuation of the conversation.${droppedResumeNote(p)}`;
+    }
+    case "menu":
+    case "model-pick": {
+      let line = "No single skill won \u2014 the model was offered a menu";
+      if (p.offered && p.offered.length > 0)
+        line += ` of ${p.offered.length}: ${quoteList(p.offered)}`;
+      if (p.stayOffered) line += `; 'stay' was on the menu`;
+      return `${line}.${droppedResumeNote(p)}`;
+    }
+    case "none": {
+      if (p.droppedResume) {
+        let line = `The conversation's saved place (${q(p.droppedResume.id)}) no longer exists in this deployment \u2014 the turn started fresh.`;
+        if (p.offered && p.offered.length > 0)
+          line += ` Options on the record: ${quoteList(p.offered)}.`;
+        return line;
+      }
+      if (p.offered && p.offered.length > 0) {
+        const top = p.scores?.[0]?.score;
+        const floor = p.policy?.floor;
+        const cleared = top !== void 0 && Number.isFinite(top) && (floor === void 0 || top > floor);
+        if (p.decisive === false && (p.scores?.length ?? 0) >= 2 && cleared) {
+          return `This message matched ${quoteList(p.offered)} too closely to call, and rails mode does not let the model break the tie \u2014 the turn ran on the base prompt.`;
+        }
+        if (top !== void 0 && !cleared) {
+          return `No rule or intent matched this message strongly enough, and rails mode does not let the model route \u2014 the turn ran on the base prompt. The full menu stayed on the record: ${quoteList(p.offered)}.`;
+        }
+        return `Routing ended in a menu, but rails mode does not let the model route \u2014 the turn ran on the base prompt. On the record: ${quoteList(p.offered)}.`;
+      }
+      return "Routing decided nothing this turn \u2014 the turn ran on the base prompt.";
+    }
+    default:
+      return `Turn routing: ${p.by}${p.to !== void 0 ? ` \u2192 ${q(p.to)}` : ""}.`;
+  }
+}
+var COUNT_WORDS = ["Zero", "One", "Two", "Three", "Four", "Five"];
+function humanizeRouteConflict(p) {
+  const winner = p.winner;
+  const losers = p.losers ?? [];
+  const winnerClause = winner ? `${winner.toolName ?? "a tool"} \u2192 ${q(winner.target) ?? "its target"} won (first in the batch)` : "the first match in the batch won";
+  if (losers.length === 0) {
+    return `Tool results conflicted on the next skill \u2014 ${winnerClause}.`;
+  }
+  const count = losers.length + 1;
+  const countWord = count < COUNT_WORDS.length ? COUNT_WORDS[count] : String(count);
+  const loserClause = losers.map((l) => `${l.toolName ?? "a tool"} \u2192 ${q(l.target) ?? "another skill"}`).join(", ");
+  const verb = losers.length === 1 ? "was" : "were";
+  return `${countWord} tool results wanted different next skills \u2014 ${winnerClause}; ${loserClause} ${verb} suppressed and ${losers.length === 1 ? "is" : "are"} on the record.`;
+}
+function humanizeSkillRejected(p) {
+  const pick = `The model tried to switch to ${q(p.requestedId)}`;
+  if (p.posture === "guard") {
+    let line2 = `${pick}, but that pick was off the menu it was given \u2014 refused (guard).`;
+    if (p.allowed && p.allowed.length > 0) line2 += ` Reachable: ${quoteList(p.allowed)}.`;
+    return line2;
+  }
+  if (p.posture === "rails") {
+    return `${pick}, but rails mode does not let the model route \u2014 refused.`;
+  }
+  const at = p.currentSkillId !== void 0 ? q(p.currentSkillId) : "the start";
+  let line = `${pick}, but it is not reachable from ${at} \u2014 refused.`;
+  if (p.allowed && p.allowed.length > 0) line += ` Reachable: ${quoteList(p.allowed)}.`;
+  return line;
+}
+function humanizeCursorMovePick(move) {
+  if (!move || move.by !== "model-pick") return null;
+  if (move.offered === void 0 && move.declinedOffer === void 0) return null;
+  let line = move.to !== void 0 ? `The model chose ${q(move.to)}` : "The model made a pick";
+  if (move.offered !== void 0 && move.declinedOffer !== true) {
+    line += ` from a ${move.offered.length}-item menu`;
+    const rest = move.to !== void 0 ? move.offered.filter((id) => id !== move.to) : move.offered;
+    if (rest.length > 0) line += ` (${quoteList(rest)} were offered too)`;
+  }
+  if (move.from !== void 0 && move.from !== move.to) {
+    line += `, moving from ${q(move.from)}`;
+  }
+  line += ".";
+  if (move.declinedOffer === true) {
+    line += " Its pick was not on the offered menu \u2014 the divergence is on the record.";
+  }
+  return line;
+}
+
+// src/core/bugReport/selection.ts
+var DEFAULT_MAX_BYTES = 24 * 1024 * 1024;
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 bytes";
+  if (bytes < 1024) return `${Math.round(bytes)} bytes`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function conversationUnits(manifest) {
+  return manifest.units.filter((unit) => unit.kind === "conversation");
+}
+function fileUnits(manifest) {
+  return manifest.units.filter((unit) => unit.kind !== "conversation");
+}
+function defaultSelection(manifest, recent = 3) {
+  const conversations = conversationUnits(manifest);
+  const keep = recent <= 0 ? [] : conversations.slice(Math.max(0, conversations.length - recent));
+  return [...keep.map((unit) => unit.id), ...fileUnits(manifest).map((unit) => unit.id)];
+}
+function measureSelection(manifest, selected, limitBytes = DEFAULT_MAX_BYTES) {
+  const ticked = new Set(selected);
+  const units = manifest.units.filter((unit) => ticked.has(unit.id));
+  const bytes = units.reduce((sum, unit) => sum + (unit.bytes || 0), 0);
+  const over = bytes > limitBytes;
+  const hint = over ? trimHintFor(manifest, ticked, limitBytes) : void 0;
+  return {
+    bytes,
+    limitBytes,
+    over,
+    label: `${formatBytes(bytes)} of ${formatBytes(limitBytes)}`,
+    conversations: units.filter((unit) => unit.kind === "conversation").length,
+    ...hint !== void 0 && { hint }
+  };
+}
+function trimHintFor(manifest, selected, limitBytes = DEFAULT_MAX_BYTES) {
+  const ticked = new Set(selected);
+  const droppable = manifest.units.filter((unit) => ticked.has(unit.id) && unit.kind === "conversation").sort((left, right) => right.bytes - left.bytes);
+  let remaining = manifest.units.filter((unit) => ticked.has(unit.id)).reduce((sum, unit) => sum + (unit.bytes || 0), 0);
+  if (remaining <= limitBytes) return void 0;
+  const named = [];
+  for (const unit of droppable) {
+    if (named.length >= droppable.length - 1) break;
+    remaining -= unit.bytes || 0;
+    named.push(`${unit.id} (${formatBytes(unit.bytes || 0)})`);
+    if (remaining <= limitBytes) break;
+  }
+  if (remaining > limitBytes) {
+    return `Even with one conversation left this is over ${formatBytes(limitBytes)}. Untick a derived file, record a shorter reproduction, or file the issue and attach the zip by hand.`;
+  }
+  return `Untick ${joinWithAnd(named)} to fit.`;
+}
+function joinWithAnd(parts) {
+  if (parts.length <= 1) return parts[0] ?? "";
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+
+// src/core/humanizeArtifacts.ts
+var ticket = (ref, kind, bytes) => `${ref ?? "art_?"} [${kind ?? "?"} \xB7 ${formatBytes(bytes ?? 0)}]`;
+function humanizeArtifactMinted(p) {
+  const label = p.label !== void 0 ? ` "${p.label}"` : "";
+  const by = p.tool !== void 0 ? ` by tool "${p.tool}"` : "";
+  return `Artifact minted${by} \u2014${label} ${ticket(p.ref, p.kind, p.bytes)}. The model routes this ticket, not the bytes.`;
+}
+function humanizeArtifactResolved(p) {
+  const actor = p.tool !== void 0 ? `Tool "${p.tool}"` : "The screen";
+  const verb = p.via === "head" ? "described" : p.via === "get" ? "fetched" : `redeemed (${p.via ?? "?"})`;
+  return `${actor} ${verb} artifact ${ticket(p.ref, p.kind, p.bytes)}.`;
+}
+function humanizeArtifactExpired(p) {
+  return `Artifact ${ticket(p.ref, p.kind, p.bytes)} swept (${p.reason ?? "retention"}) \u2014 its ref no longer resolves, and says so.`;
+}
+function humanizeArtifactRefused(p) {
+  const ref = p.ref !== void 0 ? ` for '${p.ref}'` : "";
+  const by = p.tool !== void 0 ? ` (tool "${p.tool}")` : "";
+  const detail = p.detail !== void 0 ? ` \u2014 ${p.detail}` : "";
+  return `Artifact ${p.op ?? "?"}${ref} refused: ${p.reason ?? "unknown reason"}${by}${detail}`;
+}
+function humanizeArtifactPresented(p) {
+  const s = p.snapshot;
+  const label = s?.label !== void 0 ? ` "${s.label}"` : "";
+  return `Presented${label} to the screen as '${p.as ?? "?"}' \u2014 ${ticket(p.ref, s?.kind, s?.bytes)}. The screen redeems the ref under its own session.`;
+}
+
+// src/core/humanizer.ts
 var defaultHumanizer = (event) => {
-  if (event.type === "agentfootprint.context.evaluated") return null;
+  if (event.type === "agentfootprint.context.evaluated") {
+    const cursorMove = event.payload.cursorMove;
+    return humanizeCursorMovePick(cursorMove);
+  }
+  if (event.type === "agentfootprint.skill.turn_routed") {
+    return humanizeTurnRouted(event.payload);
+  }
+  if (event.type === "agentfootprint.skill.route_conflict") {
+    return humanizeRouteConflict(event.payload);
+  }
+  switch (event.type) {
+    case "agentfootprint.artifacts.minted":
+      return humanizeArtifactMinted(event.payload);
+    case "agentfootprint.artifacts.resolved":
+      return humanizeArtifactResolved(event.payload);
+    case "agentfootprint.artifacts.expired":
+      return humanizeArtifactExpired(event.payload);
+    case "agentfootprint.artifacts.refused":
+      return humanizeArtifactRefused(event.payload);
+    case "agentfootprint.artifacts.presented":
+      return humanizeArtifactPresented(event.payload);
+  }
   switch (event.type) {
     // Composition
     case "agentfootprint.composition.enter":
@@ -1637,6 +1883,8 @@ var defaultHumanizer = (event) => {
       return `Skill "${event.payload.skillId}" activated \u2014 ${event.payload.reason}.`;
     case "agentfootprint.skill.deactivated":
       return `Skill "${event.payload.skillId}" deactivated \u2014 ${event.payload.reason}.`;
+    case "agentfootprint.skill.rejected":
+      return humanizeSkillRejected(event.payload);
     // Error
     case "agentfootprint.error.fatal":
       return `\u26D4 The run failed \u2014 ${event.payload.error}`;
@@ -2525,20 +2773,20 @@ function expandSubflowInternals(subflows) {
     replayWalkInto(subRec, walkSubflowSpec(spec, path, { recurse: false }));
     const sub = subTrace.getGraph();
     const prefix = path.endsWith("/") ? path : `${path}/`;
-    const q = (id) => id.startsWith(prefix) ? id : `${prefix}${id}`;
+    const q2 = (id) => id.startsWith(prefix) ? id : `${prefix}${id}`;
     for (const n of sub.nodes) {
       nodes.push({
         ...n,
-        id: q(n.id),
+        id: q2(n.id),
         data: { ...n.data, subflowOf: subflowId }
       });
     }
     for (const e of sub.edges) {
       edges.push({
         ...e,
-        id: `${q(e.source)}->${q(e.target)}`,
-        source: q(e.source),
-        target: q(e.target)
+        id: `${q2(e.source)}->${q2(e.target)}`,
+        source: q2(e.source),
+        target: q2(e.target)
       });
     }
   }
@@ -2821,62 +3069,6 @@ function layoutLensGraph(output, options = {}) {
   };
 }
 
-// src/core/bugReport/selection.ts
-var DEFAULT_MAX_BYTES = 24 * 1024 * 1024;
-function formatBytes(bytes) {
-  if (!Number.isFinite(bytes) || bytes < 0) return "0 bytes";
-  if (bytes < 1024) return `${Math.round(bytes)} bytes`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-function conversationUnits(manifest) {
-  return manifest.units.filter((unit) => unit.kind === "conversation");
-}
-function fileUnits(manifest) {
-  return manifest.units.filter((unit) => unit.kind !== "conversation");
-}
-function defaultSelection(manifest, recent = 3) {
-  const conversations = conversationUnits(manifest);
-  const keep = recent <= 0 ? [] : conversations.slice(Math.max(0, conversations.length - recent));
-  return [...keep.map((unit) => unit.id), ...fileUnits(manifest).map((unit) => unit.id)];
-}
-function measureSelection(manifest, selected, limitBytes = DEFAULT_MAX_BYTES) {
-  const ticked = new Set(selected);
-  const units = manifest.units.filter((unit) => ticked.has(unit.id));
-  const bytes = units.reduce((sum, unit) => sum + (unit.bytes || 0), 0);
-  const over = bytes > limitBytes;
-  const hint = over ? trimHintFor(manifest, ticked, limitBytes) : void 0;
-  return {
-    bytes,
-    limitBytes,
-    over,
-    label: `${formatBytes(bytes)} of ${formatBytes(limitBytes)}`,
-    conversations: units.filter((unit) => unit.kind === "conversation").length,
-    ...hint !== void 0 && { hint }
-  };
-}
-function trimHintFor(manifest, selected, limitBytes = DEFAULT_MAX_BYTES) {
-  const ticked = new Set(selected);
-  const droppable = manifest.units.filter((unit) => ticked.has(unit.id) && unit.kind === "conversation").sort((left, right) => right.bytes - left.bytes);
-  let remaining = manifest.units.filter((unit) => ticked.has(unit.id)).reduce((sum, unit) => sum + (unit.bytes || 0), 0);
-  if (remaining <= limitBytes) return void 0;
-  const named = [];
-  for (const unit of droppable) {
-    if (named.length >= droppable.length - 1) break;
-    remaining -= unit.bytes || 0;
-    named.push(`${unit.id} (${formatBytes(unit.bytes || 0)})`);
-    if (remaining <= limitBytes) break;
-  }
-  if (remaining > limitBytes) {
-    return `Even with one conversation left this is over ${formatBytes(limitBytes)}. Untick a derived file, record a shorter reproduction, or file the issue and attach the zip by hand.`;
-  }
-  return `Untick ${joinWithAnd(named)} to fit.`;
-}
-function joinWithAnd(parts) {
-  if (parts.length <= 1) return parts[0] ?? "";
-  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
-}
-
 // src/core/bugReport/issueBody.ts
 function buildIssueBody(args) {
   const { fields, manifest, evidence } = args;
@@ -2995,6 +3187,186 @@ function encodeBase64(bytes) {
   return btoa(binary);
 }
 
+// src/core/artifacts/resolvers.ts
+var ARTIFACT_HEAD_OP = "artifact-head";
+var ARTIFACT_GET_OP = "artifact-get";
+var NOT_FOUND_CODE = "ERR_ARTIFACT_NOT_FOUND";
+function httpArtifactResolver(options) {
+  if (typeof options?.url !== "string" || options.url.trim().length === 0) {
+    throw new Error(
+      "httpArtifactResolver needs `url` \u2014 the served agent's invoke path, the same one conversation turns POST to (e.g. '/invoke' or 'https://host/invoke')."
+    );
+  }
+  const doFetch = options.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new Error(
+      "httpArtifactResolver found no fetch: this runtime has no global fetch and none was passed. Pass one via { fetch } (Node < 18 needs a polyfill)."
+    );
+  }
+  const redeem = async (op, ref) => {
+    let response;
+    try {
+      response = await doFetch(options.url, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...options.headers },
+        body: JSON.stringify({
+          op,
+          ref,
+          ...options.sessionId !== void 0 && { sessionId: options.sessionId },
+          ...options.userId !== void 0 && { userId: options.userId }
+        })
+      });
+    } catch (err) {
+      return {
+        status: "failed",
+        message: `Could not reach ${options.url} to redeem '${ref}' (${err instanceof Error ? err.name || "network error" : "network error"}).`
+      };
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      return {
+        status: "failed",
+        message: `${options.url} answered ${response.status} with a body that is not JSON \u2014 not an artifact wire reply.`
+      };
+    }
+    const artifact = body?.artifact;
+    if (artifact !== null && typeof artifact === "object") {
+      const parcel = artifact;
+      const meta = parcel.meta;
+      if (meta === null || typeof meta !== "object" || typeof meta.kind !== "string") {
+        return {
+          status: "failed",
+          message: `${options.url} answered with an artifact body carrying no readable meta \u2014 not the published wire shape.`
+        };
+      }
+      return {
+        status: "live",
+        meta,
+        ...op === ARTIFACT_GET_OP && "data" in parcel && { data: parcel.data }
+      };
+    }
+    const code = typeof body?.code === "string" ? body.code : void 0;
+    if (code === NOT_FOUND_CODE) return { status: "absent" };
+    const message = typeof body?.error === "string" ? body.error : `${options.url} answered ${response.status} with no error message.`;
+    return { status: "failed", message, ...code !== void 0 && { code } };
+  };
+  return {
+    head: (ref) => redeem(ARTIFACT_HEAD_OP, ref),
+    get: (ref) => redeem(ARTIFACT_GET_OP, ref)
+  };
+}
+function storeArtifactResolver(options) {
+  const store = options?.store;
+  if (store === null || typeof store !== "object" || typeof store.head !== "function" || typeof store.get !== "function") {
+    throw new Error(
+      "storeArtifactResolver needs `store` \u2014 an object with the artifact read verbs `head(scope, ref)` and `get(scope, ref)` (any agentfootprint artifact store qualifies)."
+    );
+  }
+  if (!("scope" in options)) {
+    throw new Error(
+      'storeArtifactResolver needs `scope` \u2014 the isolation tuple the refs were minted under. A wrong scope resolves to "no data" by design, so it must be stated, never guessed.'
+    );
+  }
+  const failed = (ref, err) => ({
+    status: "failed",
+    message: err instanceof Error && err.message ? err.message : `The store threw while redeeming '${ref}'.`
+  });
+  return {
+    async head(ref) {
+      try {
+        const meta = await store.head(options.scope, ref);
+        return meta === null ? { status: "absent" } : { status: "live", meta };
+      } catch (err) {
+        return failed(ref, err);
+      }
+    },
+    async get(ref) {
+      try {
+        const record = await store.get(options.scope, ref);
+        return record === null ? { status: "absent" } : { status: "live", meta: record.meta, data: record.data };
+      } catch (err) {
+        return failed(ref, err);
+      }
+    }
+  };
+}
+
+// src/core/artifacts/presented.ts
+var PRESENTED_EVENT_TYPE = "agentfootprint.artifacts.presented";
+function readSnapshot(value) {
+  if (value === null || typeof value !== "object") return void 0;
+  const s = value;
+  if (typeof s.kind !== "string" || typeof s.mediaType !== "string" || typeof s.bytes !== "number")
+    return void 0;
+  return {
+    kind: s.kind,
+    mediaType: s.mediaType,
+    bytes: s.bytes,
+    ...typeof s.label === "string" && { label: s.label }
+  };
+}
+function readPresentedShape(value) {
+  if (typeof value.ref !== "string" || typeof value.as !== "string") return void 0;
+  const snapshot = readSnapshot(value.snapshot);
+  if (!snapshot) return void 0;
+  return { ref: value.ref, as: value.as, snapshot };
+}
+function readPresentedResult(value) {
+  let parsed = value;
+  if (typeof value === "string") {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      return void 0;
+    }
+  }
+  if (parsed === null || typeof parsed !== "object") return void 0;
+  const record = parsed;
+  if (record.presented !== true) return void 0;
+  const trunk = readPresentedShape(record);
+  if (!trunk) return void 0;
+  return {
+    ...trunk,
+    ...typeof record.toolCallId === "string" && { toolCallId: record.toolCallId }
+  };
+}
+function presentedFromEvents(events) {
+  if (!events) return [];
+  const found = [];
+  for (const item of events) {
+    if (item === null || typeof item !== "object") continue;
+    const wrapper = item;
+    const event = typeof wrapper.type === "string" ? wrapper : wrapper.event !== null && typeof wrapper.event === "object" ? wrapper.event : void 0;
+    if (!event || event.type !== PRESENTED_EVENT_TYPE) continue;
+    const payload = event.payload;
+    if (payload === null || typeof payload !== "object") continue;
+    const record = payload;
+    const trunk = readPresentedShape(record);
+    if (!trunk) continue;
+    found.push({
+      ...trunk,
+      ...typeof record.toolCallId === "string" && { toolCallId: record.toolCallId },
+      ...typeof record.iteration === "number" && { iteration: record.iteration }
+    });
+  }
+  return found;
+}
+function kindNoun(kind) {
+  const head = kind.split("/")[0]?.trim() ?? "";
+  if (head.length === 0) return "Artifact";
+  return head[0].toUpperCase() + head.slice(1);
+}
+function describePresented(presented) {
+  const { snapshot } = presented;
+  const name = snapshot.label !== void 0 ? `"${snapshot.label}"` : presented.ref;
+  return `${kindNoun(snapshot.kind)} \u2014 ${name} (${presented.as}, ${formatBytes(snapshot.bytes)})`;
+}
+function artifactPlaceholder(presented) {
+  return `${describePresented(presented)} \u2014 expired; re-run to regenerate.`;
+}
+
 export {
   ChangeNotifier,
   lensSnapshotRecorder,
@@ -3005,6 +3377,13 @@ export {
   observeRecording,
   buildStepGraphFromSnapshot,
   buildSpecTreeFromBoundary,
+  DEFAULT_MAX_BYTES,
+  formatBytes,
+  conversationUnits,
+  fileUnits,
+  defaultSelection,
+  measureSelection,
+  trimHintFor,
   defaultHumanizer,
   humanizeWith,
   makeTeachingHumanizer,
@@ -3041,18 +3420,17 @@ export {
   toReactFlow,
   defaultSize,
   layoutLensGraph,
-  DEFAULT_MAX_BYTES,
-  formatBytes,
-  conversationUnits,
-  fileUnits,
-  defaultSelection,
-  measureSelection,
-  trimHintFor,
   buildIssueBody,
   parseGithubRepo,
   MAX_ISSUE_URL_BYTES,
   TRUNCATION_NOTICE,
   buildNewIssueUrl,
-  encodeBase64
+  encodeBase64,
+  httpArtifactResolver,
+  storeArtifactResolver,
+  readPresentedResult,
+  presentedFromEvents,
+  describePresented,
+  artifactPlaceholder
 };
-//# sourceMappingURL=chunk-QBSH233H.js.map
+//# sourceMappingURL=chunk-ZSOYNKUI.js.map