@intentic/sandbox-contract 1.340.0 → 1.342.0

package/src/text/preview-guide.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+
+// What the daemon puts first in a workspace web page it serves for a preview (GET /workspace/preview/{ticket}/*), and
+// what that page may say to the editor framing it. The page runs as it would on a static file server, in a frame
+// sandboxed without `allow-same-origin`, so its origin is opaque: it cannot read the editor, the daemon's API or any
+// storage. This script is what keeps a page written for an ordinary origin working there, and what lets the editor
+// print it, show a Copy button over it, and say which of its files are missing:
+// - `localStorage`, `sessionStorage` and `document.cookie` throw in an opaque origin, and a page that touches them at
+//   load stops dead; each is stood in for by one held in memory for the page's life.
+// - A Vite build whose base is an absolute path preloads chunks from the server's root, outside the ticket; its
+//   `vite:preloadError` is cancelled, so the import itself, which is relative, goes ahead.
+// - `new Worker(url)` refuses any script an opaque origin did not make, which is every one; a worker is started from a
+//   script made here that loads the real one, its own relative imports and fetches resolved against where it lives.
+// - A link to another site opens in a new tab (most refuse to be framed); a link within the page's own files is
+//   followed in the frame, as a browser would.
+// - Every file it loads from beside itself is told, so the editor redraws it when one changes, and every one that
+//   fails, so the editor can name it.
+// - `intenticPrint` is answered with the page as it stands, addresses made absolute and canvases drawn as pictures.
+export const PREVIEW_GUIDE_SCRIPT = `(() => {
+    const say = (message) => parent.postMessage({ intenticHtmlPreview: message }, "*");
+    const memory = () => {
+        const held = new Map();
+        return {
+            get length() { return held.size; },
+            key: (index) => [...held.keys()][index] ?? null,
+            getItem: (key) => (held.has(String(key)) ? held.get(String(key)) : null),
+            setItem: (key, value) => { held.set(String(key), String(value)); },
+            removeItem: (key) => { held.delete(String(key)); },
+            clear: () => { held.clear(); },
+        };
+    };
+    for (const name of ["localStorage", "sessionStorage"]) {
+        try { void window[name]; } catch { Object.defineProperty(window, name, { value: memory(), configurable: true }); }
+    }
+    try { void document.cookie; } catch {
+        const jar = new Map();
+        Object.defineProperty(document, "cookie", {
+            configurable: true,
+            get: () => [...jar].map(([name, value]) => name + "=" + value).join("; "),
+            set: (text) => {
+                const [pair, ...attributes] = String(text).split(";");
+                const at = pair.indexOf("=");
+                const name = (at < 0 ? "" : pair.slice(0, at)).trim();
+                const value = (at < 0 ? pair : pair.slice(at + 1)).trim();
+                const gone = attributes.some((attribute) => {
+                    const [key, ...rest] = attribute.split("=");
+                    const setting = rest.join("=").trim();
+                    const lower = key.trim().toLowerCase();
+                    return (lower === "max-age" && Number(setting) <= 0) || (lower === "expires" && Date.parse(setting) < Date.now());
+                });
+                if (gone) jar.delete(name); else jar.set(name, value);
+            },
+        });
+    }
+    addEventListener("vite:preloadError", (event) => event.preventDefault());
+    const Native = window.Worker;
+    if (typeof Native === "function") {
+        window.Worker = function Worker(script, options) {
+            const url = new URL(String(script), location.href);
+            if (!/^https?:$/.test(url.protocol)) return new Native(script, options);
+            const at = JSON.stringify(url.href);
+            const fetches = "const get = self.fetch.bind(self); self.fetch = (input, init) => get(typeof input === 'string' ? new URL(input, " + at + ").href : input, init);";
+            // Chromium starts no module worker from a blob an opaque origin made, but does from a data address; the
+            // fetch fix is a module of its own so it runs before the worker's, as static imports run in order.
+            if (options?.type === "module") {
+                const data = (code) => "data:text/javascript," + encodeURIComponent(code);
+                return new Native(data("import " + JSON.stringify(data(fetches)) + "; import " + at + ";"), options);
+            }
+            const body = fetches + "const load = self.importScripts.bind(self);" +
+                "self.importScripts = (...urls) => load(...urls.map((each) => new URL(each, " + at + ").href)); load(" + at + ");";
+            return new Native(URL.createObjectURL(new Blob([body], { type: "text/javascript" })), options);
+        };
+        window.Worker.prototype = Native.prototype;
+    }
+    const prefix = location.pathname.split("/").slice(0, 4).join("/") + "/";
+    const own = (url) => {
+        try {
+            const parsed = new URL(url, location.href);
+            return parsed.origin === location.origin && parsed.pathname.startsWith(prefix) ? decodeURIComponent(parsed.pathname.slice(prefix.length)) : undefined;
+        // allow(silent-catch): an address that does not parse or decode is not one of the page's own files.
+        } catch { return undefined; }
+    };
+    addEventListener("click", (event) => {
+        const link = event.target instanceof Element ? event.target.closest("a[href], area[href]") : null;
+        if (link === null || event.button !== 0 || event.defaultPrevented) return;
+        const href = link.href;
+        if (!/^https?:/i.test(href) || own(href) !== undefined) return;
+        event.preventDefault();
+        say({ href });
+    });
+    const told = new Set();
+    const tell = (urls) => {
+        const fresh = [];
+        for (const url of urls) {
+            const path = own(url);
+            if (path !== undefined && !told.has(path)) { told.add(path); fresh.push(path); }
+        }
+        if (fresh.length > 0) say({ loaded: fresh });
+    };
+    tell([location.href]);
+    new PerformanceObserver((list) => tell(list.getEntries().map((entry) => entry.name))).observe({ type: "resource", buffered: true });
+    addEventListener("error", (event) => {
+        const element = event.target;
+        if (!(element instanceof Element)) return;
+        const url = element.currentSrc || element.src || element.href;
+        const path = typeof url === "string" ? own(url) : undefined;
+        if (path !== undefined) say({ missing: path });
+    }, true);
+    let moved = 0;
+    addEventListener("pointermove", (event) => {
+        if (event.pointerType === "touch" || event.timeStamp - moved < 150) return;
+        moved = event.timeStamp;
+        say({ pointer: true });
+    }, true);
+    addEventListener("pointerout", (event) => {
+        if (event.relatedTarget !== null || event.pointerType === "touch") return;
+        moved = 0;
+        say({ pointer: false });
+    }, true);
+    const snapshot = () => {
+        const live = [...document.querySelectorAll("canvas")];
+        const copy = document.documentElement.cloneNode(true);
+        [...copy.querySelectorAll("canvas")].forEach((canvas, index) => {
+            try {
+                const picture = document.createElement("img");
+                picture.src = live[index].toDataURL();
+                picture.style.cssText = canvas.style.cssText;
+                picture.width = live[index].clientWidth || live[index].width;
+                canvas.replaceWith(picture);
+            // allow(silent-catch): a canvas drawn from another origin cannot be read, and prints as the page left it.
+            } catch {}
+        });
+        for (const element of copy.querySelectorAll("[src], [href], [poster]")) {
+            for (const name of ["src", "href", "poster"]) {
+                const value = element.getAttribute(name);
+                if (value !== null && !/^(?:data|blob|javascript|mailto):/i.test(value) && URL.canParse(value, document.baseURI)) {
+                    element.setAttribute(name, new URL(value, document.baseURI).href);
+                }
+            }
+        }
+        return copy.outerHTML;
+    };
+    addEventListener("message", (event) => {
+        if (event.source === parent && event.data?.intenticPrint === true) parent.postMessage({ intenticPrintHtml: snapshot() }, "*");
+    });
+})();`;
+
+// What a served page may tell the editor, parsed where it arrives since the page's own scripts can post anything: an
+// internet address to open in a tab, whether a mouse is over it, the files it loaded from beside itself, or one that
+// failed. Paths are relative to the folder the ticket serves (WorkspacePreviewTicketSchema `root`).
+export const PreviewGuideSayingSchema = z.object({
+    intenticHtmlPreview: z.union([
+        z.object({ href: z.string().regex(/^https?:\/\//i) }),
+        z.object({ pointer: z.boolean() }),
+        z.object({ loaded: z.array(z.string()).max(1000) }),
+        z.object({ missing: z.string() }),
+    ]),
+});
+export type PreviewGuideSaying = z.infer<typeof PreviewGuideSayingSchema>["intenticHtmlPreview"];

package/src/text/transcript-fold.ts

@@ -1,6 +1,6 @@
 import { cancelledRequests, settledRequests } from "../policy/request-status.js";
 import type { AgentEvent } from "../events/agent-events.js";
-import type { Page } from "../events/requests.js";
+import { drawInline, type InlineEvent, supersedeEarlier } from "./transcript-inline.js";
 import {
     REQUEST_FIELDS,
     holdsRequest,
@@ -16,6 +16,7 @@ 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 { undeliveredRow } from "../events/undelivered.js";
 import { mentionedPathTokens } from "./mentions.js";
 import { unspokenPromptRow } from "../events/agent-words.js";
 import { needRowText } from "../events/need-wake.js";
@@ -197,15 +198,6 @@ const landedRow = (event: Extract<AgentEvent, { kind: "landed" }>): TranscriptRo
 const failureOf = (event: Extract<AgentEvent, { kind: "error" }>): { message: string; error?: string } =>
     event.code === undefined ? { message: event.message } : { message: event.message, error: event.code };
 
-// The clause after a refusal that ran nothing. A turn somebody typed is held in its conversation's queue for another
-// press; a turn that started itself — an automation, a loop, a watch wake — has no typed message and nobody watching,
-// so promising a resend there names a composer the reader is not looking at. Neither version promises a retry: whether
-// one comes is the scheduler's decision, not this row's to state.
-const undelivered = (unattended: boolean): string =>
-    unattended
-        ? `Nothing ran, and nothing is held: this run started on its own, so there is no message waiting to be sent again.`
-        : `Your message was not delivered: it is held for you to send again.`;
-
 // The press a memory hold offers: the raise rides along only when the hold carried a ceiling to size it by, since a
 // stall names none and raising one would not clear it.
 const memoryPress = (event: Extract<AgentEvent, { kind: "error" }>): "sendAnyway" | "sandboxMemory" =>
@@ -230,11 +222,7 @@ const heldRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow =
         };
     }
     if (!memory || unattended) {
-        return {
-            role: "notice",
-            text: `${event.message} ${undelivered(unattended)}`,
-            noticeCode: noticeCode({ code: "undelivered", params: { ...said, unattended: unattended || undefined } }),
-        };
+        return undeliveredRow(said, unattended);
     }
     return {
         role: "notice",
@@ -462,12 +450,9 @@ export class TranscriptFold {
                 return this.steered(event);
             case "checkpoint":
                 // Anchors the pre-turn snapshot id and this turn's transcript position on its user row, for rewind.
-                return this.stampOpener((row) => {
-                    row.checkpointId = event.id;
-                    if (event.index !== undefined) {
-                        row.rewindIndex = event.index;
-                    }
-                });
+                return this.stampOpener((row) =>
+                    Object.assign(row, { checkpointId: event.id }, event.index === undefined ? {} : { rewindIndex: event.index }),
+                );
             case "preamble":
                 // Collapses the daemon's preamble notes onto the user row; an empty note list is not a disclosure.
                 return event.notes.length === 0 ? [] : this.stampOpener((row) => (row.notes = [...event.notes]));
@@ -484,7 +469,7 @@ export class TranscriptFold {
             case "handoff":
                 return this.pushRow({ role: "notice", text: handedOffLine(event), noticeCode: noticeCode(handedOffNotice(event)) });
             case "worktree":
-                return event.sync === undefined ? [] : this.synced(event.sync);
+                return this.synced(event.sync);
             case "landed":
                 return this.pushRow(landedRow(event));
             case "compact":
@@ -553,7 +538,8 @@ export class TranscriptFold {
             case "credential_offer":
                 return this.park(event.requestId, { credentialOffer: { requestId: event.requestId, offer: event.offer, status: "pending" } });
             case "page":
-                return this.showPage(event.page);
+            case "review":
+                return this.showInline(event);
             case "page_ask":
                 return this.park(event.requestId, { pageAsk: { requestId: event.requestId, page: event.page, status: "pending" } });
             case "need":
@@ -608,20 +594,16 @@ export class TranscriptFold {
     }
 
     /**
-     * A page drawn on the bubble whose call showed it, which it then closes, as a card does: the prose after it is the
-     * next row. A redraw of a page already shown folds the earlier row to a line rather than drawing two copies.
+     * Drawn on the bubble whose call showed it (a page, a review's findings), which it then closes, as a card does: the
+     * prose after it is the next row. A redraw of one already shown folds the earlier row to a line rather than drawing
+     * two copies (transcript-inline.ts).
      */
-    private showPage(page: Page): TranscriptPatch[] {
-        const patches: TranscriptPatch[] = [];
-        const earlier = this.rows.findLastIndex((row) => row.page !== undefined && row.page.id === page.id && row.page.superseded !== true);
-        if (earlier !== -1) {
-            this.rows[earlier]!.page = { ...this.rows[earlier]!.page!, superseded: true };
-            patches.push(this.replace(earlier));
-        }
+    private showInline(event: InlineEvent): TranscriptPatch[] {
+        const earlier = supersedeEarlier(this.rows, event);
         const [index, opened] = this.open();
-        this.rows[index]!.page = page;
+        drawInline(this.rows[index]!, event);
         this.bubble = undefined;
-        return [...patches, ...opened, this.replace(index)];
+        return [...(earlier === undefined ? [] : [this.replace(earlier)]), ...opened, this.replace(index)];
     }
 
     /** A message pushed into a running turn; only a person's own message is a rewind anchor. */
@@ -910,7 +892,10 @@ export class TranscriptFold {
 
     // The rebase notice, less what a resolve turn was sent to fix: that turn opens because the branch couldn't rebase, so
     // saying so again one row under its own errand only repeats it. What did move is still told.
-    private synced(sync: { commits: number; blocked: readonly string[] }): TranscriptPatch[] {
+    private synced(sync: { commits: number; blocked: readonly string[] } | undefined): TranscriptPatch[] {
+        if (sync === undefined) {
+            return [];
+        }
         const opener = this.opener === undefined ? undefined : this.rows[this.opener];
         const told = opener !== undefined && isLandConflict(opener.text) ? { ...sync, blocked: [] } : sync;
         const text = syncLine(told);

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

@@ -0,0 +1,43 @@
+import type { AgentEvent } from "../events/agent-events.js";
+import type { Page } from "../events/requests.js";
+import type { ReviewFindings } from "../events/review.js";
+import { foldTurn, userRow } from "./transcript-fold.js";
+
+// path-literals: content, a page's stored path and a finding's file as transcript rows carry them
+const PAGE: Page = { id: "p1", title: "Q3 revenue", path: ".intentic/records/artifacts/pages/c1/p1.r0.html" };
+const REVIEW: ReviewFindings = {
+    id: "review-1",
+    source: "claude",
+    level: "high",
+    findings: [{ file: "src/parse.ts", line: 12, summary: "Off-by-one drops the last token.", verdict: "CONFIRMED" }],
+};
+
+const fold = (events: readonly AgentEvent[]) => foldTurn([userRow("/code-review high", 1, [])], events).slice(1);
+
+describe("a review in the fold", () => {
+    it("draws the findings on the bubble that reported them, and starts the next words below", () => {
+        const rows = fold([
+            { kind: "tool_call", id: "t1", name: "ReportFindings", category: "other", status: "in_progress" },
+            { kind: "review", review: REVIEW },
+            { kind: "delta", text: "One finding." },
+        ]);
+        expect(rows).toHaveLength(2);
+        expect(rows[0]?.review).toEqual(REVIEW);
+        expect(rows[1]).toEqual({ role: "assistant", text: "One finding." });
+    });
+
+    // The skill re-reports the same findings once it has fixed them: the card is redrawn, not drawn twice.
+    it("folds the earlier card away when the same review is re-reported with its outcomes", () => {
+        const fixed: ReviewFindings = { ...REVIEW, findings: REVIEW.findings.map((finding) => ({ ...finding, outcome: "fixed" as const })) };
+        const rows = fold([{ kind: "review", review: REVIEW }, { kind: "delta", text: "Fixing." }, { kind: "text_end" }, { kind: "review", review: fixed }]);
+        expect(rows[0]?.review?.superseded).toBe(true);
+        expect(rows.at(-1)?.review).toEqual(fixed);
+    });
+
+    // A page and a review share the redraw rule by id, never each other's rows.
+    it("keeps a page and a review that share an id apart", () => {
+        const rows = fold([{ kind: "page", page: PAGE }, { kind: "review", review: { ...REVIEW, id: PAGE.id } }]);
+        expect(rows[0]?.page?.superseded).toBeUndefined();
+        expect(rows[1]?.review?.id).toBe(PAGE.id);
+    });
+});

package/src/text/transcript-inline.ts

@@ -0,0 +1,38 @@
+import type { AgentEvent } from "../events/agent-events.js";
+import type { TranscriptRow } from "../events/transcript.js";
+
+// What the chat draws inline, on the bubble that showed it, rather than as a card that waits for an answer: a page the
+// agent showed (show_page) and a code review's findings. Each has an id, and one shown again under its id is a redraw
+// (a page redrawn, a review re-reported with its fixes applied), so the earlier row folds to a line.
+
+export type InlineEvent = Extract<AgentEvent, { kind: "page" | "review" }>;
+
+const drawnOf = (row: TranscriptRow, kind: InlineEvent["kind"]): { readonly id: string; readonly superseded?: boolean | undefined } | undefined =>
+    kind === "page" ? row.page : row.review;
+
+// The latest row still drawing this one in full, folded now that its redraw stands below; undefined when none does.
+export const supersedeEarlier = (rows: TranscriptRow[], event: InlineEvent): number | undefined => {
+    const id = event.kind === "page" ? event.page.id : event.review.id;
+    const index = rows.findLastIndex((row) => {
+        const drawn = drawnOf(row, event.kind);
+        return drawn !== undefined && drawn.id === id && drawn.superseded !== true;
+    });
+    const row = rows[index];
+    if (row === undefined) {
+        return undefined;
+    }
+    if (event.kind === "page" && row.page !== undefined) {
+        row.page = { ...row.page, superseded: true };
+    } else if (event.kind === "review" && row.review !== undefined) {
+        row.review = { ...row.review, superseded: true };
+    }
+    return index;
+};
+
+export const drawInline = (row: TranscriptRow, event: InlineEvent): void => {
+    if (event.kind === "page") {
+        row.page = event.page;
+    } else {
+        row.review = event.review;
+    }
+};

package/src/time/zone.test.ts

@@ -1,4 +1,4 @@
-import { asCivilDay, asZone, civilDayIn, cronOptions, isZone, sameClock, utcDayOf, UTC, zoneLabel } from "./zone.js";
+import { asCivilDay, asZone, civilDayIn, cronOptions, isZone, sameClock, utcDayOf, UTC, wallClockInstant, zoneLabel } from "./zone.js";
 import type { Zone } from "./zone.js";
 
 // The distinctions this module exists to keep, each of which was a live bug before it: a cron evaluated in the
@@ -87,3 +87,20 @@ describe(`cronOptions`, () => {
         expect(cronOptions(WARSAW)).toEqual({ timezone: `Europe/Warsaw` });
     });
 });
+
+/* A time of day a program on some clock wrote ("try again at 5:46 PM") is an instant only with that clock's zone. */
+describe(`wallClockInstant`, () => {
+    test(`reads the same wall time as a different instant on each clock`, () => {
+        expect(wallClockInstant(asCivilDay(`2026-09-20`)!, 22, 43, UTC)).toBe(Date.UTC(2026, 8, 20, 22, 43));
+        expect(wallClockInstant(asCivilDay(`2026-09-20`)!, 22, 43, WARSAW)).toBe(SEPTEMBER);
+        expect(wallClockInstant(asCivilDay(`2026-12-20`)!, 15, 43, NEW_YORK)).toBe(DECEMBER);
+    });
+
+    // Warsaw changes its clocks at 01:00 UTC: on 2026-03-29 from +1 to +2, on 2026-10-25 from +2 to +1. An hour read just
+    // before the change sits on the other side of it from its naive guess, whose offset alone would be an hour out.
+    test(`takes the offset in force at the time itself, not at the naive guess, across a changeover`, () => {
+        expect(wallClockInstant(asCivilDay(`2026-03-29`)!, 1, 30, WARSAW)).toBe(Date.UTC(2026, 2, 29, 0, 30));
+        expect(wallClockInstant(asCivilDay(`2026-10-25`)!, 1, 30, WARSAW)).toBe(Date.UTC(2026, 9, 24, 23, 30));
+        expect(wallClockInstant(asCivilDay(`2026-10-25`)!, 9, 0, WARSAW)).toBe(Date.UTC(2026, 9, 25, 8, 0));
+    });
+});

package/src/time/zone.ts

@@ -115,6 +115,18 @@ export const nextDayStartIn = (at: number, zone: Zone): number => {
     return midnightUtc - offsetMinutes(midnightUtc, zone) * 60_000;
 };
 
+/**
+ * The instant a named clock reads `hours:minutes` on a calendar day: what a sentence like "try again at 5:46 PM" means,
+ * written by a program on that clock. The offset is taken again at the first answer, since across a summer-time
+ * changeover the offset at the naive guess is not the one in force at the time itself.
+ */
+export const wallClockInstant = (day: CivilDay, hours: number, minutes: number, zone: Zone): number => {
+    const [year = 0, month = 1, date = 1] = day.split("-").map(Number);
+    const naive = Date.UTC(year, month - 1, date, hours, minutes);
+    const guess = naive - offsetMinutes(naive, zone) * 60_000;
+    return naive - offsetMinutes(guess, zone) * 60_000;
+};
+
 /** Whether two zones are showing the same wall clock right now — which is when naming one on screen would be noise. */
 export const sameClock = (a: Zone, b: Zone, at: number = Date.now()): boolean => a === b || offsetMinutes(at, a) === offsetMinutes(at, b);