@coda-console/plugin-check 0.0.0-stage → 0.4.4

package/check/process.mjs

@@ -0,0 +1,87 @@
+// An agent's process as Coda's session host runs it (backend/src/adapters/session-host.mjs): `sh -c` in its own process
+// group, one JSON-RPC message per line on standard input and output. Coda ignores standard error; the checker keeps its
+// tail to say why a process ended. Request IDs are strings, as Coda's are once its host link names them.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import { group } from './leftovers.mjs';
+
+const STDERR_TAIL = 4096;
+
+export class AgentProcess {
+  // `onMessage(message)`: every request and notification the agent sends, in order. `onNoise(line, why)`: a line Coda would drop.
+  constructor({ command, cwd, env, onMessage = () => {}, onNoise = () => {} }) {
+    this.generation = randomBytes(3).toString('hex'); this.next = 0; this.pending = new Map(); this.stderr = '';
+    this.child = spawn('/bin/sh', ['-c', command], { cwd, env, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    // Its process group goes with the checker however that ends.
+    this.ended = group(this.child.pid);
+    this.child.stdin.on('error', () => {});
+    this.child.stderr.on('data', chunk => { this.stderr = (this.stderr + chunk).slice(-STDERR_TAIL); });
+    this.exit = null;
+    this.exited = new Promise(resolve => {
+      this.child.on('error', error => { this.exit ??= { code: null, signal: null, error: error.message }; resolve(this.exit); });
+      this.child.on('exit', (code, signal) => { this.exit ??= { code, signal }; resolve(this.exit); });
+    });
+    // What it wrote before it exited is read first: its output closes after it exits, or soon after when a child of it
+    // holds the pipe.
+    const drained = new Promise(resolve => this.child.on('close', resolve));
+    this.exited.then(() => Promise.race([drained, new Promise(resolve => setTimeout(resolve, 200))])).then(() => {
+      for (const { reject } of this.pending.values()) reject(new Exited(this.exit, this.lastWords()));
+      this.pending.clear();
+    });
+    createInterface({ input: this.child.stdout }).on('line', line => {
+      if (!line.trim()) return;
+      let message;
+      try { message = JSON.parse(line); } catch { onNoise(line, 'not-json'); return; }
+      if (!message || typeof message !== 'object' || Array.isArray(message)) { onNoise(line, 'not-object'); return; }
+      if ('id' in message && !('method' in message)) {
+        const waiter = this.pending.get(message.id);
+        if (waiter) { this.pending.delete(message.id); waiter.resolve(message); }
+        return;
+      }
+      onMessage(message);
+    });
+  }
+  get pid() { return this.child.pid; }
+  write(message) { if (!this.exit && this.child.stdin.writable) this.child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`); }
+  // The agent's whole answer, `{ result }` or `{ error }`; rejected with Timeout or Exited. `onReply` runs as the answer is
+  // read, before the next line is: what the agent says after it comes after it.
+  request(method, params, { timeout, id = `${this.generation}-${this.next++}`, onReply } = {}) {
+    return new Promise((resolve, reject) => {
+      let timer;
+      this.pending.set(id, { resolve: m => { clearTimeout(timer); onReply?.(m); resolve(m); }, reject: e => { clearTimeout(timer); reject(e); } });
+      if (timeout) timer = setTimeout(() => { this.pending.delete(id); reject(new Timeout(method, timeout)); }, timeout);
+      if (this.exit) { this.pending.delete(id); clearTimeout(timer); reject(new Exited(this.exit, this.lastWords())); return; }
+      this.write({ id, method, params });
+    });
+  }
+  notify(method, params) { this.write({ method, params }); }
+  respond(id, result) { this.write({ id, result }); }
+  respondError(id, code, message) { this.write({ id, error: { code, message } }); }
+  // Resolves to how long it took to exit after `start`, or null past `limit`.
+  async exitWithin(limit, start = Date.now()) {
+    let timer;
+    const done = await Promise.race([this.exited, new Promise(resolve => { timer = setTimeout(resolve, limit, null); })]);
+    clearTimeout(timer);
+    return done ? Date.now() - start : null;
+  }
+  // Closes its standard input; how long it took to exit, or null past `limit`.
+  closeInput(limit) { this.child.stdin.end(); return this.exitWithin(limit); }
+  // What Coda's session host does to stop it (adapters/session-host.mjs): SIGTERM to its process group. How long it took to
+  // exit, or null past `limit`.
+  terminate(limit) { this.signal('SIGTERM'); return this.exitWithin(limit); }
+  signal(name) { try { process.kill(-this.child.pid, name); } catch {} }
+  // Whatever is left of its process group goes, as Coda's host makes sure.
+  kill() { this.signal('SIGKILL'); this.ended(); }
+  lastWords() { return this.stderr.split('\n').map(l => l.trim()).filter(Boolean).at(-1)?.slice(0, 300) ?? ''; }
+}
+
+export class Timeout extends Error {
+  constructor(method, ms) { super(`${method} ${ms / 1000} 秒没有答复`); this.ms = ms; }
+}
+export class Exited extends Error {
+  constructor(exit, words) {
+    super(`进程退出了（${exit.error ?? (exit.signal ? `信号 ${exit.signal}` : `退出码 ${exit.code}`)}）${words ? `：${words}` : ''}`);
+    this.exit = exit;
+  }
+}

package/check/report.mjs

@@ -0,0 +1,29 @@
+// What a check found, in the order found: each line a level (清单, 握手, 一轮), what it is about (the plugin, an agent, a panel),
+// whether it passed, failed, was skipped or is worth a look (warn, info), a rule ID the tests name, and a line of Chinese.
+export const LEVELS = { manifest: '清单', handshake: '握手', live: '一轮' };
+const MARKS = { pass: '✓', fail: '✗', warn: '!', skip: '-', info: '·' };
+
+export class Report {
+  constructor() { this.items = []; }
+  scope(level, subject = '') {
+    const add = status => (rule, message) => { this.items.push({ level, subject, status, rule, message }); };
+    return { pass: add('pass'), fail: add('fail'), warn: add('warn'), skip: add('skip'), info: add('info') };
+  }
+  get failures() { return this.items.filter(item => item.status === 'fail'); }
+  get ok() { return this.failures.length === 0; }
+  count(status) { return this.items.filter(item => item.status === status).length; }
+}
+
+// Grouped by level, then by subject in the order first met; within a group, in the order found.
+export function format(report, { title }) {
+  const lines = [title], order = Object.keys(LEVELS), subjects = [...new Set(report.items.map(item => item.subject))];
+  const rank = item => order.indexOf(item.level) * subjects.length + subjects.indexOf(item.subject);
+  let heading = null;
+  for (const item of report.items.toSorted((a, b) => rank(a) - rank(b))) {
+    const at = `${LEVELS[item.level]}${item.subject ? ` · ${item.subject}` : ''}`;
+    if (at !== heading) { lines.push('', at); heading = at; }
+    lines.push(`  ${MARKS[item.status]} ${item.message}`);
+  }
+  lines.push('', `结果：${report.ok ? '通过' : '不通过'}（通过 ${report.count('pass')}，失败 ${report.count('fail')}，跳过 ${report.count('skip')}，提醒 ${report.count('warn')}）`);
+  return lines.join('\n');
+}

package/check/schema.mjs

@@ -0,0 +1,18 @@
+// ACP's own parsers, from the SDK version Coda pins (package.json). They are its generated zod schemas, which the SDK does
+// not export by name: read from the file next to its entry point.
+const sdk = import.meta.resolve('@agentclientprotocol/sdk');
+export const schemas = await import(new URL('./schema/zod.gen.js', sdk));
+
+// One line on why a value does not parse. A union (a session update is one of many kinds) names the branch it meant: the
+// one whose `sessionUpdate` matched.
+export function explain(error, value) {
+  let issue = error.issues[0], path = [];
+  while (issue?.code === 'invalid_union' && issue.errors?.length) {
+    path = [...path, ...issue.path];
+    const matched = issue.errors.filter(branch => !branch.some(i => i.path.at(-1) === 'sessionUpdate'));
+    if (!matched.length && path.at(-1) === 'update') return `update.sessionUpdate 不是 ACP 认识的类型：${JSON.stringify(value?.update?.sessionUpdate)}`;
+    const best = (matched.length ? matched : issue.errors).reduce((a, b) => b.length < a.length ? b : a);
+    issue = best[0];
+  }
+  return `${[...path, ...(issue?.path ?? [])].join('.') || '（整体）'}：${issue?.message ?? '不合 schema'}`;
+}

package/check/waits.mjs

@@ -0,0 +1,58 @@
+// `_coda/wait` as Coda takes it: validWait first (check/coda.mjs, copied), then the rules of docs/agent-protocol.md
+// 「Agent 活动」. Where Coda drops a report without a word, the checker fails it: an agent that relies on it is not heard.
+import { validWait, WAIT_STATES } from './coda.mjs';
+
+export const TERMINAL = new Set(['done', 'failed', 'cancelled']);
+const LIMITS = { sessionId: 200, waitId: 200, kind: 50, title: 500, detail: 4000, childSessionId: 200, model: 200, outputFile: 4096, toolCallId: 200 };
+
+// The first part of validWait a report fails, in words.
+export function whyInvalid(p) {
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return 'params 须为对象';
+  for (const key of ['sessionId', 'waitId']) if (typeof p[key] !== 'string' || !p[key]) return `缺 ${key}`;
+  if (!WAIT_STATES.has(p.state)) return `state 只能是 ${[...WAIT_STATES].join('、')}，现为 ${JSON.stringify(p.state)}`;
+  for (const [key, max] of Object.entries(LIMITS)) if (p[key] !== undefined && (typeof p[key] !== 'string' || p[key].length > max)) return `${key} 须为不超过 ${max} 字的文本`;
+  for (const key of ['stoppable', 'recurring']) if (p[key] !== undefined && typeof p[key] !== 'boolean') return `${key} 须为 true 或 false`;
+  if (p.at !== undefined && !(typeof p.at === 'string' && Number.isFinite(Date.parse(p.at)))) return `at 读不出时间：${JSON.stringify(p.at)}`;
+  return '不合 validWait';
+}
+
+export class Waits {
+  constructor(say) {
+    this.say = say; this.sessionId = null; this.children = new Set(); this.waits = new Map();
+    this.registered = []; this.changes = 0;
+  }
+  owns(id) { return id === this.sessionId || this.children.has(id); }
+  get open() { return [...this.waits.values()].filter(w => !TERMINAL.has(w.state)); }
+  get handling() { return this.open.filter(w => w.state === 'handling'); }
+  // One report, in order with the session's updates; `turn`: whether a turn of Coda's was under way as it came.
+  take(p, { turn }) {
+    if (!validWait(p)) { this.say.fail('wait.invalid', `_coda/wait 被 Coda 丢弃：${whyInvalid(p)}（${(JSON.stringify(p) ?? String(p)).slice(0, 160)}）`); return; }
+    if (!this.owns(p.sessionId)) { this.say.fail('wait.session', `_coda/wait 说的会话 ${p.sessionId} 不是本会话，也不是登记过的子会话：Coda 丢弃`); return; }
+    const key = `${p.sessionId}\0${p.waitId}`, known = this.waits.get(key);
+    if (known && TERMINAL.has(known.state)) {
+      this.say.fail('wait.after-terminal', `活动 ${p.waitId} 已经 ${known.state}，之后又报 ${p.state}：终态是最终的，同一个 waitId 再说什么都不算`);
+      return;
+    }
+    this.changes++;
+    if (!known) {
+      const kind = p.kind ?? 'task';
+      if (TERMINAL.has(p.state)) {
+        this.say.warn('wait.first-terminal', `活动 ${p.waitId} 第一次报告就是 ${p.state}：Coda 不登记它`);
+        this.waits.set(key, { waitId: p.waitId, kind, state: p.state });
+        return;
+      }
+      // Coda takes both as they are: a subagent whose session it is not told shows no transcript of its own, a timer without
+      // `at` no time (Coda's own Claude entry leaves it out when it cannot work out the next run).
+      if (kind === 'subagent' && !p.childSessionId) this.say.warn('wait.subagent-child', `子 Agent ${p.waitId} 没带 childSessionId：Coda 照收，但认不出它的会话：那个会话说的话与报的活动丢弃，审批与提问拒绝，委派清单里点开没有过程，也不能继续同一个子 Agent`);
+      if (kind === 'timer' && p.at === undefined) this.say.warn('wait.timer-at', `定时 ${p.waitId} 没带 at（下次触发的时刻）：Coda 照收，只是显示不出下次时间`);
+      const wait = { waitId: p.waitId, sessionId: p.sessionId, kind, state: p.state, title: p.title, stoppable: p.stoppable === true, inTurn: turn };
+      this.waits.set(key, wait);
+      this.registered.push(wait);
+    } else {
+      if (p.kind !== undefined && p.kind !== known.kind) this.say.warn('wait.kind-changed', `活动 ${p.waitId} 的 kind 从 ${known.kind} 改成 ${p.kind}：Coda 按第一次的算`);
+      known.state = p.state;
+      if (p.stoppable !== undefined) known.stoppable = p.stoppable;
+    }
+    if (p.childSessionId) this.children.add(p.childSessionId);
+  }
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@coda-console/plugin-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.4",
+  "description": "Coda 插件的契约检查：扮演 Coda 读清单、启动 Agent 讲 ACP 与 _coda/wait、读面板。",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coda-console/coda-plugins.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "coda-plugin-check": "bin/check.mjs"
+  },
+  "files": [
+    "bin",
+    "check"
+  ],
+  "scripts": {
+    "test": "node --test 'test/**/*.test.mjs'"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}