@intentic/sandbox-contract 1.159.0 → 1.161.0

package/src/title.test.ts

@@ -0,0 +1,130 @@
+import { expect, test } from "vitest";
+import { deriveTitle } from "./title.js";
+
+/* The name a conversation opens under. Every case here is a shape the naive rule (collapse whitespace, cut at
+ * 40) got wrong in a way a user notices: the title named the paste instead of the work, spent the budget on
+ * politeness, or stopped mid-syllable. */
+
+test("spends the budget on the ask rather than on the politeness in front of it", () => {
+    // `Can you please fix the auth…` is what the naive cut produced — three of its five words are ceremony.
+    expect(deriveTitle("Can you please fix the auth tests?")).toBe("Fix the auth tests?");
+    expect(deriveTitle("Hey, can you please look at the flaky test")).toBe("Look at the flaky test");
+});
+
+test("keeps a greeting whole when peeling it off would leave a fragment", () => {
+    // `Hi there` is not a conversation about `there`, and `So what?` is not one about `what?` — a one-word
+    // remnant means the opener was carrying the sentence, so the line stands as the user wrote it.
+    expect(deriveTitle("Hi there")).toBe("Hi there");
+    expect(deriveTitle("So what?")).toBe("So what?");
+});
+
+test("titles a pasted stack trace after the sentence the user wrote around it", () => {
+    // The paste is evidence, not the ask. Titling from it gives every one of the day's pastes the same name.
+    const prompt = [
+        "The build is broken again.",
+        "",
+        "```",
+        "Error: ENOENT: no such file or directory",
+        "  at Object.openSync (node:fs)",
+        "```",
+    ].join("\n");
+
+    expect(deriveTitle(prompt)).toBe("The build is broken again");
+});
+
+test("skips a greeting line and takes the ask from the line below it", () => {
+    // A line that unwinds to nothing was throat-clearing; the ask is further down. The naive rule stopped at
+    // the greeting and named every such conversation `Hey, quick one —`.
+    expect(deriveTitle("Hey, quick one —\n\nWhy does the tab title truncate mid-word?")).toBe("Why does the tab title truncate mid-word?");
+});
+
+test("keeps an ask that fits the registry's 80-character budget instead of cutting at 40", () => {
+    // The old 40-character clamp cut this to `In intentic-app/web when conflict…` on a fleet card that had
+    // room for twice that. The stored title matches what the registry and the rename input accept.
+    const prompt = "In intentic-app/web when conflicts happen during rebase show a resolution banner";
+
+    expect(deriveTitle(prompt)).toBe(prompt);
+});
+
+test("cuts on a word boundary instead of mid-syllable", () => {
+    const prompt = "Why does the tab title truncate mid-word even though the strip clearly still has unused horizontal room?";
+    const title = deriveTitle(prompt);
+    const kept = title.slice(0, -1);
+
+    expect(title.endsWith("…")).toBe(true);
+    // The old rule sliced at exactly 40, ending this title inside `mid-word`. Every word that survives has to
+    // be a whole one, so what precedes the ellipsis must stop where the prompt itself has a break.
+    expect(prompt.startsWith(kept)).toBe(true);
+    expect(prompt[kept.length]).toBe(" ");
+});
+
+test("keeps a link's last meaningful segment rather than its host and scaffolding", () => {
+    const title = deriveTitle("Look at https://gitlab.com/radarsu/intentic/-/merge_requests/42 and tell me what broke");
+
+    // A numeric tail alone (`42`) names nothing, so the segment above it comes along.
+    expect(title).toContain("merge_requests/42");
+    expect(title).not.toContain("gitlab.com");
+});
+
+test("collapses a deep path to its basename and leaves a shallow one alone", () => {
+    expect(deriveTitle("Refactor _apps/web/src/composables/chat/conversation.ts")).toBe("Refactor conversation.ts");
+    // Two segments already read as a place; collapsing them would lose the only context the reference carries.
+    expect(deriveTitle("Refactor src/foo.ts")).toBe("Refactor src/foo.ts");
+});
+
+test("ends on the first sentence when the prompt keeps going", () => {
+    expect(deriveTitle("Fix the flaky test. It fails about one run in five, usually on CI.")).toBe("Fix the flaky test");
+});
+
+test("does not mistake an abbreviation for the end of a sentence", () => {
+    // `i.e.` would otherwise cut the title to `i.e`, which names nothing at all.
+    expect(deriveTitle("i.e. the derived title should survive")).toBe("i.e. the derived title should survive");
+});
+
+test("leaves casing alone when the opening word carries meaning in its casing", () => {
+    expect(deriveTitle("useAgents leaks a watcher on unmount")).toBe("useAgents leaks a watcher on unmount");
+    expect(deriveTitle("fix the leaking watcher")).toBe("Fix the leaking watcher");
+});
+
+test("names a prompt that is nothing but a paste after what was pasted", () => {
+    // Returning empty here would render a nameless tab; the first line of the paste at least says what it is.
+    expect(deriveTitle("```ts\nconst x = 1;\n```")).toBe("const x = 1;");
+});
+
+test("never returns empty for a prompt that has any content at all", () => {
+    // A greeting with no ask behind it, and a prompt with no letters in it — both still have to name a tab.
+    expect(deriveTitle("Hey!")).toBe("Hey!");
+    expect(deriveTitle("!!!")).toBe("!!!");
+});
+
+test("reads past quoted material to the user's own words", () => {
+    expect(deriveTitle("> previous message\nWhat changed here?")).toBe("What changed here?");
+});
+
+test("skips past-work narration to the instruction behind it", () => {
+    // `We have recently added…` is the scene, not the ask — titling from it names every such conversation
+    // after last week's work. The instruction further in is what the conversation is about.
+    expect(deriveTitle("We have recently added iq map and iq deps commands. Now let's also add a health contract for the daemon.")).toBe(
+        "Add a health contract for the daemon",
+    );
+    expect(deriveTitle("We've just landed the fleet board.\n\nRename the Attention lane to Blocked.")).toBe("Rename the Attention lane to Blocked");
+});
+
+test("skips narration to an outright question", () => {
+    expect(deriveTitle("I've implemented the empty state. What should the loading state show?")).toBe("What should the loading state show?");
+});
+
+test("keeps narration when nothing behind it is unmistakably the ask", () => {
+    // A hazy follow-up is not worth skipping for — better a title about last week's work than one about `it`.
+    expect(deriveTitle("We migrated the board to SSE last week. It feels slower since.")).toBe("We migrated the board to SSE last week");
+});
+
+test("keeps a declarative problem report even when advice follows it", () => {
+    // Only NARRATION is skippable. A problem statement is the ask, and the imperative behind it is merely a
+    // pointer — `Check the broadcast path` names a step, not the conversation.
+    expect(deriveTitle("The fleet board flickers when agents land. Check the broadcast path.")).toBe("The fleet board flickers when agents land");
+});
+
+test("strips control characters the same way the registry's sanitiser does", () => {
+    expect(deriveTitle("Fix\u0000 the\u200b bug")).toBe("Fix the bug");
+});

package/src/title.ts

@@ -0,0 +1,254 @@
+/* HOW A CONVERSATION NAMES ITSELF from its opening prompt — the title a chat tab, a fleet card and the agent
+ * detail header wear from the first keystroke of a turn until something better arrives.
+ *
+ * The naive rule (collapse whitespace, cut at N) reads the prompt as if it were a headline, and opening
+ * prompts are not headlines. They are pasted stack traces, links dropped in with two words of context,
+ * politeness that eats half the budget before the ask begins, and multi-line asks whose first line is throat-
+ * clearing. Cutting those at 40 characters yields `Error: ENOENT: no such file or directo…` — a title that
+ * names the paste rather than the work, and that reads identically for every one of the day's five pastes.
+ *
+ * So the prompt is read as prose FIRST and cut second: quoted material and fenced code are not the ask, the
+ * opener is not the ask, and a reference is worth only its last segment. What survives is the earliest line
+ * that still says something, cut on a sentence or a word rather than mid-syllable.
+ *
+ * Both sides derive: the browser names a conversation the instant it sends (conversation.ts), and the daemon
+ * names a turn that arrived without one — an automation, a Discord message, a webchat visitor (agents-
+ * registry.ts). One rule, because two would let the same prompt open under two different names depending on
+ * where it entered. Nothing here calls a model: the title has to exist before the first frame comes back.
+ * (A model DOES get its say later — the daemon's title-summary pass renames a still-derived title once the
+ * first turn has an answer to read — but that is a promotion over this title, never a replacement for it.) */
+
+// The registry's title budget (agents-registry MAX_TITLE_LENGTH, the rename input's maxlength) — the widest
+// any surface stores. Every surface truncates in CSS to its own width, so the clamp here is a storage cap,
+// not a display rule: cutting shorter than the widest surface (a full-width fleet card) would throw away
+// signal that surface has room to show, and no narrow surface is hurt because its CSS cuts first anyway.
+const MAX_LENGTH = 80;
+// Below this a sentence-shaped cut is more likely an abbreviation (`e.g.`, `i.e.`) than a sentence, so the
+// length clamp takes over.
+const MIN_SENTENCE = 12;
+// A word-boundary cut this far back strands a fragment; better to cut mid-word than to title a conversation
+// with two characters and an ellipsis.
+const MIN_WORD_CUT = MAX_LENGTH * 0.6;
+
+// Markdown's two fence syntaxes, and the quote marker. Both open and close on the same shape, so a fence line
+// toggles rather than matching a pair — an UNTERMINATED fence (a paste the user never closed) then swallows
+// the rest of the prompt, which is what it visually does too.
+const FENCE = /^\s*(?:```|~~~)/;
+const QUOTE = /^\s*>/;
+
+// The ways an ask opens without starting. Stripped repeatedly, so `Hey, can you please …` unwinds one layer
+// per pass; a line that unwinds to nothing was pure throat-clearing and the next line carries the ask.
+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,
+];
+
+// A sentence ends on terminal punctuation that is actually followed by a break — which is what holds `v1.2`
+// and `foo.ts` together while still ending `Why is it red?`.
+const SENTENCE_END = /[.!?](?=\s|$)/;
+
+/* A report of work already done — `We have recently added…`, `I've just landed…`, `we were refactoring…`. The
+ * one first-sentence shape that is reliably CONTEXT rather than the ask: prompts that open on it set the scene
+ * for an instruction further down, and titling from the scene names every such conversation after last week's
+ * work instead of this one's.
+ *
+ * Detected as we/I, an optional aux chain, then a verb in past or progressive form: the regular `…ed`/`…ing`
+ * endings plus the irregular pasts that actually appear in prompts about software. The lookahead excludes the
+ * handful of present-tense verbs the `…ed` ending would swallow (`we need…`, `we embed…`); `…ing` wants three
+ * letters in front so `we ping`/`we bring` stay present tense. */
+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;
+
+// The ask read as an instruction: a sentence leading with a bare verb of the kind coding asks lead with. A
+// curated list rather than grammar — English hands out noun/verb ambiguity too freely for anything cleverer.
+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, or a question asked outright. Anything less deliberate is not worth
+// skipping a sentence for.
+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();
+
+// The prompt minus everything the user pasted rather than wrote. Fenced blocks and quoted blocks are evidence
+// attached to the ask, never 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;
+};
+
+/* Peel the openers off a line, but only keep the peeling when something with shape is left underneath.
+ *
+ * Three outcomes, and the difference between them is the whole point. A remnant of SEVERAL words is the ask —
+ * `Can you please fix the auth tests?` was carrying `fix the auth tests?`. A remnant of NOTHING was pure
+ * greeting (`Hey, quick one —`), and returning empty is how the caller learns to read the next line instead.
+ * A remnant of ONE word means the opener was load-bearing — `Hi there` is not a conversation about `there`,
+ * and `So what?` is not one about `what?` — so the line stands as written. */
+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 is worth its last meaningful segment: the host when there is no path, and the segment before a purely
+// numeric one so an issue link reads `merge_requests/42` rather than `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 is worth its basename once it is deep enough that the lead is scaffolding — `src/foo.ts` already
+// reads as a place, `_apps/web/src/composables/chat/conversation.ts` reads as a wall.
+const shortPath = (token: string): string => {
+    const segments = token.replace(/^@/, "").split("/");
+    return segments.length > 2 ? (segments.findLast((segment) => segment !== "") ?? token) : token;
+};
+
+// Trailing punctuation belongs to the sentence, not to the reference inside it, so it is set aside across the
+// shortening and put back — `see _apps/web/src/foo.ts,` collapses to `see foo.ts,`.
+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;
+    }
+    // A question mark or a bang carries tone worth keeping; a full stop on a title is just noise.
+    const terminator = text[end];
+    return terminator === "." ? text.slice(0, end) : text.slice(0, end + 1);
+};
+
+// Every sentence in turn, terminators handled as in firstSentence — the walk the ask-scan below reads. No
+// abbreviation guard here: a fragment split off at an `e.g.` never leads with an imperative, so it simply
+// loses the scan rather than corrupting it.
+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;
+};
+
+const clamped = (text: string): string => {
+    if (text.length <= MAX_LENGTH) {
+        return text;
+    }
+    const cut = text.slice(0, MAX_LENGTH);
+    const boundary = cut.lastIndexOf(" ");
+    const kept = boundary >= MIN_WORD_CUT ? cut.slice(0, boundary) : cut;
+    return `${kept.replace(/[\s,;:—–-]+$/, "")}…`;
+};
+
+// Sentence case, but only when the opening word is plainly lowercase prose. An identifier (`useAgents`), a
+// path (`src/foo`) or an abbreviation (`e.g`) means something by its casing and is left alone.
+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)}`;
+};
+
+/* Split a plan's markdown into its leading heading and the remaining body.
+ *
+ * The heading is the one place in a turn where an agent writes a name for the WHOLE job rather than for a step
+ * — a task checklist describes `Read the failing test`, `Fix the assertion`, `Run the suite`, none of which is
+ * what the conversation is about, whereas a plan opens `## Fix the flaky auth tests`. That makes it the only
+ * authored line in the stream worth promoting to a title, which is why this lives here rather than next to the
+ * plan card that also renders it: the browser titles its own tabs from it and the daemon titles fleet cards. */
+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() };
+};
+
+/* Name a conversation after the prompt that opened it. Never empty for a non-empty prompt: a paste with no
+ * prose around it still titles as its own first line, which at least names what was pasted. */
+export const deriveTitle = (prompt: string): string => {
+    const prose = proseLines(prompt)
+        .map(collapse)
+        .filter((line) => line !== "");
+    // Lines that survive opener-stripping with letters in them. The first is the title's default; the rest
+    // only matter when that default turns out to be scene-setting.
+    const lines = prose.map(withoutOpener).filter((line) => /\p{L}/u.test(line));
+    const primary = lines[0];
+    if (primary !== undefined) {
+        /* A first sentence that reports work already done is the scene, not the ask — `We have recently added
+         * iq map. Now let's expose health.` is a conversation about exposing health. Skipped only for an
+         * unmistakable ask further in (an instruction or an outright question); anything hazier and the
+         * narration stands, exactly as every non-narrative opening always does. */
+        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))));
+    }
+    // Everything the user sent was code, a quote, or a greeting — title it as what it is rather than blank.
+    const fallback = prose[0] ?? collapse(prompt.replaceAll(/^\s*(?:```|~~~).*$/gm, ""));
+    return clamped(collapseReferences(fallback === "" ? collapse(prompt) : fallback));
+};