@signalridge/pi-subagents 1.4.0 → 1.6.1

package/src/mention-clone.ts

@@ -0,0 +1,196 @@
+/**
+ * mention-clone.ts — start a mentioned agent through a clone of this
+ * conversation, without putting anything in the chat.
+ *
+ * Claude Code routes `@agent-<type>` through the main model: the mention
+ * becomes a `<system-reminder>` appended to the prompt and the model makes the
+ * tool call (see `agentMentionReminder`). That buys the spawned agent a prompt
+ * written with conversation context, and costs a visible turn — the model's
+ * reasoning and its tool block land in the transcript, for a decision the user
+ * already made when they typed the handle.
+ *
+ * So the turn happens somewhere else. The conversation is cloned into a
+ * throwaway in-memory session — same messages, same system prompt, same model —
+ * and that copy takes the turn off-screen. A literal clone: the session's own
+ * entries, projected by pi's own `sessionEntryToContextMessages`, not
+ * `inherit_context`'s text rendering of them.
+ *
+ * Cloned from memory rather than from the session file, which cannot be relied
+ * on: `SessionManager._persist` withholds every write until the first assistant
+ * message lands, so a fork taken before then reads an empty file and throws.
+ * `buildSessionContext()` has no such timing, and is compaction-aware — it walks
+ * the leaf path and substitutes the summary for entries folded into it, so a
+ * long conversation clones as what the main model is actually working from. A
+ * conversation with nothing in it yet clones to nothing in it yet, which is the
+ * correct answer rather than a failure.
+ *
+ * It is also the oldest of the equivalent Pi APIs — `buildContextEntries` on
+ * ReadonlySessionManager and the `sessionEntryToContextMessages` export both
+ * arrived in 0.80.5 — where this one has been exported unchanged from before
+ * the declared peer floor, and is the same code path (`byId` is only an index
+ * cache, so passing it or not cannot change the result). Keeping the floor
+ * honest costs nothing here: see the `compat-floor-pi` job.
+ *
+ * Its `thinkingLevel` is NOT used, and is the one place the newer API would be
+ * better. `getSessionContextSettings` starts at "off" and moves only on an
+ * explicit `thinking_level_change` entry, so a session where nobody ran
+ * `/think` reports "off" rather than the level it is really using. Omitting the
+ * field instead lets `createAgentSession` resolve it from settings, which is
+ * that real level.
+ *
+ * Three details make the spawn belong to the real session rather than the
+ * clone:
+ *
+ *   - the clone is handed the *registered* `Agent` tool, whose handler closes
+ *     over the main activation, so it spawns top-level: widget, fleet row,
+ *     handle, completion notification, all as if the main model had called it;
+ *   - that tool is re-bound to the main `ExtensionContext`, because the handler
+ *     reads `cwd`, `model` and `sessionManager.getSessionId()` off it to place
+ *     the transcript and the `rootSessionId`. The clone's own context would
+ *     file both under the throwaway fork;
+ *   - it is called with no tool-call id. The clone's turn produces one, but the
+ *     real session never issued it, and a `<tool-use-id>` pointing at nothing
+ *     is exactly the bug the mention-resume path had to fix;
+ *   - and it is forced into the background. A foreground agent returns its
+ *     answer as the tool result and is marked `resultConsumed` so no completion
+ *     notification is sent — correct when the caller is the real conversation,
+ *     silent loss when the caller is a fork about to be discarded. Background
+ *     delivery is the only route from a mention back to the main model.
+ *
+ * The clone gets one tool and one job. It cannot read, write or run anything —
+ * an invisible turn with the full toolset could do invisible work.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  buildSessionContext,
+  createAgentSession,
+  type ExtensionContext,
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { runInChildSessionContext } from "./child-context.js";
+import { agentMentionReminder } from "./mention.js";
+import type { SubagentType, ThinkingLevel } from "./types.js";
+
+export interface MentionCloneOptions {
+  /** The MAIN session's context — what the spawn is attributed to, and the
+   * source of both the conversation and the live system prompt. */
+  ctx: ExtensionContext;
+  /** Agent type the handle resolved to. */
+  type: SubagentType;
+  /** What the user typed after the handle. */
+  message: string;
+  /** The registered `Agent` tool, reused so the spawn is an ordinary one. */
+  agentTool: ToolDefinition;
+}
+
+export interface MentionCloneResult {
+  /** True once the clone actually called `Agent`. */
+  spawned: boolean;
+  /** Why not, when it didn't. Absent on success. */
+  error?: string;
+}
+
+/**
+ * Fork the conversation, let the copy make the tool call, throw the copy away.
+ * Never rejects: a clone that cannot run is reported so the caller can fall
+ * back to starting the agent directly.
+ */
+export async function runMentionClone(opts: MentionCloneOptions): Promise<MentionCloneResult> {
+  const { ctx, type, message, agentTool } = opts;
+
+  let spawned = false;
+  const cloneAgentTool: ToolDefinition = {
+    ...agentTool,
+    execute: (_cloneToolCallId, params, signal, onUpdate, _cloneCtx) => {
+      // One spawn per mention. The clone has a single tool and every reason to
+      // stop after using it, but a model that decides to "also" launch a second
+      // agent would do it where nobody can see and nobody asked.
+      if (spawned) {
+        return Promise.resolve({
+          content: [{ type: "text" as const, text: "Already started an agent for this mention. Stop here." }],
+          details: undefined,
+          isError: true,
+        });
+      }
+      spawned = true;
+      // undefined tool-call id + the main ctx: see the header. Background is
+      // forced rather than left to the clone: `run_in_background` defaults to
+      // false, and a foreground agent answers through its TOOL RESULT — which
+      // here is delivered into a session that is disposed moments later, so the
+      // agent would run, appear in the widget and the fleet, and reach nobody.
+      return agentTool.execute(
+        undefined as never,
+        { ...(params as Record<string, unknown>), run_in_background: true } as typeof params,
+        signal,
+        onUpdate,
+        ctx,
+      );
+    },
+  };
+
+  let session: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
+  try {
+    // Pi 0.80.8 moved createAgentSession from modelRegistry to modelRuntime;
+    // agent-runner.ts carries the same shim for the same reason — pass both so
+    // the clone keeps the parent's providers across the supported range.
+    const parentModelRuntime = (ctx.modelRegistry as unknown as { runtime?: unknown }).runtime;
+    // The conversation as the main session resolves it: compaction applied,
+    // branch summaries substituted.
+    const conversation = buildSessionContext(
+      ctx.sessionManager.getEntries(),
+      ctx.sessionManager.getLeafId(),
+    );
+    // Pi 0.82.0 added this; below it the field is absent and the clone takes
+    // the settings level instead, which is what a session that never ran
+    // `/think` is on anyway. Same shim shape as `modelRuntime` below.
+    const thinkingLevel = (ctx as { thinkingLevel?: ThinkingLevel }).thinkingLevel;
+    const created = await runInChildSessionContext(() =>
+      createAgentSession({
+        cwd: ctx.cwd,
+        // Nothing about the copy is worth persisting, and an in-memory manager
+        // is also what keeps the real session untouched.
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model: ctx.model as Model<never> | undefined,
+        ...(thinkingLevel && { thinkingLevel }),
+        modelRegistry: ctx.modelRegistry,
+        ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime as never }),
+        // An allowlist naming exactly the clone's own tool. NOT `noTools:
+        // "all"`, whose doc comment ("start with no tools enabled") reads like
+        // it spares custom tools and does not: it resolves to an EMPTY
+        // allowlist, and `isAllowedTool` then drops every tool from the
+        // registry — the custom one included. The clone would be prompted with
+        // nothing to call, answer in prose, and every mention would fall
+        // through to the direct start with a warning. Same idiom as
+        // agent-runner's `tools: sessionTools` beside its nested `customTools`.
+        tools: [cloneAgentTool.name],
+        customTools: [cloneAgentTool],
+      } as Parameters<typeof createAgentSession>[0]),
+    );
+    session = created.session;
+
+    // The clone rebuilds a system prompt from cwd and agentDir, which is close
+    // but not the live one — extensions contribute to it per turn. Copy the
+    // real thing, so the copy reasons under the instructions the user's model
+    // is actually working under.
+    const systemPrompt = ctx.getSystemPrompt?.();
+    if (systemPrompt) session.agent.state.systemPrompt = systemPrompt;
+
+    // The conversation itself. Pushed rather than assigned so the array the
+    // session was built around stays the one it goes on using.
+    session.agent.state.messages.push(...conversation.messages);
+
+    // User text first, reminder after — the order Claude Code's attachment
+    // renderer produces, where the reminder trails the message it is about.
+    await session.prompt(`${message}\n\n${agentMentionReminder(type)}`);
+  } catch (err) {
+    return { spawned, error: err instanceof Error ? err.message : String(err) };
+  } finally {
+    session?.dispose?.();
+  }
+
+  return spawned
+    ? { spawned: true }
+    : { spawned: false, error: "the conversation clone did not start it" };
+}

package/src/mention.ts

@@ -0,0 +1,141 @@
+/**
+ * mention.ts — the `@handle` grammar for messaging a subagent from the prompt.
+ *
+ * Claude Code lets you type `@code-review take another look` at the prompt and
+ * routes the message to that agent instead of the main model. Its grammar is
+ * reproduced here so the two behave identically:
+ *
+ *   - suggestions fire on `@` at the start of the input or after whitespace,
+ *     followed by `[\w-]*` (so `@src/foo.ts` is a file, never an agent);
+ *   - a send is recognized only at the START of the input, and only with a
+ *     non-empty message after the handle. That is why a bare `@code-review`
+ *     goes to the main model rather than anywhere near the agent.
+ *
+ * A record's own identity is a UUID plus a deliberately non-unique description,
+ * neither of which is typeable, so the handle is derived from the agent type.
+ * Colliding handles are numbered (`explore`, `explore-2`), which is also what
+ * Claude Code's `allocateName` does — it recycles a name only once the task
+ * behind it is gone. Its SendMessage prompt describes the *registry* as
+ * latest-wins, which is a different thing and not how names are allocated.
+ */
+
+/**
+ * Suggestion trigger: `@` at a token boundary plus the partial handle typed so
+ * far. Ported from Claude Code, including the CJK sentence-ending punctuation
+ * it accepts as a boundary.
+ */
+export const MENTION_TRIGGER = /(^|[\s。、？！])@([\w-]*)$/;
+
+/** Send grammar: leading `@handle`, then a non-empty message. */
+const MENTION_SEND = /^@([\w-]+)\s+([\s\S]+)$/;
+
+/**
+ * Upper bound on a handle, matching Claude Code's `dSS`. Nothing here generates
+ * a name this long, but an agent type or a model-supplied name can be arbitrary
+ * text, and an unbounded handle would wrap the suggestion popup.
+ */
+const MAX_HANDLE_LENGTH = 64;
+
+/**
+ * Handles that address something other than a subagent, and so can never be
+ * allocated to one. Claude Code reserves exactly this name (`Vq = "main"`),
+ * refusing it at spawn and routing it to the main conversation instead.
+ */
+const RESERVED_HANDLES: ReadonlySet<string> = new Set(["main"]);
+
+/** Whether `@handle` names the main conversation rather than any subagent. */
+export function isReservedHandle(handle: string): boolean {
+  return RESERVED_HANDLES.has(handle.toLowerCase());
+}
+
+/** Slug of an agent type or name, restricted to the `[\w-]` the grammar allows. */
+export function handleBase(type: string): string {
+  const slug = type.toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_HANDLE_LENGTH)
+    // The slice can land mid-run and leave the trailing hyphen back.
+    .replace(/-+$/, "");
+  return slug || "agent";
+}
+
+/**
+ * `base`, else `base-2`, `base-3`, … — the first form that is neither `taken`
+ * nor reserved. Callers pass one shared `taken` set covering type-derived
+ * handles and model-supplied aliases alike, so the two can never collide.
+ */
+export function assignHandle(base: string, taken: ReadonlySet<string>): string {
+  let candidate = base;
+  let n = 1;
+  while (taken.has(candidate) || RESERVED_HANDLES.has(candidate)) {
+    n++;
+    candidate = `${base}-${n}`;
+  }
+  return candidate;
+}
+
+/**
+ * Map a typed handle back to a registered agent type, so `@explore fix it`
+ * reaches the Explore agent even when no instance has ever run. `handleBase` is
+ * the single source of truth in both directions, so a type is addressable by
+ * exactly the handle its instances would be given.
+ */
+export function resolveHandleToType(handle: string, types: readonly string[]): string | undefined {
+  const wanted = handle.toLowerCase();
+  // A type slugging to a reserved name is unaddressable rather than shadowing
+  // it — `assignHandle` refuses that name too, so its instances never hold one.
+  if (RESERVED_HANDLES.has(wanted)) return undefined;
+  return types.find(type => handleBase(type) === wanted);
+}
+
+/**
+ * Claude Code documents `@agent-<name>` as the form you type by hand when the
+ * picker isn't involved. Accepted here as an exact synonym: the caller tries the
+ * handle as written first, so an agent genuinely called `agent-foo` still wins
+ * over `@agent-` + `foo`, and only falls back to this when that finds nothing.
+ * Returns undefined when the prefix is absent or is the whole handle.
+ */
+export function stripAgentPrefix(handle: string): string | undefined {
+  const rest = /^agent-(.+)$/i.exec(handle)?.[1];
+  return rest || undefined;
+}
+
+/**
+ * A spawn needs the short description every agent surface renders. A mention
+ * carries no separate label, so the message itself becomes one: first line,
+ * whitespace collapsed, clipped to roughly the 3-5 words the Agent tool asks of
+ * the model.
+ */
+export function describeMention(message: string): string {
+  const oneLine = message.split("\n", 1)[0].replace(/\s+/g, " ").trim();
+  return oneLine.length > 40 ? `${oneLine.slice(0, 39).trimEnd()}…` : oneLine;
+}
+
+/**
+ * What Claude Code sends the main model when a mention names an agent it could
+ * start. Its `@agent-<type>` mention is not a spawn at all: it becomes an
+ * `agent_mention` attachment, which renders to a synthetic `isMeta` user
+ * message placed after the user's own untouched text — no tool forcing, no
+ * allowed-tools narrowing, and the Task tool is not even named. The model reads
+ * this and calls the tool itself.
+ *
+ * Ported verbatim from the 2.1.233 bundle's attachment renderer, trailing space
+ * before the closing newline included, so the wording the model was trained
+ * against is the wording it gets. The one substitution is ours: pi's equivalent
+ * of Task is the `Agent` tool, and the agent listing that teaches valid
+ * `subagent_type` values is the tool spec rather than a separate attachment.
+ */
+export function agentMentionReminder(type: string): string {
+  return `<system-reminder>\nThe user has expressed a desire to invoke the agent "${type}". Please invoke the agent appropriately, passing in the required context to it. \n</system-reminder>`;
+}
+
+/**
+ * Split `@handle message` into its parts, or null when the text isn't a send —
+ * a bare handle, a leading file path, or a mention that isn't at the start.
+ */
+export function parseMention(text: string): { handle: string; message: string } | null {
+  const match = MENTION_SEND.exec(text);
+  if (!match) return null;
+  const message = match[2].trim();
+  return message ? { handle: match[1], message } : null;
+}

package/src/output-file.ts

@@ -68,6 +68,22 @@ export function writeInitialEntry(path: string, agentId: string, prompt: string,
   writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
 }
 
+/**
+ * Ensure a transcript file exists without disturbing what is already in it.
+ *
+ * A resume reuses the agent's existing transcript (same deterministic path), so
+ * it must never call `writeInitialEntry` — that truncates, discarding turns the
+ * completion notification still points the user at, and any history the session
+ * has since compacted away is gone for good (#145). Appending nothing creates
+ * the file when this is the agent's first transcript and is a no-op when it is
+ * not.
+ */
+export function ensureOutputFile(path: string): void {
+  try {
+    appendFileSync(path, "", "utf-8");
+  } catch { /* ignore — streaming writes are best-effort too */ }
+}
+
 /**
  * Subscribe to session events and flush new messages to the output file on each turn_end.
  * Returns a cleanup function that does a final flush and unsubscribes.
@@ -77,8 +93,14 @@ export function streamToOutputFile(
   path: string,
   agentId: string,
   cwd: string,
+  startIndex?: number,
 ): () => void {
-  let writtenCount = 1; // initial user prompt already written
+  // Index of the first message this stream is responsible for. A spawn writes
+  // messages[0] as the initial prompt entry, so it starts at 1. A resume hands
+  // in the session's length as of just before the run: the session already
+  // holds every prior turn, and re-emitting those would duplicate history that
+  // is already in the file.
+  let writtenCount = startIndex ?? 1;
 
   const flush = () => {
     const messages = session.messages;