@citeark/agent 0.3.20

package/src/settings/store.mjs

@@ -0,0 +1,119 @@
+import path from "node:path";
+import { homedir } from "node:os";
+import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
+import { resolveAgentRuntime } from "../runtime/config.mjs";
+
+export const settingsPath = (env = process.env) =>
+  path.join(
+    env.CITEARK_CONFIG_DIR ?? path.join(homedir(), ".citeark"),
+    "config.json",
+  );
+export async function readSettings(file = settingsPath()) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return { schemaVersion: 1, models: {}, compute: {} };
+  }
+}
+export async function writeSettings(settings, file = settingsPath()) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, JSON.stringify(settings, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  await rename(temporary, file);
+}
+export function profileName(name) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name ?? ""))
+    throw Error(
+      "Use a profile name with letters, numbers, dashes or underscores.",
+    );
+  return name;
+}
+export function modelProfile(value) {
+  const fields = [
+    "runtime",
+    "apiBaseUrl",
+    "model",
+    "apiKeyEnv",
+    "effort",
+    "subagentModel",
+    "maxBudgetUsd",
+  ];
+  const result = Object.fromEntries(
+    fields.filter((k) => value[k] !== undefined).map((k) => [k, value[k]]),
+  );
+  if (result.apiKeyEnv && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(result.apiKeyEnv))
+    throw Error("API key environment variable name is invalid.");
+  resolveAgentRuntime({ ...result, requireApi: false });
+  return result;
+}
+export function resolveModelProfile(settings, name, env = process.env) {
+  const selected = name ?? settings.defaultModel;
+  if (!selected) return null;
+  const profile = settings.models[selected];
+  if (!profile)
+    throw Error(`Unknown model profile: ${selected}. Run citeark model list.`);
+  return {
+    ...modelProfile(profile),
+    apiKey: profile.apiKeyEnv ? env[profile.apiKeyEnv] : undefined,
+    apiKeySource: profile.apiKeyEnv
+      ? `env:${profile.apiKeyEnv}`
+      : "local-session",
+  };
+}
+export function savedModel(runtime) {
+  return modelProfile({
+    ...runtime,
+    apiKeyEnv:
+      runtime.apiKeyEnv ??
+      (runtime.apiKeySource?.startsWith("env:")
+        ? runtime.apiKeySource.slice(4)
+        : undefined),
+  });
+}
+export function computeProfile(value) {
+  if (!["local", "ssh", "catalog"].includes(value.type))
+    throw Error("Compute type must be local, ssh or catalog.");
+  if (value.type === "ssh") {
+    if (!value.host || value.host.startsWith("-") || /[\s\0]/.test(value.host))
+      throw Error("Enter an SSH host or SSH config alias.");
+    if (!value.directory?.startsWith("/"))
+      throw Error("The remote workspace root must be an absolute path.");
+    if (
+      value.port !== undefined &&
+      (!Number.isInteger(value.port) || value.port < 1 || value.port > 65535)
+    )
+      throw Error("Invalid SSH port.");
+    return {
+      type: "ssh",
+      host: value.host,
+      directory: value.directory,
+      ...(value.port ? { port: value.port } : {}),
+      ...(value.identityFile
+        ? { identityFile: path.resolve(value.identityFile) }
+        : {}),
+      ...(value.configFile
+        ? { configFile: path.resolve(value.configFile) }
+        : {}),
+      command: value.command ?? "citeark",
+    };
+  }
+  if (value.type === "catalog") {
+    if (!value.catalog) throw Error("Provide a compute catalog file.");
+    return {
+      type: "catalog",
+      catalog: path.resolve(value.catalog),
+      ...(value.policy ? { policy: path.resolve(value.policy) } : {}),
+      ...(value.profile ? { profile: value.profile } : {}),
+    };
+  }
+  if (value.device && !["cpu", "cuda"].includes(value.device))
+    throw Error("Local device must be cpu or cuda.");
+  return {
+    type: "local",
+    device: value.device ?? "cpu",
+    ...(value.image ? { image: value.image } : {}),
+  };
+}

package/src/telemetry/pricing.mjs

@@ -0,0 +1,68 @@
+const RATES_CNY_PER_MILLION = Object.freeze({
+  flash: {
+    idle: { cacheHitInput: 0.05, cacheMissInput: 1.5, output: 4.5 },
+    peak: { cacheHitInput: 0.1, cacheMissInput: 3, output: 9 },
+  },
+  pro: {
+    idle: { cacheHitInput: 0.15, cacheMissInput: 4.5, output: 13.5 },
+    peak: { cacheHitInput: 0.3, cacheMissInput: 9, output: 27 },
+  },
+});
+
+export function estimateDeepSeekCost(usage, { defaultModel = "deepseek-v4-pro" } = {}) {
+  const modelEntries = Object.entries(usage?.models ?? {});
+  const entries = modelEntries.length
+    ? modelEntries
+    : [[defaultModel, {
+        inputTokens: usage?.inputTokens,
+        outputTokens: usage?.outputTokens,
+        cacheReadInputTokens: usage?.cacheReadInputTokens,
+        cacheCreationInputTokens: usage?.cacheCreationInputTokens,
+      }]];
+  const byModel = {};
+  let idleCny = 0;
+  let peakCny = 0;
+
+  for (const [model, modelUsage] of entries) {
+    const tier = model.toLowerCase().includes("flash") ? "flash" : "pro";
+    const cacheHitTokens = number(modelUsage.cacheReadInputTokens);
+    const cacheMissTokens = number(modelUsage.inputTokens) + number(modelUsage.cacheCreationInputTokens);
+    const outputTokens = number(modelUsage.outputTokens);
+    const idle = costFor(RATES_CNY_PER_MILLION[tier].idle, cacheHitTokens, cacheMissTokens, outputTokens);
+    const peak = costFor(RATES_CNY_PER_MILLION[tier].peak, cacheHitTokens, cacheMissTokens, outputTokens);
+    idleCny += idle;
+    peakCny += peak;
+    byModel[model] = {
+      tier,
+      cacheHitTokens,
+      cacheMissTokens,
+      outputTokens,
+      idleCny: rounded(idle),
+      peakCny: rounded(peak),
+    };
+  }
+
+  return {
+    currency: "CNY",
+    source: "deepseek-v4-pricing-table-2026-08",
+    idleCny: rounded(idleCny),
+    peakCny: rounded(peakCny),
+    byModel,
+  };
+}
+
+function costFor(rates, cacheHitTokens, cacheMissTokens, outputTokens) {
+  return (
+    cacheHitTokens * rates.cacheHitInput +
+    cacheMissTokens * rates.cacheMissInput +
+    outputTokens * rates.output
+  ) / 1_000_000;
+}
+
+function number(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function rounded(value) {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}

package/src/telemetry/usage.mjs

@@ -0,0 +1,265 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+const EMPTY_USAGE = Object.freeze({
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadInputTokens: 0,
+  cacheCreationInputTokens: 0,
+  totalTokens: 0,
+  costUsd: 0,
+  costStatus: "unavailable",
+  turns: 0,
+  models: {},
+});
+
+export async function readAgentUsage(tracePath, { runtimeHome, model } = {}) {
+  const traceUsage = await readTraceUsage(tracePath);
+  const codexUsage = runtimeHome
+    ? await readCodexRolloutUsage(path.join(runtimeHome, "codex", "sessions"), { model })
+    : null;
+  if (!codexUsage || codexUsage.totalTokens === 0) return traceUsage;
+  return {
+    ...codexUsage,
+    costUsd: Math.max(codexUsage.costUsd, traceUsage.costUsd),
+    costStatus: traceUsage.costStatus,
+  };
+}
+
+async function readTraceUsage(tracePath) {
+  let raw;
+  try {
+    raw = await readFile(tracePath, "utf8");
+  } catch {
+    return structuredClone(EMPTY_USAGE);
+  }
+
+  const usageEvents = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const event = JSON.parse(line);
+      const normalized = normalizeUsageEvent(event);
+      if (normalized) usageEvents.push(normalized);
+    } catch {
+      // Traces can end with a partial line if a process is interrupted.
+    }
+  }
+  return usageEvents.reduce(
+    (total, usage) => mergeAgentUsage(total, usage),
+    structuredClone(EMPTY_USAGE),
+  );
+}
+
+export async function readCodexRolloutUsage(sessionsDirectory, { model: fallbackModel } = {}) {
+  const files = await jsonlFiles(sessionsDirectory);
+  const sessions = [];
+  for (const file of files) {
+    let raw;
+    try {
+      raw = await readFile(file, "utf8");
+    } catch {
+      continue;
+    }
+    let latest = null;
+    let model = fallbackModel ?? null;
+    let turns = 0;
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line);
+        if (event.type === "turn_context") {
+          turns += 1;
+          model = event.payload?.model ?? model;
+        }
+        if (
+          event.type === "event_msg"
+          && event.payload?.type === "token_count"
+          && event.payload?.info?.total_token_usage
+        ) {
+          latest = event.payload.info.total_token_usage;
+        }
+      } catch {
+        // A force-stopped Codex rollout can end with a partial JSONL line.
+      }
+    }
+    if (!latest) continue;
+    const inputWithCache = number(latest.input_tokens);
+    const cacheReadInputTokens = Math.min(inputWithCache, number(latest.cached_input_tokens));
+    const outputTokens = number(latest.output_tokens);
+    const inputTokens = Math.max(0, inputWithCache - cacheReadInputTokens);
+    const modelName = model ?? "codex-unknown-model";
+    sessions.push({
+      inputTokens,
+      outputTokens,
+      cacheReadInputTokens,
+      cacheCreationInputTokens: 0,
+      costUsd: 0,
+      costStatus: "unavailable",
+      turns: Math.max(1, turns),
+      models: {
+        [modelName]: {
+          inputTokens,
+          outputTokens,
+          cacheReadInputTokens,
+          cacheCreationInputTokens: 0,
+          costUsd: 0,
+        },
+      },
+    });
+  }
+  return mergeAgentUsage(...sessions);
+}
+
+async function jsonlFiles(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const target = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...await jsonlFiles(target));
+    else if (entry.isFile() && entry.name.endsWith(".jsonl")) files.push(target);
+  }
+  return files.sort();
+}
+
+export function mergeAgentUsage(...values) {
+  const merged = structuredClone(EMPTY_USAGE);
+  let pricedSources = 0;
+  let unpricedSources = 0;
+  let subscriptionSources = 0;
+  for (const value of values) {
+    if (!value) continue;
+    if (hasUsage(value)) {
+      if (value.costStatus === "subscription" && number(value.costUsd) === 0) subscriptionSources += 1;
+      else if (value.costStatus === "reported" || number(value.costUsd) > 0) pricedSources += 1;
+      else if (value.costStatus === "partial") {
+        pricedSources += 1;
+        unpricedSources += 1;
+      } else unpricedSources += 1;
+    }
+    merged.inputTokens += number(value.inputTokens);
+    merged.outputTokens += number(value.outputTokens);
+    merged.cacheReadInputTokens += number(value.cacheReadInputTokens);
+    merged.cacheCreationInputTokens += number(value.cacheCreationInputTokens);
+    merged.costUsd += number(value.costUsd);
+    merged.turns += number(value.turns);
+    for (const [model, usage] of Object.entries(value.models ?? {})) {
+      const previous = merged.models[model] ?? {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUsd: 0,
+      };
+      merged.models[model] = {
+        inputTokens: previous.inputTokens + number(usage.inputTokens),
+        outputTokens: previous.outputTokens + number(usage.outputTokens),
+        cacheReadInputTokens:
+          previous.cacheReadInputTokens + number(usage.cacheReadInputTokens),
+        cacheCreationInputTokens:
+          previous.cacheCreationInputTokens + number(usage.cacheCreationInputTokens),
+        costUsd: previous.costUsd + number(usage.costUsd),
+      };
+    }
+  }
+  merged.totalTokens =
+    merged.inputTokens +
+    merged.outputTokens +
+    merged.cacheReadInputTokens +
+    merged.cacheCreationInputTokens;
+  merged.costUsd = roundedCost(merged.costUsd);
+  if (subscriptionSources > 0) merged.billingMode = pricedSources === 0 && unpricedSources === 0 ? "subscription" : "mixed";
+  merged.costStatus = subscriptionSources > 0 && pricedSources === 0 && unpricedSources === 0 ? "subscription" : pricedSources === 0
+    ? "unavailable"
+    : unpricedSources === 0 ? "reported" : "partial";
+  return merged;
+}
+
+function usageFromResult(event) {
+  const usage = event.usage ?? {};
+  const models = {};
+  for (const [model, value] of Object.entries(event.modelUsage ?? {})) {
+    models[model] = {
+      inputTokens: number(value.inputTokens),
+      outputTokens: number(value.outputTokens),
+      cacheReadInputTokens: number(value.cacheReadInputTokens),
+      cacheCreationInputTokens: number(value.cacheCreationInputTokens),
+      costUsd: number(value.costUSD),
+    };
+  }
+  return {
+    inputTokens: number(usage.input_tokens),
+    outputTokens: number(usage.output_tokens),
+    cacheReadInputTokens: number(usage.cache_read_input_tokens),
+    cacheCreationInputTokens: number(usage.cache_creation_input_tokens),
+    costUsd: number(event.total_cost_usd),
+    costStatus: finiteOwn(event, "total_cost_usd") ? "reported" : "unavailable",
+    turns: number(event.num_turns),
+    models,
+  };
+}
+
+function normalizeUsageEvent(event) {
+  if (event.type === "result" && event.usage) return usageFromResult(event);
+
+  if (event.type === "turn.completed" && event.usage) {
+    const cached = number(event.usage.cached_input_tokens);
+    return {
+      inputTokens: Math.max(0, number(event.usage.input_tokens) - cached),
+      outputTokens: number(event.usage.output_tokens),
+      cacheReadInputTokens: cached,
+      cacheCreationInputTokens: 0,
+      costUsd: 0,
+      costStatus: "unavailable",
+      turns: 1,
+      models: {},
+    };
+  }
+
+  const part = event.part ?? event.properties?.part;
+  if (
+    (event.type === "step_finish" || event.type === "step-finish" || part?.type === "step-finish") &&
+    part?.tokens
+  ) {
+    const cached = number(part.tokens.cache?.read);
+    return {
+      inputTokens: number(part.tokens.input),
+      outputTokens: number(part.tokens.output) + number(part.tokens.reasoning),
+      cacheReadInputTokens: cached,
+      cacheCreationInputTokens: number(part.tokens.cache?.write),
+      costUsd: number(part.cost),
+      costStatus: finiteOwn(part, "cost") ? "reported" : "unavailable",
+      turns: 1,
+      models: {},
+    };
+  }
+  return null;
+}
+
+function number(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function finiteOwn(value, key) {
+  return value && Object.prototype.hasOwnProperty.call(value, key)
+    && typeof value[key] === "number" && Number.isFinite(value[key]);
+}
+
+function hasUsage(value) {
+  return number(value?.totalTokens) > 0
+    || number(value?.inputTokens) > 0
+    || number(value?.outputTokens) > 0
+    || number(value?.cacheReadInputTokens) > 0
+    || number(value?.cacheCreationInputTokens) > 0
+    || number(value?.turns) > 0
+    || Object.keys(value?.models ?? {}).length > 0;
+}
+
+function roundedCost(value) {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}

package/src/terminal/events.mjs

@@ -0,0 +1,97 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { StringDecoder } from 'node:string_decoder';
+
+// The CLI subscribes locally. Hosted consumers keep their own output policy.
+const session = new AsyncLocalStorage();
+export const withSessionEvents = (sink, action) => session.run(sink, action);
+export const hasSessionEvents = () => Boolean(session.getStore());
+export function sessionEvent(event) { session.getStore()?.({ at: new Date().toISOString(), ...event }); }
+
+export function createRuntimeStream({ source, runtime, emit = sessionEvent }) {
+  const decoder = new StringDecoder('utf8');
+  let pending = '';
+  let sequence = 0;
+  const claudeMessages = new Map();
+  const texts = new Map();
+  const send = (kind, text, id, extra = {}) => {
+    if (typeof text !== 'string' || !text) return;
+    const key = `${source}:${id ?? ++sequence}`;
+    if (texts.get(key) === text) return;
+    texts.set(key, text);
+    emit({ kind, text, id: key, source, runtime, ...extra });
+  };
+  const content = (blocks, prefix) => {
+    if (typeof blocks === 'string') { send('tool-output', blocks, prefix); return; }
+    for (const [index, block] of (blocks ?? []).entries()) {
+      const id = `${prefix}:${block.id ?? block.tool_use_id ?? index}`;
+      if (block.type === 'text') send('assistant', block.text, id);
+      if (block.type === 'tool_use') send('tool', `${block.name}\n${JSON.stringify(block.input, null, 2)}`, id);
+      if (block.type === 'tool_result') {
+        const text = typeof block.content === 'string' ? block.content
+          : (block.content ?? []).filter(item => item.type === 'text').map(item => item.text).join('\n');
+        send('tool-output', text, id, { failed: block.is_error === true });
+      }
+    }
+  };
+  const record = value => {
+    if (value.type?.startsWith('citeark.')) return;
+    if (value.type === 'assistant' || value.type === 'user') {
+      content(value.message?.content, value.message?.id ?? value.uuid ?? `message-${++sequence}`);
+    } else if (value.type === 'stream_event') {
+      const event = value.event;
+      const parent = value.parent_tool_use_id ?? 'main';
+      if (event?.type === 'message_start') claudeMessages.set(parent, event.message.id);
+      if (event?.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+        const id = `${claudeMessages.get(parent) ?? parent}:${event.index}`;
+        send('assistant', (texts.get(`${source}:${id}`) ?? '') + event.delta.text, id);
+      }
+    } else if (value.type?.startsWith('item.') && value.item) {
+      const item = value.item;
+      const id = item.id ?? `item-${++sequence}`;
+      if (item.type === 'agent_message') send('assistant', item.text, id);
+      if (item.type === 'command_execution') {
+        send('tool', `$ ${item.command}`, `${id}:command`);
+        send('tool-output', item.aggregated_output, `${id}:output`, { status: item.status, exitCode: item.exit_code });
+        if (value.type === 'item.completed') send('status', `Process exited with code ${item.exit_code ?? 'unknown'}`, `${id}:exit`);
+      }
+      if (item.type === 'file_change') send('tool', (item.changes ?? []).map(change => `${change.kind} ${change.path}${change.diff ? `\n${change.diff}` : ''}`).join('\n'), id);
+      if (item.type === 'mcp_tool_call') {
+        send('tool', `${item.server}/${item.tool}\n${JSON.stringify(item.arguments ?? {}, null, 2)}`, `${id}:call`);
+        if (item.result) send('tool-output', JSON.stringify(item.result, null, 2), `${id}:result`);
+        if (item.error) send('error', JSON.stringify(item.error), `${id}:error`);
+      }
+      if (item.type === 'web_search') send('tool', `Search: ${item.query ?? JSON.stringify(item.action ?? {})}`, id);
+      if (item.type === 'error') send('error', item.message, id);
+    } else if (value.type === 'text' && value.part) {
+      send('assistant', value.part.text, value.part.id);
+    } else if (value.type === 'tool_use' && value.part) {
+      const part = value.part;
+      send('tool', `${part.tool}\n${JSON.stringify(part.state?.input ?? {}, null, 2)}`, `${part.id}:call`);
+      send('tool-output', part.state?.output, `${part.id}:output`, { status: part.state?.status });
+      send('error', part.state?.error, `${part.id}:error`);
+    } else if (value.type === 'error' || value.type === 'turn.failed') {
+      send('error', value.error?.message ?? value.message ?? JSON.stringify(value.error), value.id);
+    } else if (value.type === 'result' && value.is_error) {
+      send('error', value.result ?? value.errors?.join('\n'), value.uuid);
+    }
+  };
+  const consume = line => {
+    if (!line.trim()) return;
+    let value;
+    try { value = JSON.parse(line); } catch { send('tool-output', line); return; }
+    record(value);
+  };
+  return {
+    record,
+    write(chunk) {
+      pending += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+      let newline;
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        consume(pending.slice(0, newline));
+        pending = pending.slice(newline + 1);
+      }
+    },
+    end() { pending += decoder.end(); if (pending) consume(pending); pending = ''; },
+    stderr(chunk) { send('error', String(chunk)); },
+  };
+}

package/src/terminal/input.mjs

@@ -0,0 +1,40 @@
+import { emitKeypressEvents } from 'node:readline';
+import { PassThrough } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+
+// Readline handles keyboard keys, but treats SGR mouse reports as typed text.
+// Remove mouse/paste framing before passing keyboard sequences to readline.
+export function terminalKeys(input, onKey) {
+  const keys = new PassThrough();
+  const decoder = new StringDecoder('utf8');
+  emitKeypressEvents(keys); keys.on('keypress', onKey);
+  let pending = '', pasted = null, timer;
+  const consume = chunk => {
+    clearTimeout(timer);
+    pending += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+    while (pending) {
+      if (pasted !== null) {
+        const end = pending.indexOf('\x1b[201~');
+        if (end < 0) return;
+        onKey(pasted + pending.slice(0, end), { name: 'paste' });
+        pasted = null; pending = pending.slice(end + 6); continue;
+      }
+      const escape = pending.indexOf('\x1b');
+      if (escape !== 0) {
+        const length = escape < 0 ? pending.length : escape;
+        keys.write(pending.slice(0, length)); pending = pending.slice(length); continue;
+      }
+      const sequence = /^(?:\x1b\[[0-?]*[ -/]*[@-~]|\x1bO.|\x1b[^\[O])/s.exec(pending)?.[0];
+      if (!sequence) {
+        timer = setTimeout(() => { keys.write(pending); pending = ''; }, 50);
+        return;
+      }
+      pending = pending.slice(sequence.length);
+      if (sequence === '\x1b[200~') pasted = '';
+      else if (/^\x1b\[</.test(sequence)) onKey('', { sequence });
+      else keys.write(sequence);
+    }
+  };
+  input.on('data', consume);
+  return () => { clearTimeout(timer); input.off('data', consume); keys.off('keypress', onKey); keys.destroy(); };
+}

package/src/terminal/plain.mjs

@@ -0,0 +1,40 @@
+import { createWriteStream } from 'node:fs';
+import { finished } from 'node:stream/promises';
+import { cleanText, STAGES, workflowStage } from './transcript.mjs';
+
+// Keep pipes and ordinary terminal scrollback usable, including text deltas.
+export class PlainSession {
+  constructor({ output = process.stdout } = {}) {
+    this.output = output; this.previous = new Map(); this.initial = [];
+  }
+  async attach(filename) {
+    this.file = createWriteStream(filename, { flags: 'a', mode: 0o600 });
+    this.file.on('error', error => { this.fileError = error; });
+    for (const event of this.initial) this.file.write(`${JSON.stringify(event)}\n`);
+    this.initial = [];
+  }
+  event(event) {
+    const value = { at: new Date().toISOString(), ...event };
+    if (this.file && !this.fileError) this.file.write(`${JSON.stringify(value)}\n`);
+    else this.initial.push(value);
+    if (event.kind === 'diagnostic') return;
+    if (event.kind === 'stage') {
+      const index = workflowStage(event.stage);
+      if (index !== undefined) this.output.write(`\n[${index + 1}/5 ${STAGES[index]}]\n`);
+      this.lastId = null;
+      return;
+    }
+    const text = cleanText(event.text ?? '');
+    if (!text) return;
+    const old = event.id ? this.previous.get(event.id) : null;
+    if (text === old) return;
+    if (old && text.startsWith(old) && this.lastId === event.id) this.output.write(text.slice(old.length));
+    else this.output.write(`\n\n${text}`);
+    if (event.id) this.previous.set(event.id, text);
+    this.lastId = event.id;
+  }
+  async close() {
+    this.output.write('\n');
+    if (this.file) { this.file.end(); await finished(this.file); }
+  }
+}

package/src/terminal/remote-stream.mjs

@@ -0,0 +1,22 @@
+import { createRuntimeStream, hasSessionEvents, sessionEvent } from './events.mjs';
+
+// Read append-only trace bytes from the user's private staging object. A byte
+// cursor preserves every event between polls, including a partial UTF-8 line.
+export function watchRemoteTranscript({ storage, bucket, object, source, runtime, intervalMs = 2000 }) {
+  if (!hasSessionEvents()) return async () => {};
+  const stream = createRuntimeStream({ source, runtime });
+  let offset = 0; let active = null; let warning = false;
+  const poll = async () => {
+    try {
+      const chunk = await storage.readObjectBytes({ bucket, object, offset });
+      if (chunk.length) { stream.write(chunk); offset += chunk.length; }
+      warning = false;
+    } catch (error) {
+      if (!warning) sessionEvent({ kind: 'error', text: `Live output connection interrupted: ${error.message}. Reconnecting…` });
+      warning = true;
+    }
+  };
+  const tick = () => { if (!active) active = poll().finally(() => { active = null; }); };
+  const timer = setInterval(tick, intervalMs); timer.unref(); tick();
+  return async () => { clearInterval(timer); await active; await poll(); stream.end(); };
+}