@inhuman.tools/harness-sdk 0.0.0-stage → 0.2.0

package/src/launch/continue-pick.ts

@@ -0,0 +1,28 @@
+/**
+ * `--continue` attach target. Glance has no path — a global orphan would
+ * be cwd-wrong, so no mapping still mints.
+ */
+import { unseatedConversationIds, type UnseatedConversationOverview } from "@inhuman.tools/harness-model";
+
+export type ContinuePick = {
+  readonly sessionId: string | undefined;
+  readonly staleKeyToClear: string | null;
+};
+
+export async function pickContinueSession(args: {
+  readonly key: string | null;
+  readonly termContinue: Record<string, string>;
+  readonly sessions: Record<string, UnseatedConversationOverview | undefined>;
+  readonly occupied: ReadonlySet<string>;
+  readonly sessionExists: (id: string) => Promise<boolean>;
+}): Promise<ContinuePick> {
+  const mapped = args.key == null ? undefined : args.termContinue[args.key];
+  if (mapped == null || mapped === "") return { sessionId: undefined, staleKeyToClear: null };
+  const exists = await args.sessionExists(mapped);
+  if (exists && !args.occupied.has(mapped)) return { sessionId: mapped, staleKeyToClear: null };
+  const staleKeyToClear = !exists && args.key != null ? args.key : null;
+  for (const id of unseatedConversationIds(args.sessions, args.occupied)) {
+    if (await args.sessionExists(id)) return { sessionId: id, staleKeyToClear };
+  }
+  return { sessionId: undefined, staleKeyToClear };
+}

package/src/launch/index.ts

@@ -0,0 +1,5 @@
+export * from "./continue-pick.js";
+export * from "./model-flags.js";
+export * from "./streams.js";
+export * from "./term-continue.js";
+export * from "./term-session-key.js";

package/src/launch/model-flags.ts

@@ -0,0 +1,273 @@
+/**
+ * `--connection` / `--model` resolve against live completion catalogs.
+ * Session apply is the same kv/set `/model` writes. Unsupported verbs crash
+ * before the daemon work they would otherwise start.
+ */
+import type { KernelRpc } from "../client.js";
+
+/** Same ceiling as scheme_repl inventory enumerate — do not dump OpenRouter. */
+const MODEL_LIST_MAX = 12;
+
+export type CliAgentFlags = {
+  readonly connection?: string;
+  readonly model?: string;
+};
+
+export type ResolvedAgent = {
+  readonly connection: string;
+  readonly model?: string;
+};
+
+export type ConnectionRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly driver: string;
+  readonly abilityClaim: readonly string[];
+  readonly enabled: boolean;
+};
+
+export type CompletionCatalogRow = {
+  readonly id: string;
+  readonly models: readonly string[];
+  readonly error: string;
+};
+
+export type ResolveAgentInput = {
+  readonly flags: CliAgentFlags;
+  readonly connections: readonly ConnectionRow[];
+  readonly catalogs?: readonly CompletionCatalogRow[];
+};
+
+export type ResolveAgentResult =
+  { readonly ok: true; readonly agent: ResolvedAgent } | { readonly ok: false; readonly error: string };
+
+export function hasCliAgentFlags(flags: CliAgentFlags): boolean {
+  return nonempty(flags.connection) != null || nonempty(flags.model) != null;
+}
+
+export function unsupportedAgentFlagsError(surface: string): string {
+  return [
+    `--model and --connection are only valid for a session (TUI, --continue, eval, -p, or a .scm program).`,
+    `\`${surface}\` does not select a model.`,
+  ].join("\n");
+}
+
+export function resolveAgent(input: ResolveAgentInput): ResolveAgentResult {
+  const wantedConnection = nonempty(input.flags.connection);
+  const wantedModel = nonempty(input.flags.model);
+  if (wantedConnection == null && wantedModel == null) {
+    return { ok: true, agent: { connection: "" } };
+  }
+
+  const completion = input.connections.filter((row) => row.abilityClaim.includes("completion"));
+  const enabledCompletion = completion.filter((row) => row.enabled);
+  if (wantedConnection != null) {
+    const row = input.connections.find((item) => item.id === wantedConnection);
+    if (row == null) {
+      return { ok: false, error: unknownConnectionError(wantedConnection, input.connections) };
+    }
+    if (!row.abilityClaim.includes("completion")) {
+      return {
+        ok: false,
+        error: [
+          `connection ${quote(wantedConnection)} is not a completion connection (${row.driver}).`,
+          completionLine(enabledCompletion),
+        ].join("\n"),
+      };
+    }
+    if (!row.enabled) {
+      return { ok: false, error: `connection ${quote(wantedConnection)} is disabled.` };
+    }
+  }
+
+  if (wantedModel == null) {
+    return { ok: true, agent: { connection: wantedConnection! } };
+  }
+  if (input.catalogs == null) {
+    return {
+      ok: true,
+      agent:
+        wantedConnection == null
+          ? { connection: "", model: wantedModel }
+          : { connection: wantedConnection, model: wantedModel },
+    };
+  }
+
+  const catalogs = input.catalogs;
+  if (wantedConnection != null) {
+    const catalog = catalogs.find((row) => row.id === wantedConnection);
+    if (catalog == null) {
+      return {
+        ok: false,
+        error: `connection ${quote(wantedConnection)} did not return a model catalog.`,
+      };
+    }
+    if (!catalog.models.includes(wantedModel)) {
+      return { ok: false, error: missingOnConnectionError(wantedConnection, wantedModel, catalog) };
+    }
+    return { ok: true, agent: { connection: wantedConnection, model: wantedModel } };
+  }
+
+  const hits = catalogs.filter((row) => row.models.includes(wantedModel));
+  if (hits.length === 1) {
+    return { ok: true, agent: { connection: hits[0]!.id, model: wantedModel } };
+  }
+  if (hits.length > 1) {
+    const names = hits.map((row) => row.id).sort();
+    return {
+      ok: false,
+      error: [
+        `model ${quote(wantedModel)} is available on multiple connections: ${names.join(", ")}.`,
+        `Pass --connection to pick one.`,
+      ].join("\n"),
+    };
+  }
+  return { ok: false, error: missingAcrossError(wantedModel, catalogs, enabledCompletion) };
+}
+
+export async function resolveCliAgent(rpc: KernelRpc, flags: CliAgentFlags): Promise<ResolveAgentResult> {
+  if (!hasCliAgentFlags(flags)) return { ok: true, agent: { connection: "" } };
+  const listed = await rpc.request("connect/list", {});
+  const connections = connectionRowsOf(listed);
+  const preview = resolveAgent({ flags, connections });
+  if (!preview.ok) return preview;
+  if (nonempty(flags.model) == null) return preview;
+  const wantedConnection = nonempty(flags.connection);
+  const catalogs = catalogRowsOf(
+    await rpc.request("connect/models", wantedConnection == null ? {} : { id: wantedConnection }),
+  );
+  return resolveAgent({ flags, connections, catalogs });
+}
+
+export async function applyResolvedAgent(
+  request: (method: string, params: unknown) => Promise<unknown>,
+  agent: ResolvedAgent,
+): Promise<void> {
+  const connection = nonempty(agent.connection);
+  const model = nonempty(agent.model);
+  if (connection == null && model == null) return;
+  if (connection != null) {
+    await request("kv/set", { key: "connection", value: connection });
+  }
+  if (model != null) {
+    await request("kv/set", { key: "model", value: model });
+  }
+}
+
+function connectionRowsOf(payload: unknown): ConnectionRow[] {
+  if (payload == null || typeof payload !== "object" || !("connections" in payload)) return [];
+  const raw = (payload as { connections: unknown }).connections;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((row) => {
+    if (row == null || typeof row !== "object") return [];
+    const rec = row as Record<string, unknown>;
+    const id = typeof rec.id === "string" ? rec.id : "";
+    if (id === "") return [];
+    const can = Array.isArray(rec.abilityClaim) ? rec.abilityClaim.map(String) : [];
+    return [
+      {
+        id,
+        name: typeof rec.name === "string" ? rec.name : id,
+        driver: typeof rec.driver === "string" ? rec.driver : "",
+        abilityClaim: can,
+        enabled: rec.enabled !== false,
+      },
+    ];
+  });
+}
+
+function catalogRowsOf(payload: unknown): CompletionCatalogRow[] {
+  if (payload == null || typeof payload !== "object" || !("connections" in payload)) return [];
+  const raw = (payload as { connections: unknown }).connections;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((row) => {
+    if (row == null || typeof row !== "object") return [];
+    const rec = row as Record<string, unknown>;
+    const id = typeof rec.id === "string" ? rec.id : "";
+    if (id === "") return [];
+    return [
+      {
+        id,
+        models: Array.isArray(rec.models) ? rec.models.map(String) : [],
+        error: typeof rec.error === "string" ? rec.error : "",
+      },
+    ];
+  });
+}
+
+function unknownConnectionError(id: string, connections: readonly ConnectionRow[]): string {
+  const completion = connections.filter((row) => row.abilityClaim.includes("completion") && row.enabled);
+  const mcp = connections.filter(
+    (row) => row.abilityClaim.includes("mcp") && !row.abilityClaim.includes("completion") && row.enabled,
+  );
+  const lines = [`unknown connection ${quote(id)}.`];
+  if (connections.length === 0) {
+    lines.push("No connections are configured.");
+    return lines.join("\n");
+  }
+  lines.push(completionLine(completion));
+  if (mcp.length > 0) {
+    lines.push(`MCP connections: ${ids(mcp)}.`);
+  }
+  return lines.join("\n");
+}
+
+function missingOnConnectionError(connection: string, model: string, catalog: CompletionCatalogRow): string {
+  const lines = [`model ${quote(model)} is not available on connection ${quote(connection)}.`];
+  if (catalog.models.length === 0) {
+    const status = catalog.error.trim() === "" ? "no models loaded" : catalog.error.trim();
+    lines.push(`Connection ${quote(connection)} has no models (${status}).`);
+    return lines.join("\n");
+  }
+  lines.push(`Models on ${connection}: ${formatModels(catalog.models)}.`);
+  return lines.join("\n");
+}
+
+function missingAcrossError(
+  model: string,
+  catalogs: readonly CompletionCatalogRow[],
+  completion: readonly ConnectionRow[],
+): string {
+  const lines = [`model ${quote(model)} was not found on any completion connection.`];
+  if (catalogs.length === 0) {
+    lines.push(completionLine(completion));
+    return lines.join("\n");
+  }
+  const searched = catalogs.map((row) => {
+    const models = row.models.length === 0 ? emptyCatalogNote(row) : formatModels(row.models);
+    return `${row.id} (${models})`;
+  });
+  lines.push(`Searched: ${searched.join("; ")}.`);
+  return lines.join("\n");
+}
+
+function emptyCatalogNote(row: CompletionCatalogRow): string {
+  return row.error.trim() === "" ? "no models loaded" : row.error.trim();
+}
+
+function completionLine(rows: readonly ConnectionRow[]): string {
+  if (rows.length === 0) return "No completion connections are configured.";
+  return `Completion connections: ${ids(rows)}.`;
+}
+
+function formatModels(models: readonly string[]): string {
+  if (models.length <= MODEL_LIST_MAX) return models.join(", ");
+  const shown = models.slice(0, MODEL_LIST_MAX);
+  return `${shown.join(", ")}, and ${models.length - shown.length} more`;
+}
+
+function ids(rows: readonly ConnectionRow[]): string {
+  return [...rows]
+    .map((row) => row.id)
+    .sort()
+    .join(", ");
+}
+
+function nonempty(value: string | undefined): string | undefined {
+  const trimmed = value?.trim() ?? "";
+  return trimmed === "" ? undefined : trimmed;
+}
+
+function quote(value: string): string {
+  return JSON.stringify(value);
+}

package/src/launch/streams.ts

@@ -0,0 +1,13 @@
+/**
+ * What a shell takes from its host: the process streams, plus the working
+ * directory when the caller is not the process (tests, embedders).
+ */
+export type Streams = {
+  readonly stdin: NodeJS.ReadStream;
+  readonly stdout: NodeJS.WriteStream;
+  readonly stderr: NodeJS.WriteStream;
+  readonly cwd?: string;
+};
+
+/** `Streams` plus the one-line error sink a shell reports through. Carries no command-parser types. */
+export type ShellStreams = Streams & { readonly writeErr: (error: unknown) => void };

package/src/launch/term-continue.ts

@@ -0,0 +1,31 @@
+/**
+ * Tab→session cookie. `scope !== ""` is not a continue target (workers).
+ */
+import type { SessionRoot } from "@inhuman.tools/harness-model";
+
+import { termSessionKey, type EnvBag } from "./term-session-key.js";
+
+export type KernelRequest = (method: string, params?: unknown) => Promise<unknown>;
+
+export function termContinuePayload(
+  env: EnvBag,
+  session: Pick<SessionRoot, "sessionId" | "agent">,
+): { key: string; sessionId: string } | null {
+  const key = termSessionKey(env);
+  if (key == null || session.agent.spec.recipeScope !== "") return null;
+  return { key, sessionId: session.sessionId };
+}
+
+export async function stampTermContinue(
+  request: KernelRequest,
+  env: EnvBag,
+  session: Pick<SessionRoot, "sessionId" | "agent">,
+): Promise<void> {
+  const payload = termContinuePayload(env, session);
+  if (payload == null) return;
+  await request("term-continue/set", payload);
+}
+
+export async function clearTermContinue(request: KernelRequest, key: string): Promise<void> {
+  await request("term-continue/clear", { key });
+}

package/src/launch/term-session-key.ts

@@ -0,0 +1,70 @@
+/**
+ * Tab/pane identity for `--continue`. Null if the process has no emulator
+ * cookie and no mux pane — miss is mint. Outer TERM_SESSION_ID is not
+ * identity under tmux: mix every live mux token.
+ */
+
+export type EnvBag = Record<string, string | undefined>;
+
+export function termSessionKey(env: EnvBag): string | null {
+  const parts: string[] = [];
+  const emu = emulatorCookie(env);
+  if (emu != null) parts.push(`emu=${emu}`);
+
+  const tmux = tmuxFields(env);
+  if (tmux != null) {
+    parts.push(`tmux_sock=${tmux.socket}`, `tmux_pid=${tmux.pid}`, `tmux_pane=${tmux.pane}`);
+  }
+  if (env.ZELLIJ_PANE_ID != null && env.ZELLIJ_PANE_ID !== "") {
+    parts.push(`zellij_pane=${env.ZELLIJ_PANE_ID}`);
+    if (env.ZELLIJ_SESSION_NAME) parts.push(`zellij_session=${env.ZELLIJ_SESSION_NAME}`);
+    if (env.ZELLIJ_SOCKET_DIR) parts.push(`zellij_sock=${env.ZELLIJ_SOCKET_DIR}`);
+  }
+  if (env.STY != null && env.STY !== "") {
+    parts.push(`screen=${env.STY}`, `screen_win=${env.WINDOW === undefined || env.WINDOW === "" ? "0" : env.WINDOW}`);
+  }
+
+  return parts.length === 0 ? null : parts.join(";");
+}
+
+function emulatorCookie(env: EnvBag): string | null {
+  const term = trim(env.TERM_SESSION_ID);
+  if (term != null) {
+    const colon = term.lastIndexOf(":");
+    return colon === -1 ? term : term.slice(colon + 1);
+  }
+  const wt = trim(env.WT_SESSION);
+  if (wt != null) return wt;
+  const wezPane = trim(env.WEZTERM_PANE);
+  const wezSock = trim(env.WEZTERM_UNIX_SOCKET);
+  if (wezPane != null && wezSock != null) return `wez:${wezSock}:${wezPane}`;
+  const kittyWin = trim(env.KITTY_WINDOW_ID);
+  const kittyPid = trim(env.KITTY_PID);
+  if (kittyWin != null && kittyPid != null) return `kitty:${kittyPid}:${kittyWin}`;
+  const konsole = trim(env.SHELL_SESSION_ID);
+  if (konsole != null) return konsole;
+  const gnome = trim(env.GNOME_TERMINAL_SCREEN);
+  if (gnome != null) return gnome;
+  return null;
+}
+
+function tmuxFields(env: EnvBag): { socket: string; pid: string; pane: string } | null {
+  const raw = trim(env.TMUX);
+  const pane = trim(env.TMUX_PANE);
+  if (raw == null || pane == null) return null;
+  const last = raw.lastIndexOf(",");
+  if (last <= 0) return null;
+  const rest = raw.slice(0, last);
+  const mid = rest.lastIndexOf(",");
+  if (mid <= 0) return null;
+  const socket = rest.slice(0, mid);
+  const pid = rest.slice(mid + 1);
+  if (socket === "" || pid === "") return null;
+  return { socket, pid, pane };
+}
+
+function trim(value: string | undefined): string | null {
+  if (value == null) return null;
+  const next = value.trim();
+  return next === "" ? null : next;
+}

package/src/observable-abort-signal.ts

@@ -0,0 +1,66 @@
+/**
+ * AbortSignal whose `aborted` and `reason` reads track in MobX.
+ * Native AbortSignal is an illegal constructor; instances come from
+ * AbortController / AbortSignal.abort|timeout|any, then {@link from}.
+ */
+import { action, createAtom } from "mobx";
+
+const observed = new WeakSet<AbortSignal>();
+
+const abortedDesc = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted");
+const reasonDesc = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "reason");
+
+function observe(signal: AbortSignal): void {
+  if (abortedDesc?.get == null || reasonDesc?.get == null) {
+    throw new Error("AbortSignal.aborted/reason are not getters");
+  }
+  const atom = createAtom("AbortSignal");
+  const abortedGet = abortedDesc.get;
+  const reasonGet = reasonDesc.get;
+  Object.defineProperty(signal, "aborted", {
+    configurable: true,
+    enumerable: true,
+    get(): boolean {
+      atom.reportObserved();
+      return abortedGet.call(signal);
+    },
+  });
+  Object.defineProperty(signal, "reason", {
+    configurable: true,
+    enumerable: false,
+    get(): unknown {
+      atom.reportObserved();
+      return reasonGet.call(signal);
+    },
+  });
+  if (!abortedGet.call(signal)) {
+    signal.addEventListener(
+      "abort",
+      action("abort", () => atom.reportChanged()),
+      { once: true },
+    );
+  }
+}
+
+export class ObservableAbortSignal extends AbortSignal {
+  static from(signal: AbortSignal): ObservableAbortSignal {
+    if (!observed.has(signal)) {
+      observe(signal);
+      observed.add(signal);
+    }
+    Object.setPrototypeOf(signal, ObservableAbortSignal.prototype);
+    return signal as ObservableAbortSignal;
+  }
+
+  static override abort(reason?: unknown): ObservableAbortSignal {
+    return ObservableAbortSignal.from(AbortSignal.abort(reason));
+  }
+
+  static override timeout(milliseconds: number): ObservableAbortSignal {
+    return ObservableAbortSignal.from(AbortSignal.timeout(milliseconds));
+  }
+
+  static override any(signals: AbortSignal[]): ObservableAbortSignal {
+    return ObservableAbortSignal.from(AbortSignal.any(signals));
+  }
+}

package/src/open-external.ts

@@ -0,0 +1,22 @@
+/**
+ * Fire-and-forget URL open. No display (SSH / container) is fine.
+ * WIN_START: cmd.exe `start "" url` — without the empty title the quoted
+ * URL becomes the window title and navigation is swallowed.
+ */
+import { spawn } from "node:child_process";
+
+export function openExternalUrl(url: string): void {
+  if (!/^https?:\/\//i.test(url.trim())) return;
+  try {
+    const target = url.trim();
+    if (process.platform === "darwin") {
+      spawn("open", [target], { detached: true, stdio: "ignore" }).unref();
+      return;
+    }
+    if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", "", target], { detached: true, stdio: "ignore" }).unref();
+      return;
+    }
+    spawn("xdg-open", [target], { detached: true, stdio: "ignore" }).unref();
+  } catch {}
+}

package/src/paths.ts

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+
+export const HARNESS_DIR = ".harness";
+
+export function daemonSocketPath(systemRoot: string): string {
+  return join(systemRoot, "daemon.sock");
+}
+
+/** One append-only log for host, worker, and daemon. */
+export function daemonLogPath(systemRoot: string): string {
+  return join(systemRoot, "harness.log");
+}
+
+export function projectHarnessDir(workspacePath: string): string {
+  return join(workspacePath, HARNESS_DIR);
+}
+
+export function projectSessionsDir(workspacePath: string): string {
+  return join(projectHarnessDir(workspacePath), "sessions");
+}

package/src/text/agent-cover.ts

@@ -0,0 +1,136 @@
+/**
+ * Ask-cover copy for agent send/ask/message. Rim is dim verb + bright
+ * `{model} {Spec} agent`. Prompt (and spec one-liner) ride the composer
+ * stack — same T-join as MCP options / shell command. Not a pin.
+ *
+ * Stdlib one-liners match the named-agent bot table
+ * (`packages/harness/src/server/system-plugins/named-agents/agent-stdlib.ts`). User recipes
+ * in `KernelRoot.bots` win on the same name.
+ */
+import { AgentCallJob, CallJob, AgentMessageJob, BotCallJob } from "@inhuman.tools/harness-model";
+
+/** Wire name. Ask stamps `voidLegal` false; send and bot-call stay send. */
+const AGENT_ASK_NAME = "agent__ask";
+
+/** CHANGE ONLY with packages/harness/src/server/system-plugins/named-agents/agent-stdlib.ts one-liners. */
+export const STDLIB_AGENT_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  "quick-search": "cite matching paths; agent/ask for map",
+  explore: "thorough read-only repo investigation",
+  "web-research": "search and extract the public web; cite sources",
+  implementer: "isolated change from a brief; agent/ask for no history",
+  "test-writer": "write and run tests for a named surface",
+  "security-auditor": "find exploitable issues; do not patch",
+  "design-writer": "write a design doc from a brief",
+  "design-reviewer": "stress-test a design; do not rewrite it",
+  reviewer: "persistent reviewer for this session; later requests continue the same conversation",
+};
+
+export type AgentCoverVerb = "ask" | "send" | "message";
+
+export type CoverAskContext = {
+  /** Session `kvs.model` — the worker inherits this at mint. */
+  readonly model?: string;
+};
+
+export function agentCoverVerb(work: CallJob | AgentMessageJob): AgentCoverVerb {
+  if (work instanceof AgentMessageJob) return "message";
+  return !work.voidLegal || work.name === AGENT_ASK_NAME || work.name === "bot__ask" ? "ask" : "send";
+}
+
+export function agentSpecKey(work: object | null | undefined): string {
+  if (work instanceof CallJob) {
+    const spec = stringArg(work.args, "spec")?.trim() ?? "";
+    if (spec !== "") return spec;
+    const bot = work instanceof BotCallJob ? work.botName.trim() || work.contributionBotName.trim() : "";
+    if (bot !== "") return bot;
+    const face = work instanceof AgentCallJob ? (work.faceName ?? "").trim() : "";
+    if (face !== "" && face !== "anonymous") return face;
+    return "";
+  }
+  if (work instanceof AgentMessageJob) {
+    return stringArg(work.args, "targetName")?.trim() ?? "";
+  }
+  return "";
+}
+
+/** `quick-search` → `Quick Search`. Sentinel `agent` is anonymous, not a spec. */
+export function titleAgentSpec(spec: string): string {
+  const raw = (typeof spec === "string" ? spec : "").trim();
+  if (raw === "" || raw === "agent") return "";
+  return raw
+    .split(/[-_]+/)
+    .filter((part) => part !== "")
+    .map((part) => (part.length <= 3 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()))
+    .join(" ");
+}
+
+export function formatAskAgentWho(spec: string): string {
+  const titled = titleAgentSpec(spec);
+  return titled === "" ? "agent" : `${titled} agent`;
+}
+
+/**
+ * Occupancy pin list. Oxford comma comes from `Intl.ListFormat` (`en-US`).
+ * Noun is English v1 — one `agent` / many `agents` on the whole list.
+ */
+export function formatWaitingForAgents(specs: readonly string[], locale = "en-US"): string {
+  const names = [...specs].map((spec) => titleAgentSpec(spec)).filter((name) => name !== "");
+  if (names.length === 0) {
+    if (specs.length === 0) return "";
+    return specs.length === 1 ? "waiting for an agent" : "waiting for agents";
+  }
+  const who = new Intl.ListFormat(locale, { style: "long", type: "conjunction" }).format(names);
+  const noun = names.length === 1 ? "agent" : "agents";
+  return `waiting for ${who} ${noun}`;
+}
+
+/**
+ * Isolated-cover rim. Markdown: furniture verb + `**bright**` who.
+ * Message does not spawn — no model. Empty spec is still `… agent`.
+ */
+export function formatAgentCoverAnnotation(opts: {
+  readonly verb: AgentCoverVerb;
+  readonly model: string;
+  readonly spec: string;
+}): string {
+  const model = opts.verb === "message" ? "" : opts.model.trim();
+  const spec = titleAgentSpec(opts.spec);
+  const who = [model, spec, "agent"].filter((part) => part !== "").join(" ");
+  return `${opts.verb} **${who}**`;
+}
+
+export function agentCoverPrompt(work: CallJob | AgentMessageJob): string {
+  return stringArg(work.args, "message") ?? "";
+}
+
+export function agentAskStackedBody(prompt: string, description: string): string {
+  const desc = description.trim();
+  if (desc === "") return prompt;
+  if (prompt === "") return desc;
+  return `${desc}\n\n${prompt}`;
+}
+
+export function agentExpandBlock(prompt: string, model: string): string {
+  const body = prompt.trim();
+  const who = model.trim();
+  if (who === "") return body;
+  if (body === "") return who;
+  return `${body}\n${who}`;
+}
+
+export function agentRecipeDescription(
+  bots: Readonly<Record<string, { readonly description?: string }>>,
+  spec: string,
+): string {
+  const key = spec.trim();
+  if (key === "") return "";
+  const fromFile = (bots[key]?.description ?? "").trim();
+  if (fromFile !== "") return fromFile;
+  return STDLIB_AGENT_DESCRIPTIONS[key] ?? "";
+}
+
+function stringArg(args: Readonly<Record<string, unknown>> | null, key: string): string | undefined {
+  if (args === null) return undefined;
+  const value = args[key];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}