agentfootprint-lens 0.34.0 → 0.35.0

package/README.md

@@ -436,6 +436,73 @@ 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-*`
@@ -613,6 +680,23 @@ The headless half — `httpArtifactResolver`, `storeArtifactResolver`,
 `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-ZSOYNKUI.js → chunk-PBRAJNVI.js}

@@ -3367,6 +3367,91 @@ 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,
@@ -3431,6 +3516,13 @@ export {
   readPresentedResult,
   presentedFromEvents,
   describePresented,
-  artifactPlaceholder
+  artifactPlaceholder,
+  readAwaitingComponent,
+  isConsentAsk,
+  approveDecision,
+  declineDecision,
+  decisionRequestBody,
+  decisionSentence,
+  isConsentDecision
 };
-//# sourceMappingURL=chunk-ZSOYNKUI.js.map
+//# sourceMappingURL=chunk-PBRAJNVI.js.map