@atlaso-labs/opencode 0.1.0 → 0.2.0

package/lib/drain.ts

@@ -0,0 +1,186 @@
+/** Outbox drain — the retry half of the durability guarantee.
+ *
+ *  `outbox.ts` persists memories; this decides what a push attempt MEANT and moves
+ *  each item to its next state. It is deliberately the only place the failure
+ *  taxonomy lives, so "when do we give up on a memory" is one readable table rather
+ *  than scattered conditionals.
+ *
+ *  THE TAXONOMY. Getting this wrong fails in one of two directions — lose a user's
+ *  memory, or wedge the queue behind an item that can never succeed:
+ *
+ *    per-item `invalid`        → QUARANTINE. The server rejected the SHAPE. Retrying
+ *                               is guaranteed to fail identically, forever.
+ *    per-item anything else    → SETTLED. added / duplicate / error are all "the
+ *                               server has seen this and formed a verdict". `error`
+ *                               settles because the batch endpoint returns it for a
+ *                               per-item engine failure it already logged; retrying
+ *                               would re-run the same deposit against the same
+ *                               engine. It is recorded, not silently discarded.
+ *    item absent from results  → RETRY. We cannot prove the server took it.
+ *    HTTP 429                  → RETRY, and STOP the pass. The server is shedding;
+ *                               hammering it is the opposite of helpful. Nothing is
+ *                               lost — this is exactly the case the outbox exists
+ *                               for, and the per-item budget makes 429 reachable.
+ *    HTTP 401/403              → RETRY, and STOP. Either credentials are being
+ *                               rotated or an edge/WAF is blocking us. Both are
+ *                               transient from the memory's point of view, and the
+ *                               WAF sync-brick incident is precisely why a 403 must
+ *                               never cause us to discard data.
+ *    HTTP 5xx / 0 (timeout)    → RETRY, and STOP. Brain down, deploying, or network.
+ *    HTTP 4xx (other)          → QUARANTINE. A durable client-side defect.
+ *
+ *  AMBIGUOUS TIMEOUTS ARE SAFE. A request that times out after the server committed
+ *  the write is retried — and cannot duplicate, because `client_id` is the server's
+ *  per-item idempotency key. The retry simply comes back `duplicate` and settles.
+ *
+ *  A drain NEVER throws. It is called from editor hooks; a memory is worth less
+ *  than the user's session.
+ */
+import { depositDetailed, type Auth } from "./atlaso";
+import { log } from "./log";
+import {
+  maxDrainPerRun,
+  bumpAttempt,
+  enforceBounds,
+  hasPending,
+  pending,
+  quarantine,
+  settle,
+  type OutboxRecord,
+} from "./outbox";
+
+export interface DrainResult {
+  attempted: number;
+  settled: number;
+  retried: number;
+  quarantined: number;
+  stopped: boolean;
+}
+
+const EMPTY: DrainResult = { attempted: 0, settled: 0, retried: 0, quarantined: 0, stopped: false };
+
+/** Statuses that mean "the server has formed a verdict on this item". Anything
+ *  here leaves the queue. */
+function isSettledStatus(s: string | undefined): boolean {
+  return s !== undefined && s !== "invalid";
+}
+
+/** Classify a whole-request failure. `stop` halts the pass: when the brain is down
+ *  or shedding, the remaining items would fail identically and we would just be
+ *  burning the user's hook budget. */
+function classifyRequest(status: number): { retry: boolean; stop: boolean; why: string } {
+  if (status === 429) return { retry: true, stop: true, why: "rate limited" };
+  if (status === 401 || status === 403) return { retry: true, stop: true, why: `auth/edge ${status}` };
+  if (status === 0) return { retry: true, stop: true, why: "transport/timeout" };
+  if (status >= 500) return { retry: true, stop: true, why: `server ${status}` };
+  return { retry: false, stop: true, why: `client ${status}` }; // durable 4xx → quarantine
+}
+
+/**
+ * Attempt one bounded pass over the queue.
+ *
+ * Items go up ONE at a time rather than as one large batch on purpose: a batch
+ * shares a single fate, so one poisoned item would drag good memories into the
+ * same verdict and we could not tell which was which. Per-item costs more
+ * round-trips on a backlog, but a backlog is already the rare path, and
+ * correctness there is the entire point of this file.
+ */
+/** The push used by a drain. Injectable so tests can drive the taxonomy directly
+ *  without `mock.module`, which in Bun mutates the module registry for the WHOLE
+ *  run and silently breaks any later file importing the same module. Production
+ *  always uses the default. */
+export type DepositFn = typeof depositDetailed;
+
+export async function drain(
+  tool: string,
+  auth: Auth,
+  limit = maxDrainPerRun(),
+  deposit: DepositFn = depositDetailed,
+): Promise<DrainResult> {
+  const out: DrainResult = { ...EMPTY };
+  try {
+    enforceBounds(tool);
+    const items = pending(tool, limit);
+    if (!items.length) return out;
+
+    for (const rec of items) {
+      out.attempted++;
+      let res: Awaited<ReturnType<DepositFn>>;
+      try {
+        res = await deposit(auth, [rec.item]);
+      } catch (e) {
+        // depositDetailed already swallows transport errors; this is belt-and-braces
+        // so an unexpected throw can never abort the loop and strand the rest.
+        if (bumpAttempt(tool, rec, String(e)) === "quarantine") out.quarantined++;
+        else out.retried++;
+        out.stopped = true;
+        break;
+      }
+
+      if (res.ok) {
+        const verdict = res.results.find((r) => r.client_id === rec.client_id);
+        if (verdict && !isSettledStatus(verdict.status)) {
+          quarantine(tool, rec, `server rejected: ${verdict.status}`);
+          out.quarantined++;
+        } else if (verdict) {
+          settle(tool, rec.client_id);
+          out.settled++;
+        } else {
+          // 2xx but our item is not in the results — do not assume it landed.
+          if (bumpAttempt(tool, rec, "absent from results") === "quarantine") out.quarantined++;
+          else out.retried++;
+        }
+        continue;
+      }
+
+      const c = classifyRequest(res.status);
+      if (!c.retry) {
+        quarantine(tool, rec, `${c.why}${res.error ? `: ${res.error}` : ""}`);
+        out.quarantined++;
+      } else if (bumpAttempt(tool, rec, c.why) === "quarantine") {
+        out.quarantined++;
+      } else {
+        out.retried++;
+      }
+      if (c.stop) {
+        out.stopped = true;
+        break;
+      }
+    }
+
+    if (out.attempted) {
+      log(
+        "drain",
+        `attempted=${out.attempted} settled=${out.settled} retried=${out.retried} ` +
+          `quarantined=${out.quarantined}${out.stopped ? " stopped" : ""}`,
+      );
+    }
+  } catch (e) {
+    // A drain must never break the editor session.
+    try {
+      log("drain", `error ${e}`);
+    } catch {
+      /* logging itself failed — nothing left to do */
+    }
+  }
+  return out;
+}
+
+/** Cheap guard for latency-sensitive hooks: skip the whole drain (and its
+ *  directory parsing) when the queue is empty, which is the overwhelmingly
+ *  common case. */
+export async function drainIfPending(
+  tool: string,
+  auth: Auth,
+  limit = maxDrainPerRun(),
+  deposit: DepositFn = depositDetailed,
+): Promise<DrainResult> {
+  try {
+    if (!hasPending(tool)) return { ...EMPTY };
+  } catch {
+    return { ...EMPTY };
+  }
+  return drain(tool, auth, limit, deposit);
+}
+
+export type { OutboxRecord };

package/lib/entitlement.ts

@@ -16,7 +16,8 @@ export type { Verdict } from "./state";
 /** Should we attempt a cloud call right now? True = cloud-linked, False =
  *  local-only this turn. Never throws (memory must never break a turn). Hits the
  *  network only on a stale/foreign verdict (cached otherwise). */
-export async function online(auth: Auth | null, tool: string, deviceId: string | null): Promise<boolean> {
+export async function online(auth: Auth | null, id: { tool: string; deviceId: string | null }): Promise<boolean> {
+  const { tool, deviceId } = id;
   if (!auth) return false;
   try {
     const st = state.get();
@@ -67,7 +68,8 @@ async function verify(auth: Auth, tool: string, deviceId: string | null): Promis
 }
 
 /** The current verdict for surfacing a user notice (no network). */
-export function cloudMode(auth: Auth | null, tool: string, deviceId: string | null): state.Verdict {
+export function cloudMode(auth: Auth | null, id: { tool: string; deviceId: string | null }): state.Verdict {
+  const { tool, deviceId } = id;
   if (!auth) return { ...state.defaultState(), mode: state.LOCAL_ONLY, reason: state.NOT_CONNECTED };
   const st = state.get();
   if (!state.matches(st, tool, deviceId)) return state.defaultState(); // foreign → no notice

package/lib/lock.ts

@@ -0,0 +1,217 @@
+/** Cross-process advisory lock for per-tool credential minting — a real kernel
+ *  lock via bun:ffi flock(2), the TS counterpart of the Python client's
+ *  fcntl.flock in `_credential.py`.
+ *
+ *  WHY a kernel lock and not a lockfile-with-staleness: a self-managed lockfile
+ *  needs a staleness rule, and every staleness rule is a TOCTOU race where two
+ *  contenders both decide the other's lock is stale and stomp it. The kernel drops
+ *  a flock when the holding process dies — no staleness to reason about, nothing to
+ *  steal, and the lock file is NEVER unlinked (deleting a file another process holds
+ *  an fd to is its own race).
+ *
+ *  Where flock is unavailable (Windows, or any platform without bun:ffi) we fall back
+ *  to an O_EXCL lockfile — see `withExclusiveFileLock` at the bottom for why that is
+ *  acceptable there and was NOT acceptable as the primary mechanism. Before that
+ *  fallback existed, Windows got `held: false` on every run, which meant it never
+ *  called /v1/device/exchange, never observed `tool_revoked`, and so REMOVING A TOOL
+ *  DID NOT STOP IT SYNCING on Windows. Every platform now mints per-tool credentials.
+ *
+ *  Load-bearing invariant (never-brick): a lock we could not take is never a verdict.
+ *  `held: false` still means "do not mint this run, keep the shared bearer, retry
+ *  next run" — it must never take a tool offline.
+ */
+import { closeSync, openSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+const SPIN_MS = 50;
+
+// How long to wait for a contended lock before giving up (→ shared bearer). Shorter
+// than the exchange it guards (8s), so "proceed unlocked" is never tempting. Read
+// per-call (not at module load) so it stays env-overridable for tests.
+function lockTimeoutMs(): number {
+  const n = parseInt(process.env.ATLASO_LOCK_TIMEOUT_MS ?? "5000", 10);
+  return Number.isFinite(n) ? n : 5000;
+}
+
+type FlockFn = (fd: number, op: number) => number;
+
+// Resolve flock(2) from libc once. null = no primitive on this platform → the
+// caller degrades to the shared bearer. Cached (including the null) so we probe once.
+let _flock: FlockFn | null | undefined;
+
+function resolveFlock(): FlockFn | null {
+  if (_flock !== undefined) return _flock;
+  // Escape hatch: exercise the portable path on a machine that HAS flock. Tests use
+  // it, and it makes the Windows behaviour reproducible during support triage.
+  if (process.env.ATLASO_LOCK_NO_FLOCK === "1") {
+    _flock = null;
+    return null;
+  }
+  const libs =
+    process.platform === "darwin"
+      ? ["libSystem.B.dylib"]
+      : process.platform === "linux"
+        ? ["libc.so.6", "libc.so"]
+        : []; // win32 / others: flock is not the API — no primitive, degrade safely
+  for (const lib of libs) {
+    try {
+      // Lazy import so a platform without bun:ffi never trips over the import itself.
+      const { dlopen, FFIType } = require("bun:ffi");
+      const { symbols } = dlopen(lib, {
+        flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      });
+      _flock = symbols.flock as unknown as FlockFn;
+      return _flock;
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  _flock = null;
+  return null;
+}
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/**
+ * Run `fn(held)` holding an exclusive advisory lock on `lockPath`.
+ *
+ * - `held: true`  — the lock is ours; it's safe to exchange + write the credential.
+ * - `held: false` — no primitive, couldn't open the file, or the 5s deadline passed
+ *   while another instance held it. The caller MUST NOT mint; it falls back to the
+ *   shared bearer and retries next run. The timeout is deliberately shorter than the
+ *   exchange it guards, so "proceed unlocked" is never the tempting option.
+ *
+ * The lock is released (LOCK_UN) and the fd closed in `finally`, always. The lock
+ * file itself is left in place — never unlinked.
+ */
+export async function withToolLock<T>(
+  lockPath: string,
+  fn: (held: boolean) => Promise<T>,
+): Promise<T> {
+  const flock = resolveFlock();
+  if (!flock) return withExclusiveFileLock(lockPath, fn);
+
+  let fd: number;
+  try {
+    // "a" = O_CREAT|O_WRONLY|O_APPEND — creates the lock file if absent, never
+    // truncates, and we never write to it; we only need a stable fd to flock.
+    fd = openSync(lockPath, "a", 0o600);
+  } catch {
+    return fn(false); // can't even open the lock file → don't mint unlocked
+  }
+
+  const deadline = Date.now() + lockTimeoutMs();
+  let held = false;
+  while (Date.now() < deadline) {
+    if (flock(fd, LOCK_EX | LOCK_NB) === 0) {
+      held = true;
+      break;
+    }
+    await sleep(SPIN_MS);
+  }
+
+  try {
+    return await fn(held);
+  } finally {
+    if (held) {
+      try {
+        flock(fd, LOCK_UN);
+      } catch {
+        /* releasing on close anyway */
+      }
+    }
+    try {
+      closeSync(fd);
+    } catch {
+      /* fd already gone */
+    }
+  }
+}
+
+// ── portable fallback lock (no flock: Windows, or any platform without bun:ffi) ──
+//
+// WHY THIS EXISTS. Yielding `held: false` on Windows looked conservative, but it was
+// not: `resolveCredential` then returns the SHARED bearer without ever calling
+// /v1/device/exchange, so the tool never mints its own credential and never observes
+// a `tool_revoked` verdict. Net effect — on Windows, removing Cursor did not stop it
+// syncing. The per-tool credential guarantee was simply false there.
+// (cursor/plugins#157, Bugbot "Lock miss skips tool revoke", Medium/Security.)
+//
+// The obvious alternative — call exchange without holding a lock — is WRONG: the
+// server's exchange ROTATES the credential in place (mints a new token, deletes the
+// previous), so an un-persisted mint on every hook run would churn a fresh token row
+// per invocation, forever.
+//
+// So: give Windows a real mutex instead. O_EXCL create is atomic on every platform,
+// including Windows. The header above rejects lockfiles because staleness rules are
+// TOCTOU races — that critique is correct, and the reason it is ACCEPTABLE here is
+// the blast radius, not the absence of the race: this lock is held only across one
+// exchange (≤8s), the stale threshold is an order of magnitude beyond that, and if
+// two processes ever did mint concurrently the loser simply holds a rotated-away
+// token, 401s on its next call, clears its own tool file and re-mints. Transient
+// churn that self-heals — not corruption, and not a brick. Weighed against
+// revocation silently not working on an entire operating system, that trade is easy.
+const STALE_MS = 60_000;
+
+function staleMs(): number {
+  const n = parseInt(process.env.ATLASO_LOCK_STALE_MS ?? "", 10);
+  return Number.isFinite(n) && n > 0 ? n : STALE_MS;
+}
+
+/** Separate path from the flock lock file: the two mechanisms must never contend
+ *  on the same inode, and this one is unlinked on release while that one never is. */
+function exclPath(lockPath: string): string {
+  return lockPath + ".excl";
+}
+
+async function withExclusiveFileLock<T>(
+  lockPath: string,
+  fn: (held: boolean) => Promise<T>,
+): Promise<T> {
+  const p = exclPath(lockPath);
+  const deadline = Date.now() + lockTimeoutMs();
+  let held = false;
+
+  while (Date.now() < deadline) {
+    try {
+      // "wx" = O_CREAT|O_EXCL|O_WRONLY — atomic create-or-fail on all platforms.
+      const fd = openSync(p, "wx", 0o600);
+      try {
+        writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+      } catch {
+        /* diagnostics only — holding the lock is what matters */
+      }
+      closeSync(fd);
+      held = true;
+      break;
+    } catch {
+      // Someone holds it, or it was orphaned by a process that died mid-exchange.
+      // Reclaim ONLY when far past any legitimate hold.
+      try {
+        if (Date.now() - statSync(p).mtimeMs > staleMs()) unlinkSync(p);
+      } catch {
+        /* vanished or unreadable — the next attempt settles it */
+      }
+      await sleep(SPIN_MS);
+    }
+  }
+
+  try {
+    return await fn(held);
+  } finally {
+    if (held) {
+      try {
+        unlinkSync(p); // release; an O_EXCL lock is held by the file's existence
+      } catch {
+        /* already reclaimed as stale — nothing to release */
+      }
+    }
+  }
+}
+
+/** Reset the cached flock probe. Tests only — lets one process exercise both paths. */
+export function _resetFlockProbeForTests(): void {
+  _flock = undefined;
+}