@intentic/sandbox-contract 1.331.0 → 1.332.0

package/src/text/embed.test.ts

@@ -47,6 +47,20 @@ test("a JSON fetch answers the body or throws the refusal", async () => {
         jest.fn(async () => new Response(JSON.stringify({ error: "rate limited" }), { status: 429 })),
     );
     await expect(fetchEmbedJson("https://x/y")).rejects.toMatchObject({ message: "rate limited", status: 429 });
+    stubGlobal(
+        "fetch",
+        jest.fn(async () => new Response("<html>bad gateway</html>", { status: 502 })),
+    );
+    await expect(fetchEmbedJson("https://x/y")).rejects.toMatchObject({ message: "request failed (502)", status: 502 });
+    unstubAllGlobals();
+});
+
+test("a door that cannot be reached says so in words a visitor can read, without the URL", async () => {
+    stubGlobal(
+        "fetch",
+        jest.fn(async () => { throw new TypeError("Failed to fetch"); }),
+    );
+    await expect(fetchEmbedJson("https://x/y")).rejects.toThrow("The server could not be reached: Failed to fetch");
     unstubAllGlobals();
 });
 

package/src/text/embed.ts

@@ -1,6 +1,9 @@
+import { escapeHtml } from "@intentic/base/escape";
+import { FetchJsonError, fetchJson } from "@intentic/base/fetch-json";
+
 // The zod-free half of an embed's wire and look, shared by the two embeds (webchat-widget, issue-sdk) and the daemon's
-// doors behind them. No imports, ever: this bundles into someone else's page, and the contract's barrel would drag in
-// zod (measured at 1.1 MB for two strings).
+// doors behind them. Nothing imported but base's dependency-free subpaths: this bundles into someone else's page, and
+// the contract's barrel would drag in zod (measured at 1.1 MB for two strings).
 
 // Where an embed talks to: the daemon it came from, and the automation it is the public face of.
 export interface EmbedEndpoint {
@@ -29,13 +32,19 @@ export const embedFailure = async (response: Response): Promise<EmbedError> => {
 export const embedUrl = ({ base, automationId }: EmbedEndpoint, slug: string, path: string): string =>
     `${base}/${slug}/${encodeURIComponent(automationId)}/${path}`;
 
-// One GET against a public door, answered as JSON or refused with the server's own sentence.
+// One GET against a public door, answered as JSON or refused with the server's own sentence. Base's transport gives it
+// a deadline, so a door that stalls fails in 30 s instead of leaving the visitor's widget waiting on it for minutes,
+// and names a timeout as one. The label is what a visitor reads when the server cannot be reached.
 export const fetchEmbedJson = async <T>(url: string): Promise<T> => {
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw await embedFailure(response);
+    try {
+        // SAFETY: the caller names the shape its door answers; the embed bundles no schema library to check it with.
+        return (await fetchJson(url, { label: "The server" })) as T;
+    } catch (error) {
+        // A refusal's body arrives as the start of its text; embedFailure reads the sentence out of it as for any response.
+        throw error instanceof FetchJsonError && error.kind === "status" && error.status !== undefined
+            ? await embedFailure(new Response(error.body ?? "", { status: error.status }))
+            : error;
     }
-    return (await response.json()) as T;
 };
 
 // Find a nonce whose SHA-256 of `salt:nonce` has `difficulty` leading zero bits, signed to one caller's id so it can't
@@ -81,6 +90,7 @@ export const solveProofOfWork = async (challenge: PowChallenge, insecure: string
         if (nonce % BATCH === BATCH - 1) {
             onProgress?.(nonce + 1);
             // Hands the main thread back so the page (and the "checking..." line) keeps painting.
+            // allow(primitive-tiers): a yield to the page's event loop, not a wait; this bundle imports no async helpers.
             await new Promise((resolve) => setTimeout(resolve, 0));
         }
     }
@@ -174,6 +184,5 @@ export const onAccent = (accent: string, dark: string): string => {
 };
 
 // Text for innerHTML, safe both between tags and inside a quoted attribute: neither an owner's config nor what a
-// visitor typed is trusted with markup.
-export const escapeHtml = (value: string): string =>
-    value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char);
+// visitor typed is trusted with markup. Base's one escaper, re-exported for the embeds that import it from here.
+export { escapeHtml };

package/src/text/title.ts

@@ -1,3 +1,5 @@
+import { oneLine } from "@intentic/base/one-line";
+
 // The title a chat tab, fleet card and agent detail header show until a model names the conversation. Reads the prompt
 // as prose first, stripping openers, quotes and fences, and cuts on a sentence or word boundary rather than truncating
 // at a fixed length. Browser and daemon both call this so a prompt titles the same regardless of where it enters.
@@ -38,12 +40,6 @@ const IMPERATIVE =
 // An unmistakable ask: an instruction verb, or a question mark.
 const isAsk = (sentence: string): boolean => sentence.endsWith("?") || IMPERATIVE.test(sentence);
 
-const collapse = (text: string): string =>
-    text
-        .replaceAll(/[\p{Cc}\p{Cf}]+/gu, " ")
-        .replaceAll(/\s+/g, " ")
-        .trim();
-
 // Prompt lines minus fenced code blocks and quoted lines; those are evidence attached to the ask, not the ask itself.
 const proseLines = (prompt: string): string[] => {
     const lines: string[] = [];
@@ -180,7 +176,7 @@ export const planParts = (text: string): { title?: string; body: string } => {
 // as its own first line.
 export const deriveTitle = (prompt: string): string => {
     const prose = proseLines(prompt)
-        .map(collapse)
+        .map((line) => oneLine(line))
         .filter((line) => line !== "");
     // Prose lines, openers stripped, letters required; first is the default title, rest matter only if narration.
     const lines = prose.map(withoutOpener).filter((line) => /\p{L}/u.test(line));
@@ -197,6 +193,6 @@ export const deriveTitle = (prompt: string): string => {
         return capitalized(clamped(firstSentence(collapseReferences(ask ?? primary))));
     }
     // Nothing had letters (code, quote or greeting only); title as the first raw line rather than leaving it blank.
-    const fallback = prose[0] ?? collapse(prompt.replaceAll(/^\s*(?:```|~~~).*$/gm, ""));
-    return clamped(collapseReferences(fallback === "" ? collapse(prompt) : fallback));
+    const fallback = prose[0] ?? oneLine(prompt.replaceAll(/^\s*(?:```|~~~).*$/gm, ""));
+    return clamped(collapseReferences(fallback === "" ? oneLine(prompt) : fallback));
 };

package/src/text/transcript-fold.test.ts

@@ -1073,3 +1073,64 @@ describe(`the code beside a notice's words`, () => {
         expect(sandboxNoticeOf({ noticeCode: { code: `landConflict`, params: { files: `three` } } })).toBeUndefined();
     });
 });
+
+// A runtime's frames carry no clock; the live fold stamps what it folds, so a stored record can say when each call ran
+// and how long it took. A fold without a clock (a replay, these tests above) stamps nothing.
+describe("TranscriptFold with a clock", () => {
+    const ticking = (): (() => number) => {
+        let now = SENT_AT;
+        return () => (now += 1000);
+    };
+
+    it("stamps each card's start and the arrival of its result, and each assistant and notice row's opening", () => {
+        const fold = new TranscriptFold(openingOf("run"), ticking());
+        for (const event of [
+            { kind: "delta", text: "running" },
+            { kind: "tool_call", id: "t1", name: "Bash", category: "execute", status: "in_progress", target: "pnpm test" },
+            { kind: "tool_call_update", id: "t1", content: [{ type: "text", text: "partial" }] },
+            { kind: "tool_call_update", id: "t1", status: "failed", content: [{ type: "text", text: "1 failed" }], exitCode: 1 },
+            // Re-sending a final status does not move when the result arrived.
+            { kind: "tool_call_update", id: "t1", status: "failed" },
+            { kind: "compact", trigger: "auto" },
+        ] satisfies AgentEvent[]) {
+            fold.apply(event);
+        }
+        const [user, assistant, notice] = fold.rows;
+        expect(user).toEqual(userRow("run", SENT_AT, []));
+        expect(assistant?.openedAt).toBe(SENT_AT + 1000);
+        expect(assistant?.tools).toEqual([
+            {
+                id: "t1",
+                name: "Bash",
+                category: "execute",
+                status: "failed",
+                target: "pnpm test",
+                content: [{ type: "text", text: "1 failed" }],
+                startedAt: SENT_AT + 2000,
+                endedAt: SENT_AT + 3000,
+                exitCode: 1,
+            },
+        ]);
+        expect(notice).toMatchObject({ role: "notice", openedAt: SENT_AT + 4000 });
+        // Every stamp survives the schema a stored record is read back through.
+        expect(fold.rows.map((row) => TranscriptRowSchema.parse(row))).toEqual(fold.rows);
+    });
+
+    it("dates a call that arrives already finished to the moment it was seen, and a nested call like any other", () => {
+        const fold = new TranscriptFold(openingOf("look"), ticking());
+        fold.apply({ kind: "tool_call", id: "a1", name: "Agent", category: "other", status: "in_progress", input: '{"prompt":"look"}' });
+        const [patch] = fold.apply({ kind: "tool_call", id: "r1", name: "Read", category: "read", status: "completed", parentToolUseId: "a1" });
+        expect(patch).toMatchObject({ op: "tool", tool: { id: "r1", startedAt: SENT_AT + 3000, endedAt: SENT_AT + 3000 }, parent: "a1" });
+        expect(fold.rows[1]?.tools?.[0]).toMatchObject({ input: '{"prompt":"look"}', startedAt: SENT_AT + 2000 });
+    });
+
+    it("keeps a daemon-written row's own moment, and never stamps a user's row", () => {
+        const fold = new TranscriptFold(openingOf("go"), ticking());
+        fold.note({ role: "notice", text: "kept", openedAt: 7 });
+        fold.apply({ kind: "steer", text: "and this", sentAt: SENT_AT + 5 });
+        expect(fold.rows.slice(1)).toEqual([
+            { role: "notice", text: "kept", openedAt: 7 },
+            { role: "user", text: "and this", sentAt: SENT_AT + 5 },
+        ]);
+    });
+});

package/src/text/transcript-fold.ts

@@ -13,6 +13,7 @@ import {
 } from "../events/transcript.js";
 import { contextTrimLine, contextTrimNotice } from "../schemas/context-trim.js";
 import { keptWarmLine, keptWarmNotice } from "../schemas/keep-warm.js";
+import { handedOffLine, handedOffNotice } from "../schemas/providers/handoff.js";
 import { isLandConflict } from "../events/land-conflict.js";
 import { turnedAwayCode } from "../policy/turned-away.js";
 import { mentionedPathTokens } from "./mentions.js";
@@ -56,7 +57,12 @@ const resultWords = (tool: TranscriptTool): string =>
         .map((entry) => entry.text)
         .join("\n");
 
-const cardOf = (event: Extract<AgentEvent, { kind: "tool_call" }>): TranscriptTool => ({
+// Whether a call's status is final: the moment it turns so is when its result arrived.
+const ended = (status: TranscriptTool["status"]): boolean => status === "completed" || status === "failed";
+
+// `at` is the fold's clock reading as the call is seen, absent for a fold without one; a call that arrives already
+// finished started and ended in that same moment, as far as anyone here can tell.
+const cardOf = (event: Extract<AgentEvent, { kind: "tool_call" }>, at: number | undefined): TranscriptTool => ({
     id: event.id,
     name: event.name,
     category: event.category,
@@ -64,6 +70,8 @@ const cardOf = (event: Extract<AgentEvent, { kind: "tool_call" }>): TranscriptTo
     ...(event.target !== undefined ? { target: event.target } : {}),
     ...(event.locations !== undefined ? { locations: event.locations } : {}),
     ...(event.content !== undefined ? { content: event.content } : {}),
+    ...(event.input !== undefined ? { input: event.input } : {}),
+    ...(at !== undefined ? { startedAt: at, ...(ended(event.status) ? { endedAt: at } : {}) } : {}),
 });
 
 // Whether a just-retired prose bubble says exactly what the plan about to be drawn says, so the request can take its
@@ -339,7 +347,13 @@ export class TranscriptFold {
     // Set by `retract`: this turn was refused before it ran, and its message went back to the conversation's queue.
     private unrun = false;
 
-    constructor(opening: readonly TranscriptRow[]) {
+    // `now`, when given, stamps each card's start and end and each assistant or notice row's opening as the frame that
+    // brings it is folded: a runtime's frames carry no clock, so the live fold is the one place these moments are known.
+    // A fold replaying frames after the fact is given none, since its own clock would date them all to the replay.
+    constructor(
+        opening: readonly TranscriptRow[],
+        private readonly now?: () => number,
+    ) {
         for (const [index, row] of opening.entries()) {
             this.rows.push(row);
             // A run carried on after a restart opens on the cards it had raised, which it raises again: each is found
@@ -387,7 +401,7 @@ export class TranscriptFold {
                 return [];
             case "tool_call": {
                 const [index, opened] = this.open();
-                const tool = cardOf(event);
+                const tool = cardOf(event, this.now?.());
                 const row = this.rows[index]!;
                 row.tools = [...(row.tools ?? []), tool];
                 this.cards.set(tool.id, { tool, row: index });
@@ -399,6 +413,13 @@ export class TranscriptFold {
                 return this.patchCard(event.id, (tool) => {
                     if (event.status !== undefined) {
                         tool.status = event.status;
+                        // The first final status is when the result arrived; a later frame re-sending it is not.
+                        if (ended(event.status) && tool.endedAt === undefined && this.now !== undefined) {
+                            tool.endedAt = this.now();
+                        }
+                    }
+                    if (event.exitCode !== undefined) {
+                        tool.exitCode = event.exitCode;
                     }
                     if (event.content !== undefined) {
                         tool.content = event.content;
@@ -460,6 +481,8 @@ export class TranscriptFold {
                 // A row of its own rather than a stamp on the message: what was left out is not part of what was sent,
                 // and the fold beside the message only ever lists notes that actually rode.
                 return this.pushRow({ role: "notice", text: contextTrimLine(event), noticeCode: noticeCode(contextTrimNotice(event)) });
+            case "handoff":
+                return this.pushRow({ role: "notice", text: handedOffLine(event), noticeCode: noticeCode(handedOffNotice(event)) });
             case "worktree":
                 return event.sync === undefined ? [] : this.synced(event.sync);
             case "landed":
@@ -735,7 +758,7 @@ export class TranscriptFold {
             return [{ op: "toolThinking", index: place.row, id: parent, text: event.text }];
         }
         if (event.kind === "tool_call") {
-            const child = cardOf(event);
+            const child = cardOf(event, this.now?.());
             place.tool.children = [...(place.tool.children ?? []), child];
             this.cards.set(child.id, { tool: child, row: place.row, parent });
             this.claimById(child);
@@ -820,7 +843,7 @@ export class TranscriptFold {
         if (this.bubble !== undefined) {
             return [this.bubble, []];
         }
-        const row: TranscriptRow = { role: "assistant", text: "" };
+        const row: TranscriptRow = { role: "assistant", text: "", ...(this.now === undefined ? {} : { openedAt: this.now() }) };
         this.rows.push(row);
         this.bubble = this.rows.length - 1;
         return [this.bubble, [{ op: "append", row: structuredClone(row) }]];
@@ -842,8 +865,10 @@ export class TranscriptFold {
     }
 
     // Pushes a row that is not the open bubble; closes the bubble first so order stays: what came before, then this.
-    private pushRow(row: TranscriptRow): TranscriptPatch[] {
+    // A row other than a user's is stamped with when it landed, unless it came with its own moment.
+    private pushRow(given: TranscriptRow): TranscriptPatch[] {
         const closed = this.closeBubble();
+        const row = given.role === "user" || given.openedAt !== undefined || this.now === undefined ? given : { ...given, openedAt: this.now() };
         this.rows.push(row);
         return [...closed, { op: "append", row: structuredClone(row) }];
     }