@oar-sh/oar 0.9.23 → 0.9.25

package/server/services/remote-relay-registry-service.mjs

@@ -226,7 +226,9 @@ export function createRemoteRelayRegistry({
       version: toText(version) || null,
       platform: toText(platform) || null,
       publicUrl: settings.publicUrl || null,
-      remoteRelays: { protocol: REMOTE_RELAY_PROTOCOL, inbound: settings.inboundEnabled },
+      // imageInputs: send and create_session may carry images and image
+      // options here; an older relay would drop them and run the turn without.
+      remoteRelays: { protocol: REMOTE_RELAY_PROTOCOL, inbound: settings.inboundEnabled, imageInputs: true },
     };
   }
 

package/server/services/session-worker-launch-service.mjs

@@ -197,6 +197,16 @@ export function resolveWorkerKind(env = {}) {
   return Object.hasOwn(NODE_WORKER_DESCRIPTORS, kind) ? kind : 'copilot';
 }
 
+// The agent SDK a worker kind runs on (agent-sdk-store.mjs), or null: the
+// Claude workers (subscription, API key, DeepSeek) on the Claude SDK, Cursor
+// on its own; every other kind needs none.
+const WORKER_KIND_AGENT_SDK = Object.freeze({ claude: 'claude', 'claude-api': 'claude', deepseek: 'claude', cursor: 'cursor' });
+
+export function agentSdkForWorkerKind(kind) {
+  const key = String(kind || '').trim().toLowerCase();
+  return Object.hasOwn(WORKER_KIND_AGENT_SDK, key) ? WORKER_KIND_AGENT_SDK[key] : null;
+}
+
 export function applyClaudeProviderEnvironment(env = {}, {
   enabled = false,
   model = '',
@@ -933,6 +943,9 @@ export const TMUX_WORKER_EXPORTED_ENV_VARS = Object.freeze([
   // extension engine's "it is attached" marker.
   'OAR_MCP_SERVER',
   'OAR_MCP_SERVER_ATTACHED',
+  // The agent SDK folder a worker runs on for its whole life (agent-sdk-loader.mjs).
+  'OAR_AGENT_SDK_DIR_CLAUDE',
+  'OAR_AGENT_SDK_DIR_CURSOR',
   'SESSION_ID',
   'COPILOT_WORKSPACE_ROOT',
   'INIT_CWD',

package/server/services/session-worker-supervisor-service.mjs

@@ -556,7 +556,8 @@ export function createSessionWorkerSupervisor({
     if (!to || from === to) return true;
     const allowed = {
       new: new Set(['starting', 'ready', 'error', 'processing']),
-      starting: new Set(['ready', 'error']),
+      // 'new': a start the agent SDK gate deferred, so no worker came up.
+      starting: new Set(['ready', 'error', 'new']),
       ready: new Set(['processing', 'starting', 'error']),
       processing: new Set(['ready', 'error']),
       error: new Set(['starting', 'ready']),
@@ -683,6 +684,23 @@ export function createSessionWorkerSupervisor({
           if (!isStartActive() || isKillBlocked(sessionId)) {
             return buildStartBlockedResult();
           }
+          // Not launched, and not a failure either (the agent SDK it needs is
+          // still installing, agent-sdk-launch-gate.mjs): no worker, no
+          // restart backoff, no launch note; the turn stays queued until the
+          // gate hands the session its launch back.
+          if (spawned?.deferred) {
+            const waitingState = setWorkerState(sessionId, {
+              sdkSessionId: sessionId,
+              // No worker yet ('new'), so nothing waits for its heartbeat.
+              status: 'new',
+              workerId: null,
+              pid: null,
+              queueDepth: startingState.queueDepth || 0,
+              retryCount: startingState.retryCount || 0,
+              lastError: null,
+            });
+            return { ok: true, deferred: String(spawned.deferred), reused: false, worker: waitingState, lifecycle: toLifecycleSnapshot(sessionId) };
+          }
           const readyState = setWorkerState(sessionId, {
             ...startingState,
             workerId: String(spawned?.workerId || startingState.workerId || `worker-${sessionId.slice(0, 8)}`).trim(),

package/server/services/session-worker-websocket-service.mjs

@@ -132,6 +132,11 @@ export function createSessionWorkerWebSocketService({
   // ready: (sessionId, buildId, pid). The registry keeps it, so the relay can
   // tell a worker on older code from one that runs what the relay runs.
   onWorkerBuildId = () => {},
+  // A worker said hello: ({ sessionId, pid, kind, buildId }), with what the
+  // socket knows of it. Called before the hello's own request for work, so
+  // the relay can register the process and fence it first (a stale worker
+  // reconnecting to a new relay: the worker recycle).
+  onWorkerHello = () => {},
   // The relay's own build id, sent in every server.hello so a worker can log
   // that it runs other code; null leaves the key out.
   buildId = null,
@@ -572,6 +577,16 @@ export function createSessionWorkerWebSocketService({
         meta.ready = payload.ready !== false;
         meta.lastHelloAt = nowIso();
         noteHeartbeat(meta, 'worker-hello');
+        if (meta.sessionId) {
+          try {
+            onWorkerHello({
+              sessionId: meta.sessionId,
+              pid: meta.pid || null,
+              kind: meta.workerKind || null,
+              buildId: meta.workerBuildId || null,
+            });
+          } catch {}
+        }
         emitEvent(ws, serverHello('ack', meta.sessionId));
         void maybeDeliverToSocket(ws, 'worker-hello');
         return;

package/server/services/token-usage-service.mjs

@@ -219,6 +219,8 @@ export function createTokenUsageService({
       listAllDayRows: db.prepare(`SELECT * FROM ${TOKEN_USAGE_DAYS_TABLE}`),
       listTurnRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE turn_id = ? ORDER BY at, run_id, model`),
       listConversationRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE conversation_id = ? ORDER BY at, turn_id, run_id, model`),
+      listBillingDayRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE day = ? AND provider = ? AND billing = ? ORDER BY at, turn_id, run_id, model`),
+      listBillingConversationRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE conversation_id = ? AND provider = ? AND billing = ? ORDER BY at, turn_id, run_id, model`),
       deleteConversationRows: db.prepare(`DELETE FROM ${TURN_TOKEN_USAGE_TABLE} WHERE conversation_id = ?`),
     };
   }
@@ -410,6 +412,18 @@ export function createTokenUsageService({
     };
   }
 
+  /**
+   * The turn rows of one provider and billing, of one day or of one chat
+   * (`day` or `conversationId`), for the views that need what the day rows
+   * do not keep (cost_source); null when the tables are not there.
+   */
+  function readTurnRows({ provider, billing = '', day = null, conversationId = null } = {}) {
+    const s = ready();
+    if (!s) return null;
+    if (conversationId) return s.listBillingConversationRows.all(String(conversationId), provider, billing).map(turnRowOut);
+    return s.listBillingDayRows.all(String(day || localDay(now())), provider, billing).map(turnRowOut);
+  }
+
   /** The chat is deleted: its turn rows go, the day rows stay. */
   function forgetConversation(conversationId) {
     const s = ready();
@@ -423,6 +437,7 @@ export function createTokenUsageService({
     readPeriods,
     readTurn,
     readConversation,
+    readTurnRows,
     forgetConversation,
     localDay: (ms = now()) => localDay(ms),
     timeZone: formatDay.resolvedOptions().timeZone,

package/server/services/update-install-service.mjs

@@ -12,7 +12,7 @@ import {
   tailOf,
 } from './cli-process-runner.mjs';
 import { NATIVE_BUILD_COMMAND, buildBetterSqlite3, needsSourceBuild } from './native-addon-build-service.mjs';
-import { NPM_ALLOW_SCRIPTS_ARG, resolveNpmInvocation } from './oar-cli-helpers.mjs';
+import { resolveNpmInvocation } from './oar-cli-helpers.mjs';
 import { compareSemverIsh, parseSemverIsh } from '../../shared/update-semver.mjs';
 
 // Applies an OAR self-update: `npm i -g @oar-sh/oar@<version>` with the log
@@ -227,7 +227,7 @@ export function createUpdateInstallService({
     // (args are fixed strings + a validated semver, so no injection surface).
     const npm = resolveNpmInvocation({ execPath, packageRoot, platform, env, existsImpl });
     const command = npm.command;
-    const args = ['install', '-g', ...npm.prefixArgs, NPM_ALLOW_SCRIPTS_ARG, `${UPDATE_PACKAGE_NAME}@${target}`];
+    const args = ['install', '-g', ...npm.prefixArgs, `${UPDATE_PACKAGE_NAME}@${target}`];
     const result = await runToCompletion(
       () => spawnImpl(command, args, {
         stdio: ['ignore', 'pipe', 'pipe'],

package/server/services/worker-launch-note-service.mjs

@@ -18,6 +18,7 @@
 import { randomUUID } from 'node:crypto';
 
 export const WORKER_LAUNCH_NOTE_KINDS = Object.freeze({
+  installing: 'worker-launch-installing',
   failed: 'worker-launch-failed',
   stopped: 'worker-launch-stopped',
   started: 'worker-launch-started',
@@ -47,6 +48,11 @@ export function buildWorkerLaunchNoteText({ type, lifecycle = {}, retryEveryMs =
   const tries = Math.max(0, Number(lifecycle?.retryCount || 0));
   const triesText = `${tries} ${tries === 1 ? 'try' : 'tries'}`;
   const cause = clipCause(lifecycle?.lastError);
+  if (type === 'installing') {
+    // The first chat of a provider whose agent SDK is not installed yet
+    // (agent-sdk-store.mjs): the relay installs it before the worker starts.
+    return `⏳ Installing the ${lifecycle?.sdkLabel || 'agent SDK'} on the relay host, once for this version. Your message is delivered when it is ready.`;
+  }
   if (type === 'launched') {
     return `✅ The worker for this conversation started at ${formatTime(lifecycle?.launchAt || new Date().toISOString())}. The queued message is being delivered.`;
   }
@@ -77,6 +83,7 @@ export function createWorkerLaunchNoteService({
   const episodes = new Map();
 
   function kindFor(type) {
+    if (type === 'installing') return WORKER_LAUNCH_NOTE_KINDS.installing;
     if (type === 'launched') return WORKER_LAUNCH_NOTE_KINDS.started;
     if (type === 'stopped') return WORKER_LAUNCH_NOTE_KINDS.stopped;
     return WORKER_LAUNCH_NOTE_KINDS.failed;
@@ -105,7 +112,7 @@ export function createWorkerLaunchNoteService({
       stmts.updateConvTime?.run?.(at, conversationId);
     });
     write();
-    episodes.set(sdkSessionId, { messageId, conversationId, timestamp: at });
+    episodes.set(sdkSessionId, { messageId, conversationId, timestamp: at, kind, text });
     try { emit('assistant_message', { conversationId, messageId, message: messagePayload({ messageId, text, kind, timestamp: at }) }); } catch {}
     try { logger.log?.(`[worker-launch] conv=${conversationId.slice(0, 8)} note opened (${type}): ${clipCause(lifecycle?.lastError)}`); } catch {}
   }
@@ -113,6 +120,11 @@ export function createWorkerLaunchNoteService({
   function update(episode, sdkSessionId, { type, lifecycle }) {
     const kind = kindFor(type);
     const text = buildWorkerLaunchNoteText({ type, lifecycle, retryEveryMs, retryWindowMs, formatTime });
+    // The same note again (a launch deferred on every prime while an agent
+    // SDK installs): no write, no broadcast.
+    if (episode.kind === kind && episode.text === text) return;
+    episode.kind = kind;
+    episode.text = text;
     updateNote.run(text, kind, episode.messageId);
     try {
       emit('message_updated', {
@@ -130,7 +142,7 @@ export function createWorkerLaunchNoteService({
   /** The supervisor's onLaunchState listener. */
   function handle({ type, sdkSessionId, lifecycle = null } = {}) {
     const sid = String(sdkSessionId || '').trim();
-    if (!sid || !['exhausted', 'retry-failed', 'stopped', 'launched'].includes(type)) return false;
+    if (!sid || !['installing', 'exhausted', 'retry-failed', 'stopped', 'launched'].includes(type)) return false;
     const episode = episodes.get(sid) || null;
     if (episode) {
       update(episode, sid, { type, lifecycle });

package/server/services/worker-recycle-service.mjs

@@ -27,6 +27,31 @@
  * `quietMs` without a delivery or a turn end for the session, the runners'
  * own idle time.
  *
+ * A stale worker on an agent SDK the store installs (`isAgentSdkWorker`: the
+ * claude, claude-api, deepseek and cursor kinds, unless a git checkout runs
+ * that SDK from its own node_modules) is the exception. An update moves the
+ * SDKs out of the package, so the files such a worker would start its next
+ * CLI child from may be gone, and a message it gets once its child has idled
+ * out fails. So:
+ *
+ * - it skips the 'cli' and 'quiet' holds and is recycled as soon as its turn,
+ *   question and compaction holds (and the processing row) allow;
+ * - its background hold stays a hold, and is the one hold it is not fenced
+ *   for: background tasks run in the CLI child, so while they do the child is
+ *   up and a delivery goes to it, never to a new child from the gone files;
+ * - from the first sweep that sees it stale until its recycle, the
+ *   replacement fence (below) keeps every delivery away from it, so what is
+ *   queued waits for the new worker's cold start rather than failing on the
+ *   old one;
+ * - a relay that has just started knows its holds only from its first
+ *   heartbeat's steering snapshot: until that comes it waits ('steering'),
+ *   fenced, for at most `steeringWaitMs`; one that still has sent none by
+ *   then is judged as any other worker, unfenced.
+ *
+ * Besides the periodic sweep, a sweep runs at start and on every worker hello
+ * (`sweepNow`), so a stale worker that reconnects to a new relay is fenced
+ * before the hello's own request for work is answered.
+ *
  * From the moment a recycle passes its holds until its launch is done, the
  * replacement fence (worker-replacement.mjs) keeps every delivery away from
  * the process being replaced, and the stop and the launch run under the
@@ -61,9 +86,10 @@ const LOG_TAG = '[worker-recycle]';
  * the worker's own release holds (workerReleaseHold; 'turn' also for a
  * processing row the session owns), 'cli' while its CLI child runs, and
  * 'quiet' while a worker that does not report its CLI child has had a
- * delivery or a turn end within `quietMs`.
+ * delivery or a turn end within `quietMs`, and 'steering' while a worker on
+ * an agent SDK has not yet sent the snapshot that names its holds.
  */
-export const RECYCLE_HOLDS = Object.freeze(['turn', 'question', 'compaction', 'background', 'cli', 'quiet']);
+export const RECYCLE_HOLDS = Object.freeze(['turn', 'question', 'compaction', 'background', 'cli', 'quiet', 'steering']);
 const RECYCLABLE_STATUSES = new Set(['ready', 'processing']);
 
 function sid8(sid) {
@@ -155,6 +181,15 @@ export function createWorkerRecycleService({
   // without a delivery or a turn end: the Claude and Copilot runners'
   // idleShutdownMs, after which they stop the child themselves.
   quietMs = 10 * 60_000,
+  // worker → whether its kind runs on an agent SDK (agentSdkForWorkerKind):
+  // such a worker, once stale, skips the cli and quiet holds and is fenced
+  // until its recycle (see the header).
+  isAgentSdkWorker = () => false,
+  // How long a stale worker on an agent SDK may go without a steering
+  // snapshot (from when this service first saw its process) before it is
+  // judged as any other worker. Its heartbeat sends one within a second of
+  // a relay's hello.
+  steeringWaitMs = 30_000,
   logger = console,
 } = {}) {
   if (typeof stopWorker !== 'function' || typeof launchWorker !== 'function') {
@@ -214,8 +249,13 @@ export function createWorkerRecycleService({
         pendingLaunch: null,
         lastWaitLogAt: -Infinity,
         // When this service first saw the session's current pid: the quiet
-        // window's start for a worker with no start time and no queue rows.
+        // window's start for a worker with no start time and no queue rows,
+        // and the steering wait's start.
         firstSeen: null,
+        // The pid this service fenced as a stale worker on an agent SDK
+        // waiting for its recycle (sdkFenceUp), or null. A recycle admitted
+        // takes the fence over and clears this.
+        sdkFence: null,
       };
       bySession.set(sid, state);
     }
@@ -394,8 +434,18 @@ export function createWorkerRecycleService({
       });
     } finally {
       // A stop that did not go through (or never ran) leaves the old worker
-      // serving its session: it takes work again at once.
-      if (!stopped) fence.release(sid, pid);
+      // serving its session: it takes work again at once. Not one on an
+      // agent SDK the update took away: its fence stays up through the
+      // stop's backoff, until the worker goes or the tries reach stuckAfter
+      // (the sweep keeps it, sdkFenced), so no queued row goes to it.
+      if (!stopped) {
+        if (isAgentSdkWorker(worker) === true && state.failures > 0 && state.failures < stuckAfter && stillSameProcess(sid, pid)) {
+          state.sdkFence = pid;
+          log(`fence kept ${sid8(sid)} pid ${pid}: its stop failed, deliveries wait for the retry`);
+        } else {
+          fence.release(sid, pid);
+        }
+      }
     }
   }
 
@@ -454,17 +504,68 @@ export function createWorkerRecycleService({
    * worker's start, else when this service first saw the process. Throws
    * when a probe does; the caller counts that as a probe failure.
    */
-  function holdFor(sid, worker, state) {
+  function holdFor(sid, worker, state, sdkMode = null) {
     if (hasRunningTurn(sid) === true) return 'turn';
+    if (sdkMode === 'steering') return 'steering';
     const releaseHold = workerReleaseHold(worker);
     if (releaseHold) return releaseHold;
+    // A stale worker on an agent SDK goes as soon as its own holds allow: its
+    // next CLI child may have no files left to start from.
+    if (sdkMode === 'fast') return null;
     const cliAlive = worker?.steering?.cliAlive;
     if (cliAlive === true) return 'cli';
     if (cliAlive === false) return null;
+    const since = toTimeMs(quietSince(sid)) ?? toTimeMs(worker.startedAt) ?? firstSeenAt(state, worker);
+    return now() - since < quietMs ? 'quiet' : null;
+  }
+
+  // When this service first saw the worker's current process.
+  function firstSeenAt(state, worker) {
     const pid = toPid(worker.pid);
     if (state.firstSeen?.pid !== pid) state.firstSeen = { pid, at: now() };
-    const since = toTimeMs(quietSince(sid)) ?? toTimeMs(worker.startedAt) ?? state.firstSeen.at;
-    return now() - since < quietMs ? 'quiet' : null;
+    return state.firstSeen.at;
+  }
+
+  /**
+   * How a stale worker on an agent SDK is judged: 'fast' (its steering
+   * snapshot names its holds: no cli or quiet hold, fenced until the
+   * recycle), 'steering' (no snapshot yet, within `steeringWaitMs` of when
+   * this service first saw the process: wait for it, fenced), or null (not on
+   * an agent SDK, or a snapshot never came: as any other worker). Throws
+   * when the predicate does; the caller counts that as a probe failure.
+   */
+  function sdkModeFor(worker, state) {
+    if (isAgentSdkWorker(worker) !== true) return null;
+    if (worker?.steering && typeof worker.steering === 'object') return 'fast';
+    return now() - firstSeenAt(state, worker) < steeringWaitMs ? 'steering' : null;
+  }
+
+  // Raises the fence for a stale worker on an agent SDK until its recycle:
+  // whatever is queued for the session waits for the new worker.
+  function sdkFenceUp(sid, pid, state, confirmed) {
+    confirmed.add(sid);
+    if (state.sdkFence === pid && fence.isHeld(sid, pid)) return;
+    fence.hold(sid, pid);
+    if (state.sdkFence !== pid) log(`fenced ${sid8(sid)} pid ${pid}: stale on an agent SDK, deliveries wait for the recycle`);
+    state.sdkFence = pid;
+  }
+
+  // A recycle (or an archived stop) admitted for the session owns the fence
+  // from here: it lowers it when it is done.
+  function sdkFenceHandOver(state) {
+    state.sdkFence = null;
+  }
+
+  // Lowers the fences this service raised for workers no longer judged
+  // fenced by this sweep: gone, recycled, in a background hold, a probe that
+  // failed, a snapshot that never came.
+  function sdkFencesDown(confirmed) {
+    for (const [sid, state] of bySession) {
+      if (state.sdkFence === null || confirmed.has(sid)) continue;
+      const pid = state.sdkFence;
+      state.sdkFence = null;
+      if (fence.release(sid, pid)) log(`unfenced ${sid8(sid)} pid ${pid}`);
+    }
   }
 
   function noteWaiting(sid, state, hold, nextWaiting) {
@@ -509,6 +610,8 @@ export function createWorkerRecycleService({
       return;
     }
     const running = new Set();
+    // The sessions whose agent-SDK fence this sweep keeps up (sdkFenceUp).
+    const sdkFenced = new Set();
     for (const worker of workers) {
       const sid = String(worker?.sdkSessionId || '').trim();
       if (!sid) continue;
@@ -527,36 +630,51 @@ export function createWorkerRecycleService({
         continue;
       }
       const state = stateFor(sid);
-      if (state.inFlight || now() < state.nextAttemptAt) continue;
+      if (state.inFlight) continue;
+      if (now() < state.nextAttemptAt) {
+        // A failed stop's agent-SDK fence stays up through the backoff, up to
+        // stuckAfter tries; then the old worker serves again.
+        if (state.sdkFence !== null && state.sdkFence === pid && state.failures < stuckAfter) sdkFenced.add(sid);
+        continue;
+      }
       if (state.recycledPid && state.recycledPid === toPid(worker.pid)) continue;
       let hold = null;
       let archived = false;
+      let sdkMode = null;
       try {
-        hold = holdFor(sid, worker, state);
+        sdkMode = sdkModeFor(worker, state);
+        hold = holdFor(sid, worker, state, sdkMode);
         if (!hold) archived = isArchived(sid) === true;
       } catch (error) {
         // The relay cannot tell whether the session is busy or archived: the
         // worker is not stopped on a guess, and the probe is retried later.
+        // Nor is it fenced on a guess: an agent-SDK fence comes down.
         noteFailure(sid, state, 'probe', errorText(error, 'unknown'));
         continue;
       }
       if (hold) {
+        // Background tasks keep the CLI child up, so a delivery goes to it:
+        // the one hold such a worker waits out unfenced.
+        if (sdkMode && hold !== 'background') sdkFenceUp(sid, pid, state, sdkFenced);
         noteWaiting(sid, state, hold, nextWaiting);
         continue;
       }
       if (inFlight >= maxInFlight) {
         deferred = true;
+        if (sdkMode) sdkFenceUp(sid, pid, state, sdkFenced);
         continue;
       }
       if (archived) {
         // Fenced from here: the holds just passed, and a delivery to the
         // process being stopped would start a turn on it.
         fence.hold(sid, pid);
+        sdkFenceHandOver(state);
         startedSteps.push(begin(state, () => stopArchived(sid, worker, state)));
         continue;
       }
       if (!canLaunchNow()) {
         deferred = true;
+        if (sdkMode) sdkFenceUp(sid, pid, state, sdkFenced);
         continue;
       }
       lastAdmitAt = now();
@@ -564,8 +682,10 @@ export function createWorkerRecycleService({
       // await: no delivery can reach the old process between this check and
       // its stop, nor between the stop and the launch.
       fence.hold(sid, pid);
+      sdkFenceHandOver(state);
       startedSteps.push(begin(state, () => recycle(sid, worker, state)));
     }
+    sdkFencesDown(sdkFenced);
     // Launches owed after a stop went through: the registry lists no new
     // process for those sessions.
     for (const [sid, state] of bySession) {
@@ -639,6 +759,20 @@ export function createWorkerRecycleService({
     }
     started = true;
     scheduleNext();
+    // The start's own sweep: workers left from before the restart need not
+    // wait a whole interval.
+    runSweep();
+  }
+
+  /**
+   * A sweep now, outside the interval, while the service runs (a worker's
+   * hello). Its judging, the fence included, is done synchronously before
+   * this returns; the promise resolves once the recycles it started are done.
+   * Never rejects.
+   */
+  function sweepNow() {
+    if (!started) return Promise.resolve();
+    return sweep().catch(() => {});
   }
 
   function stop() {
@@ -667,7 +801,7 @@ export function createWorkerRecycleService({
     };
   }
 
-  return { start, stop, sweep, isStale, status };
+  return { start, stop, sweep, sweepNow, isStale, status };
 }
 
 /**

package/shared/image-header.mjs

@@ -0,0 +1,90 @@
+// The type and pixel size of a PNG, JPEG or WebP image, read from its first
+// bytes alone (no decoding). Anything else, or a header that does not hold
+// together, gives null.
+//
+// SDK-free and side-effect free: imported by the server and the browser.
+
+// Enough for every PNG and WebP header and for the JPEG frame header after
+// usual EXIF/ICC blocks; a JPEG whose frame header lies further in gives null.
+export const IMAGE_HEADER_BYTES = 256 * 1024;
+
+function asBytes(input) {
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  return null;
+}
+
+function u16be(bytes, at) {
+  return (bytes[at] << 8) | bytes[at + 1];
+}
+
+function u32be(bytes, at) {
+  return ((bytes[at] << 24) >>> 0) + (bytes[at + 1] << 16) + (bytes[at + 2] << 8) + bytes[at + 3];
+}
+
+function u24le(bytes, at) {
+  return bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+}
+
+function ascii(bytes, at, length) {
+  let text = '';
+  for (let index = at; index < at + length && index < bytes.length; index += 1) text += String.fromCharCode(bytes[index]);
+  return text;
+}
+
+function sized(mime, width, height) {
+  return width > 0 && height > 0 ? { mime, width, height } : null;
+}
+
+function readPng(bytes) {
+  // Signature, then IHDR as the first chunk: length 13, width, height.
+  if (bytes.length < 24 || ascii(bytes, 12, 4) !== 'IHDR') return null;
+  return sized('image/png', u32be(bytes, 16), u32be(bytes, 20));
+}
+
+function readJpeg(bytes) {
+  let at = 2;
+  while (at + 9 < bytes.length) {
+    if (bytes[at] !== 0xff) return null;
+    const marker = bytes[at + 1];
+    // Fill bytes, and markers without a length.
+    if (marker === 0xff) { at += 1; continue; }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) { at += 2; continue; }
+    if (marker === 0xd9 || marker === 0xda) return null;
+    const length = u16be(bytes, at + 2);
+    if (length < 2) return null;
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isFrame) return sized('image/jpeg', u16be(bytes, at + 7), u16be(bytes, at + 5));
+    at += 2 + length;
+  }
+  return null;
+}
+
+function readWebp(bytes) {
+  if (bytes.length < 30) return null;
+  const chunk = ascii(bytes, 12, 4);
+  if (chunk === 'VP8X') return sized('image/webp', u24le(bytes, 24) + 1, u24le(bytes, 27) + 1);
+  if (chunk === 'VP8 ') {
+    // Key frame start code, then 14-bit width and height.
+    if (bytes[23] !== 0x9d || bytes[24] !== 0x01 || bytes[25] !== 0x2a) return null;
+    return sized('image/webp', (bytes[26] | (bytes[27] << 8)) & 0x3fff, (bytes[28] | (bytes[29] << 8)) & 0x3fff);
+  }
+  if (chunk === 'VP8L') {
+    if (bytes[20] !== 0x2f) return null;
+    const bits = bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24);
+    return sized('image/webp', (bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+  }
+  return null;
+}
+
+/** `{ mime, width, height }` of a PNG, JPEG or WebP image's first bytes, or null. */
+export function readImageHeader(input) {
+  const bytes = asBytes(input);
+  if (!bytes || bytes.length < 12) return null;
+  if (bytes[0] === 0x89 && ascii(bytes, 1, 3) === 'PNG' && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
+    return readPng(bytes);
+  }
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return readJpeg(bytes);
+  if (ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP') return readWebp(bytes);
+  return null;
+}