benchgo-plugin 0.0.0-stage → 0.0.2

package/src/cli.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline';
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { Commander } from './runtime.mjs';
+
+const { values } = parseArgs({ options: { 'data-dir': { type: 'string' }, config: { type: 'string' }, stdio: { type: 'boolean' }, help: { type: 'boolean' } } });
+if (values.help) {
+  console.log('benchgo [--data-dir PATH] [--config JSON_FILE] [--stdio]\nInteractive native session control. --stdio is a trusted local JSONL API, not a network server.');
+  process.exit(0);
+}
+const config = values.config ? JSON.parse(await readFile(values.config, 'utf8')) : {};
+if (values['data-dir']) config.dataDir = values['data-dir'];
+const commander = await new Commander(config).open();
+const json = value => process.stdout.write(JSON.stringify(value) + '\n');
+let selected;
+let closing = false;
+const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: !values.stdio && process.stdin.isTTY });
+const stop = async () => {
+  if (closing) return; closing = true; rl.close();
+  try { await commander.close(); } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }
+};
+process.on('SIGTERM', () => void stop());
+process.on('SIGINT', () => void stop());
+commander.on('fault', error => { process.stderr.write(`BenchGo persistence error: ${error.message}\n`); void stop(); });
+commander.on('event', event => {
+  if (values.stdio) json({ event });
+  else if (event.sessionId === selected) {
+    if (event.type === 'text.delta') process.stdout.write(event.data.text);
+    else if (event.type === 'approval.requested') console.log(`\n[${event.data.kind}] ${event.data.id}\n${JSON.stringify(event.data.details, null, 2)}\n/approve ID yes|no 或 /answer ID JSON`);
+    else if (['turn.completed', 'session.error', 'input.uncertain', 'provider.retry'].includes(event.type)) console.log(`\n[${event.type}] ${JSON.stringify(event.data)}`);
+  }
+});
+
+async function dispatch(method, params) {
+  switch (method) {
+    case 'providers': return commander.catalog();
+    case 'doctor': return commander.doctor();
+    case 'list': return commander.list();
+    case 'create': return commander.create(params);
+    case 'connect': return commander.connect(params.id);
+    case 'send': return commander.submit(params.id, params.text, { requestId: params.requestId });
+    case 'steer': await commander.steer(params.id, params.text); return commander.snapshot(params.id);
+    case 'interrupt': await commander.interrupt(params.id); return commander.snapshot(params.id);
+    case 'approve': commander.approve(params.id, params.approvalId, params.answer); return commander.snapshot(params.id);
+    case 'events': return commander.events(params.id, params.after);
+    case 'history': return commander.history(params.id);
+    case 'discover': return commander.discover(params.id);
+    case 'wait': return commander.wait(params.id, { timeout: params.timeout });
+    case 'close': return commander.disconnect(params.id);
+    case 'archive': return commander.archive(params.id, params.archived);
+    default: throw new Error(`Unknown method: ${method}`);
+  }
+}
+
+if (!values.stdio) console.log('BenchGo\n/new codex|claude|pi|opencode|gemini|hermes|grok|mcode [cwd]  /list  /use ID  /resume ID\n/steer TEXT  /stop  /approve ID yes|no  /answer ID JSON\n/events [cursor]  /history  /discover  /close  /archive  /quit\n输入普通文字向当前会话发送任务。原生会话导入使用 --stdio create 的 nativeId。');
+
+// Requests can overlap in JSONL mode so an approval can be answered while a
+// wait request is pending. Commander owns session mutation serialization.
+const inFlight = new Set();
+rl.on('line', line => {
+  const task = (async () => {
+    let request;
+    try {
+      if (values.stdio) {
+        request = JSON.parse(line);
+        const result = await dispatch(request.method, request.params ?? {});
+        json({ id: request.id ?? null, result });
+      } else {
+        if (!line.trim()) return;
+        const [command, ...rest] = line.trim().split(/\s+/); const text = rest.join(' ');
+        if (command === '/quit') { void stop(); return; }
+        let result;
+        if (command === '/new') { result = await commander.create({ provider: rest[0], cwd: rest.slice(1).join(' ') || process.cwd() }); selected = result.id; }
+        else if (command === '/list') result = commander.list();
+        else if (command === '/doctor') result = await commander.doctor();
+        else if (command === '/use') { commander.get(text); selected = text; result = commander.snapshot(selected); }
+        else if (command === '/resume') { selected = text; result = await commander.connect(selected); }
+        else {
+          if (!selected) throw new Error('先使用 /new 或 /use 选择会话');
+          if (command === '/stop') result = await dispatch('interrupt', { id: selected });
+          else if (command === '/steer') result = await dispatch('steer', { id: selected, text });
+          else if (command === '/events') result = commander.events(selected, Number(text || 0));
+          else if (command === '/history') result = await commander.history(selected);
+          else if (command === '/discover') result = await commander.discover(selected);
+          else if (command === '/close') result = await commander.disconnect(selected);
+          else if (command === '/archive') result = await commander.archive(selected);
+          else if (command === '/approve') result = await dispatch('approve', { id: selected, approvalId: rest[0], answer: { allow: rest[1] === 'yes' } });
+          else if (command === '/answer') result = await dispatch('approve', { id: selected, approvalId: rest[0], answer: JSON.parse(rest.slice(1).join(' ')) });
+          else if (command.startsWith('/')) throw new Error('未知命令');
+          else result = await commander.submit(selected, line);
+        }
+        console.log(JSON.stringify(result, null, 2));
+      }
+    } catch (error) {
+      if (values.stdio) json({ id: request?.id ?? null, error: { message: error.message } });
+      else console.error(error.message);
+    }
+  })();
+  inFlight.add(task); task.finally(() => inFlight.delete(task));
+});
+rl.on('close', () => { void stop(); });

package/src/commands.mjs

@@ -0,0 +1,17 @@
+/** Provider-native slash commands; never interpret arbitrary text as shell input. */
+export function normalizeCommand(name, args = '') {
+  if (typeof name !== 'string' || !/^[\w.:-]{1,120}$/.test(name.replace(/^\//, ''))) throw new Error('Invalid native command name');
+  if (typeof args !== 'string' || args.length > 20000) throw new Error('Invalid native command arguments');
+  return { name: name.replace(/^\//, ''), arguments: args };
+}
+
+export const compactCommand = { name: 'compact', description: 'Compress the native conversation context', argumentHint: '', kind: 'command' };
+
+export function commandCatalog(commands = [], builtins = []) {
+  const result = new Map(builtins.map(command => [command.name, command]));
+  for (const command of commands) {
+    if (!command || typeof command.name !== 'string' || !/^[\w.:-]{1,120}$/.test(command.name)) continue;
+    if (!result.has(command.name)) result.set(command.name, { name: command.name, description: command.description ?? '', argumentHint: command.argumentHint ?? '', kind: command.kind === 'skill' || command.source === 'skill' ? 'skill' : 'command' });
+  }
+  return [...result.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/delegation.mjs

@@ -0,0 +1,47 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+export const delegationSchema = { type: 'object', properties: {
+  provider: { type: 'string', enum: ['codex', 'claude', 'pi', 'opencode', 'gemini', 'hermes', 'grok', 'mcode'] },
+  model: { type: 'string' }, text: { type: 'string' },
+  operation: { type: 'string', enum: ['delegate', 'result'] }, sessionId: { type: 'string' },
+}, required: [], additionalProperties: false };
+
+/** Per-process, per-session capability endpoint for native MCP/extension tools. No public listener. */
+export class DelegationBridge {
+  constructor(commander, { serverFactory = createServer } = {}) { this.commander = commander; this.tokens = new Map(); this.serverFactory = serverFactory; }
+  async open() {
+    this.server = this.serverFactory(async (req, res) => {
+      const id = this.tokens.get(req.headers.authorization?.replace(/^Bearer /, ''));
+      res.setHeader('Content-Type', 'application/json');
+      if (!id || req.method !== 'POST' || req.url !== '/delegate') { res.writeHead(403); res.end('{}'); return; }
+      try {
+        let body = ''; for await (const chunk of req) { body += chunk; if (body.length > 65536) throw new Error('Delegation request too large'); }
+        res.end(JSON.stringify(await this.commander.delegate(id, JSON.parse(body))));
+      } catch (error) { res.writeHead(400); res.end(JSON.stringify({ error: error.message })); }
+    });
+    try {
+      await new Promise((resolve, reject) => {
+        const failed = error => { this.server.removeListener('listening', ready); this.server.removeListener('error', failed); reject(error); };
+        const ready = () => { this.server.removeListener('error', failed); resolve(); };
+        this.server.once('error', failed);
+        this.server.once('listening', ready);
+        try { this.server.listen(0, '127.0.0.1'); } catch (error) { failed(error); }
+      });
+    } catch (error) { await this.close(); throw error; }
+    this.url = `http://127.0.0.1:${this.server.address().port}/delegate`;
+    return this;
+  }
+  forSession(id) {
+    const token = randomBytes(32).toString('hex'); this.tokens.set(token, id);
+    return { url: this.url, token, command: process.execPath, script: fileURLToPath(new URL('./mcp.mjs', import.meta.url)), schema: delegationSchema };
+  }
+  revoke(id) { for (const [token, owner] of this.tokens) if (owner === id) this.tokens.delete(token); }
+  async close() {
+    this.tokens.clear();
+    if (!this.server) return;
+    this.server.closeAllConnections();
+    await new Promise(resolve => this.server.close(resolve));
+  }
+}

package/src/fonts.mjs

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+
+/** Fixed asset allowlist; same owner authentication as the existing Connection routes. */
+export async function mountFonts(ctx) {
+  const root = new URL('../assets/fonts/', import.meta.url);
+  const manifest = JSON.parse(await readFile(new URL('manifest.json', root), 'utf8'));
+  for (const { file } of manifest) {
+    ctx.effect(() => ctx.connection.fetch.register({
+      path: '/api/commander-fonts/' + file, methods: ['GET'], requestBody: 'buffered',
+      async fetch() {
+        return new Response(new Uint8Array(await readFile(new URL('web/' + file, root))), {
+          headers: { 'content-type': 'font/woff2', 'cache-control': 'private, max-age=31536000, immutable', 'x-content-type-options': 'nosniff' },
+        });
+      },
+    }));
+  }
+}

package/src/harness-adapter.mjs

@@ -0,0 +1,228 @@
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import { discoverModels } from './models.mjs';
+import { singleRequestUsage } from './harness-usage.mjs';
+import { decodeRouteModelId } from './picker-catalog.mjs';
+
+const providers = { codex: 'Codex', claude: 'Claude Code', pi: 'Pi', opencode: 'OpenCode', gemini: 'Gemini CLI', hermes: 'Hermes', grok: 'Grok Build', mcode: 'MiniMax Code' };
+const route = provider => `commander-${provider}`;
+const inputPrefix = 'harness-user:';
+
+/** Native agents remain the tool executor; Harness owns the conversation UI and journal. */
+export function mountHarnessAdapter(ctx, commander, { bindOwner, cwd, discover = discoverModels } = {}) {
+  const active = new Set();
+  const metadata = new Map();
+  const jobs = new Set();
+  let disposed = false;
+  class CommanderAdapter extends LlmAdapter {
+    providerInfo(provider) { return { id: provider, name: providers[provider.slice('commander-'.length)] }; }
+    providerRetryPolicy() { return { mode: 'normal', maxRetries: 0, retryableCodes: [], initialDelayMs: 0, maxDelayMs: 0, jitterRatio: 0 }; }
+    async listModels(provider) {
+      const native = provider.slice('commander-'.length);
+      if (commander.pickerCatalog) {
+        const models = await commander.pickerCatalog.models(native);
+        for (const model of models) metadata.set(`${provider}/${model.id}`, model);
+        return models;
+      }
+      const directory = cwd ?? ctx.get('workspaceRegistry')?.list()[0]?.path;
+      const models = [{ provider, id: 'native-default', name: `${providers[native]} 默认模型`, inputModalities: ['text'] }];
+      if (directory) {
+        try {
+          const known = await discover(native, commander.providerConfig ? await commander.providerConfig(native) : commander.providers.get(native)?.config ?? {}, directory);
+          // Reuse an existing native connection; discovering a model never creates a session.
+          if (commander.drivers && commander.list) {
+            for (const session of commander.list().filter(row => row.provider === native && row.cwd === directory)) {
+              const driver = commander.drivers.get(session.id);
+              if (driver?.models) known.push(...await driver.models());
+            }
+          }
+          for (const model of known) {
+            if (models.some(value => value.id === model.id)) continue;
+            models.push({ provider, id: model.id, name: model.name, inputModalities: ['text'], ...(Number.isSafeInteger(model.contextWindow) && model.contextWindow > 0 ? { context: { contextWindow: model.contextWindow } } : {}) });
+          }
+        } catch (error) {
+          ctx.logger?.warn?.(`BenchGo ${native} model discovery failed: ${error.message}`);
+        }
+      }
+      for (const model of models) metadata.set(`${provider}/${model.id}`, model);
+      return models;
+    }
+    async resolveModel(provider, model) {
+      // Exact metadata includes native reasoning choices and supplier identity.
+      // A historical route can still resolve its identity after directory removal.
+      const binding = decodeRouteModelId(model);
+      if (binding) {
+        if (!metadata.has(`${provider}/${model}`) && commander.pickerCatalog) await this.listModels(provider);
+        return metadata.get(`${provider}/${model}`) ?? { provider, id: model, name: binding.model, inputModalities: ['text'] };
+      }
+      return metadata.get(`${provider}/${model}`) ?? { provider, id: model, name: model === 'native-default' ? `${this.providerInfo(provider).name} 默认模型` : model, inputModalities: ['text'] };
+    }
+    async *stream(options) {
+      if (disposed) throw new Error('BenchGo adapter is disposed');
+      if (options.purpose) throw new Error(`BenchGo native agents do not support auxiliary ${options.purpose} requests`);
+      if (options.reasoningEffort !== undefined) throw new Error('此工具不支持 API 模型的思考档位，请在设置 → Harness 中配置对应工具的推理强度后新建对话');
+      options.signal?.throwIfAborted();
+      const agent = ctx.agents.requireInitiator();
+      const owner = String(agent.session.id);
+      if (!options.sessionId || String(options.sessionId) !== owner) throw new Error('BenchGo requires the initiating Harness session identity');
+      const directory = agent.session.header.cwd;
+      if (!directory) throw new Error('BenchGo requires a project working directory');
+      const native = options.provider.slice('commander-'.length);
+      if (!Object.hasOwn(providers, native)) throw new Error('Unknown BenchGo provider');
+      const binding = decodeRouteModelId(options.model);
+      const nativeModel = binding?.model ?? (options.model === 'native-default' ? undefined : options.model);
+      const human = options.messages.filter(message => message.role === 'user' && message.source?.kind === 'user');
+      if (!human.length) throw new Error('BenchGo requires a durable human message');
+      for (const message of human) {
+        if (!message.id) throw new Error('BenchGo requires stable human message identities');
+        if (message.content.some(block => block.type !== 'text')) throw new Error('BenchGo currently supports text messages only; attachments are not supported');
+      }
+      const key = owner;
+      if (active.has(key)) throw new Error('A BenchGo request is already active for this conversation and model');
+      active.add(key);
+      const controller = new AbortController();
+      let done;
+      const settled = new Promise(resolve => { done = resolve; });
+      const job = { controller, settled }; jobs.add(job);
+      const abort = () => controller.abort(options.signal.reason);
+      options.signal?.addEventListener('abort', abort, { once: true });
+      let id, wake, version = 0, finished = false;
+      const notify = event => { if (event.sessionId === id) { version++; wake?.(); } };
+      let interrupting;
+      const cancelled = () => {
+        version++; wake?.();
+        if (id && ['running', 'waiting'].includes(commander.snapshot(id).status)) {
+          interrupting = commander.interrupt(id);
+          interrupting.catch(error => { ctx.logger?.warn?.(`BenchGo interrupt failed: ${error.message}`); });
+        }
+      };
+      controller.signal.addEventListener('abort', cancelled);
+      commander.on('event', notify);
+      try {
+        const ownedSessions = commander.list().filter(session => !session.archived && (!session.parentId || session.harnessAdopted) && session.ownerSessionId === owner);
+        const existing = ownedSessions.find(session => session.provider === native && session.cwd === directory && (binding
+          ? session.route?.providerId === binding.providerId
+          : !session.route && (session.model ?? 'native-default') === options.model));
+        if (existing && binding && (existing.route?.model !== binding.model || existing.model !== nativeModel)) {
+          if (['running', 'waiting', 'connecting'].includes(existing.status)) throw new Error('请等待当前轮次完成后再切换模型');
+          if (commander.pickerCatalog) {
+            const available = await commander.pickerCatalog.models(native);
+            if (!available.some(model => model.id === options.model)) throw new Error('工具供应商或模型已变更，请重新选择模型');
+          }
+          const driver = commander.drivers.get(existing.id);
+          if (driver && !driver.setModel) throw new Error(`${native} 当前连接不支持在同一会话中切换模型，请新建聊天`);
+          // Decoding a picker ID recovers identity only. Re-capture the full
+          // binding so reconnects retain validation and this session's settings.
+          const nextRoute = commander.routeService?.capture
+            ? await commander.routeService.capture({ tool: native, ...binding, ...(existing.route?.quickSettings ? { quickSettings: existing.route.quickSettings } : {}) })
+            : binding;
+          if (existing.route?.version && !nextRoute.version) throw new Error('会话绑定服务不可用，无法保存模型变更');
+          if (existing.route?.version && ['mode', 'baseURL', 'protocol', 'sourceProtocol', 'credentialRef'].some(key => existing.route[key] !== nextRoute[key])) throw new Error('绑定供应商的地址、协议或凭据引用已更改，请新建会话或恢复原配置。');
+          await driver?.setModel(nativeModel);
+          const record = commander.get(existing.id);
+          record.model = nativeModel;
+          record.route = nextRoute;
+          await commander.persist();
+          commander.event(existing.id, 'model.changed', { providerId: binding.providerId, model: binding.model, nativeModel });
+        }
+        if (!existing && commander.pickerCatalog) {
+          if (ownedSessions.length) throw new Error('此对话已绑定其他工具或供应商模型；请新建聊天，已有记录与运行配置不会被修改');
+          if (!binding) throw new Error('请选择已绑定供应商的工具模型；本机默认配置不会被自动用于新会话');
+          const available = await commander.pickerCatalog.models(native);
+          if (!available.some(model => model.id === options.model)) throw new Error('工具供应商或模型已变更，请重新选择模型');
+        }
+        const session = existing ?? await commander.create({ provider: native, cwd: directory, ...(nativeModel ? { model: nativeModel } : {}), ...(binding ? { route: binding } : {}), ownerSessionId: owner, title: human.at(-1).content.map(block => block.text).join('\n').slice(0, 120) });
+        id = session.id;
+        bindOwner?.(id, agent);
+        controller.signal.throwIfAborted();
+        if (['disconnected', 'closed', 'failed'].includes(commander.snapshot(id).status)) await commander.connect(id);
+        const record = commander.get(id);
+        const receipts = record.receipts;
+        // The terminal message id keys the whole admitted batch; preceding human messages
+        // are context only when entering this native route for the first time.
+        const latest = human.at(-1);
+        const requestId = `${inputPrefix}${latest.id}`;
+        let lastDelivered = -1;
+        human.forEach((message, index) => { if (Object.hasOwn(receipts, `${inputPrefix}${message.id}`)) lastDelivered = index; });
+        const pending = Object.hasOwn(receipts, requestId) ? [] : human.slice(lastDelivered + 1);
+        const text = pending.map(message => message.content.map(block => block.text).join('\n')).join('\n\n');
+        const prior = receipts[requestId];
+        if (prior?.receipt.status === 'uncertain') throw new Error('Native input acceptance is uncertain; inspect the native session before retrying');
+        let cursor = prior ? 0 : record.cursor;
+        const receipt = prior?.receipt ?? await commander.submit(id, text, { requestId });
+        const usageSamples = new Map();
+        let result = '', index = 0, started = false, completed = false;
+        while (!completed) {
+          controller.signal.throwIfAborted();
+          const observed = version;
+          const batch = commander.events(id, cursor, 500);
+          if (batch.truncated) throw new Error('BenchGo event history was truncated; refusing to replay an incomplete native response');
+          cursor = batch.cursor;
+          for (const event of batch.events) {
+            if (event.turnId !== receipt.turnId) continue;
+            if (event.type === 'usage') {
+              const sampleId = event.data.id;
+              // An unkeyed sample cannot prove that an update is the same request.
+              usageSamples.set(sampleId ?? 'unidentified:' + event.seq, event.data);
+            } else if (native === 'claude' && event.type === 'message' && event.data.type === 'assistant' && event.data.message?.usage) {
+              const message = event.data.message;
+              usageSamples.set(message.id ?? 'unidentified:' + event.seq, { usage: message.usage });
+            } else if (event.type === 'text.delta') {
+              if (!started) { started = true; yield { type: 'block-start', index, blockType: 'text' }; }
+              result += event.data.text;
+              yield { type: 'text-delta', index, text: event.data.text };
+            } else if (event.type === 'turn.completed') {
+              if (event.data.status !== 'completed') throw new Error(`Native ${native} turn ${event.data.status}: ${JSON.stringify(event.data.error ?? event.data.errors ?? '')}`);
+              if (!result && event.data.result) {
+                result = String(event.data.result); started = true;
+                yield { type: 'block-start', index, blockType: 'text' };
+                yield { type: 'text-delta', index, text: result };
+              }
+              completed = true; finished = true; break;
+            } else if (['session.error', 'provider.error', 'input.uncertain'].includes(event.type)) throw new Error(event.data.message ?? JSON.stringify(event.data));
+          }
+          if (!completed && cursor >= batch.latest) {
+            if (['failed', 'closed', 'disconnected'].includes(commander.snapshot(id).status)) throw new Error('Native session disconnected before completing its response');
+            await new Promise(resolve => { wake = resolve; if (version !== observed || controller.signal.aborted) resolve(); });
+            wake = undefined;
+          }
+        }
+        if (!started) throw new Error('Native agent completed without a text response');
+        yield { type: 'block-end', index, block: { type: 'text', text: result } };
+        // Let Harness stamp stream timing and fold tokenUsage/contextPressure.
+        // A replay has no live decode interval; multiple native requests are not
+        // one model context and remain available in the separate billing ledger.
+        const usage = prior ? undefined : singleRequestUsage(native, usageSamples);
+        if (usage) yield { type: 'usage', usage };
+        yield { type: 'finish', reason: { kind: 'stop' } };
+      } finally {
+        commander.off('event', notify);
+        controller.signal.removeEventListener('abort', cancelled);
+        options.signal?.removeEventListener('abort', abort);
+        try {
+          if (interrupting) await interrupting;
+          else if (!finished && id && ['running', 'waiting'].includes(commander.snapshot(id).status)) await commander.interrupt(id);
+        } finally { active.delete(key); jobs.delete(job); done(); }
+      }
+    }
+  }
+  const adapter = new CommanderAdapter();
+  const unregister = ctx.llm.registerAdapter(Object.keys(providers).map(route), adapter);
+  // Inspect original attachments before LlmRuntime converts unsupported modalities
+  // to text placeholders or projects durable file handles into text.
+  ctx.on('llm/stream', async function* (options, next) {
+    if (Object.keys(providers).some(provider => route(provider) === options.provider)
+      && options.messages.some(message => message.role === 'user' && message.source?.kind === 'user'
+        && message.content.some(block => block.type !== 'text'))) {
+      yield { type: 'finish', reason: { kind: 'error', failure: { code: 'UNSUPPORTED_ATTACHMENT', message: 'BenchGo currently supports text messages only; attachments are not supported' } } };
+      return;
+    }
+    yield* next();
+  });
+  ctx.effect(() => async () => {
+    disposed = true;
+    unregister();
+    for (const job of jobs) job.controller.abort(new Error('BenchGo adapter disposed'));
+    await Promise.allSettled([...jobs].map(job => job.settled));
+  });
+  return adapter;
+}

package/src/harness-commands.mjs

@@ -0,0 +1,39 @@
+import { harnessSelection } from './harness-selection.mjs';
+/** Native commands use the official Harness command UI and human-only result cards. */
+export function mountHarnessCommands(ctx, commander, { bindOwner } = {}) {
+  ctx.effect(() => ctx.commands.register({
+    name: 'native',
+    description: '查看或执行当前编码工具的原生命令',
+    input: { hint: '命令名与参数；留空查看可用命令' },
+    async handler(invocation) {
+      const { agent, signal, commandId } = invocation;
+      const selection = harnessSelection(ctx, agent);
+      const provider = selection.provider?.replace(/^commander-/, '');
+      if (!selection.provider?.startsWith('commander-')) return { kind: 'error', text: '请先在模型菜单中选择 Codex、Claude Code、Pi 或 OpenCode。' };
+      const id = String(agent.session.id);
+      const model = selection.model;
+      const session = commander.list().find(s => s.ownerSessionId === id && (!s.parentId || s.harnessAdopted) && !s.archived && s.provider === provider && (s.model || 'native-default') === model);
+      if (!session) return { kind: 'error', text: '先发送一条消息建立原生会话，再使用 /native。' };
+      bindOwner?.(session.id, agent);
+      signal.throwIfAborted();
+      if (['disconnected', 'closed', 'failed'].includes(session.status)) await commander.connect(session.id);
+      const line = invocation.rawInput.trim();
+      if (!line) {
+        const catalog = await commander.commands(session.id);
+        return { kind: 'success', text: catalog.length ? catalog.map(c => `/${c.name}${c.argumentHint ? ` ${c.argumentHint}` : ''}${c.description ? ` — ${c.description}` : ''}`).join('\n') : '此工具没有提供可执行的原生命令。' };
+      }
+      const match = line.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+      const abort = () => { commander.interrupt(session.id).catch(error => ctx.logger.warn(error.message)); };
+      signal.addEventListener('abort', abort, { once: true });
+      try {
+        const cursor = commander.snapshot(session.id).cursor;
+        const receipt = await commander.command(session.id, { name: match[1], arguments: match[2] || '', requestId: `harness-command:${commandId}` });
+        const result = await commander.wait(session.id, { timeout: 55000, signal });
+        const events = commander.events(session.id, cursor, 500).events.filter(e => e.turnId === receipt.turnId);
+        const text = events.filter(e => e.type === 'text.delta').map(e => e.data.text).join('') || events.findLast(e => e.type === 'turn.completed')?.data.result;
+        if (['failed', 'closed', 'disconnected'].includes(result.status)) return { kind: 'error', text: text || '原生命令未正常完成，请检查工具状态。' };
+        return { kind: 'success', text: text || (['running', 'waiting', 'connecting'].includes(result.status) ? '原生命令仍在执行，请勿重复提交。' : '原生命令已完成。') };
+      } finally { signal.removeEventListener('abort', abort); }
+    },
+  }));
+}

package/src/harness-selection.mjs

@@ -0,0 +1,5 @@
+/** Read the official durable selection; Agent construction options may be stale. */
+export function harnessSelection(ctx, agent) {
+  const projected = ctx.get?.('sessionProjections')?.stateOf(agent.session, 'modelSelection');
+  return projected?.pending ?? projected?.lastUsed ?? agent.session.requestHeader?.()?.config ?? agent.options;
+}

package/src/harness-usage.mjs

@@ -0,0 +1,31 @@
+const count = value => Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+
+/** Translate reported native counters to Harness's disjoint billing buckets. */
+export function harnessUsage(provider, value = {}, convention) {
+  const input = count(value.inputTokens ?? value.input_tokens ?? value.input);
+  const outputTokens = count(value.outputTokens ?? value.output_tokens ?? value.output);
+  const cacheReadTokens = count(value.cacheReadTokens ?? value.cachedInputTokens ?? value.cache_read_input_tokens ?? value.cacheRead ?? value.cache?.read);
+  const cacheWriteTokens = count(value.cacheWriteTokens ?? value.cache_creation_input_tokens ?? value.cacheWrite ?? value.cache?.write);
+  if (input === undefined || outputTokens === undefined) return undefined;
+  // Codex's prompt includes cached input; its protocol has no cache-write bucket.
+  const inclusive = convention === 'inclusive' || provider === 'codex';
+  if (inclusive && (cacheReadTokens === undefined || cacheReadTokens > input)) return undefined;
+  const inputTokens = inclusive ? input - cacheReadTokens : input;
+  const usage = { inputTokens, outputTokens,
+    ...(cacheReadTokens === undefined ? {} : { cacheReadTokens }),
+    ...(cacheWriteTokens === undefined ? {} : { cacheWriteTokens }),
+  };
+  const reportedTotal = count(value.totalTokens ?? value.total_tokens ?? value.total);
+  if (reportedTotal !== undefined && reportedTotal >= inputTokens + outputTokens + (cacheReadTokens ?? 0) + (cacheWriteTokens ?? 0)) usage.totalTokens = reportedTotal;
+  const reasoningTokens = count(value.reasoningTokens ?? value.reasoningOutputTokens ?? value.reasoning_output_tokens ?? value.reasoning);
+  if (reasoningTokens !== undefined) usage.reasoningTokens = reasoningTokens;
+  return usage;
+}
+
+/** Only one identifiable request can safely occupy one Harness adapter step. */
+export function singleRequestUsage(provider, samples) {
+  if (samples.size !== 1) return undefined;
+  if (String(samples.keys().next().value).startsWith('unidentified:')) return undefined;
+  const sample = samples.values().next().value;
+  return harnessUsage(provider, sample.usage, sample.convention);
+}

package/src/isolated-launch.mjs

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+// SDK history helpers read the parent environment. A separate short-lived
+// process avoids ever changing process.env across concurrent A/B sessions.
+export async function isolatedClaudeHistory(directory, operation, sessionId, cwd) {
+  if (!['info', 'messages', 'list'].includes(operation)) throw new Error('Unsupported isolated history operation');
+  const { stdout } = await promisify(execFile)(process.execPath, [fileURLToPath(import.meta.url), 'claude-history', operation, sessionId || '', cwd], {
+    env: { ...process.env, CLAUDE_CONFIG_DIR: directory }, timeout: 15_000, maxBuffer: 16 * 1024 * 1024, windowsHide: true,
+  });
+  return JSON.parse(stdout);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === 'claude-history') {
+  try {
+    const sdk = await import('@anthropic-ai/claude-agent-sdk');
+    const [, , , operation, sessionId, cwd] = process.argv;
+    const result = operation === 'info' ? await sdk.getSessionInfo(sessionId, { dir: cwd }) : operation === 'messages' ? await sdk.getSessionMessages(sessionId, { dir: cwd }) : operation === 'list' ? await sdk.listSessions({ dir: cwd, limit: 50 }) : null;
+    process.stdout.write(JSON.stringify(result ?? null));
+  } catch { process.stderr.write('Isolated Claude history read failed'); process.exitCode = 1; }
+}

package/src/line-process.mjs

@@ -0,0 +1,114 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+// The child never owns a shell. Framing, request lifetime and process lifetime
+// are shared; product methods belong to the individual provider adapters.
+export class LineProcess extends EventEmitter {
+  constructor(command, args, { cwd, env, dialect = 'jsonrpc', timeout = 30_000 } = {}) {
+    super();
+    this.dialect = dialect;
+    this.timeout = timeout;
+    this.pending = new Map();
+    this.sequence = 0;
+    this.tail = '';
+    this.stderr = '';
+    this.closed = false;
+    this.child = spawn(command, args, {
+      cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true, detached: process.platform !== 'win32',
+    });
+    this.exited = new Promise(resolve => {
+      this.child.once('close', (code, signal) => {
+        this.fail(new Error(`Agent process exited (${code ?? signal})${this.stderr ? `: ${this.stderr.slice(-1500)}` : ''}`));
+        resolve();
+      });
+    });
+    this.child.on('error', error => this.fail(error));
+    this.child.stdin.on('error', error => this.fail(error));
+    this.child.stdout.setEncoding('utf8');
+    this.child.stderr.setEncoding('utf8');
+    this.child.stderr.on('data', chunk => { this.stderr = (this.stderr + chunk).slice(-8192); });
+    this.child.stdout.on('data', chunk => {
+      this.tail += chunk;
+      if (Buffer.byteLength(this.tail) > 16 * 1024 * 1024) {
+        this.fail(new Error('Agent exceeded JSONL frame limit'));
+        void this.close();
+        return;
+      }
+      let end;
+      while ((end = this.tail.indexOf('\n')) !== -1) {
+        const line = this.tail.slice(0, end).trim();
+        this.tail = this.tail.slice(end + 1);
+        if (!line) continue;
+        try { this.receive(JSON.parse(line)); }
+        catch (error) { this.fail(new Error(`Invalid agent protocol: ${error.message}`)); void this.close(); return; }
+      }
+    });
+  }
+
+  receive(message) {
+    const response = this.dialect === 'pi' ? message.type === 'response' : !message.method;
+    const waiter = response && this.pending.get(message.id);
+    if (waiter) {
+      this.pending.delete(message.id);
+      clearTimeout(waiter.timer);
+      const error = message.error || (message.success === false && 'Pi command failed');
+      if (error) waiter.reject(new Error(typeof error === 'string' ? error : error.message ?? JSON.stringify(error)));
+      else waiter.resolve(this.dialect === 'pi' ? message.data : message.result);
+    } else if (this.dialect === 'jsonrpc' && message.method && message.id !== undefined) {
+      this.emit('request', message);
+    } else {
+      this.emit('notification', message);
+    }
+  }
+
+  send(message) {
+    if (this.closed) throw new Error('Agent transport is closed');
+    this.child.stdin.write(JSON.stringify(message) + '\n');
+  }
+
+  request(method, params = {}, timeout = this.timeout) {
+    if (this.closed) return Promise.reject(new Error('Agent transport is closed'));
+    const id = `commander-${++this.sequence}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Agent request timed out: ${method}; execution outcome may be unknown`));
+      }, timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.send(this.dialect === 'pi' ? { ...params, type: method, id } : { jsonrpc: '2.0', id, method, params });
+      } catch (error) {
+        clearTimeout(timer); this.pending.delete(id); reject(error);
+      }
+    });
+  }
+
+  notify(method, params = {}) { this.send({ jsonrpc: '2.0', method, params }); }
+  respond(id, result) { this.send({ jsonrpc: '2.0', id, result }); }
+  reject(id, message) { this.send({ jsonrpc: '2.0', id, error: { code: -32601, message } }); }
+
+  fail(error) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const waiter of this.pending.values()) { clearTimeout(waiter.timer); waiter.reject(error); }
+    this.pending.clear();
+    this.emit('failure', error);
+  }
+
+  kill(signal) {
+    if (!this.child.pid) return;
+    try {
+      if (process.platform === 'win32') this.child.kill(signal);
+      else process.kill(-this.child.pid, signal);
+    } catch (error) { if (error.code !== 'ESRCH') throw error; }
+  }
+
+  async close() {
+    this.fail(new Error('Agent transport closed'));
+    this.child.stdin.end();
+    this.kill('SIGTERM');
+    const timer = setTimeout(() => this.kill('SIGKILL'), 1500);
+    try { await this.exited; } finally { clearTimeout(timer); }
+  }
+}