@buyong/pi-devin 0.1.4 → 0.1.6

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;
+}));

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

@@ -0,0 +1,99 @@
+import type { spawn } from "node:child_process";
+import type { Deferred, Effect } from "effect";
+import type { DevinError, DevinFailure } from "../../../core/errors.ts";
+
+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;
+}
+/** A handoff and its single report. A steer shares the running handoff's report. */
+export interface Handoff { id: string; done: Deferred.Deferred<HandoffReport>; isSteer: boolean }
+
+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;
+}
+
+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;
+}
+
+/** How a sidekick child Pi is started. */
+export interface SidekickLauncherShape {
+  /** Command that runs Pi. The default is the same Node and Pi CLI as the lead. */
+  readonly resolveCommand: Effect.Effect<SidekickCommand, DevinError>;
+  /**
+   * Starts the child. Node's spawner is used directly rather than Effect's: the child stays in the lead's process group,
+   * so terminal signals reach it, and a broken stdin is noticed while writing.
+   */
+  readonly spawn: typeof spawn;
+  readonly env: NodeJS.ProcessEnv;
+  /** Passed to the child with `-e`, so it loads the same extension copy as the lead. */
+  readonly packageRoot: string;
+}
+
+/** What the sidekick needs from the lead Pi. */
+export interface SidekickHostShape {
+  /** The lead's active tools. The child gets them without the sidekick tool itself. */
+  readonly activeTools: Effect.Effect<readonly string[]>;
+  /** Delivers a background report to the lead as a follow-up message that starts a turn. */
+  readonly deliverReport: (report: { content: string; details: SidekickDetails }) => Effect.Effect<void>;
+}
+
+/** One `devin_sidekick` call. */
+export interface HandoffRequest {
+  /** Tool parameters as Pi passed them. */
+  params: unknown;
+  /** The lead's model. Only the Devin Fusion model may hand off. */
+  model: { provider?: string; api?: string; id: string } | undefined;
+  cwd: string;
+  sessionId: string;
+  /** The lead session is saved to a file; the child then keeps its own session file. */
+  isSessionSaved: boolean;
+  signal: AbortSignal | undefined;
+  /** Progress while a blocking call waits for the report. */
+  onProgress?: (text: string, details: SidekickDetails) => void;
+}
+
+export interface HandoffResult { content: { type: "text"; text: string }[]; details: SidekickDetails }
+
+export interface SidekicksShape {
+  /**
+   * Starts or steers the session's handoff. By default waits for the report; with `block: false`, or when user input arrives
+   * while waiting, the report moves to the background and is delivered once.
+   */
+  readonly handoff: (request: HandoffRequest) => Effect.Effect<HandoffResult, DevinFailure>;
+  /** User input moves a waiting handoff to the background. Input sent by extensions does not count. */
+  readonly userInput: (source: string) => Effect.Effect<void>;
+  /** Stops the sidekicks of other lead sessions. */
+  readonly sessionStarted: (sessionId: string) => Effect.Effect<void>;
+  /** Stops every sidekick. */
+  readonly reset: Effect.Effect<void>;
+}

package/src/pi/features/usage/changes.ts

@@ -0,0 +1,20 @@
+import { Context, Effect, Layer } from "effect";
+import type { UsageChangesShape } from "./types.ts";
+
+/**
+ * Change notices for displays such as the status line. Owners of account records and the current credential publish;
+ * listeners run synchronously inside the publishing effect, so a redraw sees the state that caused it.
+ */
+export class UsageChanges extends Context.Service<UsageChanges, UsageChangesShape>()("pi-devin/UsageChanges") {}
+
+export const UsageChangesLive = Layer.sync(UsageChanges, () => {
+  const listeners = new Set<{ readonly listener: Effect.Effect<void> }>();
+  return {
+    // A display failure must not affect requests or refreshes.
+    publish: Effect.suspend(() => Effect.forEach([...listeners], (entry) => Effect.catchCause(entry.listener, () => Effect.void), { discard: true })),
+    subscribe: (listener) => Effect.asVoid(Effect.acquireRelease(
+      Effect.sync(() => { const entry = { listener }; listeners.add(entry); return entry; }),
+      (entry) => Effect.sync(() => { listeners.delete(entry); }),
+    )),
+  } satisfies UsageChangesShape;
+});

package/src/pi/{usage.ts → features/usage/report.ts}

@@ -1,31 +1,6 @@
-import type { JsonObject } from "../core/types.ts";
+import type { JsonObject } from "../../../core/types.ts";
+import type { AccountUsage, SessionUsage, UsageLine, UsagePainter, UsageTone } from "./types.ts";
 
-/** Quota from the account status (`GetUserStatus`). Values may have changed since it was fetched. */
-export interface AccountUsage {
-  billingStrategy?: string;
-  dailyRemainingPercent?: number;
-  weeklyRemainingPercent?: number;
-  dailyResetAtMs?: number;
-  weeklyResetAtMs?: number;
-  fetchedAtMs: number;
-}
-
-/** Totals of Devin assistant responses recorded in the current session branch. Sidekick child conversations are separate sessions and are not included. */
-export interface SessionUsage {
-  requests: number;
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-}
-
-export interface BudgetUsage { used: number; limit: number; isActive: boolean }
-
-/** Color level by remaining amount. Matches the Pi theme color names `success`, `warning` and `error`. */
-export type UsageTone = "success" | "warning" | "error";
-export interface UsageLine { text: string; isHeading?: boolean; tone?: UsageTone }
-/** Colors a segment. The default returns it uncolored. */
-export type UsagePainter = (tone: UsageTone, text: string) => string;
 const plain: UsagePainter = (_tone, text) => text;
 
 const QUOTA_STRATEGY = "BILLING_STRATEGY_QUOTA";
@@ -87,10 +62,6 @@ export function remainingTone(percent: number): UsageTone {
   return percent <= 20 ? "error" : percent <= 40 ? "warning" : "success";
 }
 
-function budgetTone(used: number, limit: number): UsageTone {
-  return used >= limit ? "error" : used / limit >= 0.75 ? "warning" : "success";
-}
-
 function hasQuota(account: AccountUsage | undefined): account is AccountUsage & { dailyRemainingPercent: number; weeklyRemainingPercent: number } {
   return account?.billingStrategy === QUOTA_STRATEGY && account.dailyRemainingPercent !== undefined && account.weeklyRemainingPercent !== undefined;
 }
@@ -127,7 +98,7 @@ export function relativeTime(targetMs: number, nowMs: number): string {
 }
 
 /** Details shown by `/devin`. Built only from the last account status and session records; sends no requests. */
-export function usageReport(account: AccountUsage | undefined, session: SessionUsage, budget: BudgetUsage, nowMs: number): UsageLine[] {
+export function usageReport(account: AccountUsage | undefined, session: SessionUsage, nowMs: number): UsageLine[] {
   const lines: UsageLine[] = [];
   if (!account) {
     lines.push({ text: "Account quota · not received yet", isHeading: true });
@@ -147,7 +118,5 @@ export function usageReport(account: AccountUsage | undefined, session: SessionU
   lines.push({ text: "This session · lead conversation (sidekick excluded)", isHeading: true });
   lines.push({ text: `  ${session.requests} ${session.requests === 1 ? "request" : "requests"} · input ${formatTokens(session.input)} · output ${formatTokens(session.output)}`
     + ` · cache read ${formatTokens(session.cacheRead)} · cache write ${formatTokens(session.cacheWrite)}` });
-  lines.push({ text: `Run budget · ${budget.isActive ? "in progress" : "last run"}`, isHeading: true });
-  lines.push({ text: `  ${progressBar((budget.used / budget.limit) * 100)} ${budget.used}/${budget.limit} model calls used`, tone: budgetTone(budget.used, budget.limit) });
   return lines;
 }

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

@@ -0,0 +1,33 @@
+import type { Effect, Scope } from "effect";
+
+/** Quota from the account status (`GetUserStatus`). Values may have changed since it was fetched. */
+export interface AccountUsage {
+  billingStrategy?: string;
+  dailyRemainingPercent?: number;
+  weeklyRemainingPercent?: number;
+  dailyResetAtMs?: number;
+  weeklyResetAtMs?: number;
+  fetchedAtMs: number;
+}
+
+/** Totals of Devin assistant responses recorded in the current session branch. Sidekick child conversations are separate sessions and are not included. */
+export interface SessionUsage {
+  requests: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** Color level by remaining amount. Matches the Pi theme color names `success`, `warning` and `error`. */
+export type UsageTone = "success" | "warning" | "error";
+export interface UsageLine { text: string; isHeading?: boolean; tone?: UsageTone }
+/** Colors a segment. The default returns it uncolored. */
+export type UsagePainter = (tone: UsageTone, text: string) => string;
+
+export interface UsageChangesShape {
+  /** Tells every listener, in order, that the quota or the current credential may have changed. Listener failures never reach the caller. */
+  readonly publish: Effect.Effect<void>;
+  /** Listens until the scope closes. */
+  readonly subscribe: (listener: Effect.Effect<void>) => Effect.Effect<void, never, Scope.Scope>;
+}