@buyong/pi-devin 0.1.4 → 0.1.6

package/src/core/auth/login.ts

@@ -1,7 +1,15 @@
-import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { createServer } from "node:http";
-import { awaitWithSignal, ConnectClient, endpoint, RPCError, safeError } from "../protocol/transport.ts";
-import { requiredString, type Credential } from "../types.ts";
+import { randomUUID } from "node:crypto";
+import { Deferred, Effect, Exit, Fiber, Predicate } from "effect";
+import { startDeadline } from "../cancellation.ts";
+import { DevinError, RequestTimeout, toDevinError, type DevinFailure } from "../errors.ts";
+import { makeConnectClient } from "../protocol/connect-client.ts";
+import { endpoint } from "../protocol/endpoint.ts";
+import { redactFailure } from "../redaction.ts";
+import type { HttpTransport } from "../services/http-transport.ts";
+import type { Credential } from "../types.ts";
+import { failWith, requiredString } from "../validation.ts";
+import { startCallbackServer } from "./callback-server.ts";
+import { codeForExchange, createPKCE, isAuthorizationCode, matchesState, PKCE_CODE_PREFIX } from "./pkce.ts";
 import { exchangeBrowserCode } from "./rest-exchange.ts";
 
 export const DEFAULT_API_SERVER_URL = "https://server.codeium.com";
@@ -9,169 +17,114 @@ export const DEFAULT_WEBAPP_URL = "https://app.devin.ai";
 export const DEFAULT_DEVIN_API_URL = "https://api.devin.ai";
 const EXCHANGE_METHOD = "exa.seat_management_pb.SeatManagementService/ExchangeDevinCLIPKCECode";
 const PKCE_EXCHANGE_METHOD = "exa.seat_management_pb.SeatManagementService/ExchangePKCEAuthorizationCode";
-const PKCE_CODE_PREFIX = "wspkce$";
-const codeForExchange = (code: string) => code.startsWith(PKCE_CODE_PREFIX) ? code.slice(PKCE_CODE_PREFIX.length) : code;
+const LOGIN_TIMEOUT_MS = 300_000;
+const CONNECT_EXCHANGE_TIMEOUT_MS = 30_000;
+
 export type LoginFlow = "browser" | "manual" | "legacy-connect";
 export interface LoginOptions {
   apiServerURL?: string;
   webappURL?: string;
   devinAPIURL?: string;
   timeoutMs?: number;
-  signal?: AbortSignal;
-  onURL: (url: string, signal: AbortSignal) => void | Promise<void>;
-  /** Receives a one-time authorization code, never an API key or session token. */
-  promptCode?: (signal: AbortSignal) => Promise<string>;
-  fetch?: typeof fetch;
+  /** Shows or opens the authorization URL. */
+  onURL: (url: string) => Effect.Effect<void, DevinFailure>;
+  /** Reads a one-time authorization code, never an API key or session token. Interrupted as soon as the browser callback wins. */
+  promptCode?: Effect.Effect<string, DevinFailure>;
   encoding?: "proto" | "json";
   flow?: LoginFlow;
 }
 
-export function createPKCE(): { verifier: string; challenge: string; state: string } {
-  const verifier = randomBytes(32).toString("base64url");
-  return {
-    verifier,
-    challenge: createHash("sha256").update(verifier).digest("base64url"),
-    state: randomBytes(32).toString("base64url"),
-  };
-}
-
-function matchesState(received: string | null, expected: string): boolean {
-  if (!received) return false;
-  const left = Buffer.from(received), right = Buffer.from(expected);
-  return left.length === right.length && timingSafeEqual(left, right);
+/** The new account UI defaults to the REST browser flow. An explicit encoding keeps the legacy Connect path. Code exchanges go through `HttpTransport`. */
+export function loginAccount(options: LoginOptions): Effect.Effect<Credential, DevinFailure, HttpTransport> {
+  return login({ ...options, flow: options.flow ?? (options.encoding === undefined ? "browser" : "legacy-connect") });
 }
 
-function isAuthorizationCode(code: string): boolean {
-  return code.length > 0 && code.length <= 8192 && codeForExchange(code).length > 0
-    && !/[\s\u0000-\u001f\u007f]/.test(code)
-    && !/^(devin-session-token\$|cog_|sk-ws-01-|Bearer |Basic )/.test(code);
+function validate(options: LoginOptions, flow: LoginFlow): Effect.Effect<void, DevinError> {
+  if (!["browser", "manual", "legacy-connect"].includes(flow)) return failWith("Unsupported login flow.");
+  if (options.encoding !== undefined && options.encoding !== "proto" && options.encoding !== "json") return failWith("The login encoding must be proto or json.");
+  if (flow === "browser" && options.encoding !== undefined) return failWith("A Connect encoding cannot be used with the REST browser login.");
+  if (flow !== "browser" && options.devinAPIURL !== undefined) return failWith("The Devin REST login server can only be set for the REST browser flow.");
+  if (flow === "manual" && !options.promptCode) return failWith("Manual login requires an authorization code prompt.");
+  return Effect.void;
 }
 
-/** The new account UI defaults to the REST browser flow. An explicit encoding keeps the legacy Connect path. */
-export function loginAccount(options: LoginOptions): Promise<Credential> {
-  return login({ ...options, flow: options.flow ?? (options.encoding === undefined ? "browser" : "legacy-connect") });
+function connectExchange(apiServerURL: string, code: string, verifier: string, options: LoginOptions): Effect.Effect<string, DevinFailure, HttpTransport> {
+  return Effect.scoped(Effect.gen(function* () {
+    const client = yield* makeConnectClient({ baseURL: apiServerURL, timeoutMs: CONNECT_EXCHANGE_TIMEOUT_MS });
+    const isWindsurfCode = code.startsWith(PKCE_CODE_PREFIX);
+    const method = isWindsurfCode ? PKCE_EXCHANGE_METHOD : EXCHANGE_METHOD;
+    const body = isWindsurfCode ? { authorizationCode: codeForExchange(code), codeVerifier: verifier } : { code, codeVerifier: verifier };
+    const exchanged = yield* client.unary(method, body, { encoding: options.encoding ?? "proto" });
+    if (isWindsurfCode && Predicate.isString(exchanged.apiServerUrl) && exchanged.apiServerUrl && (yield* endpoint(exchanged.apiServerUrl)) !== apiServerURL) {
+      return yield* failWith("The login returned a different API server. Set the target with --api-server-url and sign in again.");
+    }
+    const tokenField = isWindsurfCode ? "apiKey" : "sessionToken";
+    return yield* requiredString(exchanged[tokenField], `${method}.${tokenField}`);
+  }));
 }
 
 /** Keeps the default Connect contract of the existing shared login(). Storage and opening the browser belong to the caller. */
-export async function login(options: LoginOptions): Promise<Credential> {
-  const flow = options.flow ?? "legacy-connect";
-  if (!["browser", "manual", "legacy-connect"].includes(flow)) throw new Error("Unsupported login flow.");
-  if (options.encoding !== undefined && options.encoding !== "proto" && options.encoding !== "json") throw new Error("The login encoding must be proto or json.");
-  if (flow === "browser" && options.encoding !== undefined) throw new Error("A Connect encoding cannot be used with the REST browser login.");
-  if (flow !== "browser" && options.devinAPIURL !== undefined) throw new Error("The Devin REST login server can only be set for the REST browser flow.");
-  if (flow === "manual" && !options.promptCode) throw new Error("Manual login requires an authorization code prompt.");
-  const apiServerURL = endpoint(options.apiServerURL ?? DEFAULT_API_SERVER_URL);
-  const webappURL = endpoint(options.webappURL ?? DEFAULT_WEBAPP_URL);
-  const devinAPIURL = endpoint(options.devinAPIURL ?? DEFAULT_DEVIN_API_URL);
-  const signal = AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout(options.timeoutMs ?? 300_000)]);
-  signal.throwIfAborted();
-  const pkce = createPKCE();
-  if (flow !== "legacy-connect") pkce.state = randomUUID();
-  let resolveCode!: (code: string) => void, rejectCode!: (error: Error) => void;
-  let hasAcceptedCode = false, authorizationCode = "";
-  let client: ConnectClient | undefined;
-  let redirectURL: string | undefined;
-  const inputController = new AbortController();
-  const inputSignal = AbortSignal.any([signal, inputController.signal]);
-  const codePromise = new Promise<string>((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
-  void codePromise.catch(() => {});
-  const acceptCode = (code: string) => {
-    if (hasAcceptedCode || !isAuthorizationCode(code)) return false;
-    hasAcceptedCode = true;
-    authorizationCode = code;
-    resolveCode(code);
-    inputController.abort(new DOMException("Authorization code received.", "AbortError"));
-    return true;
-  };
-  const server = createServer((request, response) => {
-    response.setHeader("Content-Type", "text/plain; charset=utf-8");
-    response.setHeader("Cache-Control", "no-store");
-    response.setHeader("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'");
-    response.setHeader("Referrer-Policy", "no-referrer");
-    let url: URL;
-    try { url = new URL(request.url ?? "/", "http://127.0.0.1"); }
-    catch { response.writeHead(400).end("Invalid callback URL"); return; }
-    if (request.method !== "GET" || url.pathname !== "/callback") { response.writeHead(404).end("Not found"); return; }
-    if (hasAcceptedCode || !matchesState(url.searchParams.get("state"), pkce.state)) { response.writeHead(400).end("Invalid OAuth state"); return; }
-    if (url.searchParams.has("error")) {
-      hasAcceptedCode = true;
-      response.writeHead(400).end("Login was denied.");
-      rejectCode(new Error("OAuth login was denied."));
-      inputController.abort();
-      return;
-    }
-    if (!acceptCode(url.searchParams.get("code") ?? "")) { response.writeHead(400).end("Missing authorization code"); return; }
-    response.end("Authorization code received. Check the token exchange result in your terminal.");
-  });
-  const onAbort = () => rejectCode(new DOMException(
-    signal.reason?.name === "TimeoutError" ? "OAuth login timed out." : "OAuth login was cancelled.",
-    signal.reason?.name === "TimeoutError" ? "TimeoutError" : "AbortError",
-  ));
-  signal.addEventListener("abort", onAbort, { once: true });
-  try {
-    if (flow !== "manual") {
-      await new Promise<void>((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
-      });
-      const address = server.address();
-      if (!address || typeof address === "string") throw new Error("Could not determine the callback port.");
-      redirectURL = `http://127.0.0.1:${address.port}/callback`;
-    }
-    const authorizationURL = new URL(flow === "manual" ? "/devin/account/login" : "/auth/cli/continue", webappURL);
-    authorizationURL.search = new URLSearchParams({
-      redirect_uri: flow === "manual" ? "chisel-show-auth-token" : redirectURL!,
-      state: pkce.state,
-      ...(flow === "manual" ? {} : { prompt: "select_account" }),
-      code_challenge: pkce.challenge, code_challenge_method: "S256",
-    }).toString();
-    signal.throwIfAborted();
-    await awaitWithSignal(Promise.resolve(options.onURL(authorizationURL.href, signal)), signal);
-    if (options.promptCode && !hasAcceptedCode) {
-      void awaitWithSignal(Promise.resolve().then(() => options.promptCode!(inputSignal)), inputSignal).then((value) => {
-        if (hasAcceptedCode || signal.aborted) return;
-        authorizationCode = value.trim(); // Also keeps the raw code out of errors.
-        let code = authorizationCode;
-        if (/^https?:\/\//.test(code)) {
-          const pasted = new URL(code);
-          if (!redirectURL || pasted.origin + pasted.pathname !== redirectURL || !matchesState(pasted.searchParams.get("state"), pkce.state)) {
-            throw new Error("The pasted callback URL or state does not match.");
+export function login(options: LoginOptions): Effect.Effect<Credential, DevinFailure, HttpTransport> {
+  return Effect.gen(function* () {
+    const flow = options.flow ?? "legacy-connect";
+    yield* validate(options, flow);
+    const apiServerURL = yield* endpoint(options.apiServerURL ?? DEFAULT_API_SERVER_URL);
+    const webappURL = yield* endpoint(options.webappURL ?? DEFAULT_WEBAPP_URL);
+    const devinAPIURL = yield* endpoint(options.devinAPIURL ?? DEFAULT_DEVIN_API_URL);
+    const pkce = createPKCE();
+    if (flow !== "legacy-connect") pkce.state = randomUUID();
+    let authorizationCode = "";
+    const secrets = () => [authorizationCode, codeForExchange(authorizationCode), pkce.verifier];
+
+    return yield* Effect.scoped(Effect.gen(function* () {
+      const deadline = yield* startDeadline(options.timeoutMs ?? LOGIN_TIMEOUT_MS, () => new RequestTimeout({ message: "OAuth login timed out." }));
+      return yield* deadline.guard(Effect.gen(function* () {
+        const code = yield* Deferred.make<string, DevinFailure>();
+        let hasAcceptedCode = false;
+        const accept = (value: string) => {
+          if (hasAcceptedCode || !isAuthorizationCode(value)) return false;
+          hasAcceptedCode = true;
+          authorizationCode = value;
+          Deferred.doneUnsafe(code, Exit.succeed(value));
+          return true;
+        };
+        const redirectURL = flow === "manual" ? undefined : yield* startCallbackServer({
+          state: pkce.state, accept, isSettled: () => hasAcceptedCode,
+          deny: () => {
+            hasAcceptedCode = true;
+            Deferred.doneUnsafe(code, Exit.fail(new DevinError({ message: "OAuth login was denied." })));
+          },
+        });
+        const authorizationURL = new URL(flow === "manual" ? "/devin/account/login" : "/auth/cli/continue", webappURL);
+        authorizationURL.search = new URLSearchParams({
+          redirect_uri: flow === "manual" ? "chisel-show-auth-token" : redirectURL!,
+          state: pkce.state,
+          ...(flow === "manual" ? {} : { prompt: "select_account" }),
+          code_challenge: pkce.challenge, code_challenge_method: "S256",
+        }).toString();
+        yield* options.onURL(authorizationURL.href);
+        // Typed input races the browser callback; the first valid code wins and the other wait is stopped.
+        const input = options.promptCode && !hasAcceptedCode ? yield* Effect.forkScoped(Effect.gen(function* () {
+          const value = (yield* options.promptCode!).trim();
+          if (hasAcceptedCode) return;
+          authorizationCode = value; // Also keeps the raw code out of errors.
+          let candidate = value;
+          if (/^https?:\/\//.test(candidate)) {
+            const pasted = yield* Effect.try({ try: () => new URL(candidate), catch: toDevinError });
+            if (!redirectURL || pasted.origin + pasted.pathname !== redirectURL || !matchesState(pasted.searchParams.get("state"), pkce.state)) {
+              return yield* failWith("The pasted callback URL or state does not match.");
+            }
+            candidate = pasted.searchParams.get("code") ?? "";
           }
-          code = pasted.searchParams.get("code") ?? "";
-        }
-        if (!acceptCode(code)) throw new Error("Enter a valid authorization code. API keys and session tokens are not accepted.");
-      }).catch((error) => { if (!hasAcceptedCode && !signal.aborted) rejectCode(error); });
-    }
-    authorizationCode = await codePromise;
-    signal.throwIfAborted();
-    let sessionToken: string;
-    if (flow === "browser") {
-      sessionToken = await exchangeBrowserCode({ origin: devinAPIURL, code: authorizationCode, verifier: pkce.verifier, signal, fetch: options.fetch });
-    } else {
-      client = new ConnectClient({ baseURL: apiServerURL, timeoutMs: 30_000, fetch: options.fetch });
-      const isWindsurfCode = authorizationCode.startsWith(PKCE_CODE_PREFIX);
-      const method = isWindsurfCode ? PKCE_EXCHANGE_METHOD : EXCHANGE_METHOD;
-      const body = isWindsurfCode ? { authorizationCode: codeForExchange(authorizationCode), codeVerifier: pkce.verifier }
-        : { code: authorizationCode, codeVerifier: pkce.verifier };
-      const exchanged = await client.unary(method, body, signal, { encoding: options.encoding ?? "proto" });
-      if (isWindsurfCode && typeof exchanged.apiServerUrl === "string" && exchanged.apiServerUrl && endpoint(exchanged.apiServerUrl) !== apiServerURL) {
-        throw new Error("The login returned a different API server. Set the target with --api-server-url and sign in again.");
-      }
-      const tokenField = isWindsurfCode ? "apiKey" : "sessionToken";
-      sessionToken = requiredString(exchanged[tokenField], `${method}.${tokenField}`);
-    }
-    return { version: 1, sessionToken, apiServerURL, createdAt: new Date().toISOString() };
-  } catch (error) {
-    const secrets = [authorizationCode, codeForExchange(authorizationCode), pkce.verifier];
-    if (error instanceof RPCError) { error.message = safeError(error, secrets); error.code = safeError(error.code, secrets); throw error; }
-    const failure = new Error(safeError(error, secrets));
-    if (error instanceof Error) failure.name = error.name;
-    throw failure;
-  } finally {
-    inputController.abort();
-    client?.close();
-    signal.removeEventListener("abort", onAbort);
-    server.closeAllConnections();
-    await new Promise<void>((resolve) => server.close(() => resolve()));
-  }
+          if (!accept(candidate)) return yield* failWith("Enter a valid authorization code. API keys and session tokens are not accepted.");
+        }).pipe(Effect.catch((error) => hasAcceptedCode ? Effect.void : Deferred.fail(code, error)))) : undefined;
+        const accepted = yield* Deferred.await(code);
+        if (input) yield* Fiber.interrupt(input);
+        const sessionToken = flow === "browser"
+          ? yield* exchangeBrowserCode({ origin: devinAPIURL, code: accepted, verifier: pkce.verifier })
+          : yield* connectExchange(apiServerURL, accepted, pkce.verifier, options);
+        return { version: 1, sessionToken, apiServerURL, createdAt: new Date().toISOString() } satisfies Credential;
+      }));
+    })).pipe(Effect.catch((error) => Effect.fail(redactFailure(error, secrets()))));
+  });
 }

package/src/core/auth/pkce.ts

@@ -0,0 +1,32 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+export const PKCE_CODE_PREFIX = "wspkce$";
+
+export interface PKCE { verifier: string; challenge: string; state: string }
+
+export function createPKCE(): PKCE {
+  const verifier = randomBytes(32).toString("base64url");
+  return {
+    verifier,
+    challenge: createHash("sha256").update(verifier).digest("base64url"),
+    state: randomBytes(32).toString("base64url"),
+  };
+}
+
+/** The code the exchange RPC expects: a Windsurf-style code without its prefix. */
+export function codeForExchange(code: string): string {
+  return code.startsWith(PKCE_CODE_PREFIX) ? code.slice(PKCE_CODE_PREFIX.length) : code;
+}
+
+export function matchesState(received: string | null, expected: string): boolean {
+  if (!received) return false;
+  const left = Buffer.from(received), right = Buffer.from(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+/** A one-time authorization code. API keys, session tokens and credentials of other schemes are refused. */
+export function isAuthorizationCode(code: string): boolean {
+  return code.length > 0 && code.length <= 8192 && codeForExchange(code).length > 0
+    && !/[\s\u0000-\u001f\u007f]/.test(code)
+    && !/^(devin-session-token\$|cog_|sk-ws-01-|Bearer |Basic )/.test(code);
+}

package/src/core/auth/rest-exchange.ts

@@ -1,35 +1,37 @@
-import { createHTTPTransport } from "../protocol/http.ts";
-import { awaitWithSignal, boundedJSON, discardResponse, endpoint, RPCError } from "../protocol/transport.ts";
-import { object, requiredString } from "../types.ts";
+import { Effect, Exit } from "effect";
+import { HttpBody, HttpClientRequest } from "effect/http";
+import { startDeadline } from "../cancellation.ts";
+import { RPCError, type DevinFailure } from "../errors.ts";
+import { endpoint } from "../protocol/endpoint.ts";
+import { discardResponse, fromHttpClientError, readBoundedJSON } from "../protocol/http.ts";
+import { HttpTransport } from "../services/http-transport.ts";
+import { failWith, object, requiredString } from "../validation.ts";
 
 const TOKEN_PREFIX = "devin-session-token$";
+const EXCHANGE_TIMEOUT_MS = 30_000;
+const RESPONSE_BYTES = 64 * 1024;
 
 /** REST authorization code exchange, same as the public client. Never resends or creates a refresh grant. */
-export async function exchangeBrowserCode(options: {
-  origin: string; code: string; verifier: string; signal: AbortSignal; fetch?: typeof fetch;
-}): Promise<string> {
-  const origin = endpoint(options.origin);
-  const signal = AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]);
-  signal.throwIfAborted();
-  const transport = options.fetch ? undefined : createHTTPTransport();
-  try {
-    const response = await awaitWithSignal((options.fetch ?? transport!.fetch)(`${origin}/auth/cli/token`, {
-      method: "POST", redirect: "error", signal,
-      headers: { "content-type": "application/json", accept: "application/json" },
-      body: JSON.stringify({ code: options.code, code_verifier: options.verifier }),
-    }), signal, discardResponse);
-    if (!response.ok) {
-      discardResponse(response);
-      throw new RPCError(response.status === 401 ? "unauthenticated" : `http_${response.status}`, "Devin login code exchange failed", response.status);
-    }
-    let body: unknown;
-    try { body = await boundedJSON(response, 64 * 1024, signal); }
-    catch (error) {
-      if (error instanceof SyntaxError) throw new Error("The Devin login response is not valid JSON.");
-      throw error;
-    }
-    const token = requiredString(object(body, "Devin login response").token, "Devin login response.token");
-    if (/[\s\u0000-\u001f\u007f]/.test(token)) throw new Error("The token in the Devin login response has an invalid format.");
-    return token.startsWith(TOKEN_PREFIX) ? token : TOKEN_PREFIX + token;
-  } finally { transport?.close(); }
+export function exchangeBrowserCode(options: { origin: string; code: string; verifier: string }): Effect.Effect<string, DevinFailure, HttpTransport> {
+  return Effect.scoped(Effect.gen(function* () {
+    const origin = yield* endpoint(options.origin);
+    const deadline = yield* startDeadline(EXCHANGE_TIMEOUT_MS);
+    const http = yield* (yield* HttpTransport).open;
+    return yield* deadline.guard(Effect.gen(function* () {
+      const request = HttpClientRequest.post(`${origin}/auth/cli/token`).pipe(
+        HttpClientRequest.setBody(HttpBody.raw(JSON.stringify({ code: options.code, code_verifier: options.verifier }))),
+        HttpClientRequest.setHeaders({ "content-type": "application/json", accept: "application/json" }),
+      );
+      const response = yield* http.execute(request).pipe(Effect.mapError(fromHttpClientError));
+      yield* Effect.addFinalizer((exit) => Exit.isSuccess(exit) ? Effect.void : discardResponse(response));
+      if (response.status < 200 || response.status >= 300) {
+        yield* discardResponse(response);
+        return yield* Effect.fail(RPCError.make(response.status === 401 ? "unauthenticated" : `http_${response.status}`, "Devin login code exchange failed", response.status));
+      }
+      const body = yield* object(yield* readBoundedJSON(response, RESPONSE_BYTES), "Devin login response");
+      const token = yield* requiredString(body.token, "Devin login response.token");
+      if (/[\s\u0000-\u001f\u007f]/.test(token)) return yield* failWith("The token in the Devin login response has an invalid format.");
+      return token.startsWith(TOKEN_PREFIX) ? token : TOKEN_PREFIX + token;
+    }));
+  }));
 }

package/src/core/cancellation.ts

@@ -0,0 +1,99 @@
+import { Deferred, Duration, Effect, Exit, type Scope } from "effect";
+import { RequestTimeout, toDevinFailure, type DevinFailure } from "./errors.ts";
+
+/**
+ * A one-shot stop switch that carries its reason. Interruption has no reason, so lifetimes such as a closed client,
+ * an invalidated login or an ended run fail the guarded work with the reason instead.
+ */
+export interface Cancellation {
+  /** Fails with the reason once cancelled; never succeeds. */
+  readonly await: Effect.Effect<never, DevinFailure>;
+  readonly isCancelled: () => boolean;
+  readonly reason: () => DevinFailure | undefined;
+  /** Cancels once; later reasons are ignored. Also usable from synchronous host callbacks. */
+  readonly cancelUnsafe: (reason: DevinFailure) => void;
+  readonly cancel: (reason: DevinFailure) => Effect.Effect<void>;
+  /** Stops the effect when cancelled and fails it with the reason. Already cancelled work does not start. */
+  readonly guard: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DevinFailure, R>;
+}
+
+export function makeCancellation(): Cancellation {
+  const deferred = Deferred.makeUnsafe<never, DevinFailure>();
+  let current: DevinFailure | undefined;
+  const cancelUnsafe = (reason: DevinFailure) => {
+    if (current) return;
+    current = reason;
+    Deferred.doneUnsafe(deferred, Exit.fail(reason));
+  };
+  return {
+    await: Deferred.await(deferred),
+    isCancelled: () => current !== undefined,
+    reason: () => current,
+    cancelUnsafe,
+    cancel: (reason) => Effect.sync(() => cancelUnsafe(reason)),
+    guard: (effect) => Effect.suspend(() => current ? Effect.fail(current) : Effect.raceFirst(effect, Deferred.await(deferred))),
+  };
+}
+
+/** Guards an effect with several cancellations; the first one wins. */
+export function guardAll(cancellations: readonly Cancellation[]) {
+  return <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | DevinFailure, R> =>
+    cancellations.reduce<Effect.Effect<A, E | DevinFailure, R>>((guarded, cancellation) => cancellation.guard(guarded), effect);
+}
+
+/**
+ * Starts a deadline at once. The timer is registered before the guarded work runs any of its own code,
+ * so hooks that advance or block time cannot slip past it. The timer stops with the scope.
+ */
+export function startDeadline(timeoutMs: number, reason: () => DevinFailure = () => new RequestTimeout({ message: `The request exceeded the ${timeoutMs}ms timeout.` })): Effect.Effect<Cancellation, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const deadline = makeCancellation();
+    yield* Effect.forkScoped(Effect.sleep(Duration.millis(timeoutMs)).pipe(Effect.andThen(deadline.cancel(reason()))), { startImmediately: true });
+    return deadline;
+  });
+}
+
+/** A deadline that restarts whenever data arrives. */
+export interface IdleDeadline extends Cancellation {
+  /** Restarts the wait. Has no effect once the deadline has passed. */
+  readonly touch: Effect.Effect<void>;
+}
+
+/**
+ * Starts an idle deadline at once: it passes only when nothing arrives for `timeoutMs`, so a long response that keeps
+ * streaming is not cut off. Like `startDeadline`, the timer exists before the guarded work runs. It stops with the scope.
+ */
+export function startIdleDeadline(timeoutMs: number, reason: () => DevinFailure = () => new RequestTimeout({ message: `The request received no data for ${timeoutMs}ms.` })): Effect.Effect<IdleDeadline, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const deadline = makeCancellation();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const arm = () => {
+      clearTimeout(timer);
+      if (!deadline.isCancelled()) timer = setTimeout(() => deadline.cancelUnsafe(reason()), timeoutMs);
+    };
+    arm();
+    yield* Effect.addFinalizer(() => Effect.sync(() => clearTimeout(timer)));
+    return { ...deadline, touch: Effect.sync(arm) };
+  });
+}
+
+/** Fails with the signal's reason once it aborts; never succeeds. */
+export function whenAborted(signal: AbortSignal): Effect.Effect<never, DevinFailure> {
+  return Effect.callback<never, DevinFailure>((resume) => {
+    const onAbort = () => resume(Effect.fail(toDevinFailure(signal.reason)));
+    if (signal.aborted) { onAbort(); return; }
+    signal.addEventListener("abort", onAbort, { once: true });
+    return Effect.sync(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
+/**
+ * Bridges a host `AbortSignal`: the effect stops when it aborts and fails with the signal's reason,
+ * because hosts tell cancellation from a timeout by that reason.
+ */
+export function abortWith(signal: AbortSignal | undefined) {
+  return <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | DevinFailure, R> => {
+    if (!signal) return effect;
+    return Effect.suspend(() => signal.aborted ? Effect.fail(toDevinFailure(signal.reason)) : Effect.raceFirst(effect, whenAborted(signal)));
+  };
+}