@buyong/pi-devin 0.1.5 → 0.1.6

package/src/pi/features/settings/types.ts

@@ -0,0 +1,36 @@
+import type { Effect } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import type { FusionSelection } from "../catalog/types.ts";
+import type { AccountUsage } from "../usage/types.ts";
+
+/** Display settings toggled by `/devin`. Both default to off and never change how models are used or requested. */
+export interface DevinPreferences {
+  /** Lists only the models that have a variant the catalog marks as recommended. */
+  recommendedOnly: boolean;
+  /** Shows quota and session usage in the TUI status line. */
+  showUsageStatus: boolean;
+}
+
+/** Global store for the lead and sidekick chosen with `/devin-fusion`. Every session uses the same value. */
+export interface FusionSettingsShape {
+  /** Never fails: a missing or unreadable store reads as no saved pair. */
+  readonly read: Effect.Effect<FusionSelection | undefined>;
+  write(selection: FusionSelection): Effect.Effect<void, DevinError>;
+}
+
+export interface DisplaySettingsShape {
+  /** Never fails: a missing or unreadable store reads as the defaults. */
+  readonly read: Effect.Effect<DevinPreferences>;
+  write(preferences: DevinPreferences): Effect.Effect<void, DevinError>;
+}
+
+/**
+ * Last account quota received by any Pi process that shares the agent directory, such as subagents and the Fusion sidekick.
+ * Keyed by the credential scope hash. No token, account ID or raw response is stored.
+ */
+export interface UsageStoreShape {
+  /** Never fails: a missing or unreadable record reads as none. */
+  read(scope: string): Effect.Effect<AccountUsage | undefined>;
+  /** Replaces the record unless the stored one for the same scope was fetched later. */
+  write(scope: string, usage: AccountUsage): Effect.Effect<void, DevinError>;
+}

package/src/pi/features/sidekick/child.ts

@@ -0,0 +1,228 @@
+import type { ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { Deferred, Effect, Exit } from "effect";
+import { toDevinError, type DevinError } from "../../../core/errors.ts";
+import { launchArgs } from "./command.ts";
+import type { Handoff, HandoffProgress, HandoffReport, SidekickLauncherShape, SidekickLaunch } from "./types.ts";
+
+const STDERR_TAIL = 2048;
+const RECENT_TOOLS = 5;
+const KILL_GRACE_MS = 2000;
+
+export interface SidekickChildOptions {
+  launcher: SidekickLauncherShape;
+  childEnv: Record<string, string>;
+  onProgress?: () => void;
+  /** Runs work that child process events start, in a fiber its owner tracks. */
+  fork: (effect: Effect.Effect<void>) => void;
+}
+
+interface PendingHandoff {
+  id: string;
+  startedAt: number;
+  toolCalls: number;
+  recentTools: string[];
+  lastError?: string;
+  isAborted: boolean;
+  done: Deferred.Deferred<HandoffReport>;
+}
+
+const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+/**
+ * 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 SidekickChild {
+  readonly launch: SidekickLaunch;
+  private readonly options: SidekickChildOptions;
+  private child: ChildProcess | undefined;
+  private pending: PendingHandoff | undefined;
+  private stderrTail = "";
+  private readonly waiting = new Map<string, Deferred.Deferred<string | undefined>>();
+
+  constructor(launch: SidekickLaunch, options: SidekickChildOptions) {
+    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;
+  }
+
+  /** Starts a handoff, or steers the running one. Fails only when the child cannot be started. */
+  handoff(message: string): Effect.Effect<Handoff, DevinError> {
+    return Effect.gen({ self: this }, function* () {
+      const current = this.pending;
+      if (current) {
+        this.send({ type: "steer", message });
+        return { id: current.id, done: current.done, isSteer: true };
+      }
+      if (!this.isAlive()) yield* this.start;
+      const id = randomUUID();
+      const done = Deferred.makeUnsafe<HandoffReport>();
+      this.pending = { id, startedAt: Date.now(), toolCalls: 0, recentTools: [], isAborted: false, done };
+      this.send({ id, type: "prompt", message });
+      return { id, done, isSteer: false };
+    });
+  }
+
+  get abort(): Effect.Effect<void> {
+    return Effect.sync(() => {
+      if (!this.pending) return;
+      this.pending.isAborted = true;
+      this.send({ type: "abort" });
+    });
+  }
+
+  /** Stops the child: its handoff ends as aborted and every RPC wait is released. Termination continues in the background. */
+  get close(): Effect.Effect<void> {
+    return Effect.sync(() => this.closeChild());
+  }
+
+  private closeChild(): void {
+    const child = this.child;
+    this.child = undefined;
+    if (this.pending) this.finish("aborted", "", "Stopped the sidekick process.");
+    for (const waiter of this.waiting.values()) Deferred.doneUnsafe(waiter, Exit.succeed(undefined));
+    this.waiting.clear();
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    child.stdin?.end();
+    const timer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL"); }, KILL_GRACE_MS);
+    timer.unref();
+    child.once("close", () => clearTimeout(timer));
+    child.kill("SIGTERM");
+  }
+
+  private get start(): Effect.Effect<void, DevinError> {
+    return Effect.gen({ self: this }, function* () {
+      const { launcher } = this.options;
+      const base = yield* launcher.resolveCommand;
+      const args = [...base.args, ...launchArgs(this.launch, launcher.packageRoot)];
+      const child = yield* Effect.try({
+        try: () => launcher.spawn(base.command, args, {
+          cwd: this.launch.cwd,
+          env: { ...launcher.env, ...this.options.childEnv },
+          stdio: ["pipe", "pipe", "pipe"],
+        }),
+        catch: toDevinError,
+      });
+      this.child = child;
+      this.stderrTail = "";
+      this.listen(child);
+    });
+  }
+
+  private listen(child: ChildProcess): void {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      if (this.child !== child) return;
+      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);
+        if (this.child !== child) return;
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer) => { if (this.child === child) this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL); });
+    child.stdin?.on("error", (error) => this.fail(child, error.message));
+    child.on("error", (error) => this.fail(child, error.message));
+    child.on("close", () => this.fail(child, this.stderrTail.trim() || "The sidekick process exited."));
+  }
+
+  /** Transport errors settle the handoff and all RPC waits once, even if the failed child closes after its replacement starts. */
+  private fail(child: ChildProcess | undefined, error: string): void {
+    if (this.child !== child) return;
+    this.finish(this.pending?.isAborted ? "aborted" : "error", "", error);
+    this.closeChild();
+  }
+
+  private send(value: Record<string, unknown>): void {
+    const child = this.child;
+    try {
+      if (!child?.stdin?.writable) throw new Error("Cannot write to the sidekick process.");
+      child.stdin.write(JSON.stringify(value) + "\n");
+    } catch (error) {
+      this.fail(child, errorMessage(error));
+    }
+  }
+
+  /** Sends the request at once; the returned wait is released with `undefined` when the child stops. */
+  private request(type: string): Effect.Effect<string | undefined> {
+    const id = randomUUID();
+    const waiter = Deferred.makeUnsafe<string | undefined>();
+    this.waiting.set(id, waiter);
+    this.send({ id, type });
+    return Deferred.await(waiter);
+  }
+
+  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;
+          Deferred.doneUnsafe(waiter, Exit.succeed(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))) {
+          this.send({ type: "extension_ui_response", id: record.id, cancelled: true });
+        }
+        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) this.options.fork(this.complete(current, record.aborted === true));
+        return;
+    }
+  }
+
+  private complete(current: PendingHandoff, isAborted: boolean): Effect.Effect<void> {
+    return Effect.map(this.request("get_last_assistant_text"), (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;
+    Deferred.doneUnsafe(current.done, Exit.succeed({
+      id: current.id, status, text, toolCalls: current.toolCalls, durationMs: Date.now() - current.startedAt, ...(error ? { error } : {}),
+    }));
+    this.options.onProgress?.();
+  }
+}

package/src/pi/features/sidekick/command.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Effect } from "effect";
+import { toDevinError, type DevinError } from "../../../core/errors.ts";
+import type { SidekickCommand, SidekickLaunch } from "./types.ts";
+
+const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+
+/** 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)));
+
+
+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;
+}
+
+function findPiCommand(): 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.");
+}
+
+/**
+ * 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 const resolvePiCommand: Effect.Effect<SidekickCommand, DevinError> = Effect.try({ try: findPiCommand, catch: toDevinError });
+
+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"]),
+  ];
+}

package/src/pi/features/sidekick/launcher.ts

@@ -0,0 +1,12 @@
+import { spawn } from "node:child_process";
+import { Context, Layer } from "effect";
+import { PACKAGE_ROOT, resolvePiCommand } from "./command.ts";
+import type { SidekickLauncherShape } from "./types.ts";
+
+/** How sidekick child Pi processes start. */
+export class SidekickLauncher extends Context.Service<SidekickLauncher, SidekickLauncherShape>()("pi-devin/SidekickLauncher") {}
+
+/** The same Node and Pi CLI as the lead, this process's environment and this package's own copy. */
+export const NodeSidekickLauncher = Layer.sync(SidekickLauncher, () => ({
+  resolveCommand: resolvePiCommand, spawn, env: process.env, packageRoot: PACKAGE_ROOT,
+} satisfies SidekickLauncherShape));

package/src/pi/features/sidekick/prompts.ts

@@ -0,0 +1,17 @@
+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");
+export const SIDEKICK_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");

package/src/pi/features/sidekick/report.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import { Effect, FileSystem } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import { fromPlatformError } from "../../../core/services/platform.ts";
+import type { BoundedReport } from "./types.ts";
+
+/** 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;
+
+
+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 };
+}
+
+/** Writes the complete report to a new private temporary directory and returns the file path. */
+function preserveReport(text: string): Effect.Effect<string, DevinError, FileSystem.FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const directory = yield* fs.makeTempDirectory({ prefix: "pi-devin-sidekick-report-" });
+    const path = join(directory, "report.md");
+    yield* fs.writeFileString(path, text, { mode: 0o600 });
+    return path;
+  }).pipe(Effect.mapError(fromPlatformError));
+}
+
+/**
+ * Bounds the report before it reaches the lead and keeps the complete text in a private temporary file.
+ * Never fails: background reports are delivered from a detached fiber, so a failed write only changes the notice.
+ */
+export function boundReport(text: string, maxChars = SIDEKICK_REPORT_CHAR_LIMIT): Effect.Effect<BoundedReport, never, FileSystem.FileSystem> {
+  return Effect.gen(function* () {
+    const result = truncateReport(text, maxChars);
+    if (!result.isTruncated) return { text };
+    const saved = yield* Effect.result(preserveReport(text));
+    const fullReportPath = saved._tag === "Success" ? saved.success : undefined;
+    const notice = `\n\n[The sidekick report exceeded about ${SIDEKICK_REPORT_TOKEN_LIMIT} tokens and was cut.` + (saved._tag === "Success"
+      ? ` Full report: ${saved.success}]`
+      : ` The full report could not be saved: ${saved.failure.message}]`);
+    // The notice is part of the same budget, including a filesystem error if preservation failed.
+    const suffix = truncateReport(notice, maxChars).text;
+    return { text: truncateReport(text, maxChars - suffix.length).text + suffix, ...(fullReportPath ? { fullReportPath } : {}) };
+  });
+}

package/src/pi/features/sidekick/service.ts

@@ -0,0 +1,176 @@
+import { join } from "node:path";
+import { Context, Deferred, Effect, Exit, FiberSet, FileSystem, Layer, Predicate } from "effect";
+import { toDevinFailure, type DevinFailure } from "../../../core/errors.ts";
+import { failWith } from "../../../core/validation.ts";
+import { ExtensionConfig } from "../../app/config.ts";
+import { fusionOf } from "../catalog/fusion.ts";
+import { ModelCatalog } from "../catalog/service.ts";
+import { onDefaultScheduler } from "../default-scheduler.ts";
+import { SidekickChild } from "./child.ts";
+import { SidekickLauncher } from "./launcher.ts";
+import { FUSION_CHILD_ENV, SIDEKICK_SYSTEM_PROMPT, SIDEKICK_TOOL_NAME } from "./prompts.ts";
+import { boundReport } from "./report.ts";
+import type { BoundedReport, Handoff, HandoffReport, HandoffResult, SidekickDetails, SidekickHostShape, SidekickLaunch, SidekicksShape } from "./types.ts";
+
+/** What the sidekick needs from the lead Pi. Provided by the Pi adapter. */
+export class SidekickHost extends Context.Service<SidekickHost, SidekickHostShape>()("pi-devin/SidekickHost") {}
+
+/**
+ * The Fusion sidekick: one child Pi per lead session, started on the first handoff and kept for the rest of the session.
+ * Owns the children, which call owns each report, and the fibers that deliver background reports.
+ */
+export class Sidekicks extends Context.Service<Sidekicks, SidekicksShape>()("pi-devin/Sidekicks") {}
+
+const launchKey = (launch: SidekickLaunch) => JSON.stringify([launch.cwd, launch.modelID, launch.thinking, launch.sessionFile, launch.tools]);
+const shortID = (id: string) => id.slice(0, 8);
+const reportPath = (fullReportPath: string | undefined) => fullReportPath ? { fullReportPath } : {};
+const nextMicrotask = Effect.promise(() => Promise.resolve());
+/** Stops before work starts when the call was already cancelled, as `signal.throwIfAborted()` does. */
+const checkAborted = (signal: AbortSignal | undefined): Effect.Effect<void, DevinFailure> => signal?.aborted ? Effect.fail(toDevinFailure(signal.reason)) : Effect.void;
+
+interface ReportDelivery {
+  owner: "background" | "blocking" | "delivered";
+  scheduled: boolean;
+}
+
+type WaitOutcome = "done" | "aborted" | "interrupted";
+
+export const SidekicksLive = Layer.effect(Sidekicks, Effect.gen(function* () {
+  const host = yield* SidekickHost;
+  const launcher = yield* SidekickLauncher;
+  const catalog = yield* ModelCatalog;
+  const config = yield* ExtensionConfig;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const fibers = yield* FiberSet.make<void, never>();
+  const runInFibers = yield* FiberSet.runtime(fibers)<never>();
+  const children = new Map<string, SidekickChild>();
+  // Steers share the same report; completed handoffs must not be retained by delivery bookkeeping.
+  const deliveries = new WeakMap<Deferred.Deferred<HandoffReport>, ReportDelivery>();
+  const waits = new Set<() => void>();
+  // The tool runs sequentially, so at most one blocking call shows progress at a time.
+  let progressListener: (() => void) | undefined;
+
+  /** Bound and preserve the complete report, including status, errors and any background delivery heading. */
+  const reportText = (report: HandoffReport, heading = ""): Effect.Effect<BoundedReport> => {
+    const body = report.text.trim();
+    const reason = report.error ?? (report.status === "aborted" ? "cancelled." : "failed.");
+    const text = report.status === "completed" ? body || "(The sidekick finished without a report.)"
+      : [`The sidekick task ${report.status === "aborted" ? "stopped" : "failed"}: ${reason}`, body].filter(Boolean).join("\n\n");
+    return boundReport(heading + text).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem));
+  };
+
+  const deliverLater = (handoff: Handoff, child: SidekickChild, delivery: ReportDelivery) => Effect.suspend(() => {
+    if (delivery.scheduled || delivery.owner === "delivered") return Effect.void;
+    delivery.scheduled = true;
+    // A blocking call owns the report unless user input moves it back to the background.
+    const canDeliver = () => delivery.owner === "background" && [...children.values()].includes(child);
+    return Effect.asVoid(FiberSet.run(fibers, Effect.gen(function* () {
+      const report = yield* Deferred.await(handoff.done);
+      if (report.status === "aborted" || !canDeliver()) return;
+      const { text, fullReportPath } = yield* reportText(report, `Sidekick report for background handoff ${shortID(report.id)}:\n\n`);
+      if (!canDeliver()) return;
+      delivery.owner = "delivered";
+      yield* host.deliverReport({
+        content: text,
+        details: { sidekickModel: child.launch.modelID, handoffId: report.id, status: report.status, toolCalls: report.toolCalls, durationMs: report.durationMs, isSteer: false,
+          ...reportPath(fullReportPath) },
+      });
+    }).pipe(Effect.ensuring(Effect.sync(() => { delivery.scheduled = false; }))), { startImmediately: true }));
+  });
+
+  const closeAll = (entries: readonly [string, SidekickChild][]) => Effect.forEach(entries, ([id, child]) => Effect.andThen(child.close, Effect.sync(() => {
+    children.delete(id);
+  })), { discard: true });
+
+  return {
+    handoff: (request) => Effect.gen(function* () {
+      const { signal } = request;
+      yield* checkAborted(signal);
+      const fusion = fusionOf(yield* catalog.models, request.model);
+      if (!fusion) return yield* failWith("The sidekick is only available with the Devin Fusion model.");
+      const input = Predicate.isObject(request.params) ? request.params as { message?: unknown; block?: unknown } : undefined;
+      const message = Predicate.isString(input?.message) ? input.message.trim() : "";
+      if (!message) return yield* failWith("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 = (yield* catalog.fusionChoices)?.sidekicks.find((item) => item.id === fusion.sidekickID);
+      if (!sidekickChoice) return yield* failWith("The sidekick model is not in the current Devin model list. Refresh the model list.");
+      const { sessionId } = request;
+      const launch: SidekickLaunch = {
+        cwd: request.cwd, modelID: fusion.sidekickID, thinking: sidekickChoice.level,
+        sessionFile: request.isSessionSaved ? join(config.agentDir(), "pi-devin", "sidekick", `${sessionId}.jsonl`) : undefined,
+        tools: (yield* host.activeTools).filter((name) => name !== SIDEKICK_TOOL_NAME),
+        systemPrompt: SIDEKICK_SYSTEM_PROMPT,
+      };
+      let child = children.get(sessionId);
+      // When the pair or tools change, only an idle process is restarted. Context continues through the same session file.
+      if (child && !child.isBusy() && launchKey(child.launch) !== launchKey(launch)) { yield* child.close; child = undefined; }
+      if (!child) {
+        child = new SidekickChild(launch, {
+          launcher, childEnv: { [FUSION_CHILD_ENV]: "1" }, onProgress: () => progressListener?.(),
+          fork: (effect) => { runInFibers(onDefaultScheduler(effect)); },
+        });
+        children.set(sessionId, child);
+      }
+      const active = child;
+      yield* checkAborted(signal);
+      const handoff = yield* active.handoff(message);
+      let delivery = deliveries.get(handoff.done);
+      if (!delivery) {
+        delivery = { owner: "background", scheduled: false };
+        deliveries.set(handoff.done, delivery);
+      }
+      const owned = delivery;
+      const details = (status: SidekickDetails["status"], report?: HandoffReport): SidekickDetails => ({
+        sidekickModel: launch.modelID, handoffId: handoff.id, status, toolCalls: report?.toolCalls ?? active.progress()?.toolCalls ?? 0,
+        ...(report ? { durationMs: report.durationMs } : {}), isSteer: handoff.isSteer,
+      });
+      const backgroundResult = (reason: string) => Effect.as(deliverLater(handoff, active, owned), {
+        content: [{ type: "text" as const, text: `${reason} The report will arrive as a message. (handoff ${shortID(handoff.id)})` }], details: details("background"),
+      } satisfies HandoffResult);
+      if (input?.block === false) {
+        return yield* backgroundResult(handoff.isSteer ? "Added instructions to the running sidekick task." : "The sidekick started working in the background.");
+      }
+      owned.owner = "blocking";
+      // The first event decides the outcome. The report is observed one microtask after it settles, as a promise continuation
+      // would, so user input in the same tick still moves the handoff to the background.
+      const decided = Deferred.makeUnsafe<WaitOutcome>();
+      const decide = (outcome: WaitOutcome) => () => { Deferred.doneUnsafe(decided, Exit.succeed(outcome)); };
+      const interrupt = decide("interrupted"), abort = decide("aborted");
+      const listen = Effect.gen(function* () {
+        waits.add(interrupt);
+        signal?.addEventListener("abort", abort, { once: true });
+        progressListener = () => {
+          const progress = active.progress();
+          if (progress) request.onProgress?.(`sidekick: ${progress.toolCalls} tool calls${progress.recentTools.length ? ` · ${progress.recentTools.join(", ")}` : ""}`, details("running"));
+        };
+        if (signal?.aborted) abort();
+        yield* FiberSet.run(fibers, Deferred.await(handoff.done).pipe(Effect.andThen(nextMicrotask), Effect.andThen(Effect.sync(decide("done")))), { startImmediately: true });
+      });
+      const stopListening = Effect.sync(() => {
+        progressListener = undefined;
+        waits.delete(interrupt);
+        signal?.removeEventListener("abort", abort);
+      });
+      const outcome = yield* Effect.acquireUseRelease(listen, () => Deferred.await(decided), () => stopListening);
+      if (outcome === "interrupted") {
+        owned.owner = "background";
+        return yield* backgroundResult("A user message arrived, so the sidekick task moved to the background.");
+      }
+      owned.owner = "delivered";
+      if (outcome === "aborted") {
+        yield* active.abort;
+        return yield* failWith("Cancelled the sidekick task.");
+      }
+      const report = yield* Deferred.await(handoff.done);
+      const { text, fullReportPath } = yield* reportText(report);
+      if (report.status !== "completed") return yield* failWith(text);
+      return { content: [{ type: "text" as const, text }], details: { ...details(report.status, report), ...reportPath(fullReportPath) } } satisfies HandoffResult;
+    }),
+    userInput: (source) => Effect.sync(() => {
+      if (source === "extension") return;
+      for (const interrupt of [...waits]) interrupt();
+    }),
+    sessionStarted: (sessionId) => Effect.suspend(() => closeAll([...children].filter(([id]) => id !== sessionId))),
+    reset: Effect.suspend(() => closeAll([...children])),
+  } satisfies SidekicksShape;
+}));