@buyong/pi-devin 0.1.5 → 0.1.6

package/src/pi/features/inference/request.ts

@@ -0,0 +1,190 @@
+import { clampThinkingLevel, type AssistantMessageEventStream, type Model, type SimpleStreamOptions, type TranscriptContext } from "@earendil-works/pi-ai";
+import { Cause, Effect, Stream } from "effect";
+import { assertCanInfer } from "../../../core/auth/access.ts";
+import { abortWith } from "../../../core/cancellation.ts";
+import { Cancelled, isTransientConnectionFailure, RPCError, toDevinFailure, type DevinFailure } from "../../../core/errors.ts";
+import { ChatAccumulator } from "../../../core/inference/accumulator.ts";
+import { chatRequest } from "../../../core/inference/request.ts";
+import type { BackendModelSelection, EffectiveThinkingLevel } from "../../../core/models/variants.ts";
+import { endpoint } from "../../../core/protocol/endpoint.ts";
+import { CHAT_METHOD } from "../../../core/protocol/protobuf.ts";
+import { safeError } from "../../../core/redaction.ts";
+import type { Credential, JsonObject } from "../../../core/types.ts";
+import { failWith, object, requiredString, tokenCount } from "../../../core/validation.ts";
+import { DevinResponseStream } from "../../adapters/pi/response-stream.ts";
+import { toDevinTranscript } from "../../adapters/pi/transcript.ts";
+import type { AccountsShape } from "../accounts/types.ts";
+import type { AuthStateShape, CredentialGuardShape } from "../auth/types.ts";
+import { isFusionModelID } from "../catalog/constants.ts";
+import { hasExtendedPromptCacheRetention } from "../catalog/projection.ts";
+import type { DevinAPI, ModelCatalogShape } from "../catalog/types.ts";
+import type { DevinClientsShape } from "../clients/types.ts";
+import type { ProviderLifetimeShape } from "../lifetime/types.ts";
+import type { DevinLifecycle } from "../runs/lifecycle.ts";
+import { FUSION_LEAD_GUIDANCE } from "../sidekick/prompts.ts";
+
+/** Services one request uses, resolved once when the inference service is built. */
+export interface InferenceDependencies {
+  auth: AuthStateShape;
+  guard: CredentialGuardShape;
+  catalog: ModelCatalogShape;
+  accounts: AccountsShape;
+  clients: DevinClientsShape;
+  runs: DevinLifecycle;
+  lifetime: ProviderLifetimeShape;
+}
+
+/** One provider call: Pi's event stream, returned at once, and the request that feeds it. */
+export interface InferenceRequest {
+  stream: AssistantMessageEventStream;
+  /** Never fails: every ending closes the stream with exactly one terminal event. */
+  run: Effect.Effect<void>;
+}
+
+/** Connect codes of passing server trouble, in the words Pi's host retry matches. */
+const CONNECT_RETRY_LABELS: Readonly<Record<string, string>> = {
+  resource_exhausted: "Rate limit", internal: "Internal error", deadline_exceeded: "Request timed out",
+};
+
+/**
+ * Pi decides host retries from the message text alone. Node and Connect report failures as codes ("read ECONNRESET",
+ * "resource_exhausted: …") and an error body replaces the HTTP status, so the status or code is kept in words Pi matches.
+ * The original detail stays, so Pi's rules against retrying quota and billing errors still apply.
+ */
+function hostRetryableMessage(error: unknown, message: string): string {
+  if (isTransientConnectionFailure(error)) return `Connection error (${message})`;
+  if (!(error instanceof RPCError)) return message;
+  if (error.httpStatus !== undefined && error.httpStatus >= 400) return message.includes(String(error.httpStatus)) ? message : `HTTP ${error.httpStatus} (${message})`;
+  const label = CONNECT_RETRY_LABELS[error.code];
+  return label ? `${label} (${message})` : message;
+}
+
+/** Like Pi's built-in providers: the caller option wins; otherwise only PI_CACHE_RETENTION=long (provider env first) means long retention. */
+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";
+}
+
+/** A host hook may return a value or a promise and may throw; it is withdrawn when the request stops. */
+const hook = <A>(evaluate: () => A | PromiseLike<A>) => Effect.tryPromise({ try: async () => await evaluate(), catch: toDevinFailure });
+
+/**
+ * Prepares one request synchronously: the response stream (with its start event), the sign-in generation
+ * and the provider lifetime current at the call. The returned `run` sends the request and reports into the stream.
+ */
+export const prepareRequest = (deps: InferenceDependencies, model: Model<DevinAPI>, context: TranscriptContext, requestOptions: SimpleStreamOptions = {}): Effect.Effect<InferenceRequest> => Effect.gen(function* () {
+  const effectiveLevel = (requestOptions.reasoning ?? clampThinkingLevel(model, "off")) as EffectiveThinkingLevel;
+  const response = new DevinResponseStream(model, "");
+  const accumulator = new ChatAccumulator();
+  const generation = yield* deps.auth.generation;
+  const lifetime = yield* deps.lifetime.current;
+  let credential: Credential | undefined, actualUID = "", isRedacted = false;
+
+  const run = Effect.gen(function* () {
+    const current: Credential = {
+      version: 1, sessionToken: yield* requiredString(requestOptions.apiKey, "Devin account authentication (/login required)"),
+      apiServerURL: yield* endpoint(model.baseUrl), createdAt: new Date().toISOString(),
+    };
+    credential = current;
+    // Pi can override the OAuth value with an apiKey in models.json or a caller option. Only OAuth sessions are accepted.
+    yield* deps.auth.assertOAuthSession(current);
+    yield* deps.auth.assertUsable(current);
+    let selected = yield* deps.catalog.resolve(model.id, effectiveLevel, current);
+    actualUID = selected.uid;
+    response.message.providerThinkingLevel = actualUID;
+    // Retries belong to Pi and the only transport is a Connect stream, so `maxRetries` and `transport` preferences are ignored.
+    const cacheRetention = resolveCacheRetention(requestOptions);
+    const assertCacheRetention = (selection: BackendModelSelection) => cacheRetention === "long" && !hasExtendedPromptCacheRetention(selection.variant)
+      ? failWith("Long cache lifetime is not confirmed for this Devin model. Long retention is supported only for models whose catalog Prompt Cache Retention is 24h.")
+      : Effect.void;
+    yield* assertCacheRetention(selected);
+
+    // The per-request account check (permission and quota) runs here, outside Pi's shared credential lock.
+    const known = yield* deps.accounts.get(current);
+    yield* deps.accounts.check(current, {
+      expectedGeneration: generation,
+      connection: { fetch: requestOptions.fetch, timeoutMs: requestOptions.timeoutMs },
+      beforeRecord: deps.auth.assertUsable(current),
+    }).pipe(
+      Effect.flatMap((outcome) => outcome === "stale" ? Effect.fail(new Cancelled({ message: "The Devin authentication generation changed." })) : Effect.void),
+      // A check that cannot reach the server keeps the last known account; the model request reports its own failure.
+      Effect.catch((error) => known && isTransientConnectionFailure(error) ? Effect.void : Effect.fail(error)),
+    );
+    const account = yield* deps.accounts.get(current);
+    if (!account) return yield* failWith("The Devin account check was interrupted.");
+    yield* assertCanInfer(account.status);
+
+    const lease = yield* Effect.acquireRelease(deps.runs.acquire(account.ownerHash), (acquired) => acquired.release);
+    const transcript = yield* 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 : yield* tokenCount(requestOptions.maxTokens, "maxTokens");
+    if (maximum < 1 || maximum > selected.model.maxOutputTokens) return yield* failWith("The output limit is outside the selected Devin model range.");
+    const client = yield* deps.clients.open(current, { fetch: requestOptions.fetch, timeoutMs: requestOptions.timeoutMs,
+      onRequest: (attempt) => attempt.isMetered ? lease.assertAttempt : Effect.void,
+    });
+    yield* lease.addCleanup(client.close);
+    const request = chatRequest({ metadata: yield* 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) return yield* failWith("temperature must be a finite value of 0 or more.");
+      (yield* 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]);
+
+    const frames = client.transport.stream(CHAT_METHOD, request, {
+      headers: requestOptions.headers,
+      onPayload: (payload) => Effect.gen(function* () {
+        const replacement = requestOptions.onPayload ? yield* hook(() => requestOptions.onPayload!(payload, model)) : undefined;
+        const finalPayload = replacement === undefined ? payload : yield* object(replacement, "provider payload");
+        if (JSON.stringify([finalPayload.cascadeId, finalPayload.trajectoryReference, finalPayload.executionId, finalPayload.clientSessionId]) !== identity) {
+          return yield* failWith("A payload hook cannot change the owned run, session or step identifiers.");
+        }
+        actualUID = yield* 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 (!(yield* deps.catalog.exactLevel(actualUID))) return yield* failWith("A payload hook selected an unavailable model UID.");
+          selected = yield* deps.catalog.resolveUID(actualUID, current);
+          yield* toDevinTranscript(context, selected.model); // A model change re-checks existing image and tool limits.
+          yield* assertCacheRetention(selected);
+        }
+        const outputLimit = yield* tokenCount((yield* object(finalPayload.configuration, "configuration")).maxTokens, "maxTokens");
+        if (outputLimit < 1 || outputLimit > selected.model.maxOutputTokens) return yield* failWith("The payload hook output limit is outside the model range.");
+        response.message.providerThinkingLevel = actualUID;
+        return finalPayload;
+      }),
+      onResponse: (info) => Effect.gen(function* () {
+        if (info.status === 401) yield* deps.guard.reportFailure(current, RPCError.make("unauthenticated", "HTTP 401", 401), generation);
+        if (requestOptions.onResponse) yield* hook(() => requestOptions.onResponse!(info, model));
+      }),
+      onFrame: (frame) => Effect.gen(function* () {
+        if (requestOptions.onProviderStreamEvent) yield* hook(() => requestOptions.onProviderStreamEvent!(structuredClone(frame.data), model));
+        if (frame.isEnd && frame.data.error) return; // Connect error classification belongs to the transport.
+        if (frame.data.redact === true) { isRedacted = true; yield* response.redact; }
+        yield* accumulator.accept(frame.data, frame.isEnd);
+        if (!frame.isEnd) yield* response.accept(frame.data, accumulator);
+      }),
+    });
+    yield* lease.cancellation.guard(Stream.runDrain(frames));
+    const result = yield* accumulator.finish;
+    result.message.modelUid = actualUID;
+    yield* response.finish(result);
+  });
+
+  // The scope encloses the failure report as well, so Pi sees the terminal event before the client closes and the lease lets the next request in.
+  const settled = Effect.scoped(lifetime.guard(run).pipe(
+    abortWith(requestOptions.signal),
+    // Every ending, including a defect, closes Pi's stream with exactly one terminal event.
+    Effect.catchCause((cause) => Effect.gen(function* () {
+      const error: DevinFailure = Cause.hasInterruptsOnly(cause) ? new Cancelled({ message: "The Devin request was interrupted." }) : toDevinFailure(Cause.squash(cause));
+      if (credential) yield* deps.guard.reportFailure(credential, error, generation);
+      accumulator.message.modelUid = actualUID || undefined;
+      yield* response.fail(hostRetryableMessage(error, safeError(error, credential ? [credential.sessionToken] : [])),
+        error.name === "AbortError", isRedacted ? undefined : accumulator.message);
+    })),
+  ));
+  return { stream: response.stream, run: settled };
+});

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

@@ -0,0 +1,33 @@
+import { Context, Effect, FiberSet, Layer } from "effect";
+import { Accounts } from "../accounts/service.ts";
+import { CredentialGuard } from "../auth/guard.ts";
+import { AuthState } from "../auth/state.ts";
+import { ModelCatalog } from "../catalog/service.ts";
+import { DevinClients } from "../clients/service.ts";
+import { onDefaultScheduler } from "../default-scheduler.ts";
+import { ProviderLifetime } from "../lifetime/service.ts";
+import { Runs } from "../runs/service.ts";
+import { prepareRequest, type InferenceDependencies } from "./request.ts";
+import type { InferenceShape } from "./types.ts";
+
+/**
+ * Devin requests behind Pi's provider calls. Each request owns its scope (lease, request client) and runs in a fiber of this
+ * service, so it outlives the synchronous provider call that returned its stream. It stops through its own guards, never by Pi returning.
+ */
+export class Inference extends Context.Service<Inference, InferenceShape>()("pi-devin/Inference") {}
+
+export const InferenceLive = Layer.effect(Inference, Effect.gen(function* () {
+  const deps: InferenceDependencies = {
+    auth: yield* AuthState, guard: yield* CredentialGuard, catalog: yield* ModelCatalog, accounts: yield* Accounts,
+    clients: yield* DevinClients, runs: yield* Runs, lifetime: yield* ProviderLifetime,
+  };
+  const requests = yield* FiberSet.make<void, never>();
+  return {
+    start: (model, context, options) => Effect.gen(function* () {
+      const request = yield* prepareRequest(deps, model, context, options);
+      // Starts at once, as the previous synchronous prefix did: validation failures reach the stream before the call returns.
+      yield* FiberSet.run(requests, onDefaultScheduler(request.run), { startImmediately: true });
+      return request.stream;
+    }),
+  } satisfies InferenceShape;
+}));

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

@@ -0,0 +1,11 @@
+import type { AssistantMessageEventStream, Model, SimpleStreamOptions, TranscriptContext } from "@earendil-works/pi-ai";
+import type { Effect } from "effect";
+import type { DevinAPI } from "../catalog/types.ts";
+
+export interface InferenceShape {
+  /**
+   * Returns Pi's event stream for one Devin request. Runs synchronously up to the first wait: the stream carries its
+   * start event, and the request already holds its sign-in generation and provider lifetime. The request runs on in a fiber the service owns.
+   */
+  readonly start: (model: Model<DevinAPI>, context: TranscriptContext, options?: SimpleStreamOptions) => Effect.Effect<AssistantMessageEventStream>;
+}

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

@@ -0,0 +1,19 @@
+import { Context, Effect, Layer } from "effect";
+import { makeCancellation } from "../../../core/cancellation.ts";
+import type { ProviderLifetimeShape } from "./types.ts";
+
+/**
+ * How long the provider's work may run: from a session attach until shutdown. Shutdown ends it with a reason
+ * instead of interrupting fibers, so stopped requests report that reason. The next session attach starts a new one.
+ */
+export class ProviderLifetime extends Context.Service<ProviderLifetime, ProviderLifetimeShape>()("pi-devin/ProviderLifetime") {}
+
+export const ProviderLifetimeLive = Layer.sync(ProviderLifetime, () => {
+  let current = makeCancellation();
+  return {
+    current: Effect.sync(() => current),
+    isActive: Effect.sync(() => !current.isCancelled()),
+    end: (reason) => Effect.sync(() => current.cancelUnsafe(reason)),
+    renew: Effect.sync(() => { if (current.isCancelled()) current = makeCancellation(); }),
+  } satisfies ProviderLifetimeShape;
+});

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

@@ -0,0 +1,13 @@
+import type { Effect } from "effect";
+import type { Cancellation } from "../../../core/cancellation.ts";
+import type { DevinFailure } from "../../../core/errors.ts";
+
+export interface ProviderLifetimeShape {
+  /** The lifetime current at the call. Work captures it when it starts, so a later session's lifetime never stops it. */
+  readonly current: Effect.Effect<Cancellation>;
+  readonly isActive: Effect.Effect<boolean>;
+  /** Ends the current lifetime; work guarded by it fails with this reason. */
+  readonly end: (reason: DevinFailure) => Effect.Effect<void>;
+  /** Starts a new lifetime when the current one has ended. */
+  readonly renew: Effect.Effect<void>;
+}

package/src/pi/features/runs/admission.ts

@@ -0,0 +1,36 @@
+import { Deferred, Effect, Exit } from "effect";
+
+interface Ticket {
+  turn: Deferred.Deferred<void>;
+  hasLeft: boolean;
+}
+
+export interface AdmissionTicket {
+  /** Waits until everyone who entered earlier has left. */
+  readonly turn: Effect.Effect<void>;
+  /** Idempotent. Also used by a request that gives up before its turn; those behind it still wait for everyone ahead of it. */
+  readonly leave: Effect.Effect<void>;
+}
+
+/** Admits one request at a time, strictly in the order they entered. A new arrival never takes a turn ahead of a waiting one. */
+export class AdmissionLine {
+  private readonly line: Ticket[] = [];
+
+  enter(): AdmissionTicket {
+    const ticket: Ticket = { turn: Deferred.makeUnsafe<void>(), hasLeft: false };
+    this.line.push(ticket);
+    if (this.line.length === 1) Deferred.doneUnsafe(ticket.turn, Exit.void);
+    return {
+      turn: Deferred.await(ticket.turn),
+      leave: Effect.sync(() => this.leave(ticket)),
+    };
+  }
+
+  private leave(ticket: Ticket): void {
+    if (ticket.hasLeft) return;
+    ticket.hasLeft = true;
+    while (this.line[0]?.hasLeft) this.line.shift();
+    const front = this.line[0];
+    if (front) Deferred.doneUnsafe(front.turn, Exit.void);
+  }
+}

package/src/pi/features/runs/lifecycle.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Exit } from "effect";
+import { makeCancellation, type Cancellation } from "../../../core/cancellation.ts";
+import { Cancelled, type DevinError, type DevinFailure } from "../../../core/errors.ts";
+import { failWith } from "../../../core/validation.ts";
+import { AdmissionLine, type AdmissionTicket } from "./admission.ts";
+import { freshState, MAX_STEP_INDEX, restoreState } from "./state.ts";
+import type { DevinSessionState, ExecutionKind, ExecutionState, RequestLease, SessionBinding } from "./types.ts";
+
+interface Execution {
+  data: ExecutionState;
+  /** Ends the run's work with a reason: a finished run or an invalidated login. */
+  cancellation: Cancellation;
+  /** Requests of one run are admitted one at a time, in order. */
+  admission: AdmissionLine;
+  cleanups: Set<Effect.Effect<void>>;
+  activeRequests: number;
+  hasStarted: boolean;
+  nextIsRecovery: boolean;
+  hasCheckpoint: boolean;
+}
+
+const cancelled = () => new Cancelled({ message: "The previous Devin run ended." });
+const runQuietly = (cleanup: Effect.Effect<void>) => Effect.catchCause(cleanup, () => Effect.void);
+
+/** Runs of one extension instance and its attached session. It never builds its own tool or retry loop. */
+export class DevinLifecycle {
+  private binding?: SessionBinding;
+  private state: DevinSessionState = freshState(randomUUID());
+  private execution?: Execution;
+  private isClosed = false;
+  private isAuxiliary = false;
+
+  private constructor() {}
+
+  static readonly make: Effect.Effect<DevinLifecycle> = Effect.sync(() => new DevinLifecycle());
+
+  get snapshot(): Effect.Effect<DevinSessionState> {
+    return Effect.sync(() => structuredClone(this.state));
+  }
+
+  private checkpoint(): Effect.Effect<void, Cancelled> {
+    return Effect.suspend(() => {
+      if (this.binding && this.binding.getSessionId() !== this.state.sessionId) return Effect.fail(cancelled());
+      this.binding?.append(structuredClone(this.state));
+      return Effect.void;
+    });
+  }
+
+  private activate(data: ExecutionState, hasCheckpoint = false): Execution {
+    this.state.execution = data;
+    return this.execution = {
+      data, cancellation: makeCancellation(), admission: new AdmissionLine(), cleanups: new Set(),
+      activeRequests: 0, hasStarted: false, nextIsRecovery: false, hasCheckpoint,
+    };
+  }
+
+  attach(binding: SessionBinding): Effect.Effect<void, DevinError> {
+    return Effect.gen({ self: this }, function* () {
+      yield* this.abort(cancelled());
+      this.binding = binding;
+      this.state = yield* 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): Effect.Effect<void, Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      if (this.isClosed) return yield* Effect.fail(cancelled());
+      const current = this.execution;
+      if (current && !current.data.settled) {
+        if (kind === "agent" && ["pending", "recovered"].includes(current.data.kind)) current.data.kind = "agent";
+        else if (kind === "agent" && ["manual", "tree", "direct"].includes(current.data.kind) && current.activeRequests === 0) yield* this.finish;
+        else return; // Retries and tool follow-up calls stay in the same run.
+        if (this.execution) return;
+      }
+      this.activate({ id: randomUUID(), settled: false, kind });
+    });
+  }
+
+  get agentStarted(): Effect.Effect<void, Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      if (!this.execution) yield* this.begin("agent");
+      const execution = this.execution!;
+      execution.nextIsRecovery = execution.hasStarted;
+      execution.hasStarted = true;
+    });
+  }
+
+  beforeCompaction(reason: "manual" | "threshold" | "overflow"): Effect.Effect<void, Cancelled> {
+    return Effect.andThen(this.begin(reason === "manual" ? "manual" : "pending"), Effect.sync(() => { this.isAuxiliary = true; }));
+  }
+
+  afterCompaction(reason: "manual" | "threshold" | "overflow"): Effect.Effect<void, Cancelled> {
+    return Effect.suspend(() => {
+      this.isAuxiliary = false;
+      return reason === "manual" && this.execution?.data.kind === "manual" ? this.finish : Effect.void;
+    });
+  }
+
+  get beforeTree(): Effect.Effect<void, Cancelled> {
+    return Effect.andThen(this.begin("tree"), Effect.sync(() => { this.isAuxiliary = true; }));
+  }
+
+  get finish(): Effect.Effect<void, Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      const execution = this.execution;
+      if (!execution) return;
+      execution.data.settled = true;
+      yield* this.abort(cancelled());
+      if (execution.hasCheckpoint) yield* this.checkpoint();
+      this.execution = undefined; this.isAuxiliary = false;
+    });
+  }
+
+  /** Stops the run's waiting and running requests with the reason. A cleanup failure never skips releasing other resources. */
+  abort(reason: DevinFailure): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const active = this.execution;
+      if (!active) return Effect.void;
+      active.cancellation.cancelUnsafe(reason);
+      return Effect.forEach([...active.cleanups], runQuietly, { discard: true });
+    });
+  }
+
+  get shutdown(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      if (this.isClosed) return Effect.void;
+      // An unfinished run stays in the checkpoint so a reload resumes it with the same execution ID.
+      return Effect.andThen(this.abort(cancelled()), Effect.sync(() => { this.isClosed = true; }));
+    });
+  }
+
+  get treeChanged(): Effect.Effect<void, DevinError | Cancelled> {
+    return Effect.gen({ self: this }, function* () {
+      if (!this.binding) return;
+      yield* this.abort(cancelled());
+      this.state = yield* 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) yield* this.checkpoint();
+    });
+  }
+
+  acquire(ownerHash: string): Effect.Effect<RequestLease, DevinFailure> {
+    return Effect.gen({ self: this }, function* () {
+      if (this.isClosed) return yield* Effect.fail(cancelled());
+      if (!/^[a-f0-9]{64}$/.test(ownerHash)) return yield* failWith("A verified Devin account scope is required.");
+      if (this.state.ownerHash && this.state.ownerHash !== ownerHash) return yield* failWith("This Pi session is bound to a different Devin account or endpoint. Start a new session.");
+      this.state.ownerHash = ownerHash;
+      if (!this.execution) yield* this.begin("direct");
+      const active = this.execution!, state = this.state;
+      const ownCleanups = new Set<Effect.Effect<void>>();
+      let isCounted = false, hasReleased = false;
+      let ticket: AdmissionTicket | undefined;
+      const release = Effect.suspend(() => {
+        if (hasReleased) return Effect.void;
+        hasReleased = true;
+        for (const cleanup of ownCleanups) active.cleanups.delete(cleanup);
+        return Effect.forEach([...ownCleanups], runQuietly, { discard: true }).pipe(Effect.andThen(Effect.suspend(() => {
+          if (isCounted) active.activeRequests--;
+          return ticket ? ticket.leave : Effect.void;
+        })));
+      });
+      const assertCurrent = Effect.suspend(() => {
+        const reason = active.cancellation.reason();
+        if (reason) return Effect.fail(reason);
+        if (this.execution !== active || this.state !== state || this.isClosed || (this.binding && this.binding.getSessionId() !== state.sessionId)) return Effect.fail(cancelled());
+        return Effect.void;
+      });
+      const admitted = Effect.gen({ self: this }, function* () {
+        // Entered inside the effect whose exit releases it, so an interruption cannot leave the line blocked.
+        ticket = active.admission.enter();
+        yield* active.cancellation.guard(ticket.turn);
+        yield* assertCurrent;
+        if (state.nextStepIndex >= MAX_STEP_INDEX) return yield* failWith("The Devin step number limit was reached. Start a new session.");
+        active.activeRequests++; isCounted = true;
+        const stepIndex = state.nextStepIndex++;
+        active.hasCheckpoint = true;
+        yield* this.checkpoint();
+        const isAuxiliary = this.isAuxiliary;
+        const isRecovery = !isAuxiliary && active.nextIsRecovery;
+        if (!isAuxiliary) active.nextIsRecovery = false;
+        const lease: RequestLease = {
+          executionId: active.data.id, cascadeId: state.cascadeId, trajectoryId: state.trajectoryId,
+          sessionId: state.sessionId, stepIndex, isAuxiliary, isRecovery,
+          cancellation: active.cancellation,
+          assertAttempt: assertCurrent,
+          addCleanup: (cleanup) => Effect.suspend(() => {
+            let hasCleaned = false;
+            const once = Effect.suspend(() => {
+              if (hasCleaned) return Effect.void;
+              hasCleaned = true;
+              return cleanup;
+            });
+            ownCleanups.add(once); active.cleanups.add(once);
+            return active.cancellation.isCancelled() ? runQuietly(once) : Effect.void;
+          }),
+          release,
+        };
+        return lease;
+      });
+      return yield* admitted.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : release));
+    });
+  }
+}

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

@@ -0,0 +1,10 @@
+import { Context, Layer } from "effect";
+import { DevinLifecycle } from "./lifecycle.ts";
+
+/**
+ * Runs of the attached Pi session: admission order, request leases and the stored session state.
+ * A run spans many provider calls and ends at `agent_settled`, never when one response ends.
+ */
+export class Runs extends Context.Service<Runs, DevinLifecycle>()("pi-devin/Runs") {}
+
+export const RunsLive = Layer.effect(Runs, DevinLifecycle.make);

package/src/pi/features/runs/state.ts

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Schema } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import { failWith } from "../../../core/validation.ts";
+import type { DevinSessionState, SessionBinding } from "./types.ts";
+
+export const DEVIN_STATE_ENTRY = "pi-devin.state.v1";
+export const MAX_STEP_INDEX = 2_147_483_647;
+
+const UUID = Schema.String.check(Schema.isPattern(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/));
+const isStoredState = Schema.is(Schema.Struct({
+  version: Schema.Literal(1),
+  sessionId: Schema.String,
+  ownerHash: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/))),
+  cascadeId: UUID,
+  trajectoryId: UUID,
+  nextStepIndex: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: MAX_STEP_INDEX })),
+  // `used` is the request budget count saved by 0.1.5 and earlier; it is accepted and dropped.
+  execution: Schema.optionalKey(Schema.Struct({ id: UUID, used: Schema.optionalKey(Schema.Int), settled: Schema.Boolean })),
+}));
+
+export function freshState(sessionId: string): DevinSessionState {
+  return { version: 1, sessionId, cascadeId: randomUUID(), trajectoryId: randomUUID(), nextStepIndex: 0 };
+}
+
+/** The newest state of this session's branch. Another session's state starts fresh; a corrupt one stops instead of resetting the IDs. */
+export function restoreState(binding: SessionBinding): Effect.Effect<DevinSessionState, DevinError> {
+  return Effect.suspend(() => {
+    const sessionId = binding.getSessionId();
+    const entry = [...binding.getBranch()].reverse().find((item) => item.type === "custom" && item.customType === DEVIN_STATE_ENTRY);
+    if (!entry) return Effect.succeed(freshState(sessionId));
+    if (!isStoredState(entry.data)) return failWith("The Devin session state is corrupt or an unsupported version. Start a new session.");
+    if (entry.data.sessionId !== sessionId) return Effect.succeed(freshState(sessionId));
+    const { execution, ...state } = structuredClone(entry.data);
+    return Effect.succeed({ ...state, ...(execution ? { execution: { id: execution.id, settled: execution.settled } } : {}) } as DevinSessionState);
+  });
+}

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

@@ -0,0 +1,43 @@
+import type { Effect } from "effect";
+import type { Cancellation } from "../../../core/cancellation.ts";
+import type { DevinFailure } from "../../../core/errors.ts";
+
+export type ExecutionKind = "agent" | "pending" | "manual" | "tree" | "direct" | "recovered";
+export interface ExecutionState { id: string; settled: boolean; kind: ExecutionKind }
+
+/** The `pi-devin.state.v1` session entry. Holds no token, fingerprint or message. */
+export interface DevinSessionState {
+  version: 1;
+  sessionId: string;
+  ownerHash?: string;
+  cascadeId: string;
+  trajectoryId: string;
+  nextStepIndex: number;
+  execution?: ExecutionState;
+}
+
+/** Pi's current session as the run service sees it: its ID, its branch entries and a way to append a state entry. */
+export interface SessionBinding {
+  getSessionId(): string;
+  getBranch(): readonly { type: string; customType?: string; data?: unknown }[];
+  append(data: DevinSessionState): void;
+}
+
+/** One admitted model request of a run. */
+export interface RequestLease {
+  executionId: string;
+  cascadeId: string;
+  trajectoryId: string;
+  sessionId: string;
+  stepIndex: number;
+  isAuxiliary: boolean;
+  isRecovery: boolean;
+  /** Ends when the run is aborted, failing with its reason. */
+  cancellation: Cancellation;
+  /** Checked before each model HTTP request: fails once the run has ended or the session has changed. */
+  assertAttempt: Effect.Effect<void, DevinFailure>;
+  /** Runs once when the run is aborted or the lease is released. */
+  addCleanup(cleanup: Effect.Effect<void>): Effect.Effect<void>;
+  /** Idempotent. Lets the next request of the run in. */
+  release: Effect.Effect<void>;
+}

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

@@ -0,0 +1,46 @@
+import { Context, Effect, Layer } from "effect";
+import type { FusionSelection } from "../catalog/types.ts";
+import type { AccountUsage } from "../usage/types.ts";
+import type { DevinPreferences, DisplaySettingsShape, FusionSettingsShape, UsageStoreShape } from "./types.ts";
+
+export const DEFAULT_PREFERENCES: DevinPreferences = { recommendedOnly: false, showUsageStatus: false };
+
+export class FusionSettings extends Context.Service<FusionSettings, FusionSettingsShape>()("pi-devin/FusionSettings") {}
+export class DisplaySettings extends Context.Service<DisplaySettings, DisplaySettingsShape>()("pi-devin/DisplaySettings") {}
+export class UsageStore extends Context.Service<UsageStore, UsageStoreShape>()("pi-devin/UsageStore") {}
+
+/** A newer record replaces an older one of the same scope; another scope's record is always replaced. */
+export const isNotOlder = (current: AccountUsage | undefined, next: AccountUsage) => !current || next.fetchedAtMs >= current.fetchedAtMs;
+
+/** Memory stores, so SDK callers and tests never write to the real agent directory. */
+export function memoryFusionSettings(initial?: FusionSelection): FusionSettingsShape {
+  let current = initial;
+  return {
+    read: Effect.sync(() => current),
+    write: (selection) => Effect.sync(() => { current = { ...selection }; }),
+  };
+}
+
+export function memoryDisplaySettings(initial: Partial<DevinPreferences> = {}): DisplaySettingsShape {
+  let current: DevinPreferences = { ...DEFAULT_PREFERENCES, ...initial };
+  return {
+    read: Effect.sync(() => ({ ...current })),
+    write: (preferences) => Effect.sync(() => { current = { ...preferences }; }),
+  };
+}
+
+export function memoryUsageStore(): UsageStoreShape {
+  let record: { scope: string; usage: AccountUsage } | undefined;
+  return {
+    read: (scope) => Effect.sync(() => record?.scope === scope ? { ...record.usage } : undefined),
+    write: (scope, usage) => Effect.sync(() => {
+      if (record?.scope !== scope || isNotOlder(record.usage, usage)) record = { scope, usage: { ...usage } };
+    }),
+  };
+}
+
+export const MemorySettings = (initial: { fusion?: FusionSelection; display?: Partial<DevinPreferences> } = {}) => Layer.mergeAll(
+  Layer.sync(FusionSettings, () => memoryFusionSettings(initial.fusion)),
+  Layer.sync(DisplaySettings, () => memoryDisplaySettings(initial.display)),
+  Layer.sync(UsageStore, memoryUsageStore),
+);