@djangocfg/widget-chat 0.1.1

package/src/core/recall/ladder.ts

@@ -0,0 +1,171 @@
+/**
+ * The prompt ladder: what ArrowUp and ArrowDown land on, as pure state.
+ *
+ * `boundary.ts` answers "may this press navigate"; this answers "to what". Split
+ * because they fail differently — a boundary bug moves the caret when it should
+ * not, a ladder bug loses the user's draft — and because the boundary rules were
+ * ported verbatim while this is where the queue rung is new.
+ *
+ * ## The ladder, from the bottom
+ *
+ *   draft            ← what the user was typing, stashed on the first ArrowUp
+ *   queued (last)    ← the newest prompt waiting to be sent, if any
+ *   sent[n-1]        ← the most recent sent prompt
+ *   …
+ *   sent[0]          ← the oldest kept
+ *
+ * ArrowUp climbs, ArrowDown descends, and the bottom is always the draft the
+ * user had before they started walking. Losing that draft is the failure this
+ * design exists to prevent: a user presses Up once out of curiosity and their
+ * half-written message must come back on Down.
+ *
+ * ## Why the queue is a rung, and only its LAST entry
+ *
+ * A queued prompt was written but not answered, so it is the nearest thing in
+ * time to the draft — closer than anything already sent. Only the last one is a
+ * rung: it is the one a user reaching backwards means, and it is the one they
+ * would edit. Walking the whole queue would put entries the user can already
+ * see, and remove, into a ladder they cannot see.
+ *
+ * ## Why `index` is not enough on its own
+ *
+ * The pending rung cannot be an index into `sent` — it sits between the draft
+ * and `sent[n-1]` and belongs to neither array. Encoding it as `index === -1`
+ * would make it indistinguishable from "not walking at all", and a second
+ * ArrowDown would then jump to the draft, skipping every entry just walked.
+ * Hence an explicit position type.
+ */
+
+/** Where the ladder currently is. `draft` is the bottom and the resting state. */
+export type RecallPosition =
+  | { readonly kind: "draft" }
+  | { readonly kind: "queued" }
+  | { readonly kind: "sent"; readonly index: number };
+
+export interface RecallState {
+  readonly position: RecallPosition;
+  /**
+   * The user's own text, held while they walk.
+   *
+   * `null` means nothing is stashed — i.e. the ladder is at rest. Stashed ONCE,
+   * on the first step off the draft, never on subsequent steps: re-stashing
+   * would overwrite the user's text with a recalled entry and the draft would be
+   * gone with no way back.
+   */
+  readonly stashedDraft: string | null;
+  /**
+   * What recall last wrote into the buffer.
+   *
+   * `bufferIsRecallOwned` reads this to tell "the user typed this" from "recall
+   * put this here". Cleared when the ladder returns to rest, so a stale value
+   * cannot make a fresh draft look recall-owned.
+   */
+  readonly lastRecalled: string | null;
+}
+
+export interface RecallLadder {
+  /** Sent prompts, OLDEST first — the order ArrowUp walks backwards through. */
+  readonly sent: readonly string[];
+  /** Prompts queued behind an in-flight turn, oldest first. Only the last is a rung. */
+  readonly queued: readonly string[];
+}
+
+/** A move's outcome: the new state, and the text to put in the buffer. */
+export interface RecallMove {
+  readonly state: RecallState;
+  /** `null` ⇒ nothing moved; the caller must NOT write to the buffer. */
+  readonly text: string | null;
+}
+
+export const REST: RecallState = {
+  position: { kind: "draft" },
+  stashedDraft: null,
+  lastRecalled: null,
+};
+
+/** The queue rung exists only when the newest queued prompt has content. */
+function queuedRung(ladder: RecallLadder): string | null {
+  const last = ladder.queued[ladder.queued.length - 1];
+  return last !== undefined && last !== "" ? last : null;
+}
+
+/**
+ * Step UP one rung.
+ *
+ * `draft` is the current buffer, stashed on the first step so ArrowDown can
+ * return it. Returns `text: null` when there is nowhere to go, which is how the
+ * caller knows to leave the key to the textarea rather than swallowing it.
+ */
+export function recallPrevious(
+  state: RecallState,
+  ladder: RecallLadder,
+  draft: string,
+): RecallMove {
+  // Stash before anything else, and only at rest: `stashedDraft` is the user's
+  // text, and overwriting it mid-walk with a recalled entry loses it silently.
+  const stashedDraft = state.position.kind === "draft" ? draft : state.stashedDraft;
+
+  const step = (position: RecallPosition, text: string): RecallMove => ({
+    state: { position, stashedDraft, lastRecalled: text },
+    text,
+  });
+
+  if (state.position.kind === "draft") {
+    const pending = queuedRung(ladder);
+    if (pending !== null) return step({ kind: "queued" }, pending);
+    const newest = ladder.sent.length - 1;
+    if (newest < 0) return { state, text: null };
+    return step({ kind: "sent", index: newest }, ladder.sent[newest] ?? "");
+  }
+
+  if (state.position.kind === "queued") {
+    const newest = ladder.sent.length - 1;
+    if (newest < 0) return { state, text: null };
+    return step({ kind: "sent", index: newest }, ladder.sent[newest] ?? "");
+  }
+
+  const next = state.position.index - 1;
+  // At the oldest entry: stay. Wrapping to the newest would make a long ladder
+  // an infinite loop with no way to tell you had reached the end.
+  if (next < 0) return { state, text: null };
+  return step({ kind: "sent", index: next }, ladder.sent[next] ?? "");
+}
+
+/**
+ * Step DOWN one rung, ending at the stashed draft.
+ *
+ * At rest this does nothing and returns `text: null` — ArrowDown in an untouched
+ * composer belongs to the textarea.
+ */
+export function recallNext(state: RecallState, ladder: RecallLadder): RecallMove {
+  if (state.position.kind === "draft") return { state, text: null };
+
+  const land = (): RecallMove => {
+    const text = state.stashedDraft ?? "";
+    // Back at rest: `lastRecalled` is cleared with the same write, so the
+    // restored draft is the USER's again and a further arrow will not navigate
+    // unless the buffer is empty.
+    return { state: REST, text };
+  };
+
+  if (state.position.kind === "queued") return land();
+
+  const next = state.position.index + 1;
+  if (next < ladder.sent.length) {
+    const text = ladder.sent[next] ?? "";
+    return {
+      state: { ...state, position: { kind: "sent", index: next }, lastRecalled: text },
+      text,
+    };
+  }
+
+  // Past the newest sent entry: the queued rung, then the draft.
+  const pending = queuedRung(ladder);
+  if (pending !== null) {
+    return {
+      state: { ...state, position: { kind: "queued" }, lastRecalled: pending },
+      text: pending,
+    };
+  }
+  return land();
+}

package/src/core/reload-decision.ts

@@ -0,0 +1,36 @@
+/**
+ * What to do when a room's revision moves.
+ *
+ * Split from the hook so the rule is testable without a renderer: every way
+ * live-append can misbehave — reloading over a live stream, dropping a message
+ * that arrived mid-turn, re-fetching the rows just read at mount — is decided
+ * here.
+ */
+export type ReloadDecision = "reload" | "defer" | "ignore";
+
+export interface ReloadInputs {
+  /** The room's current revision. */
+  readonly revision: number;
+  /** The last revision this reader acted on (or mounted with). */
+  readonly seen: number;
+  /** True while a turn is streaming into the transcript. */
+  readonly streaming: boolean;
+  /** True when an earlier change was deferred and has not yet been served. */
+  readonly deferred: boolean;
+}
+
+export function reloadDecision(input: ReloadInputs): ReloadDecision {
+  const changed = input.revision !== input.seen;
+
+  // Mid-stream, a change waits. Seeding replaces the transcript wholesale and
+  // clears the streaming id, so reloading now would delete the reply as it is
+  // being written.
+  if (input.streaming) return changed || input.deferred ? "defer" : "ignore";
+
+  // The stream ended with a change owed — serve it now. Without this branch a
+  // message that landed mid-turn stays invisible until the room is reopened,
+  // which is the original defect wearing a narrower window.
+  if (input.deferred) return "reload";
+
+  return changed ? "reload" : "ignore";
+}

package/src/core/scroll/index.ts

@@ -0,0 +1,17 @@
+// How many messages arrived while the reader was away.
+//
+// In core/ because none of it is DOM. HOW to follow the bottom is not here and
+// must not come back: it needs the engine's own scroll settle to blend against,
+// which a pure model cannot see, and a hand-written version shook on every
+// fling. `use-stick-to-bottom` owns the motion, wired in primitives/.
+//
+// WHETHER an arrival was the reader's own send is a different question, and one
+// the library cannot answer at all — `isOwnSend` decides it from the transcript
+// alone, which is why it is testable here and the animation is not.
+//
+// May import: utils.
+
+export { MissedCount, missedRows } from "./missed";
+export type { MissedRole } from "./missed";
+export { isOwnSend } from "./sent";
+export type { SentRole } from "./sent";

package/src/core/scroll/missed.ts

@@ -0,0 +1,106 @@
+/**
+ * How many replies arrived while the reader was scrolled away.
+ *
+ * A plain class for the same reason as `BottomPin`: nothing here is DOM. What
+ * is hard is deciding when the count starts, when it resets, and what counts —
+ * and all three are wrong in ways a rendered badge cannot show you.
+ *
+ * No store: the transcript already knows the message list and the pin state, so
+ * a second owner for "how far behind is the reader" could disagree with the
+ * scroll position it is describing.
+ */
+
+/**
+ * The reader's own messages never count.
+ *
+ * Sending scrolls them to the bottom anyway, so a `user` row can only enter the
+ * count in a race — and a badge that says "1 new" pointing at your own sentence
+ * is worse than no badge. Mirrors the server's unread rule, which excludes
+ * `author_kind = 'human'` for exactly this reason.
+ */
+export type MissedRole = "user" | "assistant" | "system";
+
+export class MissedCount {
+  /**
+   * The last row present when the reader left the bottom. Null while pinned.
+   *
+   * An id, not a length and not a set of every id seen. A length breaks when
+   * history loads ABOVE — the list grows without anything arriving. A set
+   * breaks the same way for the opposite reason: prepended rows are absent from
+   * it and read as new. New messages append, so the last row is the frontier,
+   * and everything after it is what the reader missed.
+   */
+  private frontier: string | null = null;
+  /** Distinguishes "pinned, no frontier" from "unpinned on an empty list". */
+  private armed = false;
+  private count = 0;
+
+  /**
+   * Feed the current state after every render.
+   *
+   * @param pinned whether the viewport is following the bottom
+   * @param rows every message currently in the transcript, in order
+   */
+  observe(pinned: boolean, rows: readonly { id: string; role: MissedRole }[]): void {
+    if (pinned) {
+      this.frontier = null;
+      this.armed = false;
+      this.count = 0;
+      return;
+    }
+    // The FIRST unpinned observation sets the frontier. An empty transcript
+    // leaves it null, which correctly means every later row is new.
+    if (!this.armed) {
+      this.frontier = rows.at(-1)?.id ?? null;
+      this.armed = true;
+    }
+    const at = this.frontier === null ? -1 : rows.findIndex((row) => row.id === this.frontier);
+    // A frontier that vanished (a cleared transcript, a room switch) must not
+    // count the whole list: -1 there would make every row new. Re-arm instead.
+    if (this.frontier !== null && at === -1) {
+      this.frontier = rows.at(-1)?.id ?? null;
+      this.count = 0;
+      return;
+    }
+    this.count = rows.slice(at + 1).filter((row) => row.role !== "user").length;
+  }
+
+  /**
+   * The badge's number, or null when there is nothing honest to show.
+   *
+   * Null rather than 0 so a caller cannot render an empty badge: "the button is
+   * showing but nothing arrived" and "1 arrived" are different states, and only
+   * the second deserves a number.
+   */
+  value(): number | null {
+    return this.count > 0 ? this.count : null;
+  }
+}
+
+/**
+ * The transcript's id list paired with the roles the store holds for it.
+ *
+ * Separate from the React binding so the one decision it makes is testable
+ * without a DOM: what to do with an id the store has no message for. It DROPS
+ * that row. The alternative — defaulting a role — has to pick one, and every
+ * choice is wrong in a way the badge shows: `assistant` counts a phantom and
+ * sends the reader down to a row that is not there, `user` silently suppresses
+ * a real reply if the guess is ever wrong.
+ *
+ * `ids` and the message map are written together in every store path, so the
+ * case cannot arise today. It is written down because the two consumers of that
+ * invariant had drifted apart: `selectMessages` already drops the missing id,
+ * while this side used to substitute `assistant`.
+ *
+ * Structural parameter rather than the store's own types: `core` may import
+ * only `utils`.
+ */
+export function missedRows(
+  ids: readonly string[],
+  byId: Readonly<Record<string, { readonly role: MissedRole } | undefined>>,
+): readonly { id: string; role: MissedRole }[] {
+  return ids.flatMap((id) => {
+    const message = byId[id];
+    return message === undefined ? [] : [{ id, role: message.role }];
+  });
+}

package/src/core/scroll/sent.ts

@@ -0,0 +1,54 @@
+/**
+ * Did the reader just SEND, as opposed to receive?
+ *
+ * `use-stick-to-bottom` only follows growth while the view is already pinned, so
+ * a reader scrolled into history stayed there when their own message landed —
+ * the room looked as if nothing had been sent. Returning them is a different
+ * question from "follow a streaming reply", and nothing answered it.
+ *
+ * The signal is the transcript itself rather than an event, because every entry
+ * point ends there — Enter, the send button, a host calling `store.send`, a
+ * queued prompt draining. `turn:sent` fires only on the keyboard path, so a
+ * listener would have been right about a quarter of the ways to send.
+ *
+ * Pure, and here rather than in the hook, for the same reason as `MissedCount`:
+ * the three cases it must tell apart are not visible in a rendered scroll
+ * position, and getting any of them wrong is silent.
+ */
+
+/** Only the reader's own turn asks to be shown the bottom. */
+export type SentRole = "user" | "assistant" | "system";
+
+/**
+ * @param previous the id list as last observed, or null before the first one
+ * @param ids the id list now
+ * @param roleOf the role the store holds for an id, or undefined if it has none
+ */
+export function isOwnSend(
+  previous: readonly string[] | null,
+  ids: readonly string[],
+  roleOf: (id: string) => SentRole | undefined,
+): boolean {
+  // Nothing to compare against: the first observation is the room's existing
+  // history, not something that just happened.
+  if (previous === null) return false;
+
+  // A send APPENDS exactly one id and leaves the rest identical.
+  //
+  // Compared as a WHOLE list, not by its tail, because the store outlives a room
+  // switch: `load` replaces the transcript wholesale, and a room whose history
+  // happens to end on a user message would otherwise read as a send and animate
+  // a scroll every time it is opened. History paged in ABOVE fails this too,
+  // which is correct — the reader asked for those rows where they are.
+  if (ids.length !== previous.length + 1) return false;
+  for (let index = 0; index < previous.length; index += 1) {
+    if (ids[index] !== previous[index]) return false;
+  }
+
+  const last = ids[ids.length - 1];
+  if (last === undefined) return false;
+  // The assistant opening its reply also appends exactly one id. Following that
+  // would drag a reader out of the history they scrolled up to read, which is
+  // what the jump-to-latest control exists to offer instead of forcing.
+  return roleOf(last) === "user";
+}

package/src/core/text-replace.ts

@@ -0,0 +1,20 @@
+/**
+ * Putting text into a composer that may already hold some.
+ *
+ * Three callers need this and each wrote its own: recall's Tab commit, a slash
+ * pick, and taking a queued prompt back for editing. They disagreed on the one
+ * question that matters — what happens to what the user already typed — so the
+ * rule lives here once.
+ */
+
+/**
+ * Would this write destroy something? `false` ⇒ write, and do NOT prompt.
+ *
+ * An empty field has nothing to lose, and re-inserting text the field already
+ * holds is a no-op the user would read as a pointless question.
+ */
+export function needsChoice(current: string, incoming: string): boolean {
+  const held = current.trim();
+  if (held === "") return false;
+  return held !== incoming.trim();
+}

package/src/core/tool-name.ts

@@ -0,0 +1,31 @@
+/**
+ * The qualifier an MCP client prepends to every tool it borrows from a server.
+ *
+ * Tools are declared BARE on the server — it registers `ask_weather`, not
+ * `mcp__server__ask_weather`. The prefix is the client's
+ * namespacing, so stripping it restores the name we chose rather than inventing
+ * a nickname for a name we did not.
+ *
+ * Lazy on purpose: it must close at the FIRST separator, because `__` is legal
+ * inside a tool's own name and a greedy match would eat into it.
+ */
+const QUALIFIED = /^mcp__.+?__/;
+
+/**
+ * The tool name as a reader should see it.
+ *
+ * Exactly two segments come off — the marker and the server — because `__` is
+ * legal INSIDE a tool's own name. Taking the text after the last separator
+ * instead would silently shorten any such tool, and nothing would fail: the row
+ * still renders, just under half a name.
+ *
+ * A name that is not qualified passes through untouched, which is what keeps
+ * one engine's rows (`ToolSearch`) sitting level with another's in the same
+ * transcript.
+ */
+export function readableToolName(toolName: string): string {
+  const bare = toolName.replace(QUALIFIED, "");
+  // A name that is ONLY its qualifier leaves nothing to render; the raw string
+  // is a worse label than the original, so the original stands.
+  return bare === "" ? toolName : bare;
+}

package/src/core/tool-picks-set.ts

@@ -0,0 +1,48 @@
+// The picked-tool list as a SET, keyed by id.
+//
+// May import: ./tool-picks.
+
+import type { ToolPick } from "./tool-picks";
+
+/**
+ * Add a pick unless its id is already staged.
+ *
+ * Uniqueness belongs to the list, not to each caller: three paths write it —
+ * the menu, a paste carrying a marker, a restored draft — and a rule enforced
+ * at three call sites is one an unrelated fourth breaks. A duplicate is not
+ * cosmetic either: `appendToolMarkers` would write the marker twice and the
+ * model would read two requests.
+ *
+ * Returns the SAME array when nothing changes, so a no-op cannot re-render.
+ */
+export function addToolPick(
+  picks: readonly ToolPick[],
+  pick: ToolPick,
+): readonly ToolPick[] {
+  return picks.some((staged) => staged.id === pick.id) ? picks : [...picks, pick];
+}
+
+/** Add several, in order, each subject to the same rule. */
+export function addToolPicks(
+  picks: readonly ToolPick[],
+  incoming: readonly ToolPick[],
+): readonly ToolPick[] {
+  return incoming.reduce(addToolPick, picks);
+}
+
+export function removeToolPick(picks: readonly ToolPick[], id: string): readonly ToolPick[] {
+  return picks.filter((pick) => pick.id !== id);
+}
+
+/**
+ * The menu's verb: staged ⇒ remove, absent ⇒ add.
+ *
+ * A toggle rather than an add because the menu row is the same control either
+ * way — a second press has to mean "undo", and silently ignoring it reads as a
+ * dead row.
+ */
+export function toggleToolPick(picks: readonly ToolPick[], pick: ToolPick): readonly ToolPick[] {
+  return picks.some((staged) => staged.id === pick.id)
+    ? removeToolPick(picks, pick.id)
+    : [...picks, pick];
+}

package/src/core/tool-picks.ts

@@ -0,0 +1,142 @@
+/**
+ * A tool the user picked from the menu, and the marker that carries it.
+ *
+ * The marker reaches the MODEL, not the transcript. It says "the user chose
+ * this from the menu" in a form that survives a sentence around it, which a
+ * bare name cannot: `upload_file` in prose is indistinguishable from a word
+ * that was typed, and that ambiguity is the whole reason the menu exists.
+ */
+
+import { toolURL } from "./links";
+
+/** A picked tool: the registry's id, and the label the user actually saw. */
+export interface ToolPick {
+  readonly id: string;
+  /** What the menu row said. Shown on the chip; never sent. */
+  readonly label: string;
+  /**
+   * The entry's icon KEY, carried so the chip can draw the same glyph the menu
+   * row did. Absent ⇒ no glyph; the id is not a fallback, because a host maps
+   * these keys and an id it never mapped would resolve to nothing anyway.
+   */
+  readonly icon?: string;
+  /**
+   * Carried from the catalogue row so the composer can say what is still
+   * missing without holding the catalogue itself — the draft is what the
+   * placeholder reads, and a pick is the only thing on it that knows.
+   */
+  readonly needs?: "file" | "skill";
+}
+
+/**
+ * The marker a picked tool becomes in the outbound text: a markdown link
+ * `[<label>](app://tool/<id>)`.
+ *
+ * A link rather than a bare token because the same string has two readers. The
+ * MODEL reads the label, which is the human name of the tool and says more than
+ * an id does; the RENDERER reads the href, which is the exact registry id and
+ * is what a chip must resolve. A bare `[tool:<id>]` served only the second, and
+ * printed as noise to the first.
+ *
+ * An empty label falls back to the id — a link with no text renders as nothing
+ * at all, which would hide the pick from the model entirely.
+ */
+export function toolMarker(id: string, label: string): string {
+  return `[${escapeLinkText(label || id)}](${toolURL(id)})`;
+}
+
+/**
+ * Escape the characters that would end a markdown link's text early.
+ *
+ * Only `[` and `]` matter: either one unbalances the bracket pair, so the
+ * parser stops reading the label there and the href becomes visible prose.
+ * Labels rarely contain them, and a label that does must still round-trip.
+ */
+function escapeLinkText(label: string): string {
+  return label.replace(/([[\]])/g, "\\$1");
+}
+
+/**
+ * Ids named by markers in a text, in the order they appear.
+ *
+ * For a host that must reconcile what a user typed against what they picked.
+ * Matched on the HREF, not the label: the id is the half that identifies the
+ * tool, and a label may be renamed, translated, or typed by the user.
+ *
+ * The label is skipped with an escape-aware scan so a `\]` inside it cannot end
+ * the pair early — the other half of what `escapeLinkText` writes.
+ */
+export function readToolMarkers(text: string): readonly string[] {
+  const found: string[] = [];
+  for (const match of text.matchAll(/\[(?:\\.|[^\\[\]])*\]\(app:\/\/tool\/([^)\s]+)\)/g)) {
+    // The group is guaranteed by the pattern, but not by the type: an indexed
+    // read is `string | undefined` under the compiler's checked-access rule.
+    const raw = match[1];
+    if (raw === undefined) continue;
+    // The writer percent-encodes the id, so the reader must decode it or an id
+    // with a reserved character never matches the pick it came from.
+    try {
+      found.push(decodeURIComponent(raw));
+    } catch {
+      found.push(raw);
+    }
+  }
+  return found;
+}
+
+/**
+ * Append each pick's marker to the text the model receives.
+ *
+ * Appended at the END, never at the caret: the markers describe the whole turn,
+ * and splicing one into the middle of a sentence would change what the prose
+ * around it means.
+ *
+ * A pick already named in the text is not repeated — a user who typed the
+ * marker themselves, or a draft restored from storage, would otherwise send it
+ * twice and read as two requests.
+ */
+export function appendToolMarkers(text: string, picks: readonly ToolPick[] | undefined): string {
+  // Tolerates a draft built before this field existed. `Draft` crosses the
+  // package boundary, so a host or a stored draft can still carry the old
+  // shape, and a missing list means "picked nothing" rather than a crash on
+  // the send path.
+  if (picks === undefined || picks.length === 0) return text;
+
+  const already = new Set(readToolMarkers(text));
+  const markers = picks
+    .filter((pick) => !already.has(pick.id))
+    .map((pick) => toolMarker(pick.id, pick.label));
+  if (markers.length === 0) return text;
+
+  const body = text.trim();
+  return body === "" ? markers.join(" ") : `${body} ${markers.join(" ")}`;
+}
+
+/** A text with its tool markers removed, and the ids they named. */
+export interface StrippedToolMarkers {
+  readonly text: string;
+  readonly ids: readonly string[];
+}
+
+/**
+ * Split pasted text into prose and the tools it names.
+ *
+ * The marker is what `buildOutbound` WRITES, so copying a sent turn and pasting
+ * it back returns raw markdown to the box. The user sees a URL they did not
+ * type and a tool nothing staged — the round trip loses exactly the fact the
+ * marker exists to carry.
+ *
+ * Ids only. Whether a tool is offered here is the catalogue's answer, and a
+ * label lifted from the text would name a tool this host may not register.
+ */
+export function stripToolMarkers(text: string): StrippedToolMarkers {
+  const ids = readToolMarkers(text);
+  if (ids.length === 0) return { text, ids };
+
+  // Collapse the space the marker was joined with, so removing a trailing one
+  // does not leave the prose ending in a blank.
+  const stripped = text
+    .replace(/\s*\[(?:\\.|[^\\[\]])*\]\(app:\/\/tool\/[^)\s]+\)/g, "")
+    .trim();
+  return { text: stripped, ids };
+}

package/src/core/tool-prompt.ts

@@ -0,0 +1,47 @@
+/**
+ * What the composer should say once a tool is picked.
+ *
+ * Picking states an intent, and for most tools the object arrives as the
+ * sentence typed next — which is why the caret lands in the field and why this
+ * returns nothing for them. A few tools want something a sentence cannot carry,
+ * and today the interface stays silent: the turn sends, and the agent asks a
+ * question the composer could have prevented.
+ *
+ * A HINT, never a gate. The turn still sends without the file; the agent still
+ * asks. This only removes the round-trip when the user would have known.
+ */
+
+import type { Draft } from "./outbound";
+
+/**
+ * What a picked tool still wants. Mirrors the generated `ChatTool.needs`, which
+ * is derived in Go from the tool's own required arguments.
+ */
+export type ToolNeed = "file" | "skill";
+
+/**
+ * The unmet need of the picks on this draft, or null when there is nothing to
+ * say.
+ *
+ * Reads the DRAFT alone. The need travels on the pick, so this needs no
+ * catalogue and no resolver — a second lookup here would be a second place that
+ * can disagree with the row the user actually clicked.
+ *
+ * A `file` need is ALWAYS unmet: this surface is text-only, so nothing on the
+ * draft can answer it. The hint is what tells the user to name the file in
+ * words rather than reach for an affordance that is not there.
+ *
+ * The FIRST unmet need wins. Two picks wanting two different things is a
+ * sentence, not a placeholder, and stacking them would produce a line nobody
+ * can read — the second returns as soon as the first is met.
+ */
+export function unmetNeed(draft: Draft): ToolNeed | null {
+  const picks = draft.pickedTools ?? [];
+  if (picks.length === 0) return null;
+
+  for (const pick of picks) {
+    if (pick.needs === undefined) continue;
+    return pick.needs;
+  }
+  return null;
+}