@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/text/title.ts

@@ -0,0 +1,202 @@
+// 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.
+
+// Storage cap mirroring agents-registry MAX_TITLE_LENGTH and the rename input's maxlength.
+const MAX_LENGTH = 80;
+// Below this length a sentence-shaped cut is more likely an abbreviation (`e.g.`) than a real sentence.
+const MIN_SENTENCE = 12;
+// A word-boundary cut before this point strands a fragment; cutting mid-word beats a near-empty title.
+const MIN_WORD_CUT = MAX_LENGTH * 0.6;
+
+// Fence and quote markers; a fence toggles open/closed, so an unterminated one swallows the rest of the prompt.
+const FENCE = /^\s*(?:```|~~~)/;
+const QUOTE = /^\s*>/;
+
+// Ways an ask opens without starting; stripped repeatedly, so `Hey, can you please …` unwinds one layer per pass.
+const OPENERS: readonly RegExp[] = [
+    /^(?:hey|hi|hello|yo|ok|okay|so|well|also|btw|now|next|then)\b[\s,.:;!—–-]*/i,
+    /^(?:please|pls)\b[\s,.:;!—–-]*/i,
+    /^(?:can|could|would|will)\s+(?:you|u|we)\b\s*(?:please|pls)?[\s,.:;!—–-]*/i,
+    /^i(?:'d|\s+would)?\s+(?:want|need|like)\s+(?:you\s+)?to\b[\s,.:;!—–-]*/i,
+    /^(?:let'?s|lets)\b[\s,.:;!—–-]*/i,
+    /^we\s+(?:need|have|ought)\s+to\b[\s,.:;!—–-]*/i,
+    /^(?:quick\s+(?:one|question|q)|one\s+more\s+thing)\b[\s,.:;!—–-]*/i,
+];
+
+// Terminal punctuation followed by a break; keeps `v1.2` and `foo.ts` intact while still ending `Why is it red?`.
+const SENTENCE_END = /[.!?](?=\s|$)/;
+
+// Matches a first sentence reporting past work (`We just landed…`); that is scene-setting, not the ask.
+const NARRATION =
+    /^(?:(?:recently|previously|earlier|today|yesterday|lately)[\s,]+)?(?:we|i)(?:'ve|'d|'m|'re)?(?:\s+(?:have|had|am|are|was|were|been|just|recently|already|earlier|previously|also|finally|now|currently|still))*\s+(?!(?:need|feed|speed|shed|heed|breed|bleed|embed|proceed|exceed|succeed)\b)(?:\w+ed|\w{3,}ing|built|wrote|rewrote|made|found|saw|thought|began|got|kept|put|set|sent|split|ran|did|redid|went|came|gave|held|hit|cut|let|read|understood|broke|chose|became|brought|spent|meant|lost|forgot|rebuilt|told|taught|stood|drew|grew|knew|threw|took|left|felt|hid)\b/i;
+
+// Curated imperative verbs coding asks lead with, not full grammar: English underdetermines verb/noun forms.
+const IMPERATIVE =
+    /^(?:add|fix|make|implement|create|build|write|rewrite|refactor|rename|remove|delete|drop|update|change|convert|migrate|move|extract|split|merge|rebase|revert|restore|wire|connect|integrate|support|handle|improve|clean|simplify|redesign|rework|rethink|investigate|analyze|analyse|debug|find|figure|check|verify|test|run|try|document|describe|explain|propose|design|draft|prepare|stop|prevent|ensure|allow|enable|disable|introduce|replace|swap|optimize|optimise|reduce|bump|upgrade|deploy|ship|release|adjust|tweak|polish|finish|complete|continue|extend|unify|dedupe|deduplicate|cache|persist|expose|hide|show|render|port|automate|wrap|inline|audit|review|profile|measure|instrument|validate|parse|generate|turn|look|think|come|consider|help|start|use|keep|avoid|teach|harden|tighten|localize|localise|translate)\b/i;
+
+// 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[] = [];
+    let fenced = false;
+    for (const line of prompt.split(/\r?\n/)) {
+        if (FENCE.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (!fenced && !QUOTE.test(line)) {
+            lines.push(line);
+        }
+    }
+    return lines;
+};
+
+// Strips openers only when a multi-word remnant is left; a one-word remnant (`Hi there`) or an empty one means the line
+// was pure greeting, so the original line stands or the caller reads on.
+const withoutOpener = (line: string): string => {
+    let text = line;
+    for (let pass = 0; pass < OPENERS.length; pass++) {
+        const stripped = OPENERS.reduce((current, opener) => current.replace(opener, ""), text);
+        if (stripped === text) {
+            break;
+        }
+        text = stripped;
+    }
+    const remnant = text.trim();
+    if (text === line || remnant === "") {
+        return text;
+    }
+    return remnant.includes(" ") ? text : line;
+};
+
+// A URL's last meaningful path segment, or the host when there is no path; a purely numeric last segment keeps the
+// segment before it (`merge_requests/42`).
+const shortUrl = (token: string): string => {
+    let url: URL;
+    try {
+        url = new URL(token);
+    } catch {
+        return token;
+    }
+    const segments = url.pathname.split("/").filter((segment) => segment !== "");
+    const last = segments.at(-1);
+    if (last === undefined) {
+        return url.hostname.replace(/^www\./, "");
+    }
+    const previous = segments.at(-2);
+    return /^\d+$/.test(last) && previous !== undefined ? `${previous}/${last}` : last;
+};
+
+// A path's basename once the path is deep enough that the leading segments are just scaffolding.
+const shortPath = (token: string): string => {
+    const segments = token.replace(/^@/, "").split("/");
+    return segments.length > 2 ? (segments.findLast((segment) => segment !== "") ?? token) : token;
+};
+
+// Sets trailing punctuation aside across shortening a URL or path token and reattaches it after.
+const shortReference = (token: string): string => {
+    const match = /^(.*?)([\s,.;:!?)\]]*)$/s.exec(token);
+    const core = match?.[1] ?? token;
+    const tail = match?.[2] ?? "";
+    if (/^https?:\/\//i.test(core)) {
+        return `${shortUrl(core)}${tail}`;
+    }
+    if (core.includes("/")) {
+        return `${shortPath(core)}${tail}`;
+    }
+    return token;
+};
+
+const collapseReferences = (text: string): string => text.split(" ").map(shortReference).join(" ");
+
+const firstSentence = (text: string): string => {
+    const end = text.search(SENTENCE_END);
+    if (end < MIN_SENTENCE) {
+        return text;
+    }
+    // Keep `?`/`!`; drop a trailing `.` as noise on a title.
+    const terminator = text[end];
+    return terminator === "." ? text.slice(0, end) : text.slice(0, end + 1);
+};
+
+// Splits text into sentences with the same terminator rule as firstSentence; no abbreviation guard, since a fragment
+// split at `e.g.` never starts with an imperative.
+const sentencesOf = (text: string): string[] => {
+    const parts: string[] = [];
+    let rest = text;
+    while (rest !== "") {
+        const end = rest.search(SENTENCE_END);
+        if (end === -1) {
+            parts.push(rest);
+            break;
+        }
+        parts.push(rest[end] === "." ? rest.slice(0, end) : rest.slice(0, end + 1));
+        rest = rest.slice(end + 1).trimStart();
+    }
+    return parts;
+};
+
+// Cuts to MAX_LENGTH including the ellipsis: AgentTurnSchema.title enforces this as a hard cap, so appending `…` after
+// truncating can exceed it. Falls back to a mid-word cut when no word boundary falls within MIN_WORD_CUT of the end.
+const clamped = (text: string): string => {
+    if (text.length <= MAX_LENGTH) {
+        return text;
+    }
+    const cut = text.slice(0, MAX_LENGTH - 1);
+    const boundary = cut.lastIndexOf(" ");
+    const kept = boundary >= MIN_WORD_CUT ? cut.slice(0, boundary) : cut;
+    return `${kept.replace(/[\s,;:—–-]+$/, "")}…`;
+};
+
+// Capitalizes only when the first word is plain lowercase prose; an identifier, path or abbreviation keeps its casing.
+const capitalized = (text: string): string => {
+    const [first = ""] = text.split(" ", 1);
+    if (!/^[a-z]/.test(first) || /[A-Z/.\\]/.test(first)) {
+        return text;
+    }
+    return `${text[0]?.toUpperCase() ?? ""}${text.slice(1)}`;
+};
+
+// Splits a plan's markdown into its heading and body; the heading is the one line naming the whole job rather than a
+// step, so both browser and daemon title from it.
+export const planParts = (text: string): { title?: string; body: string } => {
+    const match = /^\s*#{1,6}\s+(.+)/.exec(text);
+    if (match === null) {
+        return { body: text };
+    }
+    return { title: match[1]!.trim(), body: text.slice(match.index + match[0].length).trimStart() };
+};
+
+// Derives a conversation's title from its opening prompt; never empty for a non-empty prompt, since a pure paste titles
+// as its own first line.
+export const deriveTitle = (prompt: string): string => {
+    const prose = proseLines(prompt)
+        .map(collapse)
+        .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));
+    const primary = lines[0];
+    if (primary !== undefined) {
+        // A narration head is scene-setting; look further for an unmistakable ask, else keep the narration.
+        const head = firstSentence(primary);
+        const ask = NARRATION.test(head)
+            ? lines
+                  .flatMap(sentencesOf)
+                  .map(withoutOpener)
+                  .find((sentence) => sentence !== head && isAsk(sentence))
+            : undefined;
+        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));
+};

package/src/{transcript-fold.test.ts → text/transcript-fold.test.ts}

@@ -1,20 +1,16 @@
 import { STATE_DIR } from "@intentic/constants";
 import { describe, expect, it } from "vitest";
-import type { AgentEvent, TranscriptPatch, TranscriptRow } from "./events.js";
+import type { AgentEvent } from "../events/agent-events.js";
+import type { TranscriptPatch, TranscriptRow } from "../events/transcript.js";
 import { applyTranscriptPatch, foldTurn, TranscriptFold, userRow } from "./transcript-fold.js";
 
-// When the turn started: what its user row is stamped with (TranscriptRow.sentAt).
+// Epoch ms stamped on the opening user row's sentAt.
 const SENT_AT = 1_767_225_600_000;
 const openingOf = (prompt: string): TranscriptRow[] => [userRow(prompt, SENT_AT, [])];
 const foldOf = (prompt: string, events: readonly AgentEvent[]): TranscriptRow[] => foldTurn(openingOf(prompt), events);
 
-/* THE ONE FOLD, tested where it lives. Every window draws these rows and the record keeps them, so what is
- * asserted here is what a chat shows live, what it shows reopened, and what the record holds: one set of rules,
- * one set of tests. */
+// The one fold every window and the stored record draw from; pins what a live, reopened and stored chat all show.
 describe("foldTurn", () => {
-    /* The live bubble boundary: `text_end` retires the block that WROTE something, so the calls it introduced
-     * land in a fresh bubble under it, and the prose that reports them joins that same bubble. This is Claude
-     * Code's interleaving: says what it's about to do → the cards → what it found. */
     it("retires a prose bubble at text_end so the calls it introduced land beneath it", () => {
         const events: AgentEvent[] = [
             { kind: "delta", text: "I'll look" },
@@ -31,8 +27,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    /* THE USER SPOKE MID-TURN, and the rows hold it where the turn took it. It closes the open bubble: what the
-     * agent says next is its answer to these words and belongs below them. */
     it("writes a mid-turn steer down as a user row, with the answer to it beneath", () => {
         const events: AgentEvent[] = [
             { kind: "delta", text: "on it" },
@@ -46,8 +40,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // A text_end on a bubble holding only cards is not a boundary: retiring there would split a card away from
-    // the prose that reports it, a shape the live stream never draws.
     it("does not retire a bubble that has written no prose", () => {
         const events: AgentEvent[] = [
             { kind: "tool_call", id: "t1", name: "Read", category: "read", status: "completed" },
@@ -71,17 +63,11 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // A card the turn died mid-call keeps `in_progress`: that is what happened, and claiming a completion it
-    // never reported would be the one thing a transcript must not invent.
     it("leaves an unanswered call in progress", () => {
         const events: AgentEvent[] = [{ kind: "tool_call", id: "t1", name: "Bash", category: "execute", status: "in_progress" }];
         expect(foldOf("run", events).at(-1)?.tools?.[0]?.status).toBe("in_progress");
     });
 
-    /* A DELEGATION: its calls and its thinking nest under the Agent card that spawned them, so a delegation
-     * reads as one unit rather than a leaf card. Its PROSE stays off the card: that card has nowhere to render
-     * prose, and the child's report already arrives as the card's own result content. The child's live state
-     * (the `subagent` frames) rides the same card. */
     it("nests a subagent's calls, thinking and live state under the card that spawned them", () => {
         const events: AgentEvent[] = [
             { kind: "delta", text: "delegating" },
@@ -106,8 +92,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // Its Agent card is not in this stream (a malformed log, or one level of a deeper spawn read on its own), so
-    // there is nothing to hang the child off, which is exactly what keeps a nested level out of the level above.
     it("drops a subagent's frames when the card that spawned them is absent", () => {
         const events: AgentEvent[] = [
             { kind: "delta", text: "delegating" },
@@ -116,9 +100,6 @@ describe("foldTurn", () => {
         expect(foldOf("delegate", events).slice(1)).toEqual([{ role: "assistant", text: "delegating" }]);
     });
 
-    // One subagent's own side of the same log: what the Subagents area renders while it runs. Read at the
-    // child's level its prose IS top-level, the parent's frames are not its business, and the parent's cards
-    // stay out: read at a subagent's own level a card is not that stream's.
     it("reads one subagent's stream as a transcript of its own", () => {
         const questions = [{ question: "Which?", header: "Pick", multiSelect: false, options: [{ label: "A", description: "a" }] }];
         const events: AgentEvent[] = [
@@ -172,8 +153,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // End-of-turn accounting lands on the bubble the answer ended in, and closes the turn: a steered
-    // conversation's stream can carry several turns, and the next opens a fresh bubble below.
     it("attaches the turn's usage to its last bubble and closes it", () => {
         const events: AgentEvent[] = [
             { kind: "delta", text: "done" },
@@ -186,16 +165,11 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // Frames that are not transcript (init, the settle) carry no bubble of their own, so a turn that only
-    // emitted those folds to the prompt alone rather than an empty reply.
     it("yields nothing but the prompt for a turn that said nothing", () => {
         const events: AgentEvent[] = [{ kind: "init", model: "claude-opus-4" }, { kind: "done" }];
         expect(foldOf("hi", events)).toEqual([{ role: "user", text: "hi", sentAt: SENT_AT }]);
     });
 
-    /* A REFUSED TURN SAYS SO. The provider's answer to this one is an error frame and no prose at all, so folding
-     * only the two speakers left a question with no reply under it. The daemon's clause about what comes next
-     * rides the same line, so the reopened chat and the live one read the same. */
     it("keeps what went wrong, as the notice line the turn ended on", () => {
         const refusal = "Your organization has disabled Claude subscription access for Claude Code";
         const events: AgentEvent[] = [{ kind: "delta", text: "I'll take a look" }, { kind: "error", message: refusal }, { kind: "done" }];
@@ -226,9 +200,6 @@ describe("foldTurn", () => {
         });
     });
 
-    /* AND SO DOES A TURN THAT RAN CHEAPER THAN THE MODEL ASKED FOR. Scrolling back a week later, "was THIS
-     * answer the cheap one" is the question, and only a row per routed turn can answer it. The offer rides
-     * along so the reopened line keeps its one press. A verdict that moved nothing writes nothing. */
     it("writes down a turn that ran on a cheaper model, and nothing for a verdict that moved nothing", () => {
         const routed: AgentEvent[] = [
             { kind: "tier", tier: "fast", score: 0.1, rules: ["easy-words"], model: "claude-haiku-4-5", routed: true },
@@ -246,7 +217,6 @@ describe("foldTurn", () => {
         expect(foldOf("go", held).map((message) => message.role)).toEqual(["user", "assistant"]);
     });
 
-    // What happened to the turn outside the model's words: a rebase, a landing, a compaction, each one line.
     it("writes the turn's own events down as notices", () => {
         const events: AgentEvent[] = [
             { kind: "worktree", branch: "agent/x", base: "abc1234", sync: { commits: 2, blocked: [] } },
@@ -269,7 +239,6 @@ describe("foldTurn", () => {
         );
     });
 
-    // The checkpoint and the daemon's notes land on the turn's own user row, where a reader finds them.
     it("stamps the checkpoint and the preamble's notes on the turn's user row", () => {
         const events: AgentEvent[] = [
             { kind: "checkpoint", id: "snap-1", index: 4 },
@@ -287,9 +256,6 @@ describe("foldTurn", () => {
         });
     });
 
-    /* THE CARD THE TURN PARKED ON, and the answer that released it. The card takes the open bubble and closes it,
-     * so the ask tool's own call (which trails its card) lands in the row beneath, with what the agent said once
-     * answered. The reply settles the card's status by the one derivation (card-status.ts). */
     it("records the question a turn asked, with the picks that answered it, and closes the bubble on the card", () => {
         const questions = [
             {
@@ -318,9 +284,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // A card raised under prose that is still open joins that prose, the one row; the answer's continuation
-    // opens the next. A plan whose text IS the adjacent retired prose takes that row over instead of drawing
-    // the same markdown twice.
     it("keeps the prose that led up to a card in the card's own row, and folds a repeated plan into its prose", () => {
         const document = { path: "docs/plan.md", title: "Plan", markdown: "# Plan\n\n1. do it" };
         const events: AgentEvent[] = [
@@ -343,10 +306,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    /* A card nobody answered is nobody's decision: when the turn ends under it, it freezes as `cancelled`, with
-     * everything it was raised with intact — including the judge's sentence, which is what the user was actually
-     * reading when the turn died. (The sentence arrives ON the card now rather than as a later frame patched
-     * into it: it is the reason the card exists, so there was no card before it existed.) */
     it("freezes a card nobody answered as cancelled when the turn ends, keeping what it was raised with", () => {
         const events: AgentEvent[] = [
             { kind: "permission", requestId: "perm1", toolName: "Bash", title: "Claude wants to run pnpm test", explain: "Runs the test suite." },
@@ -366,35 +325,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // An offer's whole life is on its card: the click, the run showing itself living, and how the spend ended.
-    it("keeps an offer's decision, its stream and its receipt on the card that offered it", () => {
-        const offer = { slug: "research", name: "Research", publisher: "acme", description: "d", creditsPerRun: 3, request: "{}" };
-        const events: AgentEvent[] = [
-            { kind: "service_offer", requestId: "s1", offer },
-            { kind: "resolved", requestId: "s1", reply: { kind: "service_offer", requestId: "s1", approve: true } },
-            { kind: "service_event", requestId: "s1", event: { event: "status", text: "searching" } },
-            { kind: "service_receipt", requestId: "s1", outcome: "ok", credits: 3, remaining: 7 },
-            { kind: "delta", text: "Found it." },
-        ];
-        expect(foldOf("research", events).slice(1)).toEqual([
-            {
-                role: "assistant",
-                text: "",
-                serviceOffer: {
-                    requestId: "s1",
-                    offer,
-                    status: "approved",
-                    events: [{ event: "status", text: "searching" }],
-                    receipt: { outcome: "ok", credits: 3, remaining: 7 },
-                },
-            },
-            { role: "assistant", text: "Found it." },
-        ]);
-    });
-
-    /* A GATED CREDENTIAL's card keeps WHO released it, not merely that something was approved: the approver is
-     * the whole point of the gate, and the reply cannot carry them (it is the daemon that verified the
-     * identity), so the receipt frame is the only place that name ever appears. */
     it("keeps who released a gated credential on the card that asked for it", () => {
         const offer = {
             subject: "DATABASE_URL",
@@ -421,9 +351,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    /* A release nobody answered is nobody's refusal. The deadline passing freezes the card `cancelled` and
-     * writes NO receipt, because "refused" would name a decision a person never made — the same split the
-     * gate's two refusal sentences make to the agent. */
     it("freezes an unanswered release as nobody's decision, with no receipt", () => {
         const offer = {
             subject: "reddit",
@@ -439,7 +366,6 @@ describe("foldTurn", () => {
         ]);
     });
 
-    // A turn the user stopped says so, after freezing whatever it was parked on.
     it("writes a stop down after cancelling what the turn was waiting on", () => {
         const events: AgentEvent[] = [
             { kind: "delta", text: "half" },
@@ -452,8 +378,7 @@ describe("foldTurn", () => {
     });
 });
 
-/* THE PATCHES, the other half of the same fold: what a window applies to the rows it holds must reproduce the
- * rows the fold holds, exactly, or the two drift and the reopened chat disagrees with the live one. */
+// Patches applied to a window's rows must reproduce the fold's own rows exactly, or live and reopened chats drift.
 describe("patches", () => {
     const replay = (
         opening: readonly TranscriptRow[],
@@ -516,7 +441,6 @@ describe("patches", () => {
         ]);
     });
 
-    // A bubble the fold opened and never wrote into is dropped, and it was the last row, so nothing above moves.
     it("drop an empty bubble the turn opened and abandoned", () => {
         const events: AgentEvent[] = [
             { kind: "todos", items: [] },
@@ -528,8 +452,6 @@ describe("patches", () => {
         expect(folded.map((row) => row.role)).toEqual(["user", "user"]);
     });
 
-    // A patch carries a COPY: the row the fold keeps mutating afterwards must not reach back into a patch that
-    // was already handed out, or a slow reader applies a delta on top of text that already holds it.
     it("carry copies, not the fold's own rows", () => {
         const fold = new TranscriptFold(openingOf("go"));
         const [appended] = fold.apply({ kind: "delta", text: "a" });