@ravefox/space 0.0.0-stage → 0.2.0

package/src/lib/poller.js

@@ -0,0 +1,200 @@
+/**
+ * Event poller — polls GET /api/agents/runtime/events and forwards
+ * each event to a local handler (webhook server or callback).
+ *
+ * Used by `commonly agent connect` when running against any instance,
+ * since localhost webhooks can't receive inbound calls from remote GKE.
+ */
+
+import { createClient } from './api.js';
+import { formatDigestFrame } from './digest-frame.js';
+import { EMPTY_OUTPUT } from './claim-outcome.js';
+import { createPollLiveness, formatStall, resolvePollLivenessMs } from './poll-liveness.js';
+import { CLI } from './cli-hint.js';
+
+// Delivery failures that must stop a consumer rather than fall through to the
+// normal at-least-once retry path. A stale delivery belongs to a replacement
+// runner; a missing required nonce means this runner is misconfigured. Neither
+// can become healthy by immediately fetching and retrying more work.
+export const terminalDeliveryAckError = (ackErr, eventId, runner = 'poller') => {
+  if (ackErr?.status === 409 && ackErr?.body?.code === 'stale_delivery') {
+    return Object.assign(
+      new Error(`Delivery ${eventId} was superseded — stopping ${runner}.`),
+      { code: 'stale_delivery' },
+    );
+  }
+  if (ackErr?.status === 400 && ackErr?.body?.code === 'delivery_id_required') {
+    return Object.assign(
+      new Error(`Delivery ${eventId} requires deliveryId — stopping ${runner}; update its configuration.`),
+      { code: 'delivery_id_required' },
+    );
+  }
+  return null;
+};
+
+export const startPoller = ({
+  instanceUrl,
+  token,
+  agentName,
+  instanceId = 'default',
+  intervalMs = 5000,
+  loginInstance,    // the --instance the connect ran with, so the login hint names it
+  onEvent,          // async (event) => { outcome, content? }
+  onError,          // (err) => void
+  pollLivenessMs,   // TASK-338: see lib/poll-liveness.js
+  pollLivenessCheckMs,
+  onPollStalled,    // ({ stalledMs }) => void; the connect command exits on it
+}) => {
+  const client = createClient({ instance: instanceUrl, token });
+  let running = true;
+  let consecutiveErrors = 0;
+  // Stop-after-N-auth-failures: without this, a revoked token leaves the
+  // poller hammering 401s forever at 60s backoff, invisible to the user.
+  // 3 is deliberate — 1 would churn on a token-rotation race during
+  // reprovision-all; 5+ wastes rate-limit budget after the real-revoke case.
+  let consecutiveAuthErrors = 0;
+  const MAX_AUTH_ERRORS = 3;
+  let pollStalled = false;
+  const pollLiveness = createPollLiveness({
+    limitMs: resolvePollLivenessMs(pollLivenessMs),
+    checkEveryMs: pollLivenessCheckMs,
+    onStall: ({ stalledMs }) => {
+      if (!running) return;
+      pollStalled = true;
+      running = false;
+      pollLiveness.stop();
+      onError?.(new Error(`poll stalled: no inbox poll settled for ${formatStall(stalledMs)} — stopping poller`));
+      onPollStalled?.({ stalledMs });
+    },
+  });
+
+  const poll = async () => {
+    if (!running) return;
+
+    try {
+      // Same clock as `agent run`: running from here to the scheduled wait,
+      // paused while the local handler takes the event.
+      pollLiveness.arm();
+      const page = await client.get('/api/agents/runtime/events', {
+        agentName,
+        instanceId,
+        limit: 10,
+      });
+      pollLiveness.arm();
+      if (pollStalled) return;
+      const { events = [] } = page;
+
+      // A digest is received context, not a webhook invocation. The runtime
+      // inbox claims it only alongside a wake from the same pod.
+      const wakeEvents = events.filter((event) => event.deliveryMode !== 'digest');
+      const digestEvents = events.filter((event) => event.deliveryMode === 'digest'
+        && wakeEvents[0] && String(event.podId) === String(wakeEvents[0].podId));
+      const rollup = wakeEvents[0]?.payload?.digestRollup;
+      const frame = formatDigestFrame(digestEvents, rollup);
+      let digestConsumed = false;
+      for (const [index, event] of wakeEvents.entries()) {
+        const attachedDigest = index === 0 && frame !== null;
+        const forwarded = attachedDigest ? {
+          ...event,
+          payload: {
+            ...(event.payload || {}),
+            digestSummary: frame,
+            ...(typeof event.payload?.content === 'string' ? {
+              content: `${event.payload.content}\n\n${frame}`,
+            } : {}),
+          },
+        } : event;
+        let result = { outcome: 'no_action' };
+        try {
+          // A handler that returns nothing said nothing: not a read of the digest.
+          pollLiveness.pause();
+          result = (await onEvent(forwarded)) || { outcome: 'no_action', reason: EMPTY_OUTPUT };
+        } catch (handlerErr) {
+          result = { outcome: 'error', reason: handlerErr.message };
+        } finally {
+          pollLiveness.arm();
+        }
+
+        // Acknowledge the event
+        try {
+          const deliveryId = event.payload?.deliveryId;
+          await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
+            result,
+            ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
+          });
+          if (attachedDigest && (result.outcome === 'posted'
+            || result.outcome === 'acknowledged'
+            || (result.outcome === 'no_action' && !result.reason))) {
+            digestConsumed = true;
+          }
+        } catch (ackErr) {
+          const terminalError = terminalDeliveryAckError(ackErr, event._id);
+          if (terminalError) {
+            running = false;
+            onError?.(terminalError);
+            return;
+          }
+          // Non-fatal — event will be retried
+          onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`));
+        }
+      }
+
+      if (digestConsumed) {
+        for (const event of digestEvents) {
+          try {
+            const deliveryId = event.payload?.deliveryId;
+            await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
+              result: { outcome: 'no_action', reason: 'digest-read' },
+              ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
+            });
+          } catch (ackErr) {
+            const terminalError = terminalDeliveryAckError(ackErr, event._id);
+            if (terminalError) {
+              running = false;
+              onError?.(terminalError);
+              return;
+            }
+            onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`));
+          }
+        }
+      }
+
+      consecutiveErrors = 0;
+      consecutiveAuthErrors = 0;
+    } catch (err) {
+      if (err?.status === 401 || err?.status === 403) {
+        consecutiveAuthErrors += 1;
+        if (consecutiveAuthErrors >= MAX_AUTH_ERRORS) {
+          onError?.(new Error(
+            `Runtime token rejected ${consecutiveAuthErrors} times in a row — stopping poller. `
+            + `This connection takes its key from --token, then COMMONLY_TOKEN, then your saved login. `
+            + `If the key was rotated or revoked, re-run with the new key in --token or COMMONLY_TOKEN; `
+            + `with neither set, run ${CLI} login${loginInstance ? ` --instance ${loginInstance}` : ''}.`,
+          ));
+          running = false;
+          return;
+        }
+      }
+      consecutiveErrors++;
+      onError?.(err);
+      // Back off on repeated errors (max 60s). A wait this loop scheduled
+      // itself always ends, so the liveness clock stops for it.
+      const backoff = Math.min(intervalMs * consecutiveErrors, 60_000);
+      pollLiveness.pause();
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+
+    pollLiveness.pause();
+    if (running) setTimeout(poll, intervalMs);
+  };
+
+  // Start immediately
+  poll();
+
+  return {
+    stop: () => {
+      running = false;
+      pollLiveness.stop();
+    },
+  };
+};

package/src/lib/provider-proxy.js

@@ -0,0 +1,42 @@
+import { resolveProviderKeyFile as resolveKeyFileShared } from '@commonlyai/seats/wire/provider-proxy';
+import { effectiveSandboxTrust } from './environment.js';
+import { bwrapReadRoots } from './sandbox/bwrap.js';
+import { seatbeltSystemReadRoots } from './sandbox/seatbelt.js';
+
+export * from '@commonlyai/seats/wire/provider-proxy';
+
+/**
+ * F453. What a sandboxed seat can read on this platform, as roots, or
+ * undefined for a spawn that runs in no sandbox. macOS: the Seatbelt
+ * baseline's read grants, read from the profile itself. Linux: bwrap's read
+ * binds, including the seat's declared read-outside and write-outside.
+ * `sandboxed` is the adapter's word on whether this spawn is confined; left
+ * out, a public seat is confined and any other is not.
+ */
+export const sandboxReadableRoots = (environment, platform = process.platform, { sandboxed } = {}) => {
+  const confined = sandboxed ?? effectiveSandboxTrust(environment?.sandbox?.trust) === 'public';
+  if (!confined) return undefined;
+  if (platform === 'darwin') return seatbeltSystemReadRoots();
+  if (platform === 'linux') return bwrapReadRoots(environment);
+  return { subpaths: [], literals: [] };
+};
+
+/**
+ * The shared key-file validation, with the sandbox check every adapter gets:
+ * the proxy reads a confined seat's key file outside the sandbox, so a key
+ * file the sandbox can read is refused before the seat starts, and before
+ * anything opens the file. Adapters pass their environment; `seatDirectories`
+ * names stable directories the adapter itself gives the sandbox (a seat home),
+ * checked whenever the spawn is confined. Without options nothing changes.
+ */
+export const resolveProviderKeyFile = (provider, workspacePath, adapterLabel, {
+  environment, platform, sandboxed, seatDirectories = [],
+} = {}) => {
+  const roots = sandboxReadableRoots(environment, platform, { sandboxed });
+  return resolveKeyFileShared(provider, workspacePath, adapterLabel, {
+    readableRoots: roots && {
+      subpaths: [...roots.subpaths, ...seatDirectories.filter(Boolean)],
+      literals: roots.literals,
+    },
+  });
+};

package/src/lib/public-seat-mcp-flag.js

@@ -0,0 +1,36 @@
+/**
+ * Tell a public seat's Commonly MCP server that it serves a public seat.
+ *
+ * The server then writes nothing once Commonly has been unreachable in that
+ * process (commonly-mcp/src/public-seat-gate.js), which closes the post a model
+ * makes through the tool before the CLI's own witness withholds the reply
+ * (public-tool-error.js, TASK-256). Only the shipped Commonly server is
+ * flagged. Every adapter carries a declared literal env key through to the
+ * server's process (`deliverSeatCredential` copies the declaration's env), so
+ * one copy here reaches all of them. A server that predates the gate ignores
+ * the key.
+ *
+ * Set at spawn, on a copy: the record and the guards (`auditDeclaredMcp`,
+ * `isShippedCommonlyMcpEntry`) still see the declaration as written.
+ */
+import { isShippedCommonlyMcpCommand } from './declared-mcp-guard.js';
+import { describeMcpCommand } from './mcp-server-version.js';
+
+export const PUBLIC_SEAT_MCP_ENV = 'COMMONLY_MCP_PUBLIC_SEAT';
+
+// The npx form, or a recorded local checkout of the same package (the form
+// goose's public check and `auditDeclaredMcp` also admit).
+const isCommonlyServer = (server, describe) => isShippedCommonlyMcpCommand(server?.command)
+  || Boolean(describe(server?.command)?.isCommonly);
+
+export const withPublicSeatMcpFlag = (environment, { describe = describeMcpCommand } = {}) => {
+  const servers = Array.isArray(environment?.mcp) ? environment.mcp : null;
+  const flagged = servers ? servers.map((server) => isCommonlyServer(server, describe)) : [];
+  if (!flagged.some(Boolean)) return environment;
+  return {
+    ...environment,
+    mcp: servers.map((server, i) => (flagged[i]
+      ? { ...server, env: { ...(server.env || {}), [PUBLIC_SEAT_MCP_ENV]: '1' } }
+      : server)),
+  };
+};

package/src/lib/public-tool-error.js

@@ -0,0 +1,60 @@
+/**
+ * Which failed Commonly tool calls a public seat's model may answer in plain
+ * words. Everything else withholds the turn (#2374).
+ *
+ * The rule is inverted on purpose. Matching known connection failures let an
+ * API 5xx through: the shipped MCP turns a non-2xx into a tool error carrying
+ * the status, and during a rollout the ingress answers 503 while the socket
+ * connects, so the model narrated the outage to a stranger. A list of failures
+ * fails open on the next one nobody listed; a list of answers fails closed.
+ *
+ * The answerable ones:
+ * - an API refusal the person can be told about: 400, 403, 404, 409, 410, 413
+ *   or 422. 401 is NOT among them: a seat whose token the API rejects is
+ *   broken plumbing, and every later call fails the same way.
+ * - the runtime's own schema check, which the model fixes on its next call.
+ *   OpenCode 1.19.0 words it "The <tool> tool was called with invalid
+ *   arguments: …" (ToolInvalidArgumentsError, read from the shipped binary).
+ *
+ * Everything else withholds: a 5xx, 401, 429 or any other status; a tool error
+ * with no status (the shipped MCP's network, timeout and token failures); an
+ * MCP transport error ("MCP error -32000: Connection closed"); an empty error;
+ * and any text this module does not recognise.
+ *
+ * How the status arrives: the shipped MCP answers a failed call with
+ * `isError: true` and one text part, `JSON.stringify({ status, body, message })`
+ * for an HTTP error or `{ message }` otherwise (commonly-mcp/src/tools.js,
+ * `err`). OpenCode throws that text as the tool's error, so the event's
+ * `state.error` is the JSON (measured on the 2026-10-21 canary).
+ *
+ * The TASK-256 readiness witness uses this same predicate, so the two
+ * witnesses cannot disagree about what counts as a failure.
+ */
+
+export const ANSWERABLE_API_STATUSES = new Set([400, 403, 404, 409, 410, 413, 422]);
+
+// The two ways a public turn is withheld over its Commonly MCP server: a tool
+// call failed in a way the model must not narrate, or the server was never shown
+// working. Both leave the event unacked for retry.
+export const PUBLIC_TOOL_FAILED_CODE = 'public_tool_failed';
+export const PUBLIC_MCP_NOT_READY_CODE = 'public_mcp_not_ready';
+
+const INVALID_ARGUMENTS_RE = /^The \S+ tool was called with invalid arguments: /;
+
+const parsePayload = (text) => {
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Whether a failed tool call's error text is one the model may answer. */
+export const isAnswerableToolError = (error) => {
+  const text = typeof error === 'string' ? error.trim() : '';
+  if (!text) return false;
+  if (INVALID_ARGUMENTS_RE.test(text)) return true;
+  const payload = parsePayload(text);
+  return Boolean(payload && Number.isInteger(payload.status) && ANSWERABLE_API_STATUSES.has(payload.status));
+};

package/src/lib/public-withheld-tools.js

@@ -0,0 +1,48 @@
+// Commonly MCP tools that public seats are not offered, on any adapter.
+// Claude workspace seats follow the same list. Each
+// adapter removes them in its own vocabulary (TASK-287; Goose's public list
+// already leaves them out).
+// commonly_catch_up moves the read cursor past history unread; a wrapper seat
+// already catches up before each turn, so no seat on this list needs the tool.
+export const PUBLIC_WITHHELD_TOOLS = Object.freeze(['commonly_attach_file', 'commonly_catch_up']);
+
+// F118 (Cofounder ruling, 11-04): public agents start from nothing and earn
+// capabilities. A public seat answers strangers, so an injected message must
+// not be able to spread the agent into other pods or rewrite its memory.
+// Withheld on public trust only: a Claude workspace seat keeps its memory
+// writes, and denies self-install itself (claude.js, workspaceDenies). The
+// memory writes come back on a turn the owner woke (F145, below).
+// commonly_log_cycle is a memory write too: it appends to the agent's
+// `cycles[]` through POST /api/agents/runtime/memory/sync. Reading memory
+// (commonly_read_agent_memory, and the long_term the wrapper puts in the
+// prompt) stays offered.
+// commonly_delete_message (F141): a stranger-steered seat could delete its own
+// replies to an injection, which are the evidence of what the attack achieved.
+// A workspace seat keeps it.
+export const PUBLIC_ONLY_WITHHELD_TOOLS = Object.freeze([
+  'commonly_self_install_into_pod',
+  'commonly_write_agent_memory',
+  'commonly_save_my_memory',
+  'commonly_log_cycle',
+  'commonly_delete_message',
+]);
+
+// Everything a public seat is not offered. Codex, OpenCode, Qwen and Goose
+// confine on public trust only, so this is the whole list for them.
+export const PUBLIC_SEAT_WITHHELD_TOOLS = Object.freeze([
+  ...PUBLIC_WITHHELD_TOOLS, ...PUBLIC_ONLY_WITHHELD_TOOLS,
+]);
+
+// F145: what comes back on a turn the kernel verified its owner woke, so the
+// owner keeps a remembering agent. The kernel refuses these writes on any other
+// public turn, whatever an adapter offers.
+export const OWNER_WOKEN_MEMORY_TOOLS = Object.freeze([
+  'commonly_write_agent_memory',
+  'commonly_save_my_memory',
+  'commonly_log_cycle',
+]);
+
+/** What a public seat is not offered on this turn. Only a literal `true` opens it. */
+export const publicSeatWithheldTools = (ctx) => (ctx?.ownerWoken === true
+  ? PUBLIC_SEAT_WITHHELD_TOOLS.filter((tool) => !OWNER_WOKEN_MEMORY_TOOLS.includes(tool))
+  : PUBLIC_SEAT_WITHHELD_TOOLS);

package/src/lib/reply-receipt.js

@@ -0,0 +1,55 @@
+// D245 item 4: the receipt the wrapper posts with a reply, so a BYO reply
+// carries "how this reply was made" the way a hosted reply has its run trace.
+// It is the wrapper's own account and the server stores it as self-reported
+// (backend/services/byoReceipt.ts), which also bounds and checks every field.
+// This side keeps to what it actually observed: an adapter that reports no
+// stats sends only its name and the measured duration.
+
+const isName = (value) => typeof value === 'string' && value.length > 0;
+const isCount = (value) => Number.isInteger(value) && value >= 0;
+
+const parseLine = (raw) => {
+  try { return JSON.parse(raw); } catch { return null; }
+};
+
+/**
+ * What a Claude Code stream-json run says about itself: the model from the
+ * init event, the turn count from the result event, and each tool it called,
+ * once, in first-use order.
+ */
+export const claudeRunStats = (stdout) => {
+  const events = String(stdout || '').split('\n').map(parseLine).filter(Boolean);
+  const stats = {};
+  const init = events.find((event) => event.type === 'system' && event.subtype === 'init');
+  if (isName(init?.model)) stats.model = init.model;
+  const result = [...events].reverse().find((event) => event.type === 'result');
+  if (isCount(result?.num_turns)) stats.turns = result.num_turns;
+  const tools = [];
+  for (const event of events) {
+    if (event.type !== 'assistant') continue;
+    for (const block of event.message?.content || []) {
+      if (block?.type === 'tool_use' && isName(block.name) && !tools.includes(block.name)) tools.push(block.name);
+    }
+  }
+  if (tools.length) stats.tools = tools;
+  return stats;
+};
+
+/** The receipt for one reply, or null when there is no adapter to name. */
+export const buildReplyReceipt = ({ adapterName, stats = {}, durationMs } = {}) => {
+  if (!isName(adapterName)) return null;
+  const receipt = { adapter: adapterName };
+  // A cloud-hosted model can be named by an ARN or a resource path that
+  // carries the account or project it runs in; that is not this reply's to
+  // publish, so such a model id is left out.
+  if (isName(stats?.model) && !/^arn:|(^|\/)projects\//i.test(stats.model)) receipt.model = stats.model;
+  // D247: the effort level the adapter passed, as a bare level name.
+  if (isName(stats?.effort) && /^[a-z0-9][a-z0-9._-]{0,19}$/i.test(stats.effort)) receipt.effort = stats.effort;
+  if (isCount(stats?.turns)) receipt.turns = stats.turns;
+  if (Array.isArray(stats?.tools)) {
+    const tools = stats.tools.filter(isName);
+    if (tools.length) receipt.tools = tools;
+  }
+  if (Number.isFinite(durationMs) && durationMs >= 0) receipt.durationMs = Math.round(durationMs);
+  return receipt;
+};

package/src/lib/resolve-on-path.js

@@ -0,0 +1,22 @@
+import { accessSync, constants as fsConstants, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+
+/**
+ * The first executable `name` on `pathValue`, absolute, or null. No shell
+ * involved, and only absolute PATH entries count: a relative entry would
+ * resolve against whatever the daemon's working directory happens to be.
+ * Only a file counts: X_OK passes a directory, and execvp passes over one
+ * (EACCES) to the next entry, so a same-named folder earlier on PATH must not
+ * be returned as the binary (F146).
+ */
+export const resolveOnPath = (name, pathValue) => {
+  for (const dir of String(pathValue || '').split(delimiter)) {
+    if (!dir || !isAbsolute(dir)) continue;
+    const candidate = join(dir, name);
+    try {
+      accessSync(candidate, fsConstants.X_OK);
+      if (statSync(candidate).isFile()) return candidate;
+    } catch { /* next */ }
+  }
+  return null;
+};

package/src/lib/runtime-inventory.js

@@ -0,0 +1,56 @@
+// Probe only the walked adapter's version command. Never enumerate workspace
+// extensions to discover models: a model picker must not execute project code.
+export const WALKED_HARNESSES = ['claude', 'codex', 'opencode', 'hermes', 'dsh'];
+// `loginState` (F458), when given, adds `signedIn` to an installed harness it
+// has a verdict for, so the page can say "not signed in" before the first
+// message fails instead of after.
+export const collectRuntimeInventory = async (getAdapter, capabilities, harnesses = WALKED_HARNESSES, { loginState } = {}) => Promise.all(harnesses.map(async (harness) => {
+  const adapter = getAdapter(harness);
+  let detected = null;
+  try { detected = await adapter?.detect(); } catch { /* unavailable */ }
+  let choices = { models: null, efforts: [] };
+  if (detected) { try { choices = (await (capabilities ? capabilities(harness) : adapter?.inventory?.())) || choices; } catch { /* unavailable */ } }
+  let signedIn = null;
+  if (detected && loginState) { try { signedIn = await loginState(harness); } catch { /* no verdict */ } }
+  return { harness, installed: Boolean(detected), version: detected?.version || null,
+    models: choices.models, efforts: choices.efforts, ...(typeof signedIn === 'boolean' ? { signedIn } : {}) };
+}));
+
+// The daemon's inventory, refreshed in full every five minutes. A harness it
+// didn't find is probed again sooner, so one installed while the BYO page is
+// open shows up within a heartbeat or two, without a reload (F370 #8). One
+// that reported signed out is rechecked the same way, so a sign-in does too (F458).
+// Probes are synchronous: a binary that isn't there fails at once, but one
+// that's there and hangs on --version blocks the daemon for its timeout. A
+// re-probe slower than INVENTORY_SLOW_MS waits for the full refresh instead.
+export const INVENTORY_FULL_MS = 300_000;
+export const INVENTORY_MISSING_MS = 25_000;
+export const INVENTORY_SLOW_MS = 1_000;
+export const createInventoryCache = (collect, { now = Date.now } = {}) => {
+  let cached;
+  let fullAt = 0;
+  let missingAt = 0;
+  let slow = new Set();
+  return async () => {
+    const at = now();
+    if (!cached || at - fullAt > INVENTORY_FULL_MS) {
+      cached = await collect(WALKED_HARNESSES);
+      fullAt = at;
+      missingAt = at;
+      slow = new Set();
+      return cached;
+    }
+    const missing = cached.filter((row) => (!row.installed || row.signedIn === false) && !slow.has(row.harness))
+      .map((row) => row.harness);
+    if (missing.length && at - missingAt > INVENTORY_MISSING_MS) {
+      missingAt = at;
+      for (const harness of missing) {
+        const started = now();
+        const [fresh] = await collect([harness]);
+        if (now() - started > INVENTORY_SLOW_MS) slow.add(harness);
+        if (fresh) cached = cached.map((row) => (row.harness === harness ? fresh : row));
+      }
+    }
+    return cached;
+  };
+};

package/src/lib/runtime-observation.js

@@ -0,0 +1,37 @@
+// controlsFromArguments and observeSpawn live in the seats runtime package;
+// the reporter below posts to a Commonly instance, so it stays in the CLI.
+export { controlsFromArguments, observeSpawn } from '@commonlyai/seats/runtime-observation';
+
+export const createRuntimeReporter = ({ client, harness, detect }) => {
+  let queue = Promise.resolve();
+  const send = (body) => {
+    // Serialize so a fast process cannot have its settled report overtake its
+    // spawn report. Old backends and diagnostic outages don't stop a turn.
+    queue = queue.then(() => client.post('/api/agents/runtime/observation', body)).catch(() => {});
+    return queue;
+  };
+  return {
+    async connect() {
+      return send({ event: 'connected' });
+    },
+    spawn: ({ model, effort, at }) => {
+      const receipt = { event: 'spawn', harness, version: null, model, effort, ...(at ? { at } : {}) };
+      queue = queue.then(async () => {
+        try { receipt.version = (await detect())?.version || null; } catch { /* unavailable */ }
+        await client.post('/api/agents/runtime/observation', receipt);
+      }).catch(() => {});
+      return queue;
+    },
+    // A failed spawn carries its reason code (F370 #11). A backend from before
+    // the field refuses the whole report with a 400, so it's sent once more
+    // without the reason, and the outcome still lands.
+    settled: (outcome = null, reason = null) => {
+      const body = { event: 'settled', ...(outcome ? { outcome } : {}) };
+      if (!(outcome === 'failed' && reason)) return send(body);
+      queue = queue.then(() => client.post('/api/agents/runtime/observation', { ...body, reason })
+        .catch((error) => (error?.status === 400 ? client.post('/api/agents/runtime/observation', body) : undefined)))
+        .catch(() => {});
+      return queue;
+    },
+  };
+};