@buyong/pi-devin 0.0.0-stage → 0.1.0

package/src/pi/sidekick-report.ts

@@ -0,0 +1,42 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Upper bound on the sidekick report the lead receives. The Devin CLI analysis records no sidekick report limit, so it is fixed here. */
+export const SIDEKICK_REPORT_TOKEN_LIMIT = 131_072;
+/** Pi's context estimate (`estimateTokens`) counts 4 characters per token, so the limit uses the same unit. */
+const CHARS_PER_TOKEN = 4;
+export const SIDEKICK_REPORT_CHAR_LIMIT = SIDEKICK_REPORT_TOKEN_LIMIT * CHARS_PER_TOKEN;
+
+export interface BoundedReport {
+  text: string;
+  /** Private temporary file with the complete report, set only when the report was cut and the file was written. */
+  fullReportPath?: string;
+}
+
+const isHighSurrogate = (code: number) => code >= 0xd800 && code <= 0xdbff;
+
+/** Keeps the beginning of the report within `maxChars` without splitting a surrogate pair. */
+export function truncateReport(text: string, maxChars = SIDEKICK_REPORT_CHAR_LIMIT): { text: string; isTruncated: boolean } {
+  if (text.length <= maxChars) return { text, isTruncated: false };
+  const end = isHighSurrogate(text.charCodeAt(maxChars - 1)) ? maxChars - 1 : maxChars;
+  return { text: text.slice(0, end), isTruncated: true };
+}
+
+/**
+ * Bounds the report before it reaches the lead and keeps the complete text in a private temporary file.
+ * Never rejects: background reports are delivered from a detached promise, so a failed write only changes the notice.
+ */
+export async function boundReport(text: string, maxChars = SIDEKICK_REPORT_CHAR_LIMIT): Promise<BoundedReport> {
+  const result = truncateReport(text, maxChars);
+  if (!result.isTruncated) return { text };
+  const notice = `[The sidekick report exceeded about ${SIDEKICK_REPORT_TOKEN_LIMIT} tokens and was cut.`;
+  try {
+    const directory = await mkdtemp(join(tmpdir(), "pi-devin-sidekick-report-"));
+    const fullReportPath = join(directory, "report.md");
+    await writeFile(fullReportPath, text, { encoding: "utf8", mode: 0o600 });
+    return { text: `${result.text}\n\n${notice} Full report: ${fullReportPath}]`, fullReportPath };
+  } catch (error) {
+    return { text: `${result.text}\n\n${notice} The full report could not be saved: ${error instanceof Error ? error.message : String(error)}]` };
+  }
+}

package/src/pi/sidekick-runtime.ts

@@ -0,0 +1,287 @@
+import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+
+const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+const STDERR_TAIL = 2048;
+const RECENT_TOOLS = 5;
+const KILL_GRACE_MS = 2000;
+
+/** This package root. Passed to the child Pi with `-e` so it uses the same extension copy as the lead. Pi loads a path only once. */
+export const PACKAGE_ROOT = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+
+export interface SidekickCommand { command: string; args: string[] }
+
+/** Launch settings of the sidekick child Pi. When they change, the process restarts before the next handoff. */
+export interface SidekickLaunch {
+  cwd: string;
+  /** Devin model ID of the exact variant (its catalog UID). */
+  modelID: string;
+  thinking?: string;
+  /** Without it, the child starts with `--no-session`. */
+  sessionFile?: string;
+  tools: readonly string[];
+  systemPrompt: string;
+}
+
+export interface HandoffProgress { toolCalls: number; recentTools: string[]; elapsedMs: number }
+export interface HandoffReport {
+  id: string;
+  status: "completed" | "aborted" | "error";
+  text: string;
+  toolCalls: number;
+  durationMs: number;
+  error?: string;
+}
+export interface Handoff { id: string; done: Promise<HandoffReport>; isSteer: boolean }
+
+export interface SidekickRuntimeOptions {
+  /** Command that runs Pi. Defaults to the same Node and Pi CLI as the lead. */
+  resolveCommand?: () => SidekickCommand;
+  spawn?: typeof nodeSpawn;
+  env?: NodeJS.ProcessEnv;
+  childEnv: Record<string, string>;
+  packageRoot?: string;
+  onProgress?: () => void;
+}
+
+function piPackageRoot(start: string): string | undefined {
+  let directory = dirname(start);
+  while (directory !== dirname(directory)) {
+    const manifest = join(directory, "package.json");
+    if (existsSync(manifest)) {
+      try { if ((JSON.parse(readFileSync(manifest, "utf8")) as { name?: unknown }).name === PI_PACKAGE) return directory; } catch { /* try the next parent */ }
+    }
+    directory = dirname(directory);
+  }
+  return undefined;
+}
+
+const EXTENSION_FLAGS = new Set(["-e", "--extension"]);
+const EXTENSION_SWITCHES = new Set(["--no-extensions", "-ne", "--no-mcp"]);
+
+/**
+ * Passes only the extension selection from the lead CLI arguments to the child, so tools from extensions loaded only with `-e` work for the sidekick too.
+ * Local paths become absolute paths from the lead's working directory. Source specifiers such as `builtin:` and `npm:` stay as they are.
+ */
+export function extensionArgs(argv: readonly string[], cwd: string): string[] {
+  const forwarded: string[] = [];
+  for (let index = 0; index < argv.length; index++) {
+    const value = argv[index];
+    if (EXTENSION_SWITCHES.has(value)) forwarded.push(value);
+    else if (EXTENSION_FLAGS.has(value) && index + 1 < argv.length) {
+      const target = argv[++index];
+      forwarded.push("-e", /^[a-z][a-z0-9+.-]*:/i.test(target) || isAbsolute(target) ? target : resolve(cwd, target));
+    }
+  }
+  return forwarded;
+}
+
+/**
+ * Starts the child with the same Node, exec options and Pi CLI as the lead Pi. The running CLI is preferred so extension selection arguments carry over;
+ * when Pi is embedded through the SDK, the installed Pi package's bin is used. Inspect options are not passed, to avoid port conflicts.
+ */
+export function resolvePiCommand(): SidekickCommand {
+  const candidates: { path: string; isRunningCLI: boolean }[] = [];
+  try { if (process.argv[1]) candidates.push({ path: realpathSync(process.argv[1]), isRunningCLI: true }); } catch { /* missing path */ }
+  try { candidates.push({ path: fileURLToPath(import.meta.resolve(PI_PACKAGE)), isRunningCLI: false }); } catch { /* cannot resolve */ }
+  for (const candidate of candidates) {
+    const root = piPackageRoot(candidate.path);
+    if (!root) continue;
+    const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { bin?: string | Record<string, string> };
+    const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.pi;
+    if (bin && existsSync(join(root, bin))) {
+      const execArgv = process.execArgv.filter((value) => !/^--(inspect|debug)/.test(value));
+      const forwarded = candidate.isRunningCLI ? extensionArgs(process.argv.slice(2), process.cwd()) : [];
+      return { command: process.execPath, args: [...execArgv, join(root, bin), ...forwarded] };
+    }
+  }
+  throw new Error("Could not find a Pi CLI to run the sidekick.");
+}
+
+export function launchArgs(launch: SidekickLaunch, packageRoot: string): string[] {
+  return [
+    "--mode", "rpc",
+    ...(launch.sessionFile ? ["--session", launch.sessionFile] : ["--no-session"]),
+    "--model", `devin/${launch.modelID}`,
+    ...(launch.thinking ? ["--thinking", launch.thinking] : []),
+    "--append-system-prompt", launch.systemPrompt,
+    "-e", packageRoot,
+    ...(launch.tools.length ? ["--tools", launch.tools.join(",")] : ["--no-tools"]),
+  ];
+}
+
+interface PendingHandoff {
+  id: string;
+  startedAt: number;
+  toolCalls: number;
+  recentTools: string[];
+  lastError?: string;
+  isAborted: boolean;
+  resolve(report: HandoffReport): void;
+  done: Promise<HandoffReport>;
+}
+
+/**
+ * Sidekick child Pi RPC process bound to one lead session. Started on the first handoff; keeps its context for the rest of the session.
+ * A handoff during a run adds instructions with `steer`; when the child run ends (`agent_settled`), the last assistant text is returned as the report.
+ */
+export class SidekickRuntime {
+  readonly launch: SidekickLaunch;
+  private readonly options: SidekickRuntimeOptions;
+  private child: ChildProcess | undefined;
+  private pending: PendingHandoff | undefined;
+  private stderrTail = "";
+  private readonly waiting = new Map<string, (text: string | undefined) => void>();
+
+  constructor(launch: SidekickLaunch, options: SidekickRuntimeOptions) {
+    this.launch = launch;
+    this.options = options;
+  }
+
+  isBusy(): boolean { return this.pending !== undefined; }
+  isAlive(): boolean { return this.child !== undefined && this.child.exitCode === null && this.child.signalCode === null; }
+
+  progress(): HandoffProgress | undefined {
+    const current = this.pending;
+    return current ? { toolCalls: current.toolCalls, recentTools: [...current.recentTools], elapsedMs: Date.now() - current.startedAt } : undefined;
+  }
+
+  handoff(message: string): Handoff {
+    if (this.pending) {
+      this.send({ type: "steer", message });
+      return { id: this.pending.id, done: this.pending.done, isSteer: true };
+    }
+    if (!this.isAlive()) this.start();
+    let resolve!: (report: HandoffReport) => void;
+    const done = new Promise<HandoffReport>((settle) => { resolve = settle; });
+    const id = randomUUID();
+    this.pending = { id, startedAt: Date.now(), toolCalls: 0, recentTools: [], isAborted: false, resolve, done };
+    try { this.send({ id, type: "prompt", message }); }
+    catch (error) { this.finish("error", "", error instanceof Error ? error.message : String(error)); }
+    return { id, done, isSteer: false };
+  }
+
+  abort(): void {
+    if (!this.pending) return;
+    this.pending.isAborted = true;
+    try { this.send({ type: "abort" }); } catch { this.finish("aborted", ""); }
+  }
+
+  close(): void {
+    const child = this.child;
+    this.child = undefined;
+    if (this.pending) this.finish("aborted", "", "Stopped the sidekick process.");
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    child.stdin?.end();
+    child.kill("SIGTERM");
+    const timer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL"); }, KILL_GRACE_MS);
+    timer.unref();
+  }
+
+  private start(): void {
+    const base = (this.options.resolveCommand ?? resolvePiCommand)();
+    const args = [...base.args, ...launchArgs(this.launch, this.options.packageRoot ?? PACKAGE_ROOT)];
+    const child = (this.options.spawn ?? nodeSpawn)(base.command, args, {
+      cwd: this.launch.cwd,
+      env: { ...(this.options.env ?? process.env), ...this.options.childEnv },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.child = child;
+    this.stderrTail = "";
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      buffer += decoder.write(chunk);
+      let index: number;
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        let line = buffer.slice(0, index);
+        buffer = buffer.slice(index + 1);
+        if (line.endsWith("\r")) line = line.slice(0, -1);
+        if (!line) continue;
+        let record: Record<string, unknown>;
+        try { record = JSON.parse(line) as Record<string, unknown>; } catch { continue; }
+        this.handle(record);
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer) => { this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL); });
+    child.on("error", (error) => { if (this.child === child) this.finish("error", "", error.message); });
+    child.on("close", () => {
+      if (this.child === child) this.child = undefined;
+      for (const resolve of this.waiting.values()) resolve(undefined);
+      this.waiting.clear();
+      if (this.pending) this.finish("error", "", this.stderrTail.trim() || "The sidekick process exited.");
+    });
+  }
+
+  private send(value: Record<string, unknown>): void {
+    if (!this.child?.stdin?.writable) throw new Error("Cannot write to the sidekick process.");
+    this.child.stdin.write(JSON.stringify(value) + "\n");
+  }
+
+  private request(type: string): Promise<string | undefined> {
+    const id = randomUUID();
+    return new Promise((resolve) => {
+      this.waiting.set(id, resolve);
+      try { this.send({ id, type }); } catch { this.waiting.delete(id); resolve(undefined); }
+    });
+  }
+
+  private handle(record: Record<string, unknown>): void {
+    const current = this.pending;
+    switch (record.type) {
+      case "response": {
+        const waiter = typeof record.id === "string" ? this.waiting.get(record.id) : undefined;
+        if (waiter) {
+          this.waiting.delete(record.id as string);
+          const data = record.data as { text?: unknown } | undefined;
+          waiter(typeof data?.text === "string" ? data.text : undefined);
+        } else if (current && record.command === "prompt" && record.success === false) {
+          this.finish("error", "", String(record.error ?? "The sidekick did not receive the instructions."));
+        }
+        return;
+      }
+      case "extension_ui_request":
+        // The sidekick never talks to the user. Dialogs that need an answer are returned as cancelled.
+        if (["select", "confirm", "input", "editor"].includes(String(record.method))) {
+          try { this.send({ type: "extension_ui_response", id: record.id, cancelled: true }); } catch { /* shutting down */ }
+        }
+        return;
+      case "tool_execution_start":
+        if (!current) return;
+        current.toolCalls++;
+        current.recentTools = [...current.recentTools, String(record.toolName ?? "tool")].slice(-RECENT_TOOLS);
+        this.options.onProgress?.();
+        return;
+      case "message_end": {
+        const message = record.message as { role?: unknown; stopReason?: unknown; errorMessage?: unknown } | undefined;
+        if (current && message?.role === "assistant") {
+          current.lastError = message.stopReason === "error" && typeof message.errorMessage === "string" ? message.errorMessage : undefined;
+        }
+        return;
+      }
+      case "agent_settled":
+        if (current) void this.complete(current, record.aborted === true);
+        return;
+    }
+  }
+
+  private async complete(current: PendingHandoff, isAborted: boolean): Promise<void> {
+    const text = await this.request("get_last_assistant_text");
+    if (this.pending !== current) return;
+    if (isAborted || current.isAborted) this.finish("aborted", text ?? "");
+    else if (current.lastError) this.finish("error", text ?? "", current.lastError);
+    else this.finish("completed", text ?? "");
+  }
+
+  private finish(status: HandoffReport["status"], text: string, error?: string): void {
+    const current = this.pending;
+    if (!current) return;
+    this.pending = undefined;
+    current.resolve({ id: current.id, status, text, toolCalls: current.toolCalls, durationMs: Date.now() - current.startedAt, ...(error ? { error } : {}) });
+    this.options.onProgress?.();
+  }
+}

package/src/pi/sidekick.ts

@@ -0,0 +1,190 @@
+import { join } from "node:path";
+import type { Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { DEVIN_API, type DevinModel } from "./models.ts";
+import type { DevinProvider } from "./provider.ts";
+import { boundReport, type BoundedReport } from "./sidekick-report.ts";
+import { SidekickRuntime, type Handoff, type HandoffReport, type SidekickLaunch, type SidekickRuntimeOptions } from "./sidekick-runtime.ts";
+
+export const SIDEKICK_TOOL_NAME = "devin_sidekick";
+/** Marker set on the child Pi started as the sidekick. The child's extension does not register Fusion again. */
+export const FUSION_CHILD_ENV = "PI_DEVIN_FUSION_CHILD";
+/** Custom message type that delivers a background handoff report to the lead. */
+export const SIDEKICK_REPORT_MESSAGE = "devin-sidekick-report";
+/** Appended by the provider to Fusion lead requests only, so a custom system prompt cannot drop it. */
+export const FUSION_LEAD_GUIDANCE = [
+  `Fusion mode: you are the lead. Plan, talk to the user, and decide; delegate hands-on exploration, implementation, and verification to the \`${SIDEKICK_TOOL_NAME}\` tool with clear context and done criteria.`,
+  `The sidekick is a separate agent in this workspace with the same tools, and it keeps its context across handoffs. \`${SIDEKICK_TOOL_NAME}\` waits for the report by default; pass \`block: false\` to keep working while it runs, and its report arrives later as a message. Calling \`${SIDEKICK_TOOL_NAME}\` while it is busy adds instructions to the running handoff.`,
+  "Review its report critically, decide the next step, and do not redo work it already reported. Present the combined result as your own work.",
+].join("\n");
+const SYSTEM_PROMPT = [
+  "You are the sidekick: a hands-on software engineer paired with a lead agent in the same workspace.",
+  "The lead sends you briefs with context and done criteria and may add instructions while you work. Do the work with the available tools: explore, implement, and verify.",
+  "You cannot talk to the user. When you finish, reply without tool calls with a concise report: what you did, how you verified it, and anything unresolved or risky.",
+  "Your conversation persists across briefs from the same lead session, so build on what you already know.",
+].join("\n");
+
+export interface SidekickDetails {
+  sidekickModel: string;
+  handoffId: string;
+  status: HandoffReport["status"] | "running" | "background";
+  toolCalls: number;
+  durationMs?: number;
+  isSteer: boolean;
+  /** Complete report saved when the text the lead received was cut. */
+  fullReportPath?: string;
+}
+
+export interface SidekickToolOptions {
+  /** Pi agent directory that holds sidekick session files. */
+  agentDir: () => string;
+  /** Lets tests replace how the child is started. */
+  runtime?: Omit<SidekickRuntimeOptions, "childEnv" | "onProgress">;
+}
+
+/** The host may copy model objects in its settings layer, so Fusion data is looked up by id in the provider's current list. */
+export function fusionOf(provider: Pick<DevinProvider, "getModels">, model: Model<any> | undefined): NonNullable<DevinModel["devin"]["fusion"]> | undefined {
+  if (model?.provider !== "devin" || model.api !== DEVIN_API) return undefined;
+  return (provider.getModels() as readonly DevinModel[]).find((candidate) => candidate.id === model.id)?.devin.fusion;
+}
+
+const launchKey = (launch: SidekickLaunch) => JSON.stringify([launch.cwd, launch.modelID, launch.thinking, launch.sessionFile, launch.tools]);
+const shortID = (id: string) => id.slice(0, 8);
+
+/** Report text for the lead. The sidekick's own text is bounded on every path: tool result, failure and background message. */
+async function reportText(report: HandoffReport): Promise<BoundedReport> {
+  const body = await boundReport(report.text.trim());
+  if (report.status === "completed") return { ...body, text: body.text || "(The sidekick finished without a report.)" };
+  const reason = report.error ?? (report.status === "aborted" ? "cancelled." : "failed.");
+  return { ...body, text: [`The sidekick task ${report.status === "aborted" ? "stopped" : "failed"}: ${reason}`, body.text].filter(Boolean).join("\n\n") };
+}
+
+const reportPath = (fullReportPath: string | undefined) => fullReportPath ? { fullReportPath } : {};
+
+/**
+ * The lead's `devin_sidekick` tool. The sidekick runs as one child Pi process per lead session and uses the lead's active tools.
+ * By default it waits for the report; with `block: false`, or when a user message arrives while waiting, it moves to the background and delivers the report once.
+ */
+export function createSidekickTool(pi: ExtensionAPI, provider: DevinProvider, options: SidekickToolOptions) {
+  const runtimes = new Map<string, SidekickRuntime>();
+  const scheduled = new Set<string>();
+  const waits = new Set<() => void>();
+  let progressListener: (() => void) | undefined;
+
+  const deliverLater = (handoff: Handoff, runtime: SidekickRuntime) => {
+    if (scheduled.has(handoff.id)) return;
+    scheduled.add(handoff.id);
+    void handoff.done.then(async (report) => {
+      // Handoffs cleaned up by a session switch or shutdown, or cancelled by the lead, are not reported.
+      const isCurrent = () => [...runtimes.values()].includes(runtime);
+      if (report.status === "aborted" || !isCurrent()) return;
+      const { text, fullReportPath } = await reportText(report);
+      if (!isCurrent()) return;
+      pi.sendMessage({
+        customType: SIDEKICK_REPORT_MESSAGE, display: true,
+        content: `Sidekick report for background handoff ${shortID(report.id)}:\n\n${text}`,
+        details: { sidekickModel: runtime.launch.modelID, handoffId: report.id, status: report.status, toolCalls: report.toolCalls, durationMs: report.durationMs, isSteer: false,
+          ...reportPath(fullReportPath) } satisfies SidekickDetails,
+      }, { deliverAs: "followUp", triggerTurn: true });
+    });
+  };
+
+  const definition: ToolDefinition = {
+    name: SIDEKICK_TOOL_NAME,
+    label: "Sidekick",
+    description: "Delegate hands-on work to your persistent sidekick, a separate coding agent that shares this workspace and your tools. "
+      + "Put the task context and done criteria in `message`. By default the call waits and returns the sidekick's report; "
+      + "set `block` to false to continue while it works, and the report arrives later as a message. "
+      + "Calling it while the sidekick is busy adds instructions to the running handoff.",
+    promptSnippet: "Delegate hands-on work to a persistent sidekick agent and get its report",
+    parameters: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "Brief for the sidekick: context, the task, and done criteria." },
+        block: { type: "boolean", description: "Wait for the report (default true). Use false to keep working while the sidekick runs." },
+      },
+      required: ["message"],
+      additionalProperties: false,
+    } as unknown as ToolDefinition["parameters"],
+    defaultActive: false,
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const fusion = fusionOf(provider, ctx.model);
+      if (!fusion) throw new Error("The sidekick is only available with the Devin Fusion model.");
+      const input = params as { message?: unknown; block?: unknown } | undefined;
+      const message = typeof input?.message === "string" ? input.message.trim() : "";
+      if (!message) throw new Error("A message for the sidekick is required.");
+      // The lead list hides exact UIDs covered by groups, so the level comes from the Fusion candidates.
+      const sidekickChoice = provider.getFusionChoices()?.sidekicks.find((item) => item.id === fusion.sidekickID);
+      if (!sidekickChoice) throw new Error("The sidekick model is not in the current Devin model list. Refresh the model list.");
+      const sessionId = ctx.sessionManager.getSessionId();
+      const launch: SidekickLaunch = {
+        cwd: ctx.cwd, modelID: fusion.sidekickID, thinking: sidekickChoice.level,
+        sessionFile: ctx.sessionManager.getSessionFile() ? join(options.agentDir(), "pi-devin", "sidekick", `${sessionId}.jsonl`) : undefined,
+        tools: pi.getActiveTools().filter((name) => name !== SIDEKICK_TOOL_NAME),
+        systemPrompt: SYSTEM_PROMPT,
+      };
+      let runtime = runtimes.get(sessionId);
+      // When the pair or tools change, only an idle process is restarted. Context continues through the same session file.
+      if (runtime && !runtime.isBusy() && launchKey(runtime.launch) !== launchKey(launch)) { runtime.close(); runtime = undefined; }
+      if (!runtime) {
+        runtime = new SidekickRuntime(launch, { ...options.runtime, childEnv: { [FUSION_CHILD_ENV]: "1" }, onProgress: () => progressListener?.() });
+        runtimes.set(sessionId, runtime);
+      }
+      const handoff = runtime.handoff(message);
+      const details = (status: SidekickDetails["status"], report?: HandoffReport): SidekickDetails => ({
+        sidekickModel: launch.modelID, handoffId: handoff.id, status, toolCalls: report?.toolCalls ?? runtime!.progress()?.toolCalls ?? 0,
+        ...(report ? { durationMs: report.durationMs } : {}), isSteer: handoff.isSteer,
+      });
+      const backgroundResult = (reason: string) => {
+        deliverLater(handoff, runtime!);
+        return { content: [{ type: "text" as const, text: `${reason} The report will arrive as a message. (handoff ${shortID(handoff.id)})` }], details: details("background") };
+      };
+      if (input?.block === false) {
+        return backgroundResult(handoff.isSteer ? "Added instructions to the running sidekick task." : "The sidekick started working in the background.");
+      }
+      let settle!: (outcome: "done" | "aborted" | "interrupted") => void;
+      const waiting = new Promise<"done" | "aborted" | "interrupted">((resolve) => { settle = resolve; });
+      const interrupt = () => settle("interrupted"), abort = () => settle("aborted");
+      waits.add(interrupt);
+      signal?.addEventListener("abort", abort, { once: true });
+      progressListener = () => {
+        const progress = runtime!.progress();
+        if (progress) onUpdate?.({ content: [{ type: "text", text: `sidekick: ${progress.toolCalls} tool calls${progress.recentTools.length ? ` · ${progress.recentTools.join(", ")}` : ""}` }], details: details("running") });
+      };
+      if (signal?.aborted) abort();
+      void handoff.done.then(() => settle("done"));
+      const outcome = await waiting.finally(() => {
+        progressListener = undefined;
+        waits.delete(interrupt);
+        signal?.removeEventListener("abort", abort);
+      });
+      if (outcome === "aborted") {
+        runtime.abort();
+        throw new Error("Cancelled the sidekick task.");
+      }
+      if (outcome === "interrupted") return backgroundResult("A user message arrived, so the sidekick task moved to the background.");
+      const report = await handoff.done;
+      const { text, fullReportPath } = await reportText(report);
+      if (report.status !== "completed") throw new Error(text);
+      return { content: [{ type: "text" as const, text }], details: { ...details(report.status, report), ...reportPath(fullReportPath) } };
+    },
+  };
+
+  return {
+    definition,
+    /** On user input, a waiting handoff moves to the background. Input sent by extensions does not count. */
+    onInput(source: string): void {
+      if (source === "extension") return;
+      for (const interrupt of [...waits]) interrupt();
+    },
+    /** Cleans up the sidekick of a different lead session. */
+    onSessionStart(sessionId: string): void {
+      for (const [id, runtime] of runtimes) if (id !== sessionId) { runtime.close(); runtimes.delete(id); }
+    },
+    reset(): void {
+      for (const runtime of runtimes.values()) runtime.close();
+      runtimes.clear(); scheduled.clear();
+    },
+  };
+}

package/src/pi/stream.ts

@@ -0,0 +1,124 @@
+import { createAssistantMessageEventStream, type AssistantMessage, type Model, type ToolCall } from "@earendil-works/pi-ai";
+import type { ChatAccumulator } from "../core/inference/chat.ts";
+import type { ChatMessage, ChatResult, JsonObject } from "../core/types.ts";
+import { attachReplayMetadata } from "./messages.ts";
+import { DEVIN_API } from "./models.ts";
+
+export class DevinResponseStream {
+  readonly stream = createAssistantMessageEventStream();
+  readonly message: AssistantMessage;
+  private active?: { type: "text" | "thinking"; index: number };
+  private tools = new Map<string, { index: number; characters: number; hasEnded: boolean }>();
+  private hasTerminated = false;
+  private usageModelUid?: string;
+  private hasUsageReported = false;
+  constructor(model: Model<typeof DEVIN_API>, requestedUID: string) {
+    this.message = {
+      role: "assistant", api: DEVIN_API, provider: "devin", model: model.id, providerThinkingLevel: requestedUID,
+      content: [], stopReason: "pending", timestamp: Date.now(),
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+    };
+    this.stream.push({ type: "start", partial: this.message });
+  }
+  private closeText(): void {
+    if (!this.active) return;
+    const block = this.message.content[this.active.index];
+    if (block.type === "text") this.stream.push({ type: "text_end", contentIndex: this.active.index, content: block.text, partial: this.message });
+    else if (block.type === "thinking") this.stream.push({ type: "thinking_end", contentIndex: this.active.index, content: block.thinking, partial: this.message });
+    this.active = undefined;
+  }
+  private text(type: "text" | "thinking", delta: string, redacted = false): void {
+    if (!this.active || this.active.type !== type) {
+      this.closeText();
+      const index = this.message.content.length;
+      this.message.content.push(type === "text" ? { type, text: "" } : { type, thinking: "", ...(redacted ? { redacted: true } : {}) });
+      this.active = { type, index };
+      this.stream.push({ type: type === "text" ? "text_start" : "thinking_start", contentIndex: index, partial: this.message });
+    }
+    const block = this.message.content[this.active.index];
+    if (!delta) return;
+    if (block.type === "text") {
+      block.text += delta;
+      this.stream.push({ type: "text_delta", contentIndex: this.active.index, delta, partial: this.message });
+    } else if (block.type === "thinking") {
+      block.thinking += delta;
+      this.stream.push({ type: "thinking_delta", contentIndex: this.active.index, delta, partial: this.message });
+    }
+  }
+  accept(data: JsonObject, accumulator: ChatAccumulator): void {
+    if (this.hasTerminated) throw new Error("Cannot add a delta to a finished Pi response.");
+    if (accumulator.message.thinkingRedacted) {
+      for (const block of this.message.content) if (block.type === "thinking") { block.thinking = ""; block.redacted = true; }
+      if (!this.message.content.some((block) => block.type === "thinking")) this.text("thinking", "", true);
+    } else if (typeof data.deltaThinking === "string" && data.deltaThinking) this.text("thinking", data.deltaThinking);
+    if (typeof data.deltaText === "string" && data.deltaText) this.text("text", data.deltaText);
+    for (const call of accumulator.calls.values()) {
+      let state = this.tools.get(call.id);
+      if (!state) {
+        this.closeText();
+        const index = this.message.content.length;
+        this.message.content.push({ type: "toolCall", id: call.id, name: "", arguments: {} });
+        state = { index, characters: 0, hasEnded: false }; this.tools.set(call.id, state);
+        this.stream.push({ type: "toolcall_start", contentIndex: index, partial: this.message });
+      }
+      const block = this.message.content[state.index] as ToolCall;
+      block.name = call.name;
+      try { const value = JSON.parse(call.argumentsJson); if (value && typeof value === "object" && !Array.isArray(value)) block.arguments = value; } catch {}
+      const delta = call.argumentsJson.slice(state.characters);
+      state.characters = call.argumentsJson.length;
+      if (delta) this.stream.push({ type: "toolcall_delta", contentIndex: state.index, delta, partial: this.message });
+    }
+    if (accumulator.message.messageId) this.message.responseId = accumulator.message.messageId;
+    if (typeof data.actualModelUid === "string") this.message.responseModel = data.actualModelUid;
+    if (data.usage && typeof data.usage === "object") {
+      const usage = data.usage as JsonObject;
+      if (typeof usage.modelUid === "string") this.usageModelUid = usage.modelUid;
+      if (["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"].some((key) => usage[key] !== undefined)) this.hasUsageReported = true;
+    }
+    this.message.usage = { ...accumulator.usage, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+  }
+  private closeContent(): void {
+    this.closeText();
+    for (const state of this.tools.values()) if (!state.hasEnded) {
+      state.hasEnded = true;
+      this.stream.push({ type: "toolcall_end", contentIndex: state.index, toolCall: this.message.content[state.index] as ToolCall, partial: this.message });
+    }
+  }
+  private provenance(native: ChatMessage, usageReported: boolean): void {
+    this.message.providerThinkingLevel = native.modelUid ?? this.message.providerThinkingLevel;
+    attachReplayMetadata(this.message, native);
+    this.message.diagnostics = [{ type: "devin_provenance", timestamp: Date.now(), details: {
+      requestedUID: this.message.providerThinkingLevel ?? "", ...(this.message.responseModel ? { responseUID: this.message.responseModel } : {}),
+      ...(this.usageModelUid ? { usageUID: this.usageModelUid } : {}), costsUnknown: true, usageReported,
+    } }];
+  }
+  redact(): void {
+    for (const block of this.message.content) {
+      if (block.type === "text") block.text = "";
+      else if (block.type === "thinking") { block.thinking = ""; block.redacted = true; }
+      else block.arguments = {};
+    }
+    this.closeContent(); this.message.content = []; this.tools.clear();
+  }
+  finish(result: ChatResult): void {
+    if (this.hasTerminated) return;
+    if (!this.message.content.length && (result.message.signature || result.message.geminiThoughtSignature || result.message.outputId)) this.text("text", "");
+    this.provenance(result.message, result.usageReported);
+    this.closeContent();
+    this.hasTerminated = true;
+    this.message.rawStopReason = result.stopReason;
+    this.message.stopReason = result.stopReason === "STOP_REASON_FUNCTION_CALL" ? "toolUse" : result.stopReason === "STOP_REASON_MAX_TOKENS" ? "length" : "stop";
+    this.stream.push({ type: "done", reason: this.message.stopReason, message: this.message });
+    this.stream.end(this.message);
+  }
+  fail(errorMessage: string, isAborted: boolean, native?: ChatMessage): void {
+    if (this.hasTerminated) return;
+    if (native) this.provenance(native, this.hasUsageReported);
+    this.closeContent();
+    this.hasTerminated = true;
+    this.message.stopReason = isAborted ? "aborted" : "error";
+    this.message.errorMessage = errorMessage;
+    this.stream.push({ type: "error", reason: this.message.stopReason, error: this.message });
+    this.stream.end(this.message);
+  }
+}