@buyong/pi-devin 0.1.4 → 0.1.6

package/src/pi/devin-command.ts

@@ -1,76 +0,0 @@
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { DevinPanel, PREFERENCE_ITEMS } from "./devin-panel.ts";
-import type { DevinPreferences, DevinSettings } from "./devin-settings.ts";
-import type { DevinProvider } from "./provider.ts";
-import { sessionUsage, usageReport, usageStatusText } from "./usage.ts";
-
-export const DEVIN_COMMAND_NAME = "devin";
-/** The only status key this package uses. */
-export const USAGE_STATUS_KEY = "devin-usage";
-const USAGE = "Usage: /devin, /devin recommended on|off, /devin status on|off";
-const ARGUMENT_KEYS: Readonly<Record<string, keyof DevinPreferences>> = { recommended: "recommendedOnly", status: "showUsageStatus" };
-
-/** The status is used in the TUI only. Turning the toggle off clears only this package's key. Values come only from the last account status and session records. */
-export function updateUsageStatus(ctx: ExtensionContext, provider: DevinProvider, settings: DevinSettings): void {
-  if (ctx.mode !== "tui") return;
-  const text = settings.read().showUsageStatus
-    ? usageStatusText(provider.getAccountUsage(), sessionUsage(ctx.sessionManager.getBranch()), (tone, segment) => ctx.ui.theme.fg(tone, segment)) : undefined;
-  ctx.ui.setStatus(USAGE_STATUS_KEY, text);
-}
-
-const onOff = (value: boolean) => value ? "on" : "off";
-
-/**
- * `/devin` shows usage details and display settings. Settings are saved globally and applied immediately.
- * The TUI gets a dedicated screen; other modes use arguments and notifications.
- */
-export function registerDevinCommand(pi: ExtensionAPI, provider: DevinProvider, settings: DevinSettings, options: { now?: () => number } = {}): void {
-  const now = options.now ?? Date.now;
-  const apply = async (ctx: ExtensionCommandContext, next: DevinPreferences) => {
-    const previous = settings.read();
-    // Only write failures are thrown to the caller. A list refresh failure after saving is reported as a warning so the screen and the saved value stay in sync.
-    settings.write(next);
-    if (previous.recommendedOnly !== next.recommendedOnly) {
-      provider.rebuildModels();
-      // Pi keeps model and availability snapshots. Rebuild them without network so `/model` and RPC lists update immediately.
-      try {
-        await ctx.modelRegistry.refresh({ providers: ["devin"], allowNetwork: false });
-      } catch (error) {
-        ctx.ui.notify(`Settings were saved, but the model list could not be rebuilt: ${error instanceof Error ? error.message : String(error)}`, "warning");
-      }
-      const model = ctx.model;
-      if (model?.provider === "devin" && !provider.getModels().some((item) => item.id === model.id)) {
-        ctx.ui.notify(`The current model ${model.name} is now hidden from the list but stays in use for this session. To restore it when reopening the session, pick a model from the list.`, "warning");
-      }
-    }
-    updateUsageStatus(ctx, provider, settings);
-  };
-  pi.registerCommand(DEVIN_COMMAND_NAME, {
-    description: "Show Devin usage and change display settings (recommended models only, usage in the status line); saved globally",
-    handler: async (args, ctx) => {
-      const report = () => usageReport(provider.getAccountUsage(), sessionUsage(ctx.sessionManager.getBranch()), provider.lifecycle.budget(), now());
-      const tokens = args.trim().split(/\s+/).filter(Boolean);
-      if (tokens.length) {
-        const key = ARGUMENT_KEYS[tokens[0]];
-        if (tokens.length !== 2 || !key || (tokens[1] !== "on" && tokens[1] !== "off")) {
-          ctx.ui.notify(`Unknown argument. ${USAGE}`, "error");
-          return;
-        }
-        const value = tokens[1] === "on";
-        await apply(ctx, { ...settings.read(), [key]: value });
-        ctx.ui.notify(`${PREFERENCE_ITEMS.find((item) => item.key === key)!.label}: ${onOff(value)} (saved globally)`, "info");
-        return;
-      }
-      if (ctx.mode === "tui") {
-        await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new DevinPanel({
-          theme, report, preferences: settings.read(), onChange: (next) => apply(ctx, next),
-          requestRender: () => tui.requestRender(), done: () => done(),
-        }));
-        return;
-      }
-      const preferences = settings.read();
-      const summary = PREFERENCE_ITEMS.map((item) => `${item.label} ${onOff(preferences[item.key])}`).join(" · ");
-      ctx.ui.notify([...report().map((line) => line.text), `Settings: ${summary}`, USAGE].join("\n"), "info");
-    },
-  });
-}

package/src/pi/devin-settings.ts

@@ -1,50 +0,0 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-const SCHEMA_VERSION = 1;
-
-/** 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;
-}
-
-export const DEFAULT_PREFERENCES: DevinPreferences = { recommendedOnly: false, showUsageStatus: false };
-
-export interface DevinSettings {
-  read(): DevinPreferences;
-  write(preferences: DevinPreferences): void;
-}
-
-export function devinSettingsPath(agentDir: string): string {
-  return join(agentDir, "pi-devin", "settings.json");
-}
-
-/** Default store so SDK callers and tests never write to the real agent directory. */
-export function memoryDevinSettings(initial: Partial<DevinPreferences> = {}): DevinSettings {
-  let current: DevinPreferences = { ...DEFAULT_PREFERENCES, ...initial };
-  return { read: () => ({ ...current }), write: (preferences) => { current = { ...preferences }; } };
-}
-
-/** An unreadable or malformed file reads as the defaults and is not overwritten. Writes are replaced atomically within the same directory. */
-export function fileDevinSettings(path: string): DevinSettings {
-  return {
-    read() {
-      try {
-        const value = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
-        if (value.schemaVersion === SCHEMA_VERSION && typeof value.recommendedOnly === "boolean" && typeof value.showUsageStatus === "boolean") {
-          return { recommendedOnly: value.recommendedOnly, showUsageStatus: value.showUsageStatus };
-        }
-      } catch { /* A missing or corrupt file falls back to the defaults. */ }
-      return { ...DEFAULT_PREFERENCES };
-    },
-    write(preferences) {
-      mkdirSync(dirname(path), { recursive: true });
-      const temporary = `${path}.${process.pid}.tmp`;
-      writeFileSync(temporary, JSON.stringify({ schemaVersion: SCHEMA_VERSION, ...preferences }, null, 2) + "\n");
-      renameSync(temporary, path);
-    },
-  };
-}

package/src/pi/extension.ts

@@ -1,80 +0,0 @@
-import type { Model } from "@earendil-works/pi-ai";
-import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createDevinProvider, type DevinProvider } from "./provider.ts";
-import { DEVIN_STATE_ENTRY } from "./lifecycle.ts";
-import { registerDevinCommand, updateUsageStatus } from "./devin-command.ts";
-import { memoryDevinSettings, type DevinSettings } from "./devin-settings.ts";
-import { registerFusionCommand } from "./fusion-command.ts";
-import { memoryFusionSettings, type FusionSettings } from "./fusion-settings.ts";
-import { createSidekickTool, fusionOf, SIDEKICK_TOOL_NAME, type SidekickToolOptions } from "./sidekick.ts";
-
-type ProviderOptions = NonNullable<Parameters<typeof createDevinProvider>[0]>;
-export interface DevinExtensionOptions extends Omit<ProviderOptions, "fusion" | "listsAllExactModels" | "recommendedOnly"> {
-  /** Store for the `/devin-fusion` choice. Kept in memory only when omitted. */
-  fusionSettings?: FusionSettings;
-  /** Store for the `/devin` display settings. Kept in memory only when omitted. */
-  devinSettings?: DevinSettings;
-  /** The child Pi started as the sidekick registers no Fusion model, tool or command, and no `/devin` or status line. */
-  isFusionChild?: boolean;
-  /** Overrides the sidekick session location and how the child starts. The default location is the Pi agent directory. */
-  sidekick?: Partial<SidekickToolOptions>;
-}
-
-export function registerDevinExtension(pi: ExtensionAPI, options: DevinExtensionOptions = {}): DevinProvider {
-  const { fusionSettings, devinSettings, isFusionChild, sidekick: sidekickOptions, ...providerOptions } = options;
-  const settings = fusionSettings ?? memoryFusionSettings();
-  const preferences = isFusionChild ? undefined : devinSettings ?? memoryDevinSettings();
-  // The child Pi runs on the exact UID the lead chose, so it lists every exact UID and ignores the recommended filter.
-  const provider = createDevinProvider({
-    ...providerOptions, fusion: isFusionChild ? false : () => settings.read(), listsAllExactModels: isFusionChild === true,
-    recommendedOnly: preferences ? () => preferences.read().recommendedOnly : undefined,
-  });
-  pi.registerProvider(provider);
-  if (preferences) registerDevinCommand(pi, provider, preferences);
-  const refreshStatus = (context: Parameters<typeof updateUsageStatus>[0]) => { if (preferences) updateUsageStatus(context, provider, preferences); };
-  const sidekick = isFusionChild ? undefined
-    : createSidekickTool(pi, provider, { agentDir: sidekickOptions?.agentDir ?? getAgentDir, runtime: sidekickOptions?.runtime });
-  if (sidekick) {
-    pi.registerTool(sidekick.definition);
-    registerFusionCommand(pi, provider, settings);
-  }
-  // Enables the sidekick only for the Fusion model and leaves other extensions' and the user's active tools alone.
-  const syncSidekick = (model: Model<any> | undefined) => {
-    if (!sidekick) return;
-    const active = pi.getActiveTools(), isActive = active.includes(SIDEKICK_TOOL_NAME);
-    const shouldBeActive = fusionOf(provider, model) !== undefined;
-    if (shouldBeActive && !isActive) pi.setActiveTools([...active, SIDEKICK_TOOL_NAME]);
-    else if (!shouldBeActive && isActive) pi.setActiveTools(active.filter((name) => name !== SIDEKICK_TOOL_NAME));
-  };
-  pi.on("model_select", (event) => { syncSidekick(event.model); });
-  pi.on("input", (event) => { sidekick?.onInput(event.source); });
-  pi.on("session_start", (_event, context) => {
-    if (context.modelRegistry.getRegisteredNativeProvider("devin") !== provider) {
-      provider.shutdown();
-      throw new Error("The Devin provider ID collides with another registration. Remove the duplicate extension and reload.");
-    }
-    provider.attachSession({
-      getSessionId: () => context.sessionManager.getSessionId(),
-      getBranch: () => context.sessionManager.getBranch(),
-      append: (data) => pi.appendEntry(DEVIN_STATE_ENTRY, data),
-    });
-    sidekick?.onSessionStart(context.sessionManager.getSessionId());
-    syncSidekick(context.model);
-    refreshStatus(context);
-  });
-  pi.on("message_end", (event, context) => {
-    if (event.message.role === "assistant" && event.message.provider === "devin") refreshStatus(context);
-  });
-  pi.on("before_agent_start", () => { provider.lifecycle.begin("agent"); });
-  pi.on("agent_start", () => { provider.lifecycle.agentStarted(); });
-  // Host retry or overflow recovery can continue after agent_end.
-  pi.on("agent_settled", (_event, context) => { provider.lifecycle.finish(); refreshStatus(context); });
-  pi.on("session_before_compact", (event) => { provider.lifecycle.beforeCompaction(event.reason); });
-  pi.on("session_compact", (event) => { provider.lifecycle.afterCompaction(event.reason); });
-  pi.on("session_compact_failed", (event) => { provider.lifecycle.afterCompaction(event.reason); });
-  pi.on("session_before_tree", (event) => { if (event.preparation.userWantsSummary) provider.lifecycle.beforeTree(); });
-  pi.on("session_tree", (_event, context) => { provider.lifecycle.treeChanged(); refreshStatus(context); });
-  pi.on("cache_warming_decision", (_event, context) => context.model?.provider === "devin" ? { action: "stop" } : undefined);
-  pi.on("session_shutdown", () => { sidekick?.reset(); provider.shutdown(); });
-  return provider;
-}

package/src/pi/fusion-command.ts

@@ -1,83 +0,0 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { FUSION_MODEL_ID, type DevinModel, type FusionChoices, type FusionSelection } from "./models.ts";
-import { FusionPicker } from "./fusion-picker.ts";
-import type { FusionSettings } from "./fusion-settings.ts";
-import type { DevinProvider } from "./provider.ts";
-
-export const FUSION_COMMAND_NAME = "devin-fusion";
-const USAGE = `Usage: /${FUSION_COMMAND_NAME} or /${FUSION_COMMAND_NAME} <lead model ID> <sidekick model ID>`;
-
-function currentFusion(provider: DevinProvider): DevinModel | undefined {
-  return (provider.getModels() as readonly DevinModel[]).find((model) => model.id === FUSION_MODEL_ID);
-}
-
-/** Disambiguates duplicate display names in a select list with an index, and maps the chosen label back to its value. */
-async function choose<T>(ctx: ExtensionCommandContext, title: string, items: readonly T[], label: (item: T) => string, isCurrent: (item: T) => boolean) {
-  const names = items.map(label);
-  const labels = items.map((item, index) => {
-    const name = names.filter((other) => other === names[index]).length > 1 ? `${names[index]} (${index + 1})` : names[index];
-    return (isCurrent(item) ? "● " : "  ") + name;
-  });
-  const picked = await ctx.ui.select(title, labels);
-  return picked === undefined ? undefined : items[labels.indexOf(picked)];
-}
-
-async function pickInteractively(ctx: ExtensionCommandContext, choices: FusionChoices, current: FusionSelection | undefined): Promise<FusionSelection | undefined> {
-  const lead = await choose(ctx, "Devin Fusion · lead model", choices.leads, (item) => item.name, (item) => item.id === current?.leadID);
-  if (!lead) return undefined;
-  const groups = [...new Set(choices.sidekicks.map((item) => item.groupName))];
-  const currentGroup = choices.sidekicks.find((item) => item.id === current?.sidekickID)?.groupName;
-  const group = groups.length === 1 ? groups[0] : await choose(ctx, "Devin Fusion · sidekick model", groups, (item) => item, (item) => item === currentGroup);
-  if (group === undefined) return undefined;
-  const variants = choices.sidekicks.filter((item) => item.groupName === group);
-  const sidekick = variants.length === 1 ? variants[0]
-    : await choose(ctx, `Devin Fusion · sidekick variant (${group})`, variants, (item) => item.name, (item) => item.id === current?.sidekickID);
-  return sidekick ? { leadID: lead.id, sidekickID: sidekick.id } : undefined;
-}
-
-/**
- * `/devin-fusion` only chooses the lead/sidekick pair. Whether Fusion is used is decided by picking Devin Fusion in `/model`.
- * If the current model is Fusion, it is re-selected with the updated model object so the thinking level range matches.
- */
-export function registerFusionCommand(pi: ExtensionAPI, provider: DevinProvider, settings: FusionSettings): void {
-  pi.registerCommand(FUSION_COMMAND_NAME, {
-    description: "Choose the lead and sidekick models for Devin Fusion (saved globally)",
-    handler: async (args, ctx) => {
-      const choices = provider.getFusionChoices();
-      if (!choices?.leads.length || !choices.sidekicks.length) {
-        ctx.ui.notify("No Devin models are available for Fusion. Check that the model list refreshed after /login.", "warning");
-        return;
-      }
-      const before = currentFusion(provider);
-      const tokens = args.trim().split(/\s+/).filter(Boolean);
-      let selection: FusionSelection | undefined;
-      if (tokens.length) {
-        const [leadID, sidekickID] = tokens;
-        if (tokens.length !== 2 || !choices.leads.some((item) => item.id === leadID) || !choices.sidekicks.some((item) => item.id === sidekickID)) {
-          ctx.ui.notify(`This model cannot be used for Fusion. ${USAGE}`, "error");
-          return;
-        }
-        selection = { leadID, sidekickID };
-      } else if (ctx.mode === "tui") {
-        selection = await ctx.ui.custom<FusionSelection | undefined>((tui, theme, _keybindings, done) => new FusionPicker({
-          choices, current: before?.devin.fusion, theme, requestRender: () => tui.requestRender(), done,
-        }));
-        if (!selection) return;
-      } else if (ctx.hasUI) {
-        // RPC clients cannot draw the custom screen, so they get the select dialogs.
-        selection = await pickInteractively(ctx, choices, before?.devin.fusion);
-        if (!selection) return;
-      } else {
-        ctx.ui.notify(before ? `Current: ${before.name}` : `No Devin Fusion pair is set. ${USAGE}`, "info");
-        return;
-      }
-      settings.write(selection);
-      provider.rebuildModels();
-      // Pi keeps model and availability snapshots. Rebuild them without network so `/model` and RPC lists update immediately.
-      await ctx.modelRegistry.refresh({ providers: ["devin"], allowNetwork: false });
-      const after = currentFusion(provider);
-      if (after && ctx.model?.provider === "devin" && ctx.model.id === FUSION_MODEL_ID) await pi.setModel(after);
-      ctx.ui.notify(after ? `Saved ${after.name}. Pick Devin Fusion in /model to use it.` : "The Fusion pair was saved, but it cannot be built from the current model list.", "info");
-    },
-  });
-}

package/src/pi/fusion-settings.ts

@@ -1,44 +0,0 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import type { FusionSelection } from "./models.ts";
-
-const SCHEMA_VERSION = 1;
-
-/** Global store for the lead and sidekick chosen with `/devin-fusion`. Every session uses the same value. */
-export interface FusionSettings {
-  read(): FusionSelection | undefined;
-  write(selection: FusionSelection): void;
-}
-
-export function fusionSettingsPath(agentDir: string): string {
-  return join(agentDir, "pi-devin", "fusion.json");
-}
-
-/** Default store so SDK callers that register the extension directly, and tests, never write to the real agent directory. */
-export function memoryFusionSettings(initial?: FusionSelection): FusionSettings {
-  let current = initial;
-  return { read: () => current, write: (selection) => { current = { ...selection }; } };
-}
-
-/** An unreadable or malformed file reads as no saved value and is not overwritten. Writes are replaced atomically within the same directory. */
-export function fileFusionSettings(path: string): FusionSettings {
-  return {
-    read() {
-      try {
-        const value = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
-        // Legacy IDs (`family:…`, `uid:…`) are read as is. `effectiveFusion` maps them to the current catalog's IDs.
-        if (value.schemaVersion === SCHEMA_VERSION && typeof value.leadID === "string" && value.leadID.trim() !== ""
-          && typeof value.sidekickID === "string" && value.sidekickID.trim() !== "") {
-          return { leadID: value.leadID, sidekickID: value.sidekickID };
-        }
-      } catch { /* A missing or corrupt file falls back to the default pair. */ }
-      return undefined;
-    },
-    write(selection) {
-      mkdirSync(dirname(path), { recursive: true });
-      const temporary = `${path}.${process.pid}.tmp`;
-      writeFileSync(temporary, JSON.stringify({ schemaVersion: SCHEMA_VERSION, leadID: selection.leadID, sidekickID: selection.sidekickID }, null, 2) + "\n");
-      renameSync(temporary, path);
-    },
-  };
-}

package/src/pi/lifecycle.ts

@@ -1,217 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { awaitWithSignal } from "../core/protocol/transport.ts";
-
-export const DEVIN_STATE_ENTRY = "pi-devin.state.v1";
-export type ExecutionKind = "agent" | "pending" | "manual" | "tree" | "direct" | "recovered";
-export interface DevinSessionState {
-  version: 1;
-  sessionId: string;
-  ownerHash?: string;
-  cascadeId: string;
-  trajectoryId: string;
-  nextStepIndex: number;
-  execution?: { id: string; used: number; settled: boolean; kind: ExecutionKind };
-}
-export interface SessionBinding {
-  getSessionId(): string;
-  getBranch(): readonly { type: string; customType?: string; data?: unknown }[];
-  append(data: DevinSessionState): void;
-}
-interface Execution {
-  data: NonNullable<DevinSessionState["execution"]>;
-  controller: AbortController;
-  tail: Promise<void>;
-  cleanups: Set<() => void>;
-  activeRequests: number;
-  hasStarted: boolean;
-  nextIsRecovery: boolean;
-  hasCheckpoint: boolean;
-}
-export interface RequestLease {
-  signal: AbortSignal;
-  executionId: string;
-  cascadeId: string;
-  trajectoryId: string;
-  sessionId: string;
-  stepIndex: number;
-  isAuxiliary: boolean;
-  isRecovery: boolean;
-  consume(): void;
-  addCleanup(cleanup: () => void): void;
-  release(): void;
-}
-export class ModelBudgetError extends Error {
-  constructor(limit: number) { super(`Used all ${limit} Devin model HTTP requests in the budget.`); this.name = "ModelBudgetError"; }
-}
-
-/** Value of `PI_DEVIN_MAX_MODEL_CALLS`. Defaults to 8; anything other than an integer from 1 to 100 stops the extension from loading. */
-export function modelCallLimit(value: string | undefined): number | undefined {
-  if (value === undefined || value === "") return undefined;
-  if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 100) throw new Error("PI_DEVIN_MAX_MODEL_CALLS must be an integer from 1 to 100.");
-  return Number(value);
-}
-const cancelled = () => new DOMException("The previous Devin run ended.", "AbortError");
-const isUUID = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
-
-function restoreState(binding: SessionBinding): DevinSessionState {
-  const sessionId = binding.getSessionId();
-  const entry = [...binding.getBranch()].reverse().find((entry) => entry.type === "custom" && entry.customType === DEVIN_STATE_ENTRY);
-  if (!entry) return { version: 1, sessionId, cascadeId: randomUUID(), trajectoryId: randomUUID(), nextStepIndex: 0 };
-  const value = entry.data as DevinSessionState | undefined;
-  if (!value || value.version !== 1 || typeof value.sessionId !== "string" || !isUUID(value.cascadeId) || !isUUID(value.trajectoryId)
-    || !Number.isSafeInteger(value.nextStepIndex) || value.nextStepIndex < 0 || value.nextStepIndex > 2_147_483_647
-    || (value.ownerHash !== undefined && !/^[a-f0-9]{64}$/.test(value.ownerHash))
-    || (value.execution !== undefined && (!isUUID(value.execution.id) || !Number.isSafeInteger(value.execution.used)
-      || value.execution.used < 0 || value.execution.used > 100 || typeof value.execution.settled !== "boolean"))) {
-    throw new Error("The Devin session state is corrupt or an unsupported version. Start a new session.");
-  }
-  if (value.sessionId !== sessionId) return { version: 1, sessionId, cascadeId: randomUUID(), trajectoryId: randomUUID(), nextStepIndex: 0 };
-  return structuredClone(value);
-}
-
-/** One instance owns one Pi runtime. It never builds its own tool or retry loop. */
-export class DevinLifecycle {
-  private binding?: SessionBinding;
-  private state: DevinSessionState = { version: 1, sessionId: randomUUID(), cascadeId: randomUUID(), trajectoryId: randomUUID(), nextStepIndex: 0 };
-  private execution?: Execution;
-  private isClosed = false;
-  private isAuxiliary = false;
-  readonly maxModelCalls: number;
-  constructor(maxModelCalls = 8) {
-    if (!Number.isSafeInteger(maxModelCalls) || maxModelCalls < 1 || maxModelCalls > 100) throw new Error("The Devin request budget must be between 1 and 100.");
-    this.maxModelCalls = maxModelCalls;
-  }
-  snapshot(): DevinSessionState { return structuredClone(this.state); }
-  /** Model requests of the running or last finished run. used is 0 when this session has no run yet. */
-  budget(): { used: number; limit: number; isActive: boolean } {
-    const execution = this.state.execution;
-    return { used: execution?.used ?? 0, limit: this.maxModelCalls, isActive: execution !== undefined && !execution.settled };
-  }
-  private checkpoint(): void {
-    if (this.binding && this.binding.getSessionId() !== this.state.sessionId) throw cancelled();
-    this.binding?.append(structuredClone(this.state));
-  }
-  private activate(data: NonNullable<DevinSessionState["execution"]>, hasCheckpoint = false): Execution {
-    this.state.execution = data;
-    return this.execution = { data, controller: new AbortController(), tail: Promise.resolve(), cleanups: new Set(), activeRequests: 0, hasStarted: false, nextIsRecovery: false, hasCheckpoint };
-  }
-  attach(binding: SessionBinding): void {
-    this.abort(cancelled());
-    this.binding = binding;
-    this.state = restoreState(binding);
-    this.execution = undefined; this.isClosed = false; this.isAuxiliary = false;
-    if (this.state.execution && !this.state.execution.settled) {
-      this.activate({ ...this.state.execution, kind: "recovered" }, true);
-    }
-  }
-  begin(kind: ExecutionKind): void {
-    if (this.isClosed) throw cancelled();
-    if (this.execution && !this.execution.data.settled) {
-      if (kind === "agent" && ["pending", "recovered"].includes(this.execution.data.kind)) this.execution.data.kind = "agent";
-      else if (kind === "agent" && ["manual", "tree", "direct"].includes(this.execution.data.kind) && this.execution.activeRequests === 0) this.finish();
-      else return; // Retries and tool follow-up calls do not get a new budget.
-      if (this.execution) return;
-    }
-    this.activate({ id: randomUUID(), used: 0, settled: false, kind });
-  }
-  agentStarted(): void {
-    if (!this.execution) this.begin("agent");
-    this.execution!.nextIsRecovery = this.execution!.hasStarted;
-    this.execution!.hasStarted = true;
-  }
-  beforeCompaction(reason: "manual" | "threshold" | "overflow"): void {
-    this.begin(reason === "manual" ? "manual" : "pending");
-    this.isAuxiliary = true;
-  }
-  afterCompaction(reason: "manual" | "threshold" | "overflow"): void {
-    this.isAuxiliary = false;
-    if (reason === "manual" && this.execution?.data.kind === "manual") this.finish();
-  }
-  beforeTree(): void { this.begin("tree"); this.isAuxiliary = true; }
-  finish(): void {
-    if (!this.execution) return;
-    this.execution.data.settled = true;
-    this.abort(cancelled());
-    if (this.execution.hasCheckpoint) this.checkpoint();
-    this.execution = undefined; this.isAuxiliary = false;
-  }
-  abort(reason: unknown): void {
-    const active = this.execution;
-    if (!active) return;
-    if (!active.controller.signal.aborted) active.controller.abort(reason);
-    for (const cleanup of active.cleanups) { try { cleanup(); } catch { /* A cleanup error must not skip releasing other resources. */ } }
-  }
-  shutdown(): void {
-    if (this.isClosed) return;
-    this.abort(cancelled());
-    // An unfinished budget stays in the checkpoint so a reload cannot reset the limit.
-    this.isClosed = true;
-  }
-  treeChanged(): void {
-    if (!this.binding) return;
-    this.abort(cancelled());
-    this.state = restoreState(this.binding);
-    this.state.trajectoryId = randomUUID(); this.state.nextStepIndex = 0;
-    this.state.execution = undefined; this.execution = undefined; this.isAuxiliary = false;
-    if (this.state.ownerHash) this.checkpoint();
-  }
-  async acquire(ownerHash: string, callerSignal?: AbortSignal): Promise<RequestLease> {
-    if (this.isClosed) throw cancelled();
-    callerSignal?.throwIfAborted();
-    if (!/^[a-f0-9]{64}$/.test(ownerHash)) throw new Error("A verified Devin account scope is required.");
-    if (this.state.ownerHash && this.state.ownerHash !== ownerHash) throw new Error("This Pi session is bound to a different Devin account or endpoint. Start a new session.");
-    this.state.ownerHash = ownerHash;
-    if (!this.execution) this.begin("direct");
-    const active = this.execution!, state = this.state;
-    const signal = AbortSignal.any([active.controller.signal, ...(callerSignal ? [callerSignal] : [])]);
-    const previous = active.tail;
-    let releaseQueue!: () => void;
-    const completed = new Promise<void>((resolve) => { releaseQueue = resolve; });
-    active.tail = previous.then(() => completed);
-    let hasReleased = false, hasAcquired = false;
-    const ownCleanups = new Set<() => void>();
-    const clean = () => { for (const cleanup of ownCleanups) { try { cleanup(); } catch {} } };
-    const assertCurrent = () => {
-      signal.throwIfAborted();
-      if (this.execution !== active || this.state !== state || this.isClosed || (this.binding && this.binding.getSessionId() !== state.sessionId)) throw cancelled();
-    };
-    const release = () => {
-      if (hasReleased) return;
-      hasReleased = true;
-      signal.removeEventListener("abort", clean);
-      for (const cleanup of ownCleanups) { active.cleanups.delete(cleanup); try { cleanup(); } catch {} }
-      if (hasAcquired) active.activeRequests--;
-      releaseQueue();
-    };
-    try {
-      await awaitWithSignal(previous, signal);
-      assertCurrent();
-      if (active.data.used >= this.maxModelCalls) throw new ModelBudgetError(this.maxModelCalls);
-      if (state.nextStepIndex >= 2_147_483_647) throw new Error("The Devin step number limit was reached. Start a new session.");
-      active.activeRequests++; hasAcquired = true;
-      const stepIndex = state.nextStepIndex++;
-      active.hasCheckpoint = true;
-      this.checkpoint();
-      signal.addEventListener("abort", clean, { once: true });
-      const isAuxiliary = this.isAuxiliary;
-      const isRecovery = !isAuxiliary && active.nextIsRecovery;
-      if (!isAuxiliary) active.nextIsRecovery = false;
-      return {
-        signal, executionId: active.data.id, cascadeId: state.cascadeId, trajectoryId: state.trajectoryId,
-        sessionId: state.sessionId, stepIndex,
-        isAuxiliary, isRecovery,
-        consume: () => {
-          assertCurrent();
-          if (active.data.used >= this.maxModelCalls) { const error = new ModelBudgetError(this.maxModelCalls); this.abort(error); throw error; }
-          active.data.used++; this.checkpoint();
-        },
-        addCleanup: (cleanup) => {
-          let hasCleaned = false;
-          const once = () => { if (!hasCleaned) { hasCleaned = true; cleanup(); } };
-          ownCleanups.add(once); active.cleanups.add(once); if (signal.aborted) once();
-        },
-        release,
-      };
-    } catch (error) { release(); throw error; }
-  }
-}