@gotcos/glasses-server 6.28.0 → 6.30.0

package/server/lib/occupied-threads.ts

@@ -0,0 +1,191 @@
+// Which threads currently have a live desktop process, in ONE pass.
+//
+// WHY THIS EXISTS SEPARATELY FROM `threadOccupancy`.
+//
+// `claudeOwners(threadId, ...)` re-reads the whole session registry and shells
+// out to `ps` per entry, for ONE thread. That is correct and cheap when a user is
+// deciding whether to write into a single thread. Calling it once per row to
+// decorate a 53-row session list would mean tens of directory scans and hundreds
+// of process spawns on every list request.
+//
+// So this does the opposite shape: scan once, return the set of occupied ids, and
+// let the caller join in memory.
+//
+// THE LOAD-BEARING RULE, AND THE REASON THIS IS SAFE:
+//
+//   WHAT THIS PRODUCES IS A DISPLAY HINT. IT MUST NEVER GATE A WRITE.
+//
+// The attach and turn paths keep calling `threadOccupancy` at the moment of the
+// write, unchanged. That is deliberate: a list is rendered seconds or minutes
+// before the user acts, and a desktop session opened in that gap is exactly the
+// race the per-write probe exists to catch. This hint answers "should the UI show
+// this session as busy", never "is it safe to write".
+//
+// Being a hint is also why its failure mode is the opposite of the gate's. The
+// gate fails CLOSED — doubt means refuse. A hint that failed closed would paint
+// every session as running the moment a probe hiccuped, so doubt here means "I do
+// not know", rendered as not-running, and the real gate still refuses at the
+// write. Getting a hint wrong costs a misleading badge; getting the gate wrong
+// costs someone's conversation.
+
+import {
+  claudeOwners,
+  codexLockPath,
+  codexOwners,
+  type OccupancyDirs,
+  type OccupancyProbes,
+  type ThreadOwner,
+} from './thread-occupancy.js'
+import { isValidNativeThreadId } from './native-thread-id.js'
+
+export interface OccupiedThread {
+  threadId: string
+  /**
+   * Every process working in this thread, COS's own children included.
+   *
+   * This is the DISPLAY question — "is an agent working in here right now" — and
+   * a turn COS queued is just as much a running agent as a desktop window is.
+   */
+  owners: number
+  /**
+   * Owners that are NOT COS's own children.
+   *
+   * The separate count matters because it answers a different question: whether a
+   * Continue would be refused. Self-owned work does not block a write; a desktop
+   * window does.
+   */
+  foreignOwners: number
+}
+
+export interface OccupiedScan {
+  /** threadId -> occupancy, for every thread with at least one owner. */
+  occupied: Map<string, OccupiedThread>
+  /**
+   * True when the scan could not see clearly (unreadable registry, missing
+   * detector). The caller should render "unknown", never "everything is running".
+   */
+  degraded: boolean
+}
+
+const EMPTY: OccupiedScan = { occupied: new Map(), degraded: true }
+
+/**
+ * Probes that answer each identical question once per scan.
+ *
+ * MEASURED, not assumed. `claudeOwners` re-reads the whole registry directory and
+ * re-runs `ps` for every entry, for ONE thread — so scanning 45 real sessions on
+ * this machine cost 771ms of repeated identical I/O. With this wrapper the same
+ * scan is one directory read, one read per entry, and one `ps` per pid.
+ *
+ * Correctness comes from reusing `claudeOwners` / `codexOwners` UNCHANGED, so the
+ * self-ownership rule and the PID-reuse guard stay in exactly one place. This only
+ * removes duplicate work; it makes no decisions.
+ *
+ * Scoped to a single scan on purpose. A longer-lived cache would answer "is a
+ * desktop process holding this thread" from stale data, and liveness has a
+ * lifetime of about now.
+ */
+function memoize(probes: OccupancyProbes): OccupancyProbes {
+  const dirs = new Map<string, string[]>()
+  const files = new Map<string, string | null>()
+  const starts = new Map<number, number | null>()
+  const alive = new Map<number, boolean>()
+  const exists = new Map<string, boolean>()
+  const dirsExist = new Map<string, boolean>()
+  let ledger: ReturnType<OccupancyProbes['cosSpawnedPids']> | undefined
+
+  const once = <K, V>(cache: Map<K, V>, key: K, compute: () => V): V => {
+    if (cache.has(key)) return cache.get(key)!
+    const value = compute()
+    cache.set(key, value)
+    return value
+  }
+
+  return {
+    ...probes,
+    readDir: (path: string) => once(dirs, path, () => probes.readDir(path)),
+    readFile: (path: string) => once(files, path, () => probes.readFile(path)),
+    processStartMs: (pid: number) => once(starts, pid, () => probes.processStartMs(pid)),
+    isAlive: (pid: number) => once(alive, pid, () => probes.isAlive(pid)),
+    fileExists: (path: string) => once(exists, path, () => probes.fileExists(path)),
+    dirExists: (path: string) => once(dirsExist, path, () => probes.dirExists(path)),
+    cosSpawnedPids: () => (ledger ??= probes.cosSpawnedPids()),
+  }
+}
+
+/**
+ * Scan one provider's registry once and return the threads a desktop process
+ * holds.
+ *
+ * Reuses `claudeOwners` / `codexOwners` rather than reimplementing the parsing,
+ * so the self-ownership rule (COS's own spawned children must not read as foreign
+ * owners) and the PID-reuse guard stay in exactly one place. Reuse alone would
+ * repeat the whole registry read per thread — `memoize` is what removes that, so
+ * the saving is real I/O rather than a claim in a comment.
+ */
+export function occupiedThreads(
+  provider: string,
+  threadIds: readonly string[],
+  probes: OccupancyProbes,
+  dirs: OccupancyDirs,
+): OccupiedScan {
+  if (provider !== 'claude' && provider !== 'codex') return { occupied: new Map(), degraded: false }
+
+  // Deduplicated and validated up front. An invalid id cannot match a record, and
+  // it also reaches a filesystem path in `codexLockPath`.
+  const ids = [...new Set(threadIds)].filter(isValidNativeThreadId)
+  if (ids.length === 0) return { occupied: new Map(), degraded: false }
+
+  // Every identical read answered once for the whole scan. See `memoize`.
+  const probe = memoize(probes)
+  const occupied = new Map<string, OccupiedThread>()
+  let degraded = false
+
+  for (const threadId of ids) {
+    // MEASURED: `codexOwners` reaches `lsof` even when no writer lock exists, and
+    // lsof costs ~45ms a call — 761ms across 17 codex threads on this machine,
+    // against zero locks on disk. A missing lock means no writer, which is the
+    // same conclusion lsof reaches the expensive way, so skip it.
+    //
+    // Only an explicit `false` skips. `fileExists` collapses absent with
+    // unreadable, and an unreadable lock must still go through the real check
+    // rather than being read as free.
+    if (provider === 'codex') {
+      let lockPresent = true
+      try {
+        lockPresent = probe.fileExists(codexLockPath(threadId, dirs.codexLocksDir))
+      } catch {
+        lockPresent = true
+      }
+      if (!lockPresent) continue
+    }
+
+    let owners: readonly ThreadOwner[]
+    let doubt: string | null
+    try {
+      const result = provider === 'claude'
+        ? claudeOwners(threadId, probe, dirs.claudeSessionsDir)
+        : codexOwners(threadId, probe, dirs.codexLocksDir)
+      owners = result.owners
+      doubt = result.doubt
+    } catch {
+      // One thread's probe throwing does not invalidate the others.
+      degraded = true
+      continue
+    }
+    if (doubt !== null) degraded = true
+    // ANY owner means an agent is working here. Counting only foreign ones would
+    // hide COS's own queued turn from the very screen the user opens to watch it.
+    const foreign = owners.filter(o => !o.selfOwned).length
+    if (owners.length > 0) {
+      occupied.set(threadId, { threadId, owners: owners.length, foreignOwners: foreign })
+    }
+  }
+
+  return { occupied, degraded }
+}
+
+/** The safe answer when the caller cannot scan at all. */
+export function noOccupancyKnown(): OccupiedScan {
+  return { occupied: new Map(EMPTY.occupied), degraded: true }
+}

package/server/lib/thread-attach-capability.ts

@@ -0,0 +1,200 @@
+// Does this server offer Continue at all, and for what?
+//
+// The Continue/Fork affordance is a UI decision that has to be made BEFORE any
+// thread is named, so COS Control and the phone cannot discover it the way they
+// discover everything else about a thread — by asking
+// /api/agent-sessions/:provider/:threadId/attachability. When the feature is off
+// the two write routes are not registered at all, so a client that reaches for
+// them gets a bare 404 with no reason and no copy, which is indistinguishable
+// from a typo, a proxy, or a dead server. This module is what a client reads
+// instead, once, up front.
+//
+// ---------------------------------------------------------------- the rule
+//
+// ABSENT MEANS DISABLED. NEVER ENABLED.
+//
+// These fields did not exist before this build. Every client older than it will
+// read `undefined` from all three, and `undefined` MUST resolve to off — the same
+// fail-closed posture as the rest of Continue Original Agent Thread, for the same
+// reason: a client that guesses "the field is missing, so probably fine" offers a
+// Continue button that writes into a real human's conversation, and the cost of
+// guessing the other way is one Fork.
+//
+// That rule cannot be enforced by the wire format, because absence is exactly what
+// an old client sees and an old client cannot be changed. So it is enforced by
+// `readThreadAttachCapability`, which is the ONLY sanctioned way to interpret this
+// surface, and by the test that feeds it a genuine older-shaped /api/health body
+// and requires all three answers to come back off.
+//
+// `supported` exists solely to make the two OFFs distinguishable. Without it,
+// "this server has never heard of Continue" and "this server can Continue but the
+// user has not switched it on" are the same empty answer, and a client cannot tell
+// a user to flip a setting that may not exist. It is a compile-time constant: this
+// build has the code. Whether the routes are reachable is `enabled`.
+//
+// ------------------------------------------------------------ anti-drift
+//
+// `enabled` reads `threadAttachEnabled()` — the SAME function
+// routes/agent-session-bindings.ts calls to decide whether to register the two
+// POST routes. Not a second copy of `process.env.COS_THREAD_ATTACH_ENABLED === '1'`.
+// A copy is how this surface comes to advertise a write path that 404s, and the
+// repo already carries that lesson one import above the call site in
+// routes/health.ts: MEDIA_CHUNKED_UPLOAD_ENABLED is imported from the route that
+// owns the endpoints "so it cannot drift from whether they are actually
+// registered."
+//
+// `providers` is sourced from BINDABLE_PROVIDERS for the same reason. Cursor must
+// not appear (plan 2.5 makes it Fork-only), and the way to guarantee that is to
+// read the list that `isBindableProvider` — the check the attach route itself
+// applies — is built from, rather than restating two names here and hoping.
+//
+// ------------------------------------------------- why providers empties out
+//
+// When the gate is off, `providers` is `[]` rather than the list this build could
+// drive if it were on. A client that reads only `threadAttachProviders` and never
+// looks at `threadAttachEnabled` is then still correct. Every field independently
+// resolves to "no" when the answer is no; there is no combination of fields a
+// careless reader can pick that yields a Continue button pointing at an
+// unregistered route.
+//
+// The cost is that a disabled server cannot tell an operator WHICH providers it
+// would support. That is a settings-copy problem, and `supported: true` is enough
+// to say "this build can do it, turn it on."
+
+import {
+  BINDABLE_PROVIDERS,
+  isBindableProvider,
+  type BindableProvider,
+} from './agent-session-binding-store.js'
+import { threadAttachEnabled } from '../routes/agent-session-bindings.js'
+
+/**
+ * This build has the feature compiled in.
+ *
+ * A constant, not a probe. There is no configuration under which the code is
+ * absent from a build that contains this file; the reachable/unreachable question
+ * is `enabled`. It is published so that `undefined` (an older server) and `false`
+ * (this build, switched off) are different answers on the wire.
+ */
+export const THREAD_ATTACH_SUPPORTED = true
+
+export interface ThreadAttachCapability {
+  /** The build knows what Continue is. False only when read off an older payload. */
+  supported: boolean
+  /** The write routes are registered and a Continue may be attempted. */
+  enabled: boolean
+  /**
+   * Providers that can be CONTINUED, not merely browsed or forked.
+   *
+   * Empty whenever `enabled` is false. Cursor is never a member: it is Fork-only.
+   */
+  providers: BindableProvider[]
+  /**
+   * Fork is available. NOT gated by `enabled`.
+   *
+   * Fork creates a new thread and leaves the source byte-identical, so the flag
+   * that protects an existing conversation does not apply. Gating it produced an
+   * incoherent default: every refusal recommends Fork while the route 404s.
+   */
+  forkSupported: boolean
+}
+
+/**
+ * The capability as this server should publish it.
+ *
+ * @param gate Tests only. Production takes the default, which is the same
+ *   function that decides whether the write routes exist. Passing anything else
+ *   from production code re-opens the drift this module was written to close.
+ */
+export function threadAttachCapability(
+  gate: () => boolean = threadAttachEnabled,
+): ThreadAttachCapability {
+  let enabled = false
+  try {
+    // Anything other than an exact `true` is off. A gate that answers "maybe" is
+    // answering no, and a gate that throws has not answered at all.
+    enabled = gate() === true
+  } catch (error) {
+    console.error(
+      `[thread-attach-capability] gate threw: ${error instanceof Error ? error.message : error}`,
+    )
+    enabled = false
+  }
+  return {
+    supported: THREAD_ATTACH_SUPPORTED,
+    enabled,
+    providers: enabled ? [...BINDABLE_PROVIDERS] : [],
+    // NOT gated by `enabled`: fork creates a new thread and leaves the source
+    // byte-identical, so the flag protecting an existing conversation does not
+    // apply. Gating it made every refusal recommend a route that 404s.
+    forkSupported: THREAD_ATTACH_SUPPORTED,
+  }
+}
+
+/** The three keys as they appear on /api/health and /api/models. */
+export interface ThreadAttachHealthFields {
+  threadAttachSupported: boolean
+  threadAttachEnabled: boolean
+  /** Fork is available whenever the build supports it, gate or no gate. */
+  threadForkSupported: boolean
+  threadAttachProviders: BindableProvider[]
+}
+
+/** Flatten the capability onto the health payload's key names. */
+export function threadAttachHealthFields(
+  capability: ThreadAttachCapability,
+): ThreadAttachHealthFields {
+  return {
+    threadAttachSupported: capability.supported,
+    threadAttachEnabled: capability.enabled,
+    threadAttachProviders: capability.providers,
+    threadForkSupported: capability.forkSupported,
+  }
+}
+
+/**
+ * Interpret a health payload from ANY server, including one that predates these
+ * fields entirely.
+ *
+ * The whole point of this function is the defaults, so read them as the contract:
+ *
+ *   - a payload that is not an object at all -> everything off
+ *   - `threadAttachSupported` anything but exactly `true` -> not supported, and
+ *     therefore not enabled, whatever the other two fields say
+ *   - `threadAttachEnabled` anything but exactly `true` -> off, so `'true'`, `1`
+ *     and `'yes'` from a hand-rolled or proxied payload all fail closed
+ *   - `providers` dropped entirely unless enabled, and filtered to names THIS
+ *     build can actually drive, so a newer server naming a fourth provider does
+ *     not make an older client offer a Continue it cannot perform
+ *
+ * A payload that contradicts itself — enabled without supported, or providers
+ * while disabled — is a defect somewhere, and a defect resolves to refuse.
+ */
+export function readThreadAttachCapability(payload: unknown): ThreadAttachCapability {
+  const row =
+    payload && typeof payload === 'object' && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)
+      : null
+
+  const supported = row?.threadAttachSupported === true
+  const enabled = supported && row?.threadAttachEnabled === true
+
+  const providers: BindableProvider[] = []
+  const raw = row?.threadAttachProviders
+  if (enabled && Array.isArray(raw)) {
+    for (const entry of raw) {
+      // `isBindableProvider` is the attach route's own check. Anything it rejects
+      // is a provider this build has no code path for, so offering it would
+      // produce a Continue that cannot be honoured.
+      if (!isBindableProvider(entry)) continue
+      if (providers.includes(entry)) continue
+      providers.push(entry)
+    }
+  }
+
+  // Read off a payload from another server. An older build has no fork route, and
+  // its payload carries no such field, so absent must read as NOT supported — the
+  // same fail-closed rule the rest of this module runs on.
+  const forkSupported = row?.threadForkSupported === true
+  return { supported, enabled, providers, forkSupported }
+}