@oar-sh/oar 0.9.22 → 0.9.24

package/server/services/about-service.mjs

@@ -24,9 +24,10 @@ export { readGitCommit, resolveBuildCommit };
 export const ABOUT_TOTALS_CACHE_MS = 60_000;
 export const ABOUT_MESSAGE_CHUNK_ROWS = 10_000;
 
-// The packages each provider's workers run on, read from node_modules once.
+// The agent SDKs each provider's workers run on, by provider and store id
+// (agent-sdk-store.mjs). Copilot has none of its own: its workers load the
+// SDK the Copilot CLI ships, so its row names the CLI version only.
 export const ABOUT_PROVIDER_SDK_PACKAGES = Object.freeze({
-  github: '@github/copilot-sdk',
   claude: '@anthropic-ai/claude-agent-sdk',
   cursor: '@cursor/sdk',
 });
@@ -302,6 +303,7 @@ async function fileSize(fsImpl, filePath) {
  * @param {() => boolean} [deps.isRelayCliOnline] the Copilot relay CLI is connected
  * @param {() => object[]} [deps.listWorkers] the session worker registry's entries
  * @param {() => object|null} [deps.getUpdateState] buildUpdateStatePayload()
+ * @param {() => object|null} [deps.getAgentSdkStatus] the agent SDK store's snapshot(); its `installed` versions come first
  * @param {object} [deps.sdkVersions] package version by provider id; read from node_modules when absent
  * @param {() => object|null} [deps.describeBackups] the database backups (db-backup-service.mjs describeBackups)
  */
@@ -320,6 +322,7 @@ export function createAboutService({
   isRelayCliOnline = () => false,
   listWorkers = () => [],
   getUpdateState = () => null,
+  getAgentSdkStatus = null,
   sdkVersions = null,
   isPidAlive = defaultIsPidAlive,
   fsImpl = fs,
@@ -332,7 +335,23 @@ export function createAboutService({
   let resolvedSdkVersions = sdkVersions;
   const providerForConversation = db.prepare(`SELECT provider_type FROM runtime_sessions WHERE conversation_id = ?`);
 
-  function sdkVersionFor(providerId) {
+  // The store's installed versions, read per answer (an install or a
+  // reinstall changes them under a running relay); null without a store.
+  function readAgentSdkSnapshot() {
+    if (typeof getAgentSdkStatus !== 'function') return null;
+    try {
+      return getAgentSdkStatus()?.sdks || null;
+    } catch {
+      return null;
+    }
+  }
+
+  // The store's folder first, then the package's own node_modules: the order
+  // agent-sdk-loader.mjs loads them in (a git checkout runs its
+  // devDependency until the store has the pinned folder).
+  function sdkVersionFor(providerId, agentSdks) {
+    const installed = String(agentSdks?.[providerId]?.installed || '').trim();
+    if (installed) return installed;
     if (!resolvedSdkVersions) {
       resolvedSdkVersions = {};
       for (const [id, packageName] of Object.entries(ABOUT_PROVIDER_SDK_PACKAGES)) {
@@ -385,6 +404,7 @@ export function createAboutService({
     const settings = getProviderSettings() || {};
     const cli = getCachedCliProviders() || {};
     const relayCliOnline = isRelayCliOnline() === true;
+    const agentSdks = readAgentSdkSnapshot();
     const rows = [];
     for (const id of Object.keys(ABOUT_PROVIDER_LABELS)) {
       const entry = settings[id];
@@ -395,15 +415,15 @@ export function createAboutService({
       const viaRelayCli = id === 'openai' || (id === 'github' && engine === 'extension');
       const runningWorkers = workerCounts.get(id) || 0;
       const cliRow = PROVIDER_CLI_IDS[id] ? cli[PROVIDER_CLI_IDS[id]] : null;
-      const showSdk = id !== 'github' || engine === 'sdk';
+      const sdkPackage = ABOUT_PROVIDER_SDK_PACKAGES[id] || null;
       rows.push({
         id,
         label: ABOUT_PROVIDER_LABELS[id],
         engine,
         cliVersion: cliRow?.installed ? (cliRow.version || null) : null,
         cliCheckedAt: cliRow?.checkedAt || null,
-        sdkPackage: showSdk ? (ABOUT_PROVIDER_SDK_PACKAGES[id] || null) : null,
-        sdkVersion: showSdk ? sdkVersionFor(id) : null,
+        sdkPackage,
+        sdkVersion: sdkPackage ? sdkVersionFor(id, agentSdks) : null,
         state: viaRelayCli
           ? (relayCliOnline ? 'online' : 'offline')
           : (runningWorkers > 0 ? 'online' : 'idle'),

package/server/services/agent-sdk-launch-gate.mjs

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * The launch gate of the agent SDKs (agent-sdk-store.mjs): which SDK folder
+ * a worker is launched with, and what happens while there is none.
+ *
+ * A worker kind on an SDK (the Claude workers on Claude's, Cursor on its
+ * own) gets the store's ready folder, which it keeps for its whole life. A
+ * checkout's devDependency needs no folder. A missing SDK is never waited
+ * for: the gate starts (or joins) its install, puts an "Installing the …
+ * SDK" note in the conversation, and answers `deferred` at once. The
+ * supervisor counts that as no launch and no failure, so the request that
+ * asked for the worker (a new chat, a send, the queue's prime) answers right
+ * away and the turn stays queued. When the install ends, and whenever the
+ * SDK turns ready later (the Retry button, the automatic retry), the
+ * sessions that met the gate get their launch back (`onSessionsReleased`):
+ * their restart schedule is cleared and the queue is woken.
+ *
+ * An SDK that failed, or has no build for this platform, stops the launch
+ * with one line naming the Settings tab; the worker launch note carries it
+ * and the message stays queued for the Retry.
+ */
+
+export const AGENT_SDK_INSTALLING = 'agent-sdk-installing';
+
+/**
+ * Whether a stale worker of `kind` may lose its SDK's files to an update,
+ * so the recycle replaces it before its next message: a kind on an agent
+ * SDK the store installs. One whose SDK comes from a git checkout's
+ * node_modules keeps its files across a restart on new code, and is
+ * recycled like any worker (between turns, once its CLI child is idle).
+ */
+export function staleWorkerLosesAgentSdk(kind, { sdkForWorkerKind, fromCheckout }) {
+  const sdk = sdkForWorkerKind(kind);
+  return sdk !== null && !fromCheckout(sdk);
+}
+
+export function createAgentSdkLaunchGate({
+  store,
+  sdkForWorkerKind,
+  resolveSource,
+  noteInstalling = () => {},
+  onSessionsReleased = () => {},
+  logger = console,
+} = {}) {
+  if (!store) throw new Error('createAgentSdkLaunchGate requires a store');
+  // Per SDK, the sessions whose launch met the gate and waits for it.
+  const waiting = new Map();
+  // Per SDK, an install this gate already follows to its end.
+  const following = new Set();
+
+  const log = (message) => {
+    try { logger?.log?.(`[agent-sdk] ${message}`); } catch {}
+  };
+
+  function remember(sdk, sdkSessionId) {
+    if (!waiting.has(sdk)) waiting.set(sdk, new Set());
+    waiting.get(sdk).add(sdkSessionId);
+  }
+
+  /** Hands every session that waited on `sdk` its launch back. */
+  function release(sdk, reason) {
+    const sessions = [...(waiting.get(sdk) || [])];
+    waiting.delete(sdk);
+    if (!sessions.length) return [];
+    log(`${sdk}: ${reason}; ${sessions.length} waiting session(s) may launch`);
+    try { onSessionsReleased({ sdk, sessions, reason }); } catch (error) {
+      log(`${sdk}: releasing the waiting sessions failed: ${error?.message || error}`);
+    }
+    return sessions;
+  }
+
+  function follow(sdk) {
+    if (following.has(sdk)) return;
+    following.add(sdk);
+    Promise.resolve(store.ensure(sdk, { reason: 'first chat' }))
+      .catch((error) => log(`${sdk}: install failed: ${error?.message || error}`))
+      .finally(() => {
+        following.delete(sdk);
+        // Ready or failed: the next launch says which.
+        release(sdk, 'install ended');
+      });
+  }
+
+  /**
+   * What the launch of `sdkSessionId` (worker kind `workerKind`) does:
+   * `{ sdk: null }` (no SDK, or a checkout's devDependency),
+   * `{ sdk, dir }` (launch with this folder), or `{ sdk, deferred }` (not
+   * launched now). Throws for an SDK that failed or has no build here.
+   */
+  function check(sdkSessionId, workerKind) {
+    const sdk = sdkForWorkerKind(workerKind);
+    if (!sdk) return { sdk: null };
+    const found = resolveSource(sdk);
+    if (found?.source === 'checkout') return { sdk: null };
+    if (found?.dir) return { sdk, dir: found.dir };
+    const status = store.status(sdk);
+    const label = store.getDescriptor?.(sdk)?.label || status?.label || sdk;
+    if (status && ['error', 'unsupported'].includes(status.state) && !status.active) {
+      // Remembered too: a Retry that brings the SDK back launches it.
+      remember(sdk, sdkSessionId);
+      const tab = sdk === 'cursor' ? 'Cursor' : 'Claude';
+      const why = status.state === 'unsupported'
+        ? `${label} is not available on this platform`
+        : `${label} could not be installed: ${status.error || 'unknown error'}`;
+      throw new Error(`${why} (Settings → Providers → ${tab})`);
+    }
+    remember(sdk, sdkSessionId);
+    try { noteInstalling(sdkSessionId, { sdk, label }); } catch {}
+    follow(sdk);
+    return { sdk, deferred: AGENT_SDK_INSTALLING };
+  }
+
+  /** The store's ready hook: an SDK that came back launches its waiters. */
+  function onReady(sdk) {
+    return release(sdk, 'ready');
+  }
+
+  return {
+    check,
+    onReady,
+    waitingSessions: (sdk) => [...(waiting.get(sdk) || [])],
+  };
+}

package/server/services/agent-sdk-paths.mjs

@@ -0,0 +1,307 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveOarRoot } from './oar-state-root.mjs';
+
+/**
+ * Where the agent SDKs the relay installs on demand live, and which folder
+ * holds a usable copy. Synchronous, without a database and without imports
+ * of the relay's own services: the relay's lock check (koffi on Windows) and
+ * a worker's loader read this before anything else runs. The installing half
+ * is agent-sdk-store.mjs.
+ *
+ *   <root>/<sdk>/<version>-<hash8>/          one folder per SDK, version and platform
+ *     oar-sdk.json                            the marker, written last
+ *   <root>/<sdk>/.leases/<folder>/<pid>-*.json  who uses a folder (agent-sdk-store.mjs)
+ *   <root>/<sdk>/.store.lock                 held while one process installs or deletes
+ *
+ * <root> is <state root>/sdks, or OAR_SDK_DIR. <hash8> covers the pins
+ * folder's files (package.json, lockfile, entries) and the platform, so a
+ * changed entry file or a root shared by Windows and WSL never reuses a
+ * folder made for something else.
+ */
+
+export const AGENT_SDK_PINS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'agent-sdks');
+export const AGENT_SDK_MARKER = 'oar-sdk.json';
+export const AGENT_SDK_LEASES_DIR = '.leases';
+// Bumped when the folder layout or the marker changes meaning.
+export const AGENT_SDK_STORE_FORMAT = 1;
+
+/** What each pins folder installs, and which file a loader imports. */
+export const AGENT_SDK_DESCRIPTORS = Object.freeze({
+  claude: Object.freeze({
+    id: 'claude',
+    label: 'Claude Agent SDK',
+    packageName: '@anthropic-ai/claude-agent-sdk',
+    entries: Object.freeze({ main: 'entry.mjs' }),
+    platformScope: '@anthropic-ai/claude-agent-sdk-',
+    // Platforms without a vendor build where the SDK runs the host's own
+    // Claude Code CLI instead (CLAUDE_CODE_EXECUTABLE). None is verified
+    // yet; native Termux (android) would be the candidate.
+    hostCliPlatforms: Object.freeze([]),
+    platforms: null,
+  }),
+  cursor: Object.freeze({
+    id: 'cursor',
+    label: 'Cursor SDK',
+    packageName: '@cursor/sdk',
+    entries: Object.freeze({ main: 'entry.mjs', sqlite: 'entry-sqlite.mjs' }),
+    platformScope: '@cursor/sdk-',
+    platforms: null,
+  }),
+  koffi: Object.freeze({
+    id: 'koffi',
+    label: 'Windows helper (koffi)',
+    packageName: 'koffi',
+    entries: Object.freeze({ main: 'entry.cjs' }),
+    platformScope: '@koromix/koffi-',
+    // The relay needs it only for its lock check on Windows.
+    platforms: Object.freeze(['win32']),
+  }),
+});
+
+export const AGENT_SDK_IDS = Object.freeze(Object.keys(AGENT_SDK_DESCRIPTORS));
+
+export function getAgentSdkDescriptor(id) {
+  const key = String(id || '').trim().toLowerCase();
+  return Object.prototype.hasOwnProperty.call(AGENT_SDK_DESCRIPTORS, key) ? AGENT_SDK_DESCRIPTORS[key] : null;
+}
+
+/** `<state root>/sdks`, or OAR_SDK_DIR; always absolute. */
+export function resolveAgentSdkRoot({ env = process.env, platform = process.platform } = {}) {
+  const override = String(env?.OAR_SDK_DIR || '').trim();
+  if (override) return path.resolve(override);
+  return path.join(resolveOarRoot(env, platform), 'sdks');
+}
+
+/** Linux's C library as npm tells it, 'glibc' or 'musl'; null elsewhere. */
+export function detectLibc({ platform = process.platform, report = () => process.report?.getReport?.() } = {}) {
+  if (platform !== 'linux') return null;
+  try {
+    return report()?.header?.glibcVersionRuntime ? 'glibc' : 'musl';
+  } catch {
+    return null;
+  }
+}
+
+export function hostPlatform({ platform = process.platform, arch = process.arch, libc } = {}) {
+  return { platform, arch, libc: libc === undefined ? detectLibc({ platform }) : libc };
+}
+
+const pinCache = new Map();
+
+/**
+ * The pin of an SDK for this host: the pins folder's files as read once
+ * (an `oar update` replaces them under a running relay, which goes on
+ * installing what it was started with), the pinned version and the folder
+ * name, `<version>-<first 8 hex of the content hash>`.
+ */
+export function readAgentSdkPin(id, { pinsDir = AGENT_SDK_PINS_DIR, fsImpl = fs, host = hostPlatform() } = {}) {
+  const descriptor = getAgentSdkDescriptor(id);
+  if (!descriptor) return null;
+  const folder = path.join(pinsDir, descriptor.id);
+  const cacheKey = JSON.stringify([folder, host.platform, host.arch, host.libc]);
+  if (fsImpl === fs && pinCache.has(cacheKey)) return pinCache.get(cacheKey);
+  const names = ['package.json', 'package-lock.json', ...Object.values(descriptor.entries)].sort();
+  const files = {};
+  const hash = crypto.createHash('sha256').update(`oar-sdk-store:${AGENT_SDK_STORE_FORMAT}\0${host.platform}\0${host.arch}\0${host.libc || ''}\0`);
+  for (const name of names) {
+    files[name] = fsImpl.readFileSync(path.join(folder, name));
+    hash.update(`${name}\0`).update(files[name]).update('\0');
+  }
+  const packageJson = JSON.parse(files['package.json'].toString('utf8'));
+  const version = String(packageJson.dependencies?.[descriptor.packageName] || '');
+  const fullHash = hash.digest('hex');
+  const pin = Object.freeze({
+    id: descriptor.id,
+    version,
+    hash: fullHash,
+    dirName: `${version}-${fullHash.slice(0, 8)}`,
+    host: Object.freeze({ ...host }),
+    files: Object.freeze(files),
+    lock: JSON.parse(files['package-lock.json'].toString('utf8')),
+  });
+  if (fsImpl === fs) pinCache.set(cacheKey, pin);
+  return pin;
+}
+
+function matchesList(list, value) {
+  if (!Array.isArray(list) || !list.length) return true;
+  if (list.includes(`!${value}`)) return false;
+  const allowed = list.filter((item) => !String(item).startsWith('!'));
+  return !allowed.length || allowed.includes(value);
+}
+
+/**
+ * The vendor's platform package this host gets from the pinned lockfile, or
+ * null when the vendor lists none for it. Matches os, cpu and libc as npm
+ * does.
+ */
+export function platformPackageFor(pin) {
+  const descriptor = getAgentSdkDescriptor(pin?.id);
+  if (!descriptor || !pin?.lock?.packages) return null;
+  const { platform, arch, libc } = pin.host;
+  for (const [key, entry] of Object.entries(pin.lock.packages)) {
+    const name = key.slice(key.lastIndexOf('node_modules/') + 'node_modules/'.length);
+    if (!name.startsWith(descriptor.platformScope) || !entry?.os) continue;
+    if (!matchesList(entry.os, platform) || !matchesList(entry.cpu, arch)) continue;
+    if (entry.libc && libc && !matchesList(entry.libc, libc)) continue;
+    return name;
+  }
+  return null;
+}
+
+/**
+ * Whether this host can run the SDK at all, from the descriptor and the
+ * lockfile alone: 'yes' (a vendor build for it), 'cli' (none, but the
+ * descriptor lets the host's own CLI do the work there) or 'no' ("not
+ * available on this platform", never retried).
+ */
+export function agentSdkSupport(pin, { hostCliPlatforms } = {}) {
+  const descriptor = getAgentSdkDescriptor(pin?.id);
+  if (!descriptor) return 'no';
+  if (descriptor.platforms && !descriptor.platforms.includes(pin.host.platform)) return 'no';
+  if (platformPackageFor(pin)) return 'yes';
+  return (hostCliPlatforms ?? descriptor.hostCliPlatforms ?? []).includes(pin.host.platform) ? 'cli' : 'no';
+}
+
+/**
+ * The files an install is checked by, relative to its folder: the entries,
+ * each pinned package's package.json and the platform package's, the SDK's
+ * own main module. A file an antivirus took, or a half-deleted tree, changes
+ * one of them.
+ */
+export function agentSdkCheckedFiles(pin) {
+  const descriptor = getAgentSdkDescriptor(pin?.id);
+  const files = [...Object.values(descriptor.entries)];
+  const packageJson = JSON.parse(pin.files['package.json'].toString('utf8'));
+  for (const name of Object.keys(packageJson.dependencies || {})) files.push(`node_modules/${name}/package.json`);
+  const platformPackage = platformPackageFor(pin);
+  if (platformPackage) files.push(`node_modules/${platformPackage}/package.json`);
+  return files;
+}
+
+/** The marker of an installed folder, or null. */
+export function readAgentSdkMarker(dir, { fsImpl = fs } = {}) {
+  try {
+    const marker = JSON.parse(fsImpl.readFileSync(path.join(dir, AGENT_SDK_MARKER), 'utf8'));
+    return marker && typeof marker === 'object' && !Array.isArray(marker) ? marker : null;
+  } catch {
+    return null;
+  }
+}
+
+function sizesMatch(dir, files, fsImpl) {
+  if (!files || typeof files !== 'object' || !Object.keys(files).length) return false;
+  try {
+    for (const [rel, size] of Object.entries(files)) {
+      const stat = fsImpl.statSync(path.join(dir, ...rel.split('/')));
+      if (!stat.isFile() || stat.size !== size) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `dir` holds a finished install made for this host: its marker
+ * names the SDK, the store format and the platform, and every file it
+ * recorded is there at its size. With `pin`, also the pinned version and
+ * content hash.
+ */
+export function isValidAgentSdkInstall(dir, { id, pin = null, host = pin?.host || hostPlatform(), fsImpl = fs } = {}) {
+  const marker = readAgentSdkMarker(dir, { fsImpl });
+  if (!marker || marker.format !== AGENT_SDK_STORE_FORMAT || marker.id !== (pin?.id || id)) return false;
+  if (marker.platform !== host.platform || marker.arch !== host.arch || (marker.libc || null) !== (host.libc || null)) return false;
+  if (pin && (marker.version !== pin.version || marker.hash !== pin.hash || path.basename(dir) !== pin.dirName)) return false;
+  return sizesMatch(dir, marker.files, fsImpl);
+}
+
+const FOLDER_NAME = /^\d[\w.+-]*-[0-9a-f]{8}$/;
+
+/**
+ * The pinned folder of an SDK when it holds a finished install, else null.
+ * With `anyVersion`, otherwise the newest valid folder of an earlier pin
+ * (koffi: any version reads a process's start time).
+ */
+export function findReadyAgentSdkDir(id, {
+  env = process.env,
+  platform = process.platform,
+  root = resolveAgentSdkRoot({ env, platform }),
+  pinsDir = AGENT_SDK_PINS_DIR,
+  host = hostPlatform({ platform }),
+  anyVersion = false,
+  fsImpl = fs,
+} = {}) {
+  try {
+    const pin = readAgentSdkPin(id, { pinsDir, fsImpl, host });
+    if (!pin) return null;
+    const pinned = path.join(root, pin.id, pin.dirName);
+    if (isValidAgentSdkInstall(pinned, { pin, fsImpl })) return pinned;
+    if (!anyVersion) return null;
+    let best = null;
+    for (const name of fsImpl.readdirSync(path.join(root, pin.id))) {
+      if (!FOLDER_NAME.test(name)) continue;
+      const dir = path.join(root, pin.id, name);
+      if (!isValidAgentSdkInstall(dir, { id: pin.id, host, fsImpl })) continue;
+      const at = Date.parse(readAgentSdkMarker(dir, { fsImpl })?.installedAt || '') || 0;
+      if (!best || at > best.at) best = { dir, at };
+    }
+    return best?.dir || null;
+  } catch {
+    return null;
+  }
+}
+
+export const AGENT_SDK_PACKAGE_ROOT = path.resolve(AGENT_SDK_PINS_DIR, '..', '..');
+
+/**
+ * Whether this process takes the SDKs from the package's own node_modules:
+ * a git checkout has them as devDependencies at the pinned versions.
+ * OAR_AGENT_SDK_SOURCE=store makes a checkout use the store like an install
+ * does.
+ */
+export function agentSdksFromCheckout({ env = process.env, packageRoot = AGENT_SDK_PACKAGE_ROOT, fsImpl = fs } = {}) {
+  if (String(env?.OAR_AGENT_SDK_SOURCE || '').trim().toLowerCase() === 'store') return false;
+  try { return fsImpl.existsSync(path.join(packageRoot, '.git')); } catch { return false; }
+}
+
+/**
+ * Whether this process takes one SDK from the checkout: a checkout (above)
+ * whose node_modules really holds the package. One installed without its
+ * devDependencies (`npm install --omit=dev`) takes it from the store.
+ */
+export function agentSdkFromCheckout(id, { env = process.env, packageRoot = AGENT_SDK_PACKAGE_ROOT, fsImpl = fs } = {}) {
+  const descriptor = getAgentSdkDescriptor(id);
+  if (!descriptor || !agentSdksFromCheckout({ env, packageRoot, fsImpl })) return false;
+  try {
+    return fsImpl.existsSync(path.join(packageRoot, 'node_modules', ...descriptor.packageName.split('/'), 'package.json'));
+  } catch {
+    return false;
+  }
+}
+
+export function isAgentSdkFolderName(name) {
+  return FOLDER_NAME.test(String(name || ''));
+}
+
+/**
+ * Records that process `pid` uses the folder `dir`, so no store's clean-up
+ * deletes it while the process runs (agent-sdk-store.mjs judges the
+ * leases). `holder` is the process's identity as the relay lock records it.
+ * Returns the lease file, or null when it could not be written.
+ */
+export function writeAgentSdkLease(dir, { pid = process.pid, holder = null, bootId = '', now = () => new Date(), fsImpl = fs } = {}) {
+  try {
+    const leasesDir = path.join(path.dirname(dir), AGENT_SDK_LEASES_DIR, path.basename(dir));
+    fsImpl.mkdirSync(leasesDir, { recursive: true });
+    const file = path.join(leasesDir, `${pid}-${crypto.randomBytes(3).toString('hex')}.json`);
+    fsImpl.writeFileSync(file, `${JSON.stringify({ format: 2, pid, holder, ...(bootId ? { bootId } : {}), startedAt: now().toISOString() })}\n`, { flag: 'wx' });
+    return file;
+  } catch {
+    return null;
+  }
+}