@commonlyai/cli 0.1.173 → 0.1.175

package/node_modules/@commonlyai/seats/src/record/otel.js

@@ -0,0 +1,238 @@
+/**
+ * Export run records as OTLP/JSON traces (an ExportTraceServiceRequest), so
+ * a tracing backend can show who let which agent do what beside its own
+ * spans. docs/record-v1.md §5 is the mapping; the gen_ai.* names follow the
+ * OpenTelemetry GenAI conventions, which are Development status upstream.
+ *
+ * Ids are derived, never random: the same entries export to the same bytes.
+ */
+import { createHash } from 'node:crypto';
+import { KINDS, RECORD_SCHEMA, RECORD_VERSION } from './format.js';
+
+const SPAN_KIND_INTERNAL = 1;
+const STATUS_UNSET = 0;
+const STATUS_ERROR = 2;
+const FAILED_OUTCOMES = new Set(['failed', 'stuck', 'cancelled']);
+// Content stays out of the export, as upstream makes content capture opt-in.
+const CONTENT_KINDS = new Set(['agent.message_chunk', 'agent.thought_chunk']);
+
+const digest = (text, bytes) => {
+  const hex = createHash('sha256').update(text, 'utf8').digest('hex').slice(0, bytes * 2);
+  // An all-zero id is invalid in OTLP; vanishingly unlikely, cheap to exclude.
+  return /^0+$/.test(hex) ? digest(`${text}#`, bytes) : hex;
+};
+
+/** 16-byte trace id per task (task ids repeat across pods, so the pod is in it), else per run. */
+export const traceIdOf = (entry) => digest(entry.taskId
+  ? `seats.record/trace/task/${entry.podId}/${entry.taskId}`
+  : `seats.record/trace/run/${entry.runId}`, 16);
+/** 8-byte span id for the span an entry opens; the run span uses seq 0. */
+export const spanIdOf = (runId, seq) => digest(`seats.record/span/${runId}/${seq}`, 8);
+
+/** RFC 3339 → Unix nanoseconds as a decimal string, keeping sub-millisecond digits. */
+const nanos = (ts) => {
+  const match = /^(.*T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?Z$/.exec(ts);
+  if (!match) return '0';
+  return String(BigInt(Date.parse(`${match[1]}Z`)) * 1000000n + BigInt((match[2] || '').padEnd(9, '0')));
+};
+
+const snake = (key) => key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+const anyValue = (value) => {
+  if (typeof value === 'string') return { stringValue: value };
+  if (typeof value === 'boolean') return { boolValue: value };
+  if (Number.isInteger(value)) return { intValue: String(value) };
+  if (typeof value === 'number') return { doubleValue: value };
+  if (Array.isArray(value)) return { arrayValue: { values: value.filter((v) => v !== null && v !== undefined).map(anyValue) } };
+  return {
+    kvlistValue: {
+      values: Object.keys(value).filter((k) => value[k] !== null && value[k] !== undefined).sort()
+        .map((k) => ({ key: snake(k), value: anyValue(value[k]) })),
+    },
+  };
+};
+const attr = (key, value) => ({ key, value: anyValue(value) });
+const attrs = (pairs) => pairs.filter(([, value]) => value !== null && value !== undefined).map(([key, value]) => attr(key, value));
+
+/** Nested data → `seats.<path>` attributes, keys sorted for a stable export. */
+const flatten = (data, prefix = 'seats') => Object.keys(data || {}).sort().flatMap((key) => {
+  const value = data[key];
+  const name = `${prefix}.${snake(key)}`;
+  if (value === null || value === undefined) return [];
+  if (typeof value === 'object' && !Array.isArray(value)) return flatten(value, name);
+  return [attr(name, value)];
+});
+
+const eventOf = (entry) => ({
+  timeUnixNano: nanos(entry.ts),
+  name: entry.kind,
+  attributes: [
+    attr('seats.seq', entry.seq),
+    ...(entry.actor ? attrs([
+      ['seats.actor.type', entry.actor.type], ['seats.actor.id', entry.actor.id],
+      ['seats.actor.owner', entry.actor.owner], ['seats.actor.name', entry.actor.name],
+      ['seats.actor.on_behalf_of.id', entry.actor.onBehalfOf?.id], ['seats.actor.on_behalf_of.role', entry.actor.onBehalfOf?.role],
+    ]) : []),
+    ...flatten(entry.data),
+  ],
+});
+
+const fail = (span, errorType) => {
+  span.status = { code: STATUS_ERROR, message: errorType };
+  span.attributes.push(attr('error.type', errorType));
+};
+
+/** One run's entries, in seq order → its spans. */
+const spansOfRun = (entries) => {
+  const head = entries[0];
+  const traceId = traceIdOf(head);
+  const last = entries[entries.length - 1];
+  const span = ({ seq, parent, name, attributes, start }) => ({
+    traceId,
+    spanId: spanIdOf(head.runId, seq),
+    ...(parent ? { parentSpanId: parent.spanId } : {}),
+    name,
+    kind: SPAN_KIND_INTERNAL,
+    startTimeUnixNano: nanos(start),
+    endTimeUnixNano: null,
+    attributes,
+    events: [],
+    status: { code: STATUS_UNSET },
+  });
+  const run = span({
+    seq: 0,
+    name: 'seats.run',
+    start: head.ts,
+    attributes: attrs([['seats.run.id', head.runId], ['seats.task.id', head.taskId], ['seats.pod.id', head.podId]]),
+  });
+  const spans = [run];
+  let attempt = null; // { span, number, tools: Map<toolCallId, span>, usage, context, sessionId }
+  const cards = new Map(); // decisionCardId → the span its request sits on
+  const end = (s, ts) => { if (s && s.endTimeUnixNano === null) s.endTimeUnixNano = nanos(ts); };
+  const closeAttempt = (ts) => {
+    if (!attempt) return;
+    for (const tool of attempt.tools.values()) end(tool, ts);
+    if (attempt.usage) {
+      attempt.span.attributes.push(...attrs([
+        ['gen_ai.usage.input_tokens', attempt.usage.inputTokens], ['gen_ai.usage.output_tokens', attempt.usage.outputTokens],
+      ]));
+    }
+    attempt.span.attributes.push(...attrs([
+      ['seats.usage.context_tokens', attempt.context.tokens], ['seats.usage.context_size', attempt.context.size],
+    ]));
+    // The session an attempt opened names the conversation when attempt.started did not.
+    if (attempt.sessionId && !attempt.span.attributes.some((a) => a.key === 'gen_ai.conversation.id')) {
+      attempt.span.attributes.push(attr('gen_ai.conversation.id', attempt.sessionId));
+    }
+    end(attempt.span, ts);
+    attempt = null;
+  };
+  const current = () => attempt?.span || run;
+
+  for (const entry of entries) {
+    const { kind, data = {} } = entry;
+    if (!Object.hasOwn(KINDS, kind) || CONTENT_KINDS.has(kind)) continue; // unknown kinds are skipped
+    if (kind === 'attempt.started') {
+      closeAttempt(entry.ts);
+      const agentName = entry.actor?.name || entry.actor?.id;
+      const s = span({
+        seq: entry.seq,
+        parent: run,
+        name: agentName ? `invoke_agent ${agentName}` : 'invoke_agent',
+        start: entry.ts,
+        attributes: attrs([
+          ['gen_ai.operation.name', 'invoke_agent'],
+          ['gen_ai.agent.id', entry.actor?.id], ['gen_ai.agent.name', agentName],
+          ['gen_ai.conversation.id', data.sessionId],
+          ['seats.agent.owner', entry.actor?.owner],
+          ['seats.agent.on_behalf_of.id', entry.actor?.onBehalfOf?.id], ['seats.agent.on_behalf_of.role', entry.actor?.onBehalfOf?.role],
+          ['seats.attempt.number', data.attempt], ['seats.adapter', data.adapter],
+          ['seats.cli.name', data.cli?.name], ['seats.cli.version', data.cli?.version],
+        ]),
+      });
+      spans.push(s);
+      attempt = {
+        span: s, number: data.attempt, agentName, tools: new Map(), usage: null, context: { tokens: null, size: null }, sessionId: null,
+      };
+    } else if (kind === 'attempt.settled' && attempt && attempt.number === data.attempt) {
+      attempt.span.attributes.push(attr('seats.attempt.outcome', data.outcome));
+      if (FAILED_OUTCOMES.has(data.outcome)) fail(attempt.span, data.failure?.kind || data.outcome);
+      closeAttempt(entry.ts);
+    } else if (kind === 'run.settled') {
+      run.attributes.push(...attrs([['seats.run.outcome', data.outcome], ['seats.run.attempts', data.attempts]]));
+      if (FAILED_OUTCOMES.has(data.outcome)) {
+        const errorType = data.failure?.kind || data.outcome;
+        fail(run, errorType);
+        // The run's outcome is the last attempt's when nothing settled it.
+        if (attempt) fail(attempt.span, errorType);
+      }
+      closeAttempt(entry.ts);
+      end(run, entry.ts);
+    } else if (kind === 'tool.call') {
+      const toolName = data.name || data.title || 'tool';
+      const s = span({
+        seq: entry.seq,
+        parent: current(),
+        name: `execute_tool ${toolName}`,
+        start: entry.ts,
+        attributes: attrs([
+          ['gen_ai.operation.name', 'execute_tool'],
+          ['gen_ai.tool.name', toolName], ['gen_ai.tool.call.id', data.toolCallId],
+          ['gen_ai.agent.name', attempt?.agentName],
+          ['seats.actor.on_behalf_of.id', entry.actor?.onBehalfOf?.id], ['seats.actor.on_behalf_of.role', entry.actor?.onBehalfOf?.role],
+          ['seats.tool.kind', data.kind], ['seats.tool.surface', data.surface], ['seats.tool.args_digest', data.argsDigest],
+        ]),
+      });
+      spans.push(s);
+      if (attempt && data.toolCallId) attempt.tools.set(data.toolCallId, s);
+    } else if (kind === 'tool.update') {
+      const tool = attempt?.tools.get(data.toolCallId);
+      (tool || current()).events.push(eventOf(entry));
+      if (tool && data.status === 'failed') fail(tool, 'tool_failed');
+      if (tool && (data.status === 'completed' || data.status === 'failed')) end(tool, entry.ts);
+    } else if (kind === 'usage' && attempt) {
+      attempt.usage = data;
+      // Context fill comes from the stream's usage updates; a later entry without it keeps the last known.
+      if (Number.isInteger(data.contextTokens)) attempt.context.tokens = data.contextTokens;
+      if (Number.isInteger(data.contextSize)) attempt.context.size = data.contextSize;
+      attempt.span.events.push(eventOf(entry));
+    } else if (kind === 'permission.requested' || kind === 'permission.decided') {
+      const target = attempt?.tools.get(data.toolCallId) || current();
+      target.events.push(eventOf(entry));
+      if (data.decisionCardId && !cards.has(data.decisionCardId)) cards.set(data.decisionCardId, target);
+    } else if (kind === 'session.opened') {
+      if (attempt && typeof data.sessionId === 'string') attempt.sessionId = data.sessionId;
+      current().events.push(eventOf(entry));
+    } else if (kind === 'decision.ruled') {
+      // A ruling on a card that a request rode on joins that request; any other is an event where it happened.
+      (cards.get(data.decisionCardId) || current()).events.push(eventOf(entry));
+    } else {
+      current().events.push(eventOf(entry));
+    }
+  }
+  closeAttempt(last.ts);
+  end(run, last.ts);
+  return spans;
+};
+
+/**
+ * toOtlpJson(entries, { serviceName? }) → ExportTraceServiceRequest (OTLP/JSON)
+ *
+ * `entries` are record entries (readRun's output, or parsed lines) from one
+ * or more runs. Entries of another schema or a newer version are left out.
+ */
+export const toOtlpJson = (entries, { serviceName = 'seats' } = {}) => {
+  const runs = new Map();
+  for (const entry of entries || []) {
+    if (!entry || entry.schema !== RECORD_SCHEMA || !(entry.v <= RECORD_VERSION)) continue;
+    if (!runs.has(entry.runId)) runs.set(entry.runId, []);
+    runs.get(entry.runId).push(entry);
+  }
+  const spans = [...runs.values()].flatMap((run) => spansOfRun([...run].sort((a, b) => a.seq - b.seq)));
+  return {
+    resourceSpans: [{
+      resource: { attributes: [attr('service.name', serviceName)] },
+      scopeSpans: [{ scope: { name: RECORD_SCHEMA, version: String(RECORD_VERSION) }, spans }],
+    }],
+  };
+};

package/node_modules/@commonlyai/seats/src/runtime-observation.js

@@ -0,0 +1,29 @@
+// Read only adapter-owned control arguments. Callers exclude prompt/stdin and
+// provide every value-taking option, so a flag-shaped model/session value is
+// never reinterpreted as a second option. Raw arguments never leave the runner.
+export const controlsFromArguments = (args, { modelFlag, effortFlag, valueFlags = [], codex = false }) => {
+  const controls = { model: null, effort: null };
+  const flags = new Set([modelFlag, effortFlag, ...valueFlags].filter(Boolean));
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index];
+    if (!flags.has(flag)) continue;
+    const value = args[++index];
+    if (flag === modelFlag) controls.model = value || null;
+    if (flag === effortFlag) controls.effort = value || null;
+    if (codex && flag === '-c' && value?.startsWith('model_reasoning_effort=')) {
+      try { controls.effort = JSON.parse(value.slice('model_reasoning_effort='.length)); } catch { /* unknown encoding */ }
+    }
+  }
+  return controls;
+};
+
+// Called at the child's successful OS spawn event, not when a requested
+// configuration is saved or when a turn is merely queued. Never send argv.
+// The child rides along as a second argument so a supervisor can read its
+// output as a liveness signal and kill it; a reporter reads only the first.
+export const observeSpawn = (child, onSpawn, controls) => {
+  if (typeof onSpawn !== 'function') return;
+  child.once('spawn', () => {
+    try { onSpawn({ model: controls.model || null, effort: controls.effort || null, at: new Date().toISOString() }, child); } catch { /* diagnostic only */ }
+  });
+};

package/node_modules/@commonlyai/seats/src/seat-model.js

@@ -0,0 +1,17 @@
+/**
+ * The model a seat runs on is a declared field (`environment.model`), never a
+ * CLI default the operator did not choose. Whether a missing model is an error
+ * is the host's policy, passed as `required`.
+ */
+export const requireSeatModel = (environment, adapterName, required = false) => {
+  const model = environment?.model;
+  if (typeof model !== 'string' || !model.trim()) {
+    if (!required) return undefined;
+    const error = new Error(
+      `${adapterName} requires environment.model; set the seat model with commonly agent config <name> --model <model> before running`,
+    );
+    error.code = 'seat_model_missing';
+    throw error;
+  }
+  return model.trim();
+};

package/node_modules/@commonlyai/seats/src/supervisor.js

@@ -0,0 +1,308 @@
+/**
+ * The run supervisor: one prompt, one traced run, and a guarantee that the run
+ * settles. A turn that hangs is named `stuck` in the trace, cancelled, and if
+ * the adapter will not let go, abandoned and settled anyway. Nothing this
+ * module starts is allowed to sit in "running" forever.
+ *
+ * Liveness is read from progress signals, not from the reply: any trace event
+ * the adapter emits, and any byte on the stdout/stderr of a child the adapter
+ * reports through `ctx.onSpawn`. A run that is busy but quiet past the window
+ * is indistinguishable from a hung one, which is why the window is long.
+ *
+ * The adapter is told (ctx.ownProcessGroup) that it may start its child as the
+ * leader of a new process group; a child it marks as one is killed as a group,
+ * so the CLI's own children (MCP servers, a native binary behind a launcher)
+ * die with it. See process-group.js, which also kills those groups when the
+ * wrapper itself is signalled or exits.
+ */
+import { RunFailure, runFailure, failureKindOf, FAILURE_KINDS } from './failures.js';
+import { redactKnownCredentials, scrubAdapterFailure, spawnCredentials } from './upstream-refusal.js';
+import { killProcessTree, trackSupervisedGroup, OWN_PROCESS_GROUP } from './process-group.js';
+
+export const SUPERVISOR_DEFAULTS = Object.freeze({
+  // Longer than the quiet stretches a healthy turn has: a long-context first
+  // token, or a tool (an install, a test suite) whose output the CLI buffers.
+  stallMs: 120_000,
+  // Covers an adapter's own SIGTERM -> 5 s -> SIGKILL ladder with room to spare.
+  cancelGraceMs: 10_000,
+  // The turn budget the run loop already enforces (COMMONLY_AGENT_RUN_TIMEOUT_MS's
+  // fallback), so supervising a turn does not shorten or lengthen it.
+  timeoutMs: 15 * 60 * 1000,
+});
+
+export const DEFAULT_RETRY_ON = Object.freeze(['stuck', 'exited', 'timeout']);
+
+// setTimeout overflows past this and fires immediately.
+const MAX_TIMER_MS = 2_147_483_647;
+// The supervisor's own events; an adapter writing them would forge the run's outcome.
+const SUPERVISOR_EVENTS = new Set(['run.started', 'run.settled']);
+
+const windowOf = (value, fallback) => {
+  if (value === undefined || value === null) return fallback;
+  const number = Number(value);
+  if (number === 0 || number === Infinity) return null; // explicitly off
+  if (!Number.isFinite(number) || number < 0) throw new Error(`supervisor window must be a non-negative number, got ${value}`);
+  return Math.min(number, MAX_TIMER_MS);
+};
+
+const resolvePolicy = (policy = {}) => {
+  const retry = policy.retry || {};
+  return {
+    stallMs: windowOf(policy.stallMs, SUPERVISOR_DEFAULTS.stallMs),
+    cancelGraceMs: windowOf(policy.cancelGraceMs, SUPERVISOR_DEFAULTS.cancelGraceMs) ?? 0,
+    timeoutMs: windowOf(policy.timeoutMs, SUPERVISOR_DEFAULTS.timeoutMs),
+    retryMax: Math.max(0, Math.floor(Number(retry.max) || 0)),
+    retryOn: Array.isArray(retry.on) ? retry.on : DEFAULT_RETRY_ON,
+    onStalled: typeof policy.onStalled === 'function' ? policy.onStalled : null,
+  };
+};
+
+const isChild = (value) => !!value && typeof value.kill === 'function' && typeof value.once === 'function';
+const isAlive = (child) => child.exitCode === null && child.signalCode === null;
+
+// The retryable flag in FAILURE_KINDS outranks the caller's list: a refusal
+// listed in `on` is still never re-sent.
+const shouldRetry = (failure, attempt, settings) => {
+  const kind = failureKindOf(failure);
+  return attempt <= settings.retryMax
+    && !!kind && FAILURE_KINDS[kind].retryable
+    && settings.retryOn.includes(kind)
+    && !failure.adapterIgnoredCancel;
+};
+
+const outcomeOf = (failure) => {
+  if (!failure) return 'ok';
+  const kind = failureKindOf(failure);
+  if (kind === 'stuck') return 'stuck';
+  if (kind === 'cancelled') return 'cancelled';
+  return 'failed';
+};
+
+// An adapter that threw a bare Error broke the RunFailure rule; its text is
+// still scrubbed before it reaches the trace, and it carries no kind rather
+// than a guessed one. A RunFailure's detail keeps its shape but loses any
+// credential this spawn was handed, whoever built it.
+const failureData = (failure, credentials) => (failure instanceof RunFailure
+  ? { kind: failure.kind, detail: redactKnownCredentials(failure.detail, credentials) }
+  : { kind: null, detail: scrubAdapterFailure(String(failure?.message ?? failure ?? ''), { credentials }).detail });
+
+const sessionIdOf = (failure) => {
+  const id = failure?.sessionId ?? failure?.newSessionId;
+  return typeof id === 'string' && id ? id : null;
+};
+
+const ignoredCancel = (reason, graceMs) => {
+  const failure = new RunFailure(reason.kind, `${reason.detail}; the adapter did not settle within ${graceMs}ms of cancellation`);
+  failure.adapterIgnoredCancel = true;
+  return failure;
+};
+
+const callerCancel = (signal) => (failureKindOf(signal.reason) === 'cancelled'
+  ? signal.reason : runFailure('cancelled', 'cancelled by the caller'));
+
+/** One attempt. Resolves { result } or { failure }; never rejects, never stays pending. */
+const runAttempt = ({ adapter, prompt, ctx, run, settings, attempt, sessionId, external }) => new Promise((resolve) => {
+  const controller = new AbortController();
+  const children = new Set();
+  let live = true;
+  let abortedBy = null;
+  let lastSignal = Date.now();
+  let stallTimer = null;
+  let wallTimer = null;
+  let graceTimer = null;
+
+  const touch = () => { if (live) lastSignal = Date.now(); };
+
+  const killChildren = () => {
+    let killed = 0;
+    for (const child of children) {
+      if (!isAlive(child)) continue;
+      if (killProcessTree(child, 'SIGKILL')) killed += 1;
+    }
+    return killed;
+  };
+
+  const onExternal = () => cancel(callerCancel(external), { recovery: false });
+
+  const finish = (outcome) => {
+    if (!live) return;
+    live = false;
+    clearTimeout(stallTimer);
+    clearTimeout(wallTimer);
+    clearTimeout(graceTimer);
+    external?.removeEventListener?.('abort', onExternal);
+    // An adapter that honoured the abort can still leave its child behind.
+    if (abortedBy && !outcome.failure?.adapterIgnoredCancel && killChildren() > 0) {
+      run.emit('liveness.recovery', { action: 'kill', attempt });
+    }
+    resolve(outcome);
+  };
+
+  function cancel(reason, { recovery = true } = {}) {
+    if (abortedBy || !live) return;
+    abortedBy = reason;
+    clearTimeout(stallTimer);
+    clearTimeout(wallTimer);
+    if (recovery) run.emit('liveness.recovery', { action: 'cancel', attempt });
+    controller.abort(reason);
+    graceTimer = setTimeout(() => {
+      if (!live) return;
+      run.emit('liveness.recovery', { action: 'kill', attempt });
+      killChildren();
+      finish({ failure: ignoredCancel(reason, settings.cancelGraceMs) });
+    }, settings.cancelGraceMs);
+  }
+
+  const checkStall = () => {
+    if (!live || abortedBy) return;
+    const idleMs = Date.now() - lastSignal;
+    if (idleMs < settings.stallMs) {
+      stallTimer = setTimeout(checkStall, settings.stallMs - idleMs);
+      return;
+    }
+    const windowMs = settings.stallMs;
+    run.emit('liveness.stalled', { idleMs, windowMs });
+    if (settings.onStalled) {
+      // A host's notifier failing must not keep the run from recovering.
+      try {
+        Promise.resolve(settings.onStalled({ runId: run.runId, adapter: adapter.name, attempt, idleMs, windowMs })).catch(() => {});
+      } catch { /* notifier only */ }
+    }
+    cancel(runFailure('stuck', `no progress signal for ${idleMs}ms (window ${windowMs}ms)`));
+  };
+
+  // Counts as progress only while this attempt is live, so a cancelled
+  // attempt's late output cannot keep the next one alive or reach the trace.
+  // The emit options (the entry's actor) pass through unchanged. `redact` is
+  // offered only when the run has one, so prepareRunEnv cannot hand its
+  // values to a no-op; it is not gated on `live`, since adding a value to
+  // scrub is never unsafe.
+  const trace = {
+    emit(type, data, options) {
+      if (!live || SUPERVISOR_EVENTS.has(type)) return null;
+      touch();
+      return run.emit(type, data, options);
+    },
+    ...(typeof run.redact === 'function' ? { redact: (values) => run.redact(values) } : {}),
+  };
+
+  // Wraps the caller's onSpawn: every argument reaches it unchanged.
+  // A group-leading child is tracked for the wrapper's exit even when it
+  // arrives after this attempt ended: it is outside the seat's own group, so
+  // nothing else would kill it.
+  const onSpawn = (...args) => {
+    for (const child of args.filter(isChild)) trackSupervisedGroup(child);
+    if (live) {
+      touch();
+      for (const child of args.filter(isChild)) {
+        children.add(child);
+        child.stdout?.on?.('data', touch);
+        child.stderr?.on?.('data', touch);
+      }
+    }
+    return typeof ctx.onSpawn === 'function' ? ctx.onSpawn(...args) : undefined;
+  };
+
+  if (external?.aborted) {
+    abortedBy = callerCancel(external);
+    finish({ failure: abortedBy });
+    return;
+  }
+  external?.addEventListener?.('abort', onExternal, { once: true });
+  if (settings.stallMs) stallTimer = setTimeout(checkStall, settings.stallMs);
+  if (settings.timeoutMs) {
+    wallTimer = setTimeout(() => cancel(runFailure('timeout', `exceeded the ${settings.timeoutMs}ms wall-clock budget`)), settings.timeoutMs);
+  }
+
+  let pending;
+  try {
+    pending = Promise.resolve(adapter.spawn(prompt, {
+      ...ctx, ...(sessionId ? { sessionId } : {}), trace, signal: controller.signal, onSpawn, [OWN_PROCESS_GROUP]: true,
+    }));
+  } catch (error) {
+    pending = Promise.reject(error);
+  }
+  // Once the supervisor has aborted, the abort's reason is the outcome, even
+  // if the adapter answers inside the grace window: the trace already says why.
+  pending.then(
+    (result) => finish(abortedBy ? { failure: abortedBy } : { result }),
+    (error) => finish({ failure: abortedBy || error }),
+  );
+});
+
+/**
+ * Run one prompt under liveness supervision.
+ *
+ * @param {object} args
+ * @param {import('./contract.js').Adapter} args.adapter
+ * @param {string} args.prompt
+ * @param {object} [args.ctx]  passed to adapter.spawn; `trace`, `signal` and `onSpawn` are wrapped,
+ *   and `ownProcessGroup` is set to true.
+ *   `ctx.signal`, when given, cancels the run (outcome `cancelled`).
+ * @param {ReturnType<import('./trace/store.js').createTraceStore>} args.store
+ * @param {object} [args.policy]
+ * @param {number} [args.policy.stallMs]        no-progress window; 0 turns it off
+ * @param {number} [args.policy.cancelGraceMs]  how long a cancelled adapter has to settle
+ * @param {number} [args.policy.timeoutMs]      wall-clock budget per attempt; 0 turns it off
+ * @param {{max: number, on?: string[]}} [args.policy.retry]  off unless max > 0
+ * @param {(info: {runId, adapter, attempt, idleMs, windowMs}) => void} [args.policy.onStalled]
+ * @param {string} [args.runId]
+ * @param {string} [args.label]
+ * @param {string} [args.taskId]  the board task this run works; needs `podId`
+ * @param {string} [args.podId]
+ * @param {object} [args.actor]   the run's own party, {type, id, owner?, onBehalfOf?};
+ *   entries the run writes without naming an actor (run.started, tool calls,
+ *   permission requests) record this one instead of null
+ * @returns {Promise<{ runId: string, outcome: string, attempts: number, result?: object, failure?: Error }>}
+ */
+export const superviseRun = async ({
+  adapter, prompt, ctx = {}, store, policy = {}, runId, label, taskId, podId, actor,
+} = {}) => {
+  if (!adapter || typeof adapter.spawn !== 'function') throw new Error('superviseRun needs an adapter with spawn()');
+  if (!store || typeof store.startRun !== 'function') throw new Error('superviseRun needs a trace store');
+  const settings = resolvePolicy(policy);
+  const run = store.startRun({
+    runId, adapter: adapter.name, label, taskId, podId, actor,
+  });
+  // The runtime token rides in ctx, not through the valet, so the store would
+  // not otherwise know to scrub it from agent text.
+  if (typeof run.redact === 'function' && typeof ctx.runtimeToken === 'string' && ctx.runtimeToken) {
+    run.redact([ctx.runtimeToken]);
+  }
+  const startedAt = Date.now();
+  const external = ctx.signal;
+  let attempt = 0;
+  let sessionId = ctx.sessionId || null;
+  let last = { failure: null };
+
+  try {
+    for (;;) {
+      attempt += 1;
+      run.emit('run.started', { adapter: adapter.name, ...(sessionId ? { sessionId } : {}), attempt });
+      last = await runAttempt({ adapter, prompt, ctx, run, settings, attempt, sessionId, external });
+      if (!last.failure || external?.aborted || !shouldRetry(last.failure, attempt, settings)) break;
+      sessionId = sessionIdOf(last.failure) || sessionId;
+      run.emit('liveness.recovery', { action: 'retry', attempt: attempt + 1 });
+    }
+  } catch (error) {
+    // The supervisor's own fault (a trace write failing, say) still settles the run.
+    last = { failure: error };
+  }
+
+  const outcome = outcomeOf(last.failure);
+  const credentials = spawnCredentials(ctx, [adapter.providerKeyEnv].filter(Boolean));
+  try {
+    run.emit('run.settled', {
+      outcome,
+      ...(last.failure ? { failure: failureData(last.failure, credentials) } : {}),
+      durationMs: Date.now() - startedAt,
+      attempts: attempt,
+    });
+  } catch { /* the outcome is still returned */ }
+  return {
+    runId: run.runId,
+    outcome,
+    attempts: attempt,
+    ...(last.failure ? { failure: last.failure } : { result: last.result }),
+  };
+};

package/node_modules/@commonlyai/seats/src/trace/events.js

@@ -0,0 +1,45 @@
+/**
+ * Trace event vocabulary. Names follow ACP's session/update kinds where one
+ * exists, so an ACP agent's stream maps across without a translation table.
+ *
+ * Event: { runId, seq, ts, type, data }, plus the record envelope (kind, v,
+ * actor, prev, taskId?, podId?) when read back from the store; the on-disk
+ * format is docs/record-v1.md. `seq` is per run, starting at 1; `ts` is
+ * an ISO string. Events never carry prompt text, credentials or
+ * environment values — only names, ids, sizes and the agent's own output.
+ */
+export const EVENT_TYPES = Object.freeze([
+  'run.started', // { adapter, cli: {name, version}?, sessionId?, attempt }
+  'run.settled', // { outcome: 'ok'|'failed'|'stuck'|'cancelled', failure?: {kind, detail}, durationMs, attempts }
+  'turn.prompt_sent', // { chars }
+  'agent.message_chunk', // { text }
+  'agent.thought_chunk', // { chars }  thoughts are counted, not stored
+  'agent.retry', // { state: 'scheduled'|'started', attempt?, nextRetryAt?, status?, errorType? }  the agent retrying its provider; never the provider's text
+  'tool.call', // { toolCallId, title, kind?, status?, name?, surface?, argsDigest? }
+  'tool.update', // { toolCallId, status?, title? }
+  'plan', // { entries: [{content, status}] }
+  'permission.requested', // { toolCallId?, options: [{optionId, kind}], question, askedOf: {id, role}, grantId?, decisionCardId?, argsDigest? }
+  'permission.decided', // { outcome: 'selected'|'cancelled', optionId?, kind?, toolCallId?, rule?: {list, pattern}, approval? }
+  'usage', // { inputTokens?, outputTokens?, totalTokens?, cost? }  null-not-zero when unknown
+  'liveness.stalled', // { idleMs, windowMs }
+  'liveness.recovery', // { action: 'cancel'|'kill'|'retry', attempt }
+  'credential.granted', // { names: [...] }  names only, never values
+  'credential.denied', // { name, reason?: 'not_granted'|'unresolved'|'too_short' }
+  'process.exited', // { code, signal }
+  // Record kinds with no earlier trace name (docs/record-v1.md has the full data).
+  'task.claimed', // { leaseUntil? }  mirrors the board's claim; the board stays the source of truth
+  'task.released', // { reason? }
+  'task.done', // { doneBy? }  written for the board; ends grants bound to the task
+  'grant.issued', // { grantId, parentGrantId?, scope: {connectionId?, tools: [names], writeMode?, budget?, audience}, target?, issuedBy?, expiresAt?, binding? }
+  'grant.revoked', // { grantIds: [...], reason: 'task.done'|'expired'|'cascade'|'manual' }
+  'attempt.settled', // { attempt, outcome, failure?: {kind, detail} }
+  'decision.ruled', // { decisionCardId, value, decidedBy, decidedByRole }  a card ruling not tied to a parked tool call
+  'result.reported', // { status: 'done'|'partial'|'blocked'|'failed', refs?: [{type, id}] }
+]);
+
+const KNOWN = new Set(EVENT_TYPES);
+export const isEventType = (type) => KNOWN.has(type);
+
+/** The trace hook an adapter receives as ctx.trace. Absent hook → no-op. */
+export const NULL_TRACE = Object.freeze({ emit() {} });
+export const traceOf = (ctx) => (ctx && ctx.trace && typeof ctx.trace.emit === 'function' ? ctx.trace : NULL_TRACE);