@buyong/pi-devin 0.1.4 → 0.1.6

package/src/pi/adapters/pi/sidekick-tool.ts

@@ -0,0 +1,45 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Effect, Layer, type ManagedRuntime } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import { SIDEKICK_REPORT_MESSAGE, SIDEKICK_TOOL_NAME } from "../../features/sidekick/prompts.ts";
+import { SidekickHost, Sidekicks } from "../../features/sidekick/service.ts";
+
+/** The lead Pi as the sidekick sees it. */
+export const PiSidekickHost = (pi: ExtensionAPI) => Layer.succeed(SidekickHost, {
+  activeTools: Effect.sync(() => pi.getActiveTools()),
+  deliverReport: (report) => Effect.sync(() => {
+    pi.sendMessage({ customType: SIDEKICK_REPORT_MESSAGE, display: true, content: report.content, details: report.details }, { deliverAs: "followUp", triggerTurn: true });
+  }),
+});
+
+/**
+ * The lead's `devin_sidekick` tool. The sidekick runs as one child Pi process per lead session and uses the lead's active tools.
+ * By default it waits for the report; with `block: false`, or when a user message arrives while waiting, it moves to the background and delivers the report once.
+ */
+export function sidekickTool(runtime: ManagedRuntime.ManagedRuntime<Sidekicks, DevinError>): ToolDefinition {
+  const sidekicks = runtime.runSync(Sidekicks);
+  return {
+    name: SIDEKICK_TOOL_NAME,
+    label: "Sidekick",
+    description: "Delegate hands-on work to your persistent sidekick, a separate coding agent that shares this workspace and your tools. "
+      + "Put the task context and done criteria in `message`. By default the call waits and returns the sidekick's report; "
+      + "set `block` to false to continue while it works, and the report arrives later as a message. "
+      + "Calling it while the sidekick is busy adds instructions to the running handoff.",
+    promptSnippet: "Delegate hands-on work to a persistent sidekick agent and get its report",
+    parameters: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "Brief for the sidekick: context, the task, and done criteria." },
+        block: { type: "boolean", description: "Wait for the report (default true). Use false to keep working while the sidekick runs." },
+      },
+      required: ["message"],
+      additionalProperties: false,
+    } as unknown as ToolDefinition["parameters"],
+    defaultActive: false,
+    executionMode: "sequential",
+    execute: (_toolCallId, params, signal, onUpdate, ctx) => runtime.runPromise(sidekicks.handoff({
+      params, model: ctx.model, cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId(), isSessionSaved: Boolean(ctx.sessionManager.getSessionFile()), signal,
+      onProgress: (text, details) => onUpdate?.({ content: [{ type: "text", text }], details }),
+    })),
+  };
+}

package/src/pi/adapters/pi/transcript.ts

@@ -0,0 +1,177 @@
+import { randomUUID } from "node:crypto";
+import { getCurrentSystemPrompt, getCurrentTools, type AssistantMessage, type TranscriptContext } from "@earendil-works/pi-ai";
+import { Effect, Predicate } from "effect";
+import { DevinError } from "../../../core/errors.ts";
+import { imageFromBase64, MAX_IMAGES_BYTES } from "../../../core/inference/images.ts";
+import type { ChatMessage, ChatTool, ModelInfo } from "../../../core/types.ts";
+import { failWith, object, requiredString } from "../../../core/validation.ts";
+import { DEVIN_API } from "../../features/catalog/constants.ts";
+
+const REPLAY_PREFIX = "devin:v1:";
+const replayStrings = ["signature", "signatureType", "geminiThoughtSignature", "outputId", "thinkingId", "phase", "modelUid"] as const;
+type ReplayMetadata = Pick<ChatMessage, typeof replayStrings[number] | "thinkingRedacted">;
+export interface DevinTranscript { messages: ChatMessage[]; tools: ChatTool[]; systemPrompt: string }
+
+export function encodeReplayMetadata(message: ChatMessage): string {
+  const metadata: ReplayMetadata = {};
+  for (const key of replayStrings) if (message[key] !== undefined) metadata[key] = message[key];
+  if (message.thinkingRedacted !== undefined) metadata.thinkingRedacted = message.thinkingRedacted;
+  return REPLAY_PREFIX + JSON.stringify(metadata);
+}
+
+function replayMetadata(value: string | undefined): Effect.Effect<ReplayMetadata | undefined, DevinError> {
+  if (!value?.startsWith(REPLAY_PREFIX)) return Effect.succeed(undefined);
+  return Effect.gen(function* () {
+    const parsed = yield* Effect.try({ try: () => JSON.parse(value.slice(REPLAY_PREFIX.length)) as unknown, catch: () => undefined }).pipe(
+      Effect.flatMap((json) => object(json, "Devin replay metadata")),
+      Effect.mapError(() => new DevinError({ message: "Invalid Devin response replay metadata." })),
+    );
+    const result: ReplayMetadata = {};
+    for (const key of replayStrings) {
+      const field = parsed[key];
+      if (field !== undefined && !Predicate.isString(field)) return yield* failWith("Unexpected Devin response replay metadata format.");
+      if (Predicate.isString(field)) result[key] = field;
+    }
+    if (parsed.thinkingRedacted !== undefined) {
+      if (!Predicate.isBoolean(parsed.thinkingRedacted)) return yield* failWith("Invalid Devin redacted thinking metadata.");
+      result.thinkingRedacted = parsed.thinkingRedacted;
+    }
+    return result;
+  });
+}
+
+/** Stores the native response metadata on every content block, so the next request can replay it exactly. */
+export function attachReplayMetadata(output: AssistantMessage, message: ChatMessage): void {
+  const signature = encodeReplayMetadata(message);
+  for (const block of output.content) {
+    if (block.type === "thinking") block.thinkingSignature = signature;
+    else if (block.type === "text") block.textSignature = signature;
+    else block.thoughtSignature = signature;
+  }
+}
+
+const NON_VISION_USER_IMAGE_PLACEHOLDER = "(image omitted: model does not support images)";
+const NON_VISION_TOOL_IMAGE_PLACEHOLDER = "(tool image omitted: model does not support images)";
+const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"]);
+const SCHEMA_DATA = new Set(["enum", "const", "default", "examples", "example"]);
+
+/** Devin's own tools give every schema a single `type`; its Gemini route rejects a list such as `["integer", "null"]`. */
+function toDevinToolSchema(schema: unknown): unknown {
+  if (Array.isArray(schema)) return schema.map(toDevinToolSchema);
+  if (!schema || typeof schema !== "object") return schema;
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (SCHEMA_DATA.has(key)) result[key] = value;
+    else if (SCHEMA_MAPS.has(key) && Predicate.isObject(value)) {
+      result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, toDevinToolSchema(child)]));
+    } else if (key === "type" && Array.isArray(value)) {
+      // Omitting the field still covers null; several remaining types become one branch each.
+      const types = value.filter((type) => type !== "null");
+      if (types.length === 1) result.type = types[0];
+      else if (types.length > 1 && !("anyOf" in schema)) result.anyOf = types.map((type) => ({ type }));
+      else result.type = value;
+    } else result[key] = toDevinToolSchema(value);
+  }
+  return result;
+}
+
+function toolDeclarations(context: TranscriptContext, model: ModelInfo): Effect.Effect<ChatTool[], DevinError> {
+  return Effect.gen(function* () {
+    const declarations = getCurrentTools(context.messages);
+    if (declarations.length && !model.supportsToolCalls) return yield* failWith("This model does not support the current Pi tool declarations.");
+    const tools: ChatTool[] = [];
+    for (const tool of declarations) {
+      // Grammar sampling is optional; like Pi's providers without grammar tools, send the JSON schema instead.
+      if (tool.constrainedSampling && tool.constrainedSampling.type === "json_schema" && tool.constrainedSampling.strict === "require") {
+        return yield* failWith(`Devin does not support this tool's forced sampling format: ${tool.name}`);
+      }
+      tools.push({ name: tool.name, description: tool.description, jsonSchemaString: JSON.stringify(toDevinToolSchema(tool.parameters)) });
+    }
+    return tools;
+  });
+}
+
+type ContextMessage = TranscriptContext["messages"][number];
+
+/** A successful assistant response with its own replay metadata, never a failed or unfinished one. */
+function assistantMessage(message: Extract<ContextMessage, { role: "assistant" }>): Effect.Effect<ChatMessage, DevinError> {
+  return Effect.gen(function* () {
+    const own = message.provider === "devin" && message.api === DEVIN_API;
+    const result: ChatMessage = { messageId: message.responseId ?? randomUUID(), source: "CHAT_MESSAGE_SOURCE_SYSTEM", prompt: "" };
+    let replay: ReplayMetadata | undefined;
+    for (const block of message.content) {
+      if (block.type === "text") result.prompt += block.text;
+      else if (block.type === "thinking") {
+        if (!block.redacted) result.thinking = (result.thinking ?? "") + block.thinking;
+        else result.thinkingRedacted = true;
+      } else {
+        result.toolCalls ??= [];
+        result.toolCalls.push({ id: yield* requiredString(block.id, "tool call id"), name: block.namespace ? `${block.namespace}.${block.name}` : block.name,
+          argumentsJson: JSON.stringify(yield* object(block.arguments, "tool arguments")) });
+      }
+      if (own) {
+        const metadata = yield* replayMetadata(block.type === "text" ? block.textSignature : block.type === "thinking" ? block.thinkingSignature : block.thoughtSignature);
+        if (metadata) {
+          if (replay && JSON.stringify(replay) !== JSON.stringify(metadata)) return yield* failWith("Devin replay metadata differs within one response.");
+          replay = metadata;
+        }
+      }
+    }
+    Object.assign(result, replay);
+    if (own && message.providerThinkingLevel) result.modelUid = message.providerThinkingLevel;
+    if (result.thinkingRedacted) result.thinking = "";
+    return result;
+  });
+}
+
+/** A user message or tool result with its images, within the per-message image budget. */
+function inputMessage(message: Exclude<ContextMessage, { role: "assistant" | "system" }>, model: ModelInfo): Effect.Effect<ChatMessage, DevinError> {
+  return Effect.gen(function* () {
+    const result: ChatMessage = {
+      messageId: randomUUID(), source: message.role === "toolResult" ? "CHAT_MESSAGE_SOURCE_TOOL" : "CHAT_MESSAGE_SOURCE_USER", prompt: "",
+      ...(message.role === "toolResult" ? { toolCallId: message.toolCallId, toolResultIsError: message.isError } : {}),
+    };
+    let imageBytes = 0, isAfterPlaceholder = false;
+    const content = typeof message.content === "string" ? [{ type: "text" as const, text: message.content }] : message.content;
+    for (const block of content) {
+      if (block.type === "text") {
+        result.prompt += block.text; isAfterPlaceholder = false;
+      } else if (!model.supportsImages) {
+        // Like Pi's own providers: a text-only model gets a note instead, so earlier images do not stop the conversation.
+        if (!isAfterPlaceholder) result.prompt += message.role === "toolResult" ? NON_VISION_TOOL_IMAGE_PLACEHOLDER : NON_VISION_USER_IMAGE_PLACEHOLDER;
+        isAfterPlaceholder = true;
+      } else {
+        const converted = yield* imageFromBase64(block.data, block.mimeType);
+        imageBytes += converted.sizeBytes;
+        if (imageBytes > MAX_IMAGES_BYTES) return yield* failWith(`Images in one message must total at most ${MAX_IMAGES_BYTES} bytes.`);
+        (result.images ??= []).push(converted.image);
+      }
+    }
+    return result;
+  });
+}
+
+/** Pi history as Devin chat messages. Failed or aborted assistants and the results of their tool calls are not replayed. */
+export function toDevinTranscript(context: TranscriptContext, model: ModelInfo): Effect.Effect<DevinTranscript, DevinError> {
+  return Effect.gen(function* () {
+    const tools = yield* toolDeclarations(context, model);
+    // Results follow their assistant, so only the calls of the latest failed assistant are skipped. A later failure that
+    // reuses an earlier call ID leaves the earlier result in place.
+    let failedCalls = new Set<string>();
+    const messages: ChatMessage[] = [];
+    for (const message of context.messages) {
+      if (message.role === "system") continue;
+      if (message.role === "assistant") {
+        const isFailed = message.stopReason === "error" || message.stopReason === "aborted";
+        failedCalls = new Set(isFailed ? message.content.filter((block) => block.type === "toolCall").map((block) => block.id) : []);
+        if (isFailed) continue;
+        if (message.stopReason === "pending") return yield* failWith("An unfinished assistant response cannot be sent as Devin history.");
+        messages.push(yield* assistantMessage(message));
+        continue;
+      }
+      if (message.role === "toolResult" && failedCalls.has(message.toolCallId)) continue;
+      messages.push(yield* inputMessage(message, model));
+    }
+    return { messages, tools, systemPrompt: getCurrentSystemPrompt(context.messages) };
+  });
+}

package/src/pi/adapters/pi/types.ts

@@ -0,0 +1,14 @@
+import type { Provider } from "@earendil-works/pi-ai";
+import type { ExtensionRuntime } from "../../app/runtime.ts";
+import type { DevinAPI } from "../../features/catalog/types.ts";
+
+/** Pi's provider contract, and nothing else: extension features reach the services through the runtime. */
+export interface DevinProvider extends Provider<DevinAPI> {
+  refreshModels: NonNullable<Provider<DevinAPI>["refreshModels"]>;
+}
+
+/** A registered extension instance: the provider Pi holds and the runtime its handlers run on. */
+export interface DevinExtension {
+  readonly provider: DevinProvider;
+  readonly runtime: ExtensionRuntime;
+}

package/src/pi/{devin-panel.ts → adapters/pi/ui/devin-panel.ts}

@@ -1,11 +1,13 @@
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import type { DevinPreferences } from "./devin-settings.ts";
+import { Cause, Effect, Exit } from "effect";
+import type { DevinError } from "../../../../core/errors.ts";
+import type { DevinPreferences } from "../../../features/settings/types.ts";
+import type { UsageLine } from "../../../features/usage/types.ts";
 import type { PickerTheme } from "./fusion-picker.ts";
-import type { UsageLine } from "./usage.ts";
 
 export const PREFERENCE_ITEMS: readonly { key: keyof DevinPreferences; label: string; detail: string }[] = [
   { key: "recommendedOnly", label: "Recommended models only", detail: "/model shows only models with a recommended variant and Devin Fusion" },
-  { key: "showUsageStatus", label: "Usage in status line", detail: "shows quota and session tokens in the footer" },
+  { key: "showUsageStatus", label: "Usage in status line", detail: "shows quota and session tokens in the footer while a Devin model is selected" },
 ];
 const HELP = "↑↓ move · space/↵ toggle · esc close";
 
@@ -14,7 +16,7 @@ export interface DevinPanelOptions {
   report: () => UsageLine[];
   preferences: DevinPreferences;
   /** Saves and applies on every toggle. On failure, shows a notice and reverts to the previous value. */
-  onChange: (next: DevinPreferences) => Promise<void>;
+  onChange: (next: DevinPreferences) => Effect.Effect<void, DevinError>;
   requestRender: () => void;
   done: () => void;
 }
@@ -48,14 +50,14 @@ export class DevinPanel {
     const key = PREFERENCE_ITEMS[this.cursor].key, previous = this.preferences;
     this.preferences = { ...previous, [key]: !previous[key] };
     this.isSaving = true; this.notice = undefined; this.changed();
-    try {
-      await this.options.onChange(this.preferences);
-    } catch (error) {
+    const exit = await Effect.runPromiseExit(this.options.onChange(this.preferences));
+    if (Exit.isFailure(exit)) {
       this.preferences = previous;
+      // A thrown host error is reported with its own message, like a failed save.
+      const error = Cause.squash(exit.cause);
       this.notice = `Could not save: ${error instanceof Error ? error.message : String(error)}`;
-    } finally {
-      this.isSaving = false; this.changed();
     }
+    this.isSaving = false; this.changed();
   }
 
   render(width: number): string[] {

package/src/pi/{fusion-picker.ts → adapters/pi/ui/fusion-picker.ts}

@@ -1,6 +1,6 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { decodeKittyPrintable, fuzzyFilter, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import type { FusionChoices, FusionSelection } from "./models.ts";
+import type { FusionChoices, FusionSelection } from "../../../features/catalog/types.ts";
 
 export type PickerTheme = Pick<Theme, "fg" | "bold">;
 interface Item { id: string; name: string; recommended?: true }

package/src/pi/adapters/pi/usage-status.ts

@@ -0,0 +1,65 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Context, Effect, Layer } from "effect";
+import { ExtensionConfig } from "../../app/config.ts";
+import { Accounts } from "../../features/accounts/service.ts";
+import { ModelCatalog } from "../../features/catalog/service.ts";
+import { DisplaySettings } from "../../features/settings/service.ts";
+import { UsageChanges } from "../../features/usage/changes.ts";
+import { sessionUsage, usageStatusText } from "../../features/usage/report.ts";
+import type { AccountsShape } from "../../features/accounts/types.ts";
+import type { ModelCatalogShape } from "../../features/catalog/types.ts";
+import type { AccountUsage } from "../../features/usage/types.ts";
+
+/** The only status key this package uses. */
+export const USAGE_STATUS_KEY = "devin-usage";
+
+export interface UsageStatusShape {
+  /** Newest quota for the credential of the last model refresh. Makes no request. */
+  readonly accountUsage: Effect.Effect<AccountUsage | undefined>;
+  /**
+   * Draws the status in the TUI only, while the session's current model is a Devin model, from the last account status and
+   * the session records. `pendingMessage` is a response Pi has not stored yet. Another provider's model or turning the toggle
+   * off clears only this package's key; `/devin` reports usage whatever the model.
+   */
+  readonly update: (context: ExtensionContext, pendingMessage?: unknown) => Effect.Effect<void>;
+  /** The session whose status line follows quota changes that happen outside event handlers. */
+  readonly bind: (context: ExtensionContext | undefined) => Effect.Effect<void>;
+}
+
+export class UsageStatus extends Context.Service<UsageStatus, UsageStatusShape>()("pi-devin/UsageStatus") {}
+
+/** Newest quota for the credential of the last model refresh: the account `/devin` and the status line show. Makes no request. */
+export const currentAccountUsage = (catalog: ModelCatalogShape, accounts: AccountsShape): Effect.Effect<AccountUsage | undefined> =>
+  Effect.flatMap(catalog.currentScope, (scope) => scope ? accounts.usage(scope) : Effect.succeed(undefined));
+
+/** Pi stores a message only after every `message_end` handler ran, so a just-finished response is counted explicitly. */
+function branchWith(context: ExtensionContext, pendingMessage: unknown): readonly unknown[] {
+  const branch = context.sessionManager.getBranch();
+  if (!pendingMessage || branch.some((entry) => entry.type === "message" && entry.message === pendingMessage)) return branch;
+  return [...branch, { type: "message", message: pendingMessage }];
+}
+
+export const UsageStatusLive = Layer.effect(UsageStatus, Effect.gen(function* () {
+  const config = yield* ExtensionConfig;
+  const settings = yield* DisplaySettings;
+  const accounts = yield* Accounts;
+  const catalog = yield* ModelCatalog;
+  const changes = yield* UsageChanges;
+  let bound: ExtensionContext | undefined;
+  const accountUsage = currentAccountUsage(catalog, accounts);
+  // The sidekick child shows no status line.
+  const update = (context: ExtensionContext, pendingMessage?: unknown) => config.isFusionChild ? Effect.void : Effect.gen(function* () {
+    if (context.mode !== "tui") return;
+    const isShown = context.model?.provider === "devin" && (yield* settings.read).showUsageStatus;
+    const text = isShown
+      ? usageStatusText(yield* accountUsage, sessionUsage(branchWith(context, pendingMessage)), (tone, segment) => context.ui.theme.fg(tone, segment)) : undefined;
+    context.ui.setStatus(USAGE_STATUS_KEY, text);
+  });
+  // The session may be replaced or reloaded meanwhile; its next session_start redraws.
+  yield* changes.subscribe(Effect.suspend(() => bound ? update(bound) : Effect.void));
+  return {
+    accountUsage,
+    update,
+    bind: (context) => Effect.sync(() => { bound = context; }),
+  } satisfies UsageStatusShape;
+}));

package/src/pi/adapters/storage/files.ts

@@ -0,0 +1,66 @@
+import { join } from "node:path";
+import { Effect, Layer, Option, Schema } from "effect";
+import { DisplaySettings, DEFAULT_PREFERENCES, FusionSettings, isNotOlder, UsageStore } from "../../features/settings/service.ts";
+import type { DisplaySettingsShape, FusionSettingsShape, UsageStoreShape } from "../../features/settings/types.ts";
+import type { FusionSelection } from "../../features/catalog/types.ts";
+import { readJsonFile, writeJsonFile } from "./json-file.ts";
+
+const SCHEMA_VERSION = 1;
+
+export const fusionSettingsPath = (agentDir: string) => join(agentDir, "pi-devin", "fusion.json");
+export const devinSettingsPath = (agentDir: string) => join(agentDir, "pi-devin", "settings.json");
+export const accountUsagePath = (agentDir: string) => join(agentDir, "pi-devin", "account-usage.json");
+
+const ModelID = Schema.String.check(Schema.makeFilter((value: string) => value.trim() !== ""));
+// Legacy IDs (`family:…`, `uid:…`) are read as is. `effectiveFusion` maps them to the current catalog's IDs.
+const FusionFile = Schema.Struct({ schemaVersion: Schema.Literal(SCHEMA_VERSION), leadID: ModelID, sidekickID: ModelID });
+const SettingsFile = Schema.Struct({ schemaVersion: Schema.Literal(SCHEMA_VERSION), recommendedOnly: Schema.Boolean, showUsageStatus: Schema.Boolean });
+const Percent = Schema.optionalKey(Schema.Finite);
+const UsageRecord = Schema.Struct({
+  schemaVersion: Schema.Literal(SCHEMA_VERSION),
+  scope: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+  usage: Schema.Struct({
+    fetchedAtMs: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })),
+    billingStrategy: Schema.optionalKey(Schema.String),
+    dailyRemainingPercent: Percent,
+    weeklyRemainingPercent: Percent,
+    dailyResetAtMs: Percent,
+    weeklyResetAtMs: Percent,
+  }),
+});
+
+/** 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): FusionSettingsShape {
+  return {
+    read: Effect.map(readJsonFile(path, FusionFile), Option.match({
+      onNone: () => undefined,
+      onSome: (value): FusionSelection => ({ leadID: value.leadID, sidekickID: value.sidekickID }),
+    })),
+    write: (selection) => writeJsonFile(path, { schemaVersion: SCHEMA_VERSION, leadID: selection.leadID, sidekickID: selection.sidekickID }),
+  };
+}
+
+/** An unreadable or malformed file reads as the defaults and is not overwritten. Writes are replaced atomically within the same directory. */
+export function fileDisplaySettings(path: string): DisplaySettingsShape {
+  return {
+    read: Effect.map(readJsonFile(path, SettingsFile), Option.match({
+      onNone: () => ({ ...DEFAULT_PREFERENCES }),
+      onSome: (value) => ({ recommendedOnly: value.recommendedOnly, showUsageStatus: value.showUsageStatus }),
+    })),
+    write: (preferences) => writeJsonFile(path, { schemaVersion: SCHEMA_VERSION, ...preferences }),
+  };
+}
+
+/** An unreadable or malformed file reads as no record and is not repaired by reading. Writes are replaced atomically within the same directory. */
+export function fileUsageStore(path: string): UsageStoreShape {
+  const readRecord = readJsonFile(path, UsageRecord);
+  return {
+    read: (scope) => Effect.map(readRecord, (record) => Option.isSome(record) && record.value.scope === scope ? { ...record.value.usage } : undefined),
+    write: (scope, usage) => Effect.flatMap(readRecord, (current) => Option.isSome(current) && current.value.scope === scope && !isNotOlder(current.value.usage, usage)
+      ? Effect.void : writeJsonFile(path, { schemaVersion: SCHEMA_VERSION, scope, usage })),
+  };
+}
+
+export const FusionSettingsFile = (path: string) => Layer.succeed(FusionSettings, fileFusionSettings(path));
+export const DisplaySettingsFile = (path: string) => Layer.succeed(DisplaySettings, fileDisplaySettings(path));
+export const UsageStoreFile = (path: string) => Layer.succeed(UsageStore, fileUsageStore(path));

package/src/pi/adapters/storage/json-file.ts

@@ -0,0 +1,31 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { Effect, Option, Schema } from "effect";
+import { toDevinError, type DevinError } from "../../../core/errors.ts";
+
+/*
+ * Pi reads these small global files from synchronous callbacks, such as TUI rendering and model list rebuilds,
+ * and other Pi processes may change them at any time. They are therefore read fresh and synchronously on each use;
+ * Effect's FileSystem service is asynchronous only.
+ */
+
+/** The file's value when it exists, parses and matches the schema. A missing or malformed file is never repaired by reading. */
+export function readJsonFile<S extends Schema.ConstraintDecoder<unknown>>(path: string, schema: S): Effect.Effect<Option.Option<S["Type"]>> {
+  const decode = Schema.decodeUnknownOption(schema);
+  return Effect.sync(() => {
+    try { return decode(JSON.parse(readFileSync(path, "utf8"))); } catch { return Option.none(); }
+  });
+}
+
+/** Replaces the file atomically within its directory. */
+export function writeJsonFile(path: string, value: unknown): Effect.Effect<void, DevinError> {
+  return Effect.try({
+    try: () => {
+      mkdirSync(dirname(path), { recursive: true });
+      const temporary = `${path}.${process.pid}.tmp`;
+      writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n");
+      renameSync(temporary, path);
+    },
+    catch: toDevinError,
+  });
+}

package/src/pi/app/config.ts

@@ -0,0 +1,25 @@
+import { Context } from "effect";
+
+export interface LoginSettings {
+  apiServerURL?: string;
+  webappURL?: string;
+  devinAPIURL?: string;
+  timeoutMs?: number;
+}
+
+/** Values the entry point chooses for one extension instance. Read by the services that need them. */
+export interface ExtensionConfigShape {
+  /** Clock of quota timestamps and session check times. */
+  readonly now: () => number;
+  /**
+   * This Pi is the Fusion sidekick child: it lists every exact UID, builds no Fusion entry, ignores the recommended filter,
+   * and registers no sidekick tool, `/devin`, `/devin-fusion` or status line.
+   */
+  readonly isFusionChild: boolean;
+  /** Endpoints and the time limit of `/login`. */
+  readonly login: LoginSettings;
+  /** Pi agent directory that holds sidekick session files. Read when a handoff starts. */
+  readonly agentDir: () => string;
+}
+
+export class ExtensionConfig extends Context.Service<ExtensionConfig, ExtensionConfigShape>()("pi-devin/ExtensionConfig") {}

package/src/pi/app/environment.ts

@@ -0,0 +1,30 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Layer } from "effect";
+import { NodeDeviceIdentitySource } from "../../core/services/device-identity.ts";
+import { NodeHttpTransport, nodeTransport } from "../../core/services/http-transport.ts";
+import { NodePlatformLayer } from "../../core/services/platform.ts";
+import { accountUsagePath, devinSettingsPath, DisplaySettingsFile, fusionSettingsPath, FusionSettingsFile, UsageStoreFile } from "../adapters/storage/files.ts";
+import { LoginTransport } from "../features/auth/login.ts";
+import { DisplaySettings, FusionSettings, memoryDisplaySettings, memoryFusionSettings } from "../features/settings/service.ts";
+import { NodeSidekickLauncher } from "../features/sidekick/launcher.ts";
+import { ExtensionConfig } from "./config.ts";
+import type { ExtensionEnvironment } from "./layer.ts";
+
+/**
+ * The environment Pi loads the extension with: Node's network, process and file services, and the global stores in Pi's agent directory.
+ * The sidekick child keeps no Fusion or display settings, but records its quota so the lead shows what the sidekick used.
+ */
+export function productionEnvironment(options: { isFusionChild: boolean }): Layer.Layer<ExtensionEnvironment> {
+  const agentDir = getAgentDir();
+  const settings = options.isFusionChild
+    ? Layer.mergeAll(Layer.sync(FusionSettings, () => memoryFusionSettings()), Layer.sync(DisplaySettings, () => memoryDisplaySettings()))
+    : Layer.mergeAll(FusionSettingsFile(fusionSettingsPath(agentDir)), DisplaySettingsFile(devinSettingsPath(agentDir)));
+  return Layer.mergeAll(
+    Layer.succeed(ExtensionConfig, { isFusionChild: options.isFusionChild, now: Date.now, login: {}, agentDir: getAgentDir }),
+    NodeHttpTransport(),
+    Layer.succeed(LoginTransport, nodeTransport()),
+    settings,
+    UsageStoreFile(accountUsagePath(agentDir)),
+    NodeSidekickLauncher,
+  ).pipe(Layer.provideMerge(Layer.mergeAll(NodeDeviceIdentitySource.pipe(Layer.provide(NodePlatformLayer)), NodePlatformLayer)));
+}

package/src/pi/app/layer.ts

@@ -0,0 +1,43 @@
+import { Layer, type FileSystem } from "effect";
+import type { DeviceIdentitySource } from "../../core/services/device-identity.ts";
+import type { HttpTransport } from "../../core/services/http-transport.ts";
+import { UsageStatusLive } from "../adapters/pi/usage-status.ts";
+import { AccountsLive } from "../features/accounts/service.ts";
+import { CredentialGuardLive } from "../features/auth/guard.ts";
+import { AccountLoginLive, type LoginTransport } from "../features/auth/login.ts";
+import { AuthStateLive } from "../features/auth/state.ts";
+import { RemoteCatalogLive } from "../features/catalog/remote.ts";
+import { ModelCatalogLive } from "../features/catalog/service.ts";
+import { DevinClientsLive } from "../features/clients/service.ts";
+import { InferenceLive } from "../features/inference/service.ts";
+import { ProviderLifetimeLive } from "../features/lifetime/service.ts";
+import { RunsLive } from "../features/runs/service.ts";
+import type { DisplaySettings, FusionSettings, UsageStore } from "../features/settings/service.ts";
+import type { SidekickLauncher } from "../features/sidekick/launcher.ts";
+import { SidekicksLive } from "../features/sidekick/service.ts";
+import { UsageChangesLive } from "../features/usage/changes.ts";
+import type { ExtensionConfig } from "./config.ts";
+
+/** What the entry point provides for the provider: its values and external I/O. */
+export type ProviderEnvironment = ExtensionConfig | HttpTransport | LoginTransport | DeviceIdentitySource | FusionSettings | DisplaySettings | UsageStore;
+/** The provider environment plus what the extension's host features need. */
+export type ExtensionEnvironment = ProviderEnvironment | SidekickLauncher | FileSystem.FileSystem;
+
+/** State owners that need no other feature. */
+const StateLive = Layer.mergeAll(ProviderLifetimeLive, AuthStateLive, UsageChangesLive, RunsLive);
+
+/**
+ * Features behind Pi's provider contract. Each layer receives the ones below it, so dependencies only point downward:
+ * requests and sign-in use the catalog, which uses the guard and accounts, which use clients and the state owners.
+ */
+export const ProviderLive = Layer.mergeAll(InferenceLive, AccountLoginLive).pipe(
+  Layer.provideMerge(ModelCatalogLive),
+  Layer.provideMerge(RemoteCatalogLive),
+  Layer.provideMerge(CredentialGuardLive),
+  Layer.provideMerge(AccountsLive),
+  Layer.provideMerge(DevinClientsLive),
+  Layer.provideMerge(StateLive),
+);
+
+/** The provider and the features that need Pi's host: the Fusion sidekick and the usage status line. */
+export const ExtensionLive = Layer.mergeAll(SidekicksLive, UsageStatusLive).pipe(Layer.provideMerge(ProviderLive));

package/src/pi/app/runtime.ts

@@ -0,0 +1,20 @@
+import { Layer, ManagedRuntime } from "effect";
+import type { DevinError } from "../../core/errors.ts";
+import type { SidekickHost } from "../features/sidekick/service.ts";
+import { ExtensionLive, ProviderLive, type ExtensionEnvironment, type ProviderEnvironment } from "./layer.ts";
+
+export type ProviderServices = Layer.Success<typeof ProviderLive> | ProviderEnvironment;
+export type ExtensionServices = Layer.Success<typeof ExtensionLive> | ExtensionEnvironment | SidekickHost;
+export type ProviderRuntime = ManagedRuntime.ManagedRuntime<ProviderServices, DevinError>;
+export type ExtensionRuntime = ManagedRuntime.ManagedRuntime<ExtensionServices, DevinError>;
+
+/**
+ * One runtime per extension instance. It is never disposed on `session_shutdown`: Pi may still call the same provider
+ * afterwards, and the next `session_start` reuses it with a new provider lifetime. Its layers hold no operating system
+ * resources; connection pools close with their clients and sidekick children with their sessions.
+ */
+export const makeProviderRuntime = (environment: Layer.Layer<ProviderEnvironment>): ProviderRuntime =>
+  ManagedRuntime.make(ProviderLive.pipe(Layer.provideMerge(environment)));
+
+export const makeExtensionRuntime = (environment: Layer.Layer<ExtensionEnvironment>, host: Layer.Layer<SidekickHost>): ExtensionRuntime =>
+  ManagedRuntime.make(ExtensionLive.pipe(Layer.provideMerge(Layer.mergeAll(environment, host))));

package/src/pi/app/session.ts

@@ -0,0 +1,26 @@
+import { Effect } from "effect";
+import { Cancelled } from "../../core/errors.ts";
+import { Accounts } from "../features/accounts/service.ts";
+import { DevinClients } from "../features/clients/service.ts";
+import { ProviderLifetime } from "../features/lifetime/service.ts";
+import { Runs } from "../features/runs/service.ts";
+import type { SessionBinding } from "../features/runs/types.ts";
+
+/** Binds the provider to Pi's current session: a new provider lifetime if the last one ended, then the session's stored run state. Fails on a corrupt state. */
+export const attachSession = (binding: SessionBinding) => Effect.gen(function* () {
+  yield* (yield* ProviderLifetime).renew;
+  yield* (yield* Runs).attach(binding);
+});
+
+/**
+ * Stops the provider's work. The lifetime ends first, so running requests stop with its reason rather than an interruption;
+ * an unfinished run stays in the session's checkpoint. The extension instance and its runtime stay usable.
+ */
+export const shutdownProvider = Effect.gen(function* () {
+  const clients = yield* DevinClients;
+  yield* (yield* ProviderLifetime).end(new Cancelled({ message: "The Devin provider shut down." }));
+  yield* (yield* Runs).shutdown;
+  yield* clients.closeAll;
+  yield* clients.clearFingerprints;
+  yield* (yield* Accounts).clear;
+});