@inhuman.tools/harness-sdk 0.0.0-stage → 0.1.0

package/src/text/sugarcoat.ts

@@ -0,0 +1,165 @@
+/**
+ * Scheme result projection for the tape and for plain-text clients: sugarcoat the
+ * stored source, and classify printed values into typed parts. No colour and no
+ * widget types. `sugarcoat-paint.ts` adds those, so a headless client can read this
+ * file without loading the paint substrate.
+ */
+import { toSExprString } from "@here.build/arrival-serializer";
+import { schemeToSugarcoat } from "@here.build/arrival-sugarcoat";
+import type { ToolOutcomeSnap } from "@inhuman.tools/harness-model/schemas";
+
+import { unwrapTopLevelSource } from "./unwrap-program.js";
+
+export function sugarcoatSource(src: string): string {
+  if (src.trim() === "") return src;
+  try {
+    const sweet = schemeToSugarcoat(src);
+    return sweet === "" ? src : sweet;
+  } catch {
+    return src;
+  }
+}
+
+/** Tape/object paint for a scheme_repl program. Splices wrapping begin/list/`[]` first. */
+export function sugarcoatProgram(src: string): string {
+  return sugarcoatSource(unwrapTopLevelSource(src));
+}
+
+/** JSON-quoted payloads (`"a\\nb"`) become the string with real newlines. Bare `C:\\new` stays. */
+export function decodeDisplayString(text: string): string {
+  const trimmed = text.trim();
+  if (trimmed.length < 2 || !trimmed.startsWith('"') || !trimmed.endsWith('"')) return text;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return typeof parsed === "string" ? parsed : text;
+  } catch {
+    return text;
+  }
+}
+
+export type SchemePaintKind = "text" | "markdown" | "number" | "boolean" | "syntax";
+
+export type SchemePaintPart = {
+  readonly kind: SchemePaintKind;
+  readonly text: string;
+};
+
+export type SchemePaintReceipt =
+  | { readonly kind: "none" }
+  | SchemePaintPart
+  | {
+      readonly kind: "parts";
+      readonly parts: readonly SchemePaintPart[];
+    };
+
+/** Scheme boolean spellings. The highlighter colours the same atoms. */
+export const BOOLEAN_ATOMS: ReadonlySet<string> = new Set(["#t", "#f", "#true", "#false"]);
+
+/** Prefixes `toSExprString` emits. A cut marker is recognized anywhere so a
+ *  leading display note does not hide it. */
+function serializerForm(text: string): boolean {
+  if (text.includes("\n#| … output hard-truncated at ") || text.includes("…(+")) return true;
+  const trimmed = text.trimStart();
+  return (
+    trimmed.startsWith(";;") ||
+    trimmed.startsWith("#|") ||
+    trimmed.startsWith("(") ||
+    trimmed.startsWith("[") ||
+    trimmed.startsWith("{") ||
+    trimmed.startsWith('"') ||
+    trimmed.startsWith("'") ||
+    trimmed.startsWith("#\\") ||
+    trimmed.startsWith(":")
+  );
+}
+
+export function formatSchemeResult(snap: ToolOutcomeSnap | null | undefined): string {
+  const painted = schemePaintReceipt(snap);
+  if (painted.kind === "none") return "";
+  if (painted.kind === "parts") return painted.parts.map((part) => part.text).join("\n");
+  return painted.text;
+}
+
+export type FilePaintHint = { readonly path: string; readonly text: string };
+
+/** One receipt per printed value. A display string stays plain. Serializer text is syntax. */
+export function schemePaintReceipt(
+  snap: ToolOutcomeSnap | null | undefined,
+  hints: readonly FilePaintHint[] = [],
+): SchemePaintReceipt {
+  if (snap == null) return { kind: "none" };
+  if (snap.ok === false) {
+    const text = decodeDisplayString(snap.text ?? "");
+    return text === "" ? { kind: "none" } : { kind: "text", text };
+  }
+  if (!("value" in snap) || snap.value === undefined) {
+    const text = decodeDisplayString(typeof snap.text === "string" ? snap.text : "");
+    return text === "" ? { kind: "none" } : { kind: "text", text };
+  }
+  const items = Array.isArray(snap.value) ? snap.value : [snap.value];
+  const parts = items
+    .map((item) => schemePart(item, hints))
+    .filter((part): part is SchemePaintPart => part !== undefined);
+  if (parts.length === 0) return { kind: "none" };
+  if (parts.length === 1) {
+    const only = parts[0];
+    return only === undefined ? { kind: "none" } : only;
+  }
+  return { kind: "parts", parts };
+}
+
+export function isMarkdownPath(path: string): boolean {
+  return path.endsWith(".md") || path.endsWith(".mdx");
+}
+
+export function fileSchemePart(path: string, text: string): SchemePaintPart | undefined {
+  const body = decodeDisplayString(text);
+  if (body === "") return undefined;
+  return isMarkdownPath(path) ? { kind: "markdown", text: body } : { kind: "text", text: body };
+}
+
+function isFilePrint(value: unknown): value is { text: string; face: { kind: "file"; path: string } } {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const rec = value as { text?: unknown; face?: { kind?: unknown; path?: unknown } };
+  return typeof rec.text === "string" && rec.face?.kind === "file" && typeof rec.face.path === "string";
+}
+
+function hintedFilePart(text: string, hints: readonly FilePaintHint[]): SchemePaintPart | undefined {
+  const matched = new Set(hints.filter((hint) => hint.text === text).map((hint) => hint.path));
+  if (matched.size !== 1) return undefined;
+  const [path] = matched;
+  return path === undefined ? undefined : fileSchemePart(path, text);
+}
+
+function schemePart(value: unknown, hints: readonly FilePaintHint[] = []): SchemePaintPart | undefined {
+  if (typeof value === "boolean") return { kind: "boolean", text: value ? "#t" : "#f" };
+  if (typeof value === "number" && Number.isFinite(value)) return { kind: "number", text: String(value) };
+  if (typeof value === "bigint") return { kind: "number", text: String(value) };
+  if (isFilePrint(value)) return fileSchemePart(value.face.path, value.text);
+  if (typeof value === "string") {
+    const text = decodeDisplayString(value);
+    const hinted = hintedFilePart(text, hints);
+    if (hinted !== undefined) return hinted;
+    if (BOOLEAN_ATOMS.has(text)) return { kind: "boolean", text };
+    // Whole-value number, not a tokenizer prefix. `#t` is a boolean, not `#`+digit.
+    if (
+      text !== "" &&
+      !/\s/.test(text) &&
+      !BOOLEAN_ATOMS.has(text) &&
+      (Number.isFinite(Number(text)) || /^[+-]?#[xbodei]/i.test(text))
+    ) {
+      return { kind: "number", text };
+    }
+    if (text === "") return undefined;
+    // Eval already stored `toSExprString` as a string. Those forms highlight;
+    // a display sentence and a file body do not start this way.
+    return serializerForm(text) ? { kind: "syntax", text } : { kind: "text", text };
+  }
+  try {
+    const text = toSExprString(value);
+    return text === "" ? undefined : { kind: "syntax", text };
+  } catch {
+    const text = decodeDisplayString(String(value));
+    return text === "" ? undefined : { kind: "text", text };
+  }
+}

package/src/text/unwrap-program.ts

@@ -0,0 +1,133 @@
+// Tape projection of substrate `unwrap-begin.ts`. Execution splices the AST;
+// this file splices the stored expr so the identity line matches what ran.
+// CHANGE ONLY with that file — same three wrappers, same quote/dot refusals.
+
+import { tokenize } from "@here.build/arrival/lsp-internals";
+
+const SPLICE_HEADS = new Set(["begin", "list"]);
+const CLOSE = new Set([")", "]", "}"]);
+const QUOTE_PREFIX = new Set(["'", "`", ",", ",@"]);
+
+function isOpen(tok: string): boolean {
+  return (
+    tok === "(" || tok === "[" || tok === "{" || (tok.startsWith("#") && !tok.startsWith("#\\") && tok.endsWith("("))
+  );
+}
+
+function isSkippable(tok: string): boolean {
+  return /^\s+$/.test(tok) || tok.startsWith(";") || tok.startsWith("#|") || tok.startsWith("#;");
+}
+
+type Token = { readonly token: string; readonly offset: number };
+
+function tokenAt(tokens: readonly Token[], index: number): Token | undefined {
+  return tokens[index];
+}
+
+function skipSkippable(tokens: readonly Token[], index: number): number {
+  let i = index;
+  for (;;) {
+    const tok = tokenAt(tokens, i);
+    if (tok == null || !isSkippable(tok.token)) return i;
+    i += 1;
+  }
+}
+
+function splitTopLevel(source: string): string[] {
+  const tokens = tokenize(source, true);
+  const starts: number[] = [];
+  let depth = 0;
+  let between = true;
+  for (const { token, offset } of tokens) {
+    if (isSkippable(token)) continue;
+    if (between) {
+      starts.push(offset);
+      between = false;
+    }
+    if (isOpen(token)) depth++;
+    else if (CLOSE.has(token)) {
+      if (depth > 0) depth--;
+      if (depth === 0) between = true;
+    } else if (depth === 0 && !QUOTE_PREFIX.has(token)) {
+      between = true;
+    }
+  }
+  return starts.map((s, i) => source.slice(s, starts[i + 1] ?? source.length).trim()).filter(Boolean);
+}
+
+function matchGroup(
+  tokens: readonly Token[],
+  openIdx: number,
+  closeTok: string,
+): { readonly closeIdx: number; readonly dotted: boolean } | undefined {
+  let depth = 0;
+  let dotted = false;
+  for (let i = openIdx; i < tokens.length; i++) {
+    const row = tokenAt(tokens, i);
+    if (row == null) return undefined;
+    const tok = row.token;
+    if (isSkippable(tok)) continue;
+    if (isOpen(tok)) {
+      depth += 1;
+      continue;
+    }
+    if (CLOSE.has(tok)) {
+      depth -= 1;
+      if (depth === 0) {
+        if (tok !== closeTok) return undefined;
+        return { closeIdx: i, dotted };
+      }
+      continue;
+    }
+    if (depth === 1 && tok === ".") dotted = true;
+  }
+  return undefined;
+}
+
+function wrapperInterior(src: string): string[] | undefined {
+  const tokens = tokenize(src, true);
+  const firstIdx = skipSkippable(tokens, 0);
+  const first = tokenAt(tokens, firstIdx);
+  if (first == null || QUOTE_PREFIX.has(first.token)) return undefined;
+
+  if (first.token === "[" || first.token === "#(") {
+    const closed = matchGroup(tokens, firstIdx, first.token === "[" ? "]" : ")");
+    if (closed == null || closed.dotted) return undefined;
+    if (skipSkippable(tokens, closed.closeIdx + 1) < tokens.length) return undefined;
+    const closer = tokenAt(tokens, closed.closeIdx);
+    if (closer == null) return undefined;
+    return splitTopLevel(src.slice(first.offset + first.token.length, closer.offset));
+  }
+
+  if (first.token !== "(") return undefined;
+  const nameIdx = skipSkippable(tokens, firstIdx + 1);
+  const name = tokenAt(tokens, nameIdx);
+  if (name == null || !SPLICE_HEADS.has(name.token.toLowerCase())) return undefined;
+  const closed = matchGroup(tokens, firstIdx, ")");
+  if (closed == null || closed.dotted) return undefined;
+  if (skipSkippable(tokens, closed.closeIdx + 1) < tokens.length) return undefined;
+  const closer = tokenAt(tokens, closed.closeIdx);
+  if (closer == null) return undefined;
+  return splitTopLevel(src.slice(name.offset + name.token.length, closer.offset));
+}
+
+export function unwrapTopLevelSource(src: string): string {
+  if (src.trim() === "") return src;
+  try {
+    const out: string[] = [];
+    let spliced = false;
+    const visit = (stmt: string): void => {
+      const body = wrapperInterior(stmt);
+      if (body === undefined) {
+        out.push(stmt);
+        return;
+      }
+      spliced = true;
+      for (const inner of body) visit(inner);
+    };
+    for (const stmt of splitTopLevel(src)) visit(stmt);
+    return spliced ? out.join("\n") : src;
+  } catch {
+    return src;
+  }
+}

package/src/text/work-text.ts

@@ -0,0 +1,388 @@
+/**
+ * What a tool or scheme call says, as plain data: state, identity, receipt. No
+ * paint. `work-cells.ts` turns a `WorkCellFace` into layout nodes; the headless
+ * eval client prints the same face as text. Nothing here may import quickdraw —
+ * a helper that needs it belongs in `work-cells.ts`.
+ */
+import {
+  ApprovableJob,
+  type BlobPeek,
+  documentRoot,
+  FileMutateToolJob,
+  type KernelRoot,
+  MCPToolJob,
+  type PriorText,
+  ProgrammaticJob,
+  reactChunks,
+  SessionRoot,
+  SessionTurn,
+  shellTailOf,
+  ToolCallJob,
+} from "@inhuman.tools/harness-model";
+
+import { agentExpandBlock } from "./agent-cover.js";
+import { coverAskAnnotation, identityLine, isPathShapedName } from "./identity.js";
+import { outcomeSnapOf, schemeCellState, toolCellState, type SchemeCellState, type ToolCellState } from "./liveness.js";
+import { prettyResult } from "./pretty-identity.js";
+import { schemePaintReceipt, type SchemePaintPart } from "./sugarcoat.js";
+
+export type WorkCellState = ToolCellState | SchemeCellState;
+
+export type ReceiptFace =
+  | { readonly kind: "none" }
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "markdown"; readonly text: string }
+  | { readonly kind: "stream"; readonly text: string }
+  | { readonly kind: "syntax"; readonly text: string }
+  | { readonly kind: "number"; readonly text: string }
+  | { readonly kind: "boolean"; readonly text: string }
+  | { readonly kind: "parts"; readonly parts: readonly SchemePaintPart[] }
+  | {
+      readonly kind: "diff";
+      readonly old: string;
+      readonly new: string;
+      readonly path: string;
+      /** 1-based file line of the span. Omitted when the span is the whole file. */
+      readonly lineStart?: number;
+    };
+
+export function receiptPlainText(receipt: ReceiptFace): string {
+  if (receipt.kind === "none" || receipt.kind === "diff") return "";
+  if (receipt.kind === "parts") return receipt.parts.map((part) => part.text).join("\n");
+  return receipt.text;
+}
+
+export type WorkCellFace = {
+  readonly key: string;
+  readonly state: WorkCellState;
+  readonly name: string;
+  readonly object: string;
+  readonly status: string;
+  readonly caption: string;
+  readonly pathShaped: boolean;
+  /** Quiet server / louder action (MCP). Plain tools stay one voice Text. */
+  readonly split: boolean;
+  readonly agent: boolean;
+  readonly pretty: boolean;
+  readonly prettyBlock: string;
+  /** What the worker actually answered. Empty until a reply lands. */
+  readonly response: string;
+  readonly indent: boolean;
+  readonly collapsed: boolean;
+  readonly receipt: ReceiptFace;
+  /** Cover rim already names this work (`coverAskAnnotation`). */
+  readonly rimNamed: boolean;
+};
+
+function stringArg(args: Readonly<Record<string, unknown>> | null, key: string): string {
+  const value = args?.[key];
+  return typeof value === "string" ? value : "";
+}
+
+/** Whole-file `read_file` of the same path on this turn — already on the tape when host prior did not sync. */
+function priorFromTape(work: ToolCallJob, filePath: string, span: string): string | null {
+  if (filePath === "") return null;
+  const session = documentRoot(work);
+  if (!(session instanceof SessionRoot)) return null;
+  const turn = session.head;
+  if (!(turn instanceof SessionTurn)) return null;
+  for (const chunk of reactChunks(turn)) {
+    if (!(chunk instanceof ToolCallJob) || chunk.name !== "read_file" || chunk === work) continue;
+    const args = chunk.args;
+    if (stringArg(args, "path") !== filePath) continue;
+    if (args?.offset !== undefined || args?.limit !== undefined) continue;
+    const text = resultText(chunk);
+    if (text !== "" && (span === "" || containsSpan(text, span))) return text;
+  }
+  return null;
+}
+
+/**
+ * The prior stamped on the job: inline, or the reference to its blob. Field reads, not
+ * `instanceof` — duplicate class identity must not drop the file.
+ */
+function stampedPrior(work: ToolCallJob): PriorText | null {
+  const host = work as { prior?: PriorText | null; priorContent?: unknown };
+  if (host.prior !== undefined) return host.prior;
+  return typeof host.priorContent === "string" ? { kind: "inline", text: host.priorContent } : null;
+}
+
+/**
+ * Host prior text. A blob prior whose text the cache does not hold yet reads as no prior, so the
+ * face is the one a replica without the prior paints, and asks the cache for the text.
+ */
+function priorOf(work: ToolCallJob, filePath: string, span: string, blobs?: BlobPeek): string | null {
+  const stamped = stampedPrior(work);
+  let text: string | null = null;
+  if (stamped?.kind === "inline") text = stamped.text;
+  else if (stamped?.kind === "blob") {
+    const { sha256 } = stamped.blob;
+    text = blobs?.peek(sha256) ?? null;
+    if (text === null) blobs?.want(sha256);
+  }
+  return text ?? priorFromTape(work, filePath, span);
+}
+
+function containsSpan(file: string, span: string): boolean {
+  if (span === "" || file.includes(span)) return true;
+  return file.replaceAll("\r\n", "\n").includes(span.replaceAll("\r\n", "\n"));
+}
+
+function spanLineStart(file: string | null | undefined, span: string): number | undefined {
+  if (file == null || span === "") return undefined;
+  const normalizedFile = file.replaceAll("\r\n", "\n");
+  const normalizedSpan = span.replaceAll("\r\n", "\n");
+  let idx = normalizedFile.indexOf(normalizedSpan);
+  if (idx === -1) {
+    const first = normalizedSpan.split("\n")[0] ?? "";
+    if (first === "" || first === normalizedSpan) return undefined;
+    idx = normalizedFile.indexOf(first);
+  }
+  if (idx === -1) return undefined;
+  let line = 1;
+  for (let i = 0; i < idx; i++) if (normalizedFile[i] === "\n") line++;
+  return line <= 1 ? undefined : line;
+}
+
+/** Literal insert. String.replace treats `$` in new_string as a substitution pattern. */
+function replaceSpan(haystack: string, needle: string, replacement: string, all: boolean): string {
+  if (all) return haystack.split(needle).join(replacement);
+  const at = haystack.indexOf(needle);
+  return at === -1 ? haystack : haystack.slice(0, at) + replacement + haystack.slice(at + needle.length);
+}
+
+function editFileDiff(work: ToolCallJob, blobs?: BlobPeek): ReceiptFace {
+  const args = work.args;
+  const old = stringArg(args, "old_string");
+  const next = stringArg(args, "new_string");
+  if (old === "" && next === "") return { kind: "none" };
+  const filePath = stringArg(args, "path");
+  const replaceAll = args?.replace_all === true;
+  const prior = priorOf(work, filePath, old, blobs);
+  if (prior !== null && old !== "" && prior.includes(old)) {
+    return {
+      kind: "diff",
+      old: prior,
+      new: replaceSpan(prior, old, next, replaceAll),
+      path: filePath,
+    };
+  }
+  const stampedLine = (work as { priorLineStart?: unknown }).priorLineStart;
+  const lineStart =
+    spanLineStart(prior, old) ??
+    (typeof stampedLine === "number" && Number.isFinite(stampedLine) && stampedLine > 1 ? stampedLine : undefined);
+  return {
+    kind: "diff",
+    old,
+    new: next,
+    path: filePath,
+    ...(lineStart === undefined ? {} : { lineStart }),
+  };
+}
+
+/** Create = empty-old. Overwrite = stored prior text. Binary / unstamped exist is not a create Diff. */
+function writeFileDiff(work: ToolCallJob, blobs?: BlobPeek): ReceiptFace {
+  const args = work.args;
+  const next = stringArg(args, "content");
+  const filePath = stringArg(args, "path");
+  if (next === "") return { kind: "none" };
+  const prior = priorOf(work, filePath, "", blobs);
+  if (prior !== null) {
+    return { kind: "diff", old: prior, new: next, path: filePath };
+  }
+  if (work instanceof FileMutateToolJob && work.existed === true) return { kind: "none" };
+  return { kind: "diff", old: "", new: next, path: filePath };
+}
+
+function fileHintsOf(work: ProgrammaticJob): { readonly path: string; readonly text: string }[] {
+  const hints: { path: string; text: string }[] = [];
+  for (const inner of work.toolCalls) {
+    if (inner.name !== "read_file") continue;
+    const text = resultText(inner);
+    const path = stringArg(inner.args, "path");
+    if (text === "" || path === "") continue;
+    hints.push({ path, text });
+  }
+  return hints;
+}
+
+function resultText(work: ToolCallJob | ProgrammaticJob): string {
+  const snap = outcomeSnapOf(work);
+  if (snap === null) return "";
+  if (typeof snap.text === "string" && snap.text !== "") return snap.text;
+  if ("value" in snap) {
+    try {
+      return typeof snap.value === "string" ? snap.value : JSON.stringify(snap.value);
+    } catch {
+      return String(snap.value);
+    }
+  }
+  return "";
+}
+
+function shellReceipt(work: ToolCallJob): string {
+  const snap = outcomeSnapOf(work);
+  const value = snap?.value;
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const rec = value as { stdout?: unknown; stderr?: unknown };
+    const parts: string[] = [];
+    if (typeof rec.stdout === "string" && rec.stdout !== "") parts.push(rec.stdout);
+    if (typeof rec.stderr === "string" && rec.stderr !== "") parts.push(rec.stderr);
+    if (parts.length > 0) return parts.join("\n");
+  }
+  return resultText(work);
+}
+
+/** `applyDenyReceipt` copies this into `outcomeJson.text`. The tape shows that copy once. */
+function denialExplanation(work: ToolCallJob): string | null {
+  const snap = outcomeSnapOf(work);
+  const vote = work.policyResult;
+  const denied =
+    snap?.code === "policy_denied" ||
+    ((vote === "block" || vote === "deny") && snap?.ok !== true && work.humanApprove !== true);
+  if (!denied) return null;
+  const policy = (work.policyMessage ?? "").trim();
+  const outcome = resultText(work);
+  const outcomeTrim = outcome.trim();
+  if (policy !== "" && (outcomeTrim === "" || outcomeTrim === policy)) return policy;
+  return outcomeTrim === "" ? "" : outcome;
+}
+
+function shellDenialLine(text: string): ReceiptFace {
+  return { kind: "parts", parts: [{ kind: "text", text }] };
+}
+
+/** Suggestion Diff from args. Pin uses this even after `approved`, while tape live does not. */
+export function mutateSuggestionReceipt(work: ToolCallJob, blobs?: BlobPeek): ReceiptFace {
+  if (work.name === "edit_file") return editFileDiff(work, blobs);
+  if (work.name === "write_file") return writeFileDiff(work, blobs);
+  return { kind: "none" };
+}
+
+function receiptFace(work: ToolCallJob | ProgrammaticJob, state: WorkCellState, blobs?: BlobPeek): ReceiptFace {
+  if (state === "live") {
+    if (work instanceof ToolCallJob && work.name === "shell") {
+      const tail = shellTailOf(work);
+      if (tail !== null && tail.text !== "") return { kind: "stream", text: tail.text };
+    }
+    return { kind: "none" };
+  }
+  if (state === "ask") {
+    if (work instanceof ToolCallJob) {
+      const suggestion = mutateSuggestionReceipt(work, blobs);
+      if (suggestion.kind !== "none") return suggestion;
+    }
+    if (work instanceof ToolCallJob && work.name === "shell") {
+      const policy = work.policyMessage ?? "";
+      return policy === "" ? { kind: "none" } : { kind: "text", text: policy };
+    }
+    if (work instanceof MCPToolJob) {
+      return { kind: "none" };
+    }
+    return { kind: "none" };
+  }
+  if (work instanceof ProgrammaticJob) {
+    return schemePaintReceipt(outcomeSnapOf(work), fileHintsOf(work));
+  }
+  const explanation = denialExplanation(work);
+  if (explanation !== null) {
+    if (explanation === "") return { kind: "none" };
+    return work.name === "shell" ? shellDenialLine(explanation) : { kind: "text", text: explanation };
+  }
+  if (work.name === "edit_file") return editFileDiff(work, blobs);
+  if (work.name === "write_file") {
+    const diff = writeFileDiff(work, blobs);
+    if (diff.kind !== "none") return diff;
+    const text = resultText(work);
+    return text === "" ? { kind: "none" } : { kind: "text", text };
+  }
+  if (work.name === "read_file") {
+    // The tape row is the path only. File text is not a receipt.
+    return { kind: "none" };
+  }
+  if (work.name === "shell") {
+    const sealed = shellReceipt(work);
+    return sealed === "" ? { kind: "none" } : { kind: "text", text: sealed };
+  }
+  const serialized = prettyResult(work, outcomeSnapOf(work));
+  if (serialized !== null && serialized !== "") {
+    return serialized.includes("**") || serialized.includes("`") || serialized.includes("![")
+      ? { kind: "markdown", text: serialized }
+      : { kind: "text", text: serialized };
+  }
+  const text = resultText(work);
+  return text === "" ? { kind: "none" } : { kind: "text", text };
+}
+
+/** Kernel glance overlay for a named-agent call. `status` is the dim suffix. */
+export type CallStatus = {
+  readonly status?: string;
+  readonly model?: string;
+};
+
+function faceText(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/** The worker's reply, not the prompt we sent. Failures stay the gutter. */
+function agentResponseText(work: ToolCallJob | ProgrammaticJob): string {
+  if (!(work instanceof ToolCallJob)) return "";
+  const snap = outcomeSnapOf(work);
+  if (snap === null || snap.ok !== true) return "";
+  if ("value" in snap && snap.value != null) {
+    if (typeof snap.value === "string") return snap.value.trim();
+    try {
+      return JSON.stringify(snap.value, null, 2);
+    } catch {
+      return String(snap.value);
+    }
+  }
+  return typeof snap.text === "string" ? snap.text.trim() : "";
+}
+
+export function workCellFace(
+  work: ToolCallJob | ProgrammaticJob,
+  key: string,
+  indent: boolean,
+  collapsed = true,
+  glance: CallStatus | string = "",
+  kernel?: KernelRoot | null,
+  blobs?: BlobPeek,
+): WorkCellFace {
+  const jobState = work instanceof ProgrammaticJob ? schemeCellState(work) : toolCellState(work);
+  const line = identityLine(work, kernel);
+  const comment =
+    work instanceof ApprovableJob && work.approvalComment != null && work.approvalComment !== ""
+      ? work.approvalComment
+      : "";
+  const agent = line.agent === true;
+  const pretty = line.pretty === true && !agent;
+  const tape = typeof glance === "string" ? { status: glance } : glance;
+  return {
+    key,
+    // Live bag with an open inner paints sealed chrome, not a spinner.
+    state:
+      work instanceof ProgrammaticJob &&
+      jobState === "live" &&
+      work.toolCalls.some((inner) => {
+        const innerState = toolCellState(inner);
+        return innerState === "live" || innerState === "ask";
+      })
+        ? "ok"
+        : jobState,
+    name: faceText(line.name),
+    object: agent ? faceText(tape.status).trim() : faceText(line.object),
+    status: [faceText(line.status), comment].filter((part) => part !== "").join("  "),
+    caption: faceText(line.caption),
+    pathShaped: !pretty && work instanceof ToolCallJob && isPathShapedName(faceText(work.name)),
+    split: !pretty && !agent && work instanceof MCPToolJob,
+    agent,
+    pretty,
+    prettyBlock: agent ? agentExpandBlock(faceText(line.block), faceText(tape.model)) : faceText(line.block),
+    response: agent ? agentResponseText(work) : "",
+    indent,
+    collapsed,
+    receipt: receiptFace(work, jobState, blobs),
+    rimNamed: coverAskAnnotation(work, { kernel }) !== undefined,
+  };
+}