agentfootprint-lens 0.33.1 → 0.35.0

package/README.md

@@ -358,6 +358,151 @@ 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.
+
+---
+
+## Answer a paused run with a real component (typed HITL)
+
+agentfootprint 9.24 taught every human-ask door (`askHuman`, the `ask`
+middleware, `defineTool({ checkInComponent })`) to carry an optional typed
+half beside the prose question: `{ componentId, props?, propsRef? }`. The id
+names a component **your screen registered** — ids + props, never markup the
+model wrote, the same no-eval law artifacts follow. Small props ride the ask
+inline; the big half (a 200-option picker's options) rides the **artifact
+store** as a `propsRef` claim ticket, redeemed through the same resolver and
+the same session identity as every other artifact.
+
+`<AwaitingPane>` is the screen's half:
+
+```tsx
+import {
+  AwaitingPane,
+  decisionRequestBody,
+  httpArtifactResolver,
+  registerDecisionComponent,
+} from 'agentfootprint-lens';
+
+// 1. Teach Lens your collectors, once at startup. ('option-picker' ships.)
+registerDecisionComponent({
+  componentId: 'refund-form',
+  component: ({ question, props, data, respond }) => (
+    <MyRefundForm limits={props} rows={data} onSubmit={(answer) => respond(answer)} />
+  ),
+});
+
+// 2. When a reply comes back awaiting, render the pane. The lens does NOT
+//    own the POST — your app does; decisionRequestBody formats the body.
+const resolver = httpArtifactResolver({ url: '/invoke', sessionId });
+<AwaitingPane
+  awaiting={reply.awaiting}
+  resolver={resolver}
+  onDecision={(decision) =>
+    fetch('/invoke', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(decisionRequestBody({ decision, sessionId })),
+    })
+  }
+/>
+```
+
+The person clicks; `onDecision` receives **the structured decision** — the
+option's id, or the approve/decline record (`approveDecision` /
+`declineDecision`, byte-compatible with agentfootprint's check-in
+vocabulary). After answering, the pane renders the decision as one sentence —
+*"Approved by alice@ops — 'verified'."* — which is **display only**: the
+structured decision is the record; the words are a rendering of it.
+
+Nothing on this road dead-ends the human. An unknown `componentId` falls back
+to the prose question plus a plain answer box and *says so*; an expired
+`propsRef` renders the honest placeholder plus the answer box; a crashed
+registered component is caught and stated; a consent gate (`checkIn` /
+middleware `ask`) falls back to Approve/Decline with a required "deciding as"
+field, because an audit record with no actor names nobody.
+
+The headless half is on `agentfootprint-lens/core` — `readAwaitingComponent`
+(era-robust: reads `awaiting.component` and the three `pauseData` homes),
+`approveDecision` / `declineDecision`, `decisionRequestBody`,
+`decisionSentence`, `isConsentAsk` — so a Vue or CLI shell can build the same
+pane.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -522,6 +667,36 @@ 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).
+
+### `<AwaitingPane>` — answer a paused run with a real component
+
+Takes the `awaiting` payload a served agent replied with (`awaiting`), an
+optional `ArtifactResolver` (`resolver`, only needed when the ask ships a
+`propsRef`), and `onDecision` — which receives the person's STRUCTURED
+decision; your app posts it (`decisionRequestBody` formats the wire body).
+Renders the component registered for the ask's `componentId`
+(`registerDecisionComponent({ componentId, component })`) with `{ question,
+props, data, respond }`; `'option-picker'` ships as a built-in. Unknown id,
+expired ref, failed door and crashed component all state themselves and fall
+back to a live answer surface — never a dead end. After answering it renders
+the decision as one sentence (display only; the structured decision is the
+record). The headless half — `readAwaitingComponent`, `approveDecision` /
+`declineDecision`, `decisionRequestBody`, `decisionSentence`, `isConsentAsk`
+— is on `agentfootprint-lens/core`. See
+[Answer a paused run with a real component](#answer-a-paused-run-with-a-real-component-typed-hitl).
+
 ### Headless core
 
 `agentfootprint-lens/core` is React-free: `LensRecorder`, `ChangeNotifier`,

package/dist/{chunk-6EHPI5F6.js → chunk-PBRAJNVI.js}

@@ -1693,6 +1693,89 @@ function humanizeCursorMovePick(move) {
   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") {
@@ -1705,6 +1788,18 @@ var defaultHumanizer = (event) => {
   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":
@@ -2974,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;
@@ -3148,6 +3187,271 @@ 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.`;
+}
+
+// src/core/hitl/decision.ts
+function readAwaitingComponent(awaiting) {
+  if (typeof awaiting !== "object" || awaiting === null) return void 0;
+  const pending = awaiting;
+  const direct = asComponent(pending.component);
+  if (direct) return direct;
+  const bag = pending.pauseData;
+  if (typeof bag !== "object" || bag === null) return void 0;
+  const homes = bag;
+  return asComponent(homes.component) ?? asComponent(
+    typeof homes.checkIn === "object" && homes.checkIn !== null ? homes.checkIn.component : void 0
+  ) ?? asComponent(
+    typeof homes.ask === "object" && homes.ask !== null ? homes.ask.component : void 0
+  );
+}
+function asComponent(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const c = value;
+  if (typeof c.componentId !== "string" || c.componentId.length === 0) return void 0;
+  return value;
+}
+function isConsentAsk(awaiting) {
+  if (typeof awaiting !== "object" || awaiting === null) return false;
+  const pending = awaiting;
+  return typeof pending.checkIn === "object" && pending.checkIn !== null || typeof pending.ask === "object" && pending.ask !== null;
+}
+function approveDecision(input) {
+  return buildConsent(true, input, "approveDecision");
+}
+function declineDecision(input) {
+  return buildConsent(false, input, "declineDecision");
+}
+function buildConsent(approved, input, door) {
+  if (typeof input?.by !== "string" || input.by.trim().length === 0) {
+    throw new Error(
+      `${door} needs \`by\` \u2014 who is deciding (an operator id, an email). The decision is an audit record, and a record with no actor names nobody; it cannot be defaulted.`
+    );
+  }
+  return {
+    approved,
+    by: input.by,
+    at: Date.now(),
+    ...input.note !== void 0 && input.note.length > 0 && { note: input.note }
+  };
+}
+function decisionRequestBody(args) {
+  if (args === null || typeof args !== "object" || !("decision" in args)) {
+    throw new Error(
+      "decisionRequestBody needs `decision` \u2014 the structured answer to the pending ask. Its presence is what distinguishes a resume from a new message on the wire."
+    );
+  }
+  if (args.decision === void 0) {
+    throw new Error(
+      "decisionRequestBody refused `decision: undefined` \u2014 JSON drops the key, the wire would read a NEW MESSAGE, and the pause would sit unanswered while the screen believed it answered. Post the actual decision (`null` is allowed; absence is not)."
+    );
+  }
+  return {
+    input: args.input ?? "",
+    decision: args.decision,
+    ...args.sessionId !== void 0 && { sessionId: args.sessionId }
+  };
+}
+var SENTENCE_JSON_CAP = 120;
+function decisionSentence(decision) {
+  if (isConsentDecision(decision)) {
+    const verb = decision.approved ? "Approved" : "Declined";
+    const note = decision.note !== void 0 ? ` \u2014 "${decision.note}"` : "";
+    return `${verb} by ${decision.by}${note}.`;
+  }
+  if (typeof decision === "string") return `Answered: "${decision}".`;
+  if (decision === null || typeof decision !== "object")
+    return `Answered: ${String(decision)}.`;
+  let json;
+  try {
+    json = JSON.stringify(decision) ?? String(decision);
+  } catch {
+    json = "[unserializable]";
+  }
+  if (json.length > SENTENCE_JSON_CAP) json = `${json.slice(0, SENTENCE_JSON_CAP)}\u2026`;
+  return `Answered with a structured decision: ${json}.`;
+}
+function isConsentDecision(value) {
+  return typeof value === "object" && value !== null && typeof value.approved === "boolean" && typeof value.by === "string";
+}
+
 export {
   ChangeNotifier,
   lensSnapshotRecorder,
@@ -3158,6 +3462,13 @@ export {
   observeRecording,
   buildStepGraphFromSnapshot,
   buildSpecTreeFromBoundary,
+  DEFAULT_MAX_BYTES,
+  formatBytes,
+  conversationUnits,
+  fileUnits,
+  defaultSelection,
+  measureSelection,
+  trimHintFor,
   defaultHumanizer,
   humanizeWith,
   makeTeachingHumanizer,
@@ -3194,18 +3505,24 @@ 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,
+  readAwaitingComponent,
+  isConsentAsk,
+  approveDecision,
+  declineDecision,
+  decisionRequestBody,
+  decisionSentence,
+  isConsentDecision
 };
-//# sourceMappingURL=chunk-6EHPI5F6.js.map
+//# sourceMappingURL=chunk-PBRAJNVI.js.map