@buyong/pi-devin 0.1.4 → 0.1.6

package/src/pi/provider.ts

@@ -1,249 +0,0 @@
-import {
-  clampThinkingLevel,
-  type AssistantMessageEventStream, type Model, type Provider, type SimpleStreamOptions, type TranscriptContext,
-} from "@earendil-works/pi-ai";
-import { DevinClient, type DevinClientOptions } from "../core/client.ts";
-import { assertCanInfer } from "../core/auth/access.ts";
-import { ChatAccumulator, chatRequest } from "../core/inference/chat.ts";
-import { applyTeamModelPolicy } from "../core/models/access.ts";
-import type { BackendModelSelection, EffectiveThinkingLevel } from "../core/models/variants.ts";
-import { createFingerprintProvider, type FingerprintProvider } from "../core/protocol/fingerprint.ts";
-import { CHAT_METHOD } from "../core/protocol/protobuf.ts";
-import { awaitWithSignal, endpoint, isAuthenticationError, isTransientConnectionFailure, RPCError, safeError } from "../core/protocol/transport.ts";
-import { object, requiredString, tokenCount, type Credential, type JsonObject } from "../core/types.ts";
-import { createDevinAccountAuth } from "./auth.ts";
-import { DevinLifecycle, type RequestLease, type SessionBinding } from "./lifecycle.ts";
-import { toDevinTranscript } from "./messages.ts";
-import { catalogScope, createDevinModelSource, DEVIN_API, hasExtendedPromptCacheRetention, isFusionModelID, type FusionChoices, type FusionSelection } from "./models.ts";
-import { FUSION_LEAD_GUIDANCE } from "./sidekick.ts";
-import { DevinResponseStream } from "./stream.ts";
-import { accountUsage, type AccountUsage } from "./usage.ts";
-
-type LoginConfiguration = NonNullable<Parameters<typeof createDevinAccountAuth>[0]>["loginOptions"];
-
-/** Like Pi's built-in providers: the caller option wins; otherwise only PI_CACHE_RETENTION=long (provider env first) means long retention. */
-/** Node and Connect report these failures as codes ("read ECONNRESET", "unavailable: …") that Pi's host retry does not match. */
-function hostRetryableMessage(error: unknown, message: string): string {
-  return isTransientConnectionFailure(error) ? `Connection error (${message})` : message;
-}
-
-function resolveCacheRetention(options: SimpleStreamOptions): NonNullable<SimpleStreamOptions["cacheRetention"]> {
-  if (options.cacheRetention) return options.cacheRetention;
-  return (options.env?.PI_CACHE_RETENTION || process.env.PI_CACHE_RETENTION) === "long" ? "long" : "short";
-}
-export interface DevinProvider extends Provider<typeof DEVIN_API> {
-  refreshModels: NonNullable<Provider<typeof DEVIN_API>["refreshModels"]>;
-  readonly lifecycle: DevinLifecycle;
-  attachSession(binding: SessionBinding): void;
-  getFusionChoices(): FusionChoices | undefined;
-  /** Rebuilds the model list from the current catalog without network after the saved Fusion choice or display settings change. */
-  rebuildModels(): void;
-  /** Quota from the last account status received. Makes no request; undefined if none was received. */
-  getAccountUsage(): AccountUsage | undefined;
-  shutdown(): void;
-}
-
-export function createDevinProvider(options: {
-  fetch?: typeof fetch;
-  fingerprint?: (credential: Credential) => FingerprintProvider;
-  http?: DevinClientOptions["http"];
-  loginOptions?: LoginConfiguration;
-  maxModelCalls?: number;
-  /** Reads the saved Fusion choice. false (sidekick process) creates no Fusion entry. */
-  fusion?: false | (() => FusionSelection | undefined);
-  /** Reads the saved recommended filter setting. */
-  recommendedOnly?: () => boolean;
-  /** Also lists exact UIDs that a group already covers. Used only by the sidekick child Pi. */
-  listsAllExactModels?: boolean;
-  now?: () => number;
-} = {}): DevinProvider {
-  const lifecycle = new DevinLifecycle(options.maxModelCalls);
-  let lifetime = new AbortController();
-  const clients = new Set<DevinClient>();
-  const fingerprints = new Map<string, FingerprintProvider>();
-  const accounts = new Map<string, { ownerHash: string; status: JsonObject }>();
-  const now = options.now ?? Date.now;
-  let latestUsage: AccountUsage | undefined;
-  const clientFor = (credential: Credential, extra: DevinClientOptions = {}): DevinClient => {
-    const key = catalogScope(credential);
-    let fingerprint = fingerprints.get(key);
-    if (!fingerprint) {
-      if (fingerprints.size >= 16) fingerprints.delete(fingerprints.keys().next().value!);
-      fingerprint = options.fingerprint?.(credential) ?? createFingerprintProvider(credential.sessionToken);
-      fingerprints.set(key, fingerprint);
-    }
-    const fetch = extra.fetch ?? options.fetch;
-    const client = new DevinClient(credential, { ...extra, fingerprint, fetch, ...(!fetch && options.http ? { http: options.http } : {}) });
-    const close = client.transport.close.bind(client.transport);
-    let hasClosed = false;
-    client.transport.close = () => { if (!hasClosed) { hasClosed = true; clients.delete(client); close(); } };
-    clients.add(client);
-    return client;
-  };
-  const rememberAccount = (credential: Credential, ownerHash: string, status: JsonObject) => {
-    if (lifetime.signal.aborted) return;
-    if (accounts.size >= 16) accounts.delete(accounts.keys().next().value!);
-    accounts.set(catalogScope(credential), { ownerHash, status });
-    latestUsage = accountUsage(status, now());
-  };
-  const auth = createDevinAccountAuth({
-    loginOptions: { ...options.loginOptions, fetch: options.loginOptions?.fetch ?? options.fetch },
-    createClient: (credential) => clientFor(credential, { profile: "login" }),
-    getSignal: () => lifetime.signal,
-    isAccountChecked: (credential) => accounts.has(catalogScope(credential)),
-    onValidated: rememberAccount,
-    onInvalidated: (credential, error) => { accounts.delete(catalogScope(credential)); latestUsage = undefined; lifecycle.abort(error); },
-    onLogin: () => {
-      accounts.clear(); fingerprints.clear(); latestUsage = undefined; source.invalidate();
-      lifecycle.abort(new DOMException("The Devin account was re-authenticated.", "AbortError"));
-    },
-  });
-  const authenticationFailed = (credential: Credential, error: unknown, generation: number) => {
-    if (!isAuthenticationError(error)) return;
-    auth.invalidate(credential, error, generation);
-  };
-  const source = createDevinModelSource({
-    fusion: options.fusion,
-    recommendedOnly: options.recommendedOnly,
-    listsAllExactModels: options.listsAllExactModels,
-    credentialFromHost: (credential) => credential?.type === "oauth" ? auth.credentialFromHost(credential) : undefined,
-    fetchCatalog: async (credential, signal) => {
-      const generation = auth.generation;
-      auth.assertUsable(credential);
-      const client = clientFor(credential);
-      try {
-        const catalog = await client.catalog(signal);
-        applyTeamModelPolicy(catalog.models, await client.teamSettings(signal));
-        return catalog;
-      } catch (error) { authenticationFailed(credential, error, generation); throw error; }
-      finally { client.transport.close(); }
-    },
-  });
-  const infer = (model: Model<typeof DEVIN_API>, context: TranscriptContext, requestOptions: SimpleStreamOptions = {}) => {
-    const effectiveLevel = (requestOptions.reasoning ?? clampThinkingLevel(model, "off")) as EffectiveThinkingLevel;
-    const response = new DevinResponseStream(model, "");
-    void (async () => {
-      let client: DevinClient | undefined, lease: RequestLease | undefined;
-      let credential: Credential | undefined;
-      const accumulator = new ChatAccumulator();
-      let actualUID = "", isRedacted = false;
-      const generation = auth.generation;
-      const signal = AbortSignal.any([lifetime.signal, ...(requestOptions.signal ? [requestOptions.signal] : [])]);
-      try {
-        signal.throwIfAborted();
-        credential = { version: 1, sessionToken: requiredString(requestOptions.apiKey, "Devin account authentication (/login required)"), apiServerURL: endpoint(model.baseUrl), createdAt: new Date().toISOString() };
-        // Pi can override the OAuth value with an apiKey in models.json or a caller option. Only OAuth sessions are accepted.
-        auth.assertOAuthSession(credential);
-        auth.assertUsable(credential);
-        let selected = source.resolve(model.id, effectiveLevel, credential);
-        actualUID = selected.uid;
-        response.message.providerThinkingLevel = actualUID;
-        if (requestOptions.maxRetries !== undefined && requestOptions.maxRetries !== 0) throw new Error("Devin uses Pi host retries. Only provider maxRetries 0 is supported.");
-        if (requestOptions.transport && !["auto", "sse"].includes(requestOptions.transport)) throw new Error("Devin supports HTTP Connect streams only.");
-        const cacheRetention = resolveCacheRetention(requestOptions);
-        const assertCacheRetention = (selection: BackendModelSelection) => {
-          if (cacheRetention === "long" && !hasExtendedPromptCacheRetention(selection.variant)) {
-            throw new Error("Long cache lifetime is not confirmed for this Devin model. Long retention is supported only for models whose catalog Prompt Cache Retention is 24h.");
-          }
-        };
-        assertCacheRetention(selected);
-        // The per-request account check (permission and quota) runs here, outside Pi's shared credential lock.
-        let account = accounts.get(catalogScope(credential));
-        const probe = clientFor(credential, { profile: "login", fetch: requestOptions.fetch, timeoutMs: requestOptions.timeoutMs });
-        try {
-          const status = await probe.status(signal);
-          signal.throwIfAborted();
-          if (generation !== auth.generation) throw new DOMException("The Devin authentication generation changed.", "AbortError");
-          auth.assertUsable(credential);
-          rememberAccount(credential, requiredString(probe.accountIdentityHash, "Devin account scope"), status);
-          account = accounts.get(catalogScope(credential));
-        } catch (error) {
-          // A check that cannot reach the server keeps the last known account; the model request reports its own failure.
-          if (!account || signal.aborted || !isTransientConnectionFailure(error)) throw error;
-        } finally { probe.transport.close(); }
-        if (!account) throw new Error("The Devin account check was interrupted.");
-        assertCanInfer(account.status);
-        lease = await lifecycle.acquire(account.ownerHash, signal);
-        const currentLease = lease;
-        const transcript = toDevinTranscript(context, selected.model);
-        if (isFusionModelID(model.id)) transcript.systemPrompt = [transcript.systemPrompt, FUSION_LEAD_GUIDANCE].filter(Boolean).join("\n\n");
-        const maximum = requestOptions.maxTokens === undefined ? selected.model.maxOutputTokens : tokenCount(requestOptions.maxTokens, "maxTokens");
-        if (maximum < 1 || maximum > selected.model.maxOutputTokens) throw new Error("The output limit is outside the selected Devin model range.");
-        client = clientFor(credential, { fetch: requestOptions.fetch, timeoutMs: requestOptions.timeoutMs,
-          onRequest: (attempt) => { if (attempt.isMetered) currentLease.consume(); },
-        });
-        currentLease.addCleanup(() => client!.transport.close());
-        const request = chatRequest({ metadata: client.metadata(), model: selected.uid, ...transcript, maxTokens: maximum,
-          cascadeId: lease.cascadeId, trajectoryId: lease.trajectoryId, stepIndex: lease.stepIndex,
-          executionId: lease.executionId, clientSessionId: requestOptions.sessionId ?? lease.sessionId,
-          isAuxiliary: lease.isAuxiliary, isRecovery: lease.isRecovery, includeContext: false,
-        });
-        if (requestOptions.temperature !== undefined) {
-          if (!Number.isFinite(requestOptions.temperature) || requestOptions.temperature < 0) throw new Error("temperature must be a finite value of 0 or more.");
-          object(request.configuration, "configuration").temperature = requestOptions.temperature;
-        }
-        if (cacheRetention === "none") for (const prompt of request.chatMessagePrompts as JsonObject[]) delete prompt.promptCacheOptions;
-        const identity = JSON.stringify([request.cascadeId, request.trajectoryReference, request.executionId, request.clientSessionId]);
-        for await (const _frame of client.transport.stream(CHAT_METHOD, request, lease.signal, {
-          headers: requestOptions.headers,
-          onPayload: async (payload, scopeSignal) => {
-            const replacement = requestOptions.onPayload ? await awaitWithSignal(Promise.resolve(requestOptions.onPayload(payload, model)), scopeSignal) : undefined;
-            const finalPayload = replacement === undefined ? payload : object(replacement, "provider payload");
-            if (JSON.stringify([finalPayload.cascadeId, finalPayload.trajectoryReference, finalPayload.executionId, finalPayload.clientSessionId]) !== identity) {
-              throw new Error("A payload hook cannot change the owned run, session or step identifiers.");
-            }
-            actualUID = requiredString(finalPayload.chatModelUid, "chatModelUid");
-            if (actualUID !== selected.uid) {
-              // An exact UID hidden from the list is re-resolved at that UID's level when the current catalog has it.
-              if (!source.exactLevel(actualUID)) throw new Error("A payload hook selected an unavailable model UID.");
-              selected = source.resolveUID(actualUID, credential!);
-              toDevinTranscript(context, selected.model); // A model change re-checks existing image and tool limits.
-              assertCacheRetention(selected);
-            }
-            const outputLimit = tokenCount(object(finalPayload.configuration, "configuration").maxTokens, "maxTokens");
-            if (outputLimit < 1 || outputLimit > selected.model.maxOutputTokens) throw new Error("The payload hook output limit is outside the model range.");
-            response.message.providerThinkingLevel = actualUID;
-            return finalPayload;
-          },
-          onResponse: async (info, scopeSignal) => {
-            if (info.status === 401) authenticationFailed(credential!, new RPCError("unauthenticated", "HTTP 401", 401), generation);
-            if (requestOptions.onResponse) await awaitWithSignal(Promise.resolve(requestOptions.onResponse(info, model)), scopeSignal);
-          },
-          onFrame: async (frame, scopeSignal) => {
-            if (requestOptions.onProviderStreamEvent) await awaitWithSignal(Promise.resolve(requestOptions.onProviderStreamEvent(structuredClone(frame.data), model)), scopeSignal);
-            if (frame.isEnd && frame.data.error) return; // Connect error classification belongs to the transport.
-            if (frame.data.redact === true) { isRedacted = true; response.redact(); }
-            accumulator.accept(frame.data, frame.isEnd);
-            if (!frame.isEnd) response.accept(frame.data, accumulator);
-          },
-        })) { /* A frame handling failure also ends the request inside the transport first. */ }
-        const result = accumulator.finish();
-        result.message.modelUid = actualUID;
-        response.finish(result);
-      } catch (error) {
-        if (credential) authenticationFailed(credential, error, generation);
-        accumulator.message.modelUid = actualUID || undefined;
-        response.fail(hostRetryableMessage(error, safeError(error, credential ? [credential.sessionToken] : [])), error instanceof Error && error.name === "AbortError", isRedacted ? undefined : accumulator.message);
-      } finally { client?.transport.close(); lease?.release(); }
-    })();
-    return response.stream;
-  };
-  return {
-    id: "devin", name: "Devin", auth: { oauth: auth }, lifecycle,
-    getModels: source.getModels, filterModels: source.filterModels,
-    getFusionChoices: source.getFusionChoices, rebuildModels: source.rebuildModels,
-    getAccountUsage: () => latestUsage ? { ...latestUsage } : undefined,
-    refreshModels: (context) => source.refreshModels({ ...context, signal: AbortSignal.any([context.signal, lifetime.signal]) }),
-    stream: (model, context, requestOptions) => infer(model, context, requestOptions), streamSimple: (model, context, requestOptions) => infer(model, context, requestOptions),
-    attachSession(binding) {
-      if (lifetime.signal.aborted) lifetime = new AbortController();
-      lifecycle.attach(binding);
-    },
-    shutdown() {
-      lifetime.abort(new DOMException("The Devin provider shut down.", "AbortError"));
-      lifecycle.shutdown();
-      for (const client of [...clients]) client.transport.close();
-      fingerprints.clear(); accounts.clear(); latestUsage = undefined;
-    },
-  };
-}

package/src/pi/sidekick-report.ts

@@ -1,47 +0,0 @@
-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 };
-  let notice = `\n\n[The sidekick report exceeded about ${SIDEKICK_REPORT_TOKEN_LIMIT} tokens and was cut.`;
-  let fullReportPath: string | undefined;
-  try {
-    const directory = await mkdtemp(join(tmpdir(), "pi-devin-sidekick-report-"));
-    const path = join(directory, "report.md");
-    await writeFile(path, text, { encoding: "utf8", mode: 0o600 });
-    fullReportPath = path;
-    notice += ` Full report: ${path}]`;
-  } catch (error) {
-    notice += ` The full report could not be saved: ${error instanceof Error ? error.message : String(error)}]`;
-  }
-  // 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/sidekick-runtime.ts

@@ -1,300 +0,0 @@
-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 {
-    const current = this.pending;
-    if (current) {
-      this.send({ type: "steer", message });
-      return { id: current.id, done: current.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 };
-    this.send({ id, type: "prompt", message });
-    return { id, done, isSteer: false };
-  }
-
-  abort(): void {
-    if (!this.pending) return;
-    this.pending.isAborted = true;
-    this.send({ type: "abort" });
-  }
-
-  close(): void {
-    const child = this.child;
-    this.child = undefined;
-    if (this.pending) this.finish("aborted", "", "Stopped the sidekick process.");
-    for (const resolve of this.waiting.values()) resolve(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 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) => {
-      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.close();
-  }
-
-  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, error instanceof Error ? error.message : String(error));
-    }
-  }
-
-  private request(type: string): Promise<string | undefined> {
-    const id = randomUUID();
-    return new Promise((resolve) => {
-      this.waiting.set(id, resolve);
-      this.send({ id, type });
-    });
-  }
-
-  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))) {
-          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) 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?.();
-  }
-}