@coda-console/plugin-check 0.4.9 → 0.5.1

package/check/coda/domain/agent-protocol.mjs

@@ -0,0 +1,45 @@
+// What Coda says to an agent and takes from it beside the connection itself (docs/agent-protocol.md): the capabilities it
+// sends, session instructions, steering, the agent's own waits, and how long Coda waits on it. Part of the plugin contract
+// coda-plugins' check is given as written (scripts/plugin-contract.mjs).
+
+// `initialize` as Coda sends it.
+export const clientCapabilities = () => ({
+  elicitation: { form: {}, url: {} },
+  // A config option may be a switch: shown as one, its value on or off (`options`).
+  session: { compaction: {}, configOptions: { boolean: {} } },
+  // Coda takes the agent's own waits.
+  _meta: { coda: { waits: {} } },
+});
+// The agent refuses until it is signed in (ACP's auth_required).
+export const SIGNED_OUT = -32000;
+// Session instructions (「会话指令」): ACP's `systemPrompt`, only to an agent that declares it, the same on every open of
+// the session, appended in one text block.
+export const takesInstructions = init => init?.agentCapabilities?.sessionCapabilities?.systemPrompt != null;
+export const systemPrompt = text => ({ mode: 'append', content: [{ type: 'text', text }] });
+// Steering (「插话」): declared beside the capabilities, as the extension has it, and sent only while a turn is under way.
+// The agent answers `STEERED` when the message joined the running turn and `NOT_STEERED` when the turn had ended; anything
+// else leaves the message of unknown fate.
+export const STEERING = '_session/steering';
+export const STEERED = 'injected', NOT_STEERED = 'promptRequired';
+export const supportsSteering = init => init?._meta?.steering?.supported === true;
+export const steeringParams = (sessionId, text) => ({ sessionId, prompt: [{ type: 'text', text }], _meta: { steering: { idleBehavior: NOT_STEERED } } });
+// The model a session runs with: its model option's value, else what ACP's older `models` names.
+export const currentModel = session => session?.configOptions?.find?.(x => x?.category === 'model')?.currentValue ?? session?.models?.currentModelId;
+
+// What an agent may say of a wait of its own (「_coda/wait」); anything else is dropped unread.
+const record = value => value && typeof value === 'object' && !Array.isArray(value);
+export const WAIT_STATES = new Set(['waiting', 'handling', 'done', 'failed', 'cancelled']);
+const fits = (value, limit) => value === undefined || (typeof value === 'string' && value.length <= limit);
+export const validWait = p => record(p) && typeof p.sessionId === 'string' && p.sessionId.length > 0 && p.sessionId.length <= 200
+  && typeof p.waitId === 'string' && p.waitId.length > 0 && p.waitId.length <= 200 && WAIT_STATES.has(p.state)
+  && fits(p.kind, 50) && fits(p.title, 500) && fits(p.detail, 4000) && fits(p.childSessionId, 200) && fits(p.model, 200) && fits(p.outputFile, 4096)
+  && fits(p.toolCallId, 200)
+  && [p.stoppable, p.recurring].every(flag => flag === undefined || typeof flag === 'boolean')
+  && (p.at === undefined || (typeof p.at === 'string' && Number.isFinite(Date.parse(p.at))));
+
+// Opening a session (initialize, then session/new or session/load) may take this long.
+export const OPEN_LIMIT = 60_000;
+// A turn the user stops ends within this, or Coda closes the agent's process group (「Agent 活动」).
+export const STOP_LIMIT = 30_000;
+// Coda stops an agent with SIGTERM to its process group, and SIGKILL this long after.
+export const TERM_GRACE = 800;

package/check/coda/domain/duration.mjs

@@ -0,0 +1,11 @@
+// ISO 8601 durations (`P30D`, `PT6H`), as JSON Schema's `format: duration` is and bpmn-engine reads its timers
+// (@0dep/piso): what plugin settings, panels and workflows all write a length of time in.
+import { parseDuration } from '@0dep/piso';
+
+// A duration, not negative.
+export function isDuration(text) {
+  if (typeof text !== 'string' || !text || text.length > 200) return false;
+  try { return parseDuration(text).result.sign !== -1; } catch { return false; }
+}
+// How long a duration is, counted back from `at` (a month is the one before it).
+export const durationMs = (text, at = Date.now()) => at - parseDuration(text).getStartAt(new Date(at)).getTime();

package/check/coda/domain/errors.mjs

@@ -0,0 +1,11 @@
+export class ContractError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ContractError';
+    this.code = code;
+  }
+}
+
+export function requireCondition(condition, code, message) {
+  if (!condition) throw new ContractError(code, message);
+}

package/check/coda/domain/values.mjs

@@ -0,0 +1,39 @@
+// Shapes every layer checks what it is given against, and the stable serialization requests are compared by.
+import { isAbsolute, normalize } from 'node:path';
+import { requireCondition as check } from './errors.mjs';
+
+// An agent's ID, as sessions, shortcuts, settings and the plugins declaring agents write it.
+export const AGENT_ID = /^[a-z][a-z0-9-]{0,39}$/;
+
+export function object(value, name) {
+  check(value && typeof value === 'object' && !Array.isArray(value), 'invalid_input', `${name} 必须是对象`);
+  return value;
+}
+
+export function text(value, name, max = 200) {
+  check(typeof value === 'string' && value.trim().length > 0 && value.length <= max && !value.includes('\0'),
+    'invalid_input', `${name} 为空或格式无效`);
+  return value;
+}
+
+export function keys(value, allowed) {
+  check(Object.keys(value).every(key => allowed.includes(key)), 'invalid_input', '包含不支持的字段');
+}
+
+// Stable serialization is only for semantic request equality, never shell quoting.
+export function canonical(value) {
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+  }
+  const encoded = JSON.stringify(value);
+  check(encoded !== undefined, 'invalid_input', '数据必须可以编码为 JSON');
+  return encoded;
+}
+
+// A path the user gave, as an absolute one.
+export function absolutePath(value) {
+  text(value, '路径', 4096);
+  check(isAbsolute(value), 'invalid_input', '需要绝对路径');
+  return normalize(value);
+}

package/check/coda/kernel/agent-failures.mjs

@@ -0,0 +1,16 @@
+const record = value => value && typeof value === 'object' && !Array.isArray(value);
+
+// Only the shared protocol establishes a category; provider codes and error text stay with the plugin.
+export function agentFailure(error) {
+  const failure = error?.data?._meta?.coda?.failure;
+  if (!record(failure)) return null;
+  return failure.kind === 'quota_exhausted' ||
+    (failure.kind === 'service_unavailable' && ['accepted', 'not_accepted'].includes(failure.input)) ? failure : null;
+}
+
+export function agentErrorMessage(error) {
+  const message = typeof error?.message === 'string' && error.message ? error.message : 'Agent 返回错误';
+  const detail = typeof error?.data?.message === 'string' ? error.data.message.trim() : '';
+  const text = detail && !message.includes(detail) ? `${message}\n\n${detail}` : message;
+  return agentFailure(error)?.kind === 'quota_exhausted' && !text.startsWith('额度不足') ? `额度不足\n\n${text}` : text;
+}

package/check/coda/resources/plugins/resources/panels/command.mjs

@@ -0,0 +1,46 @@
+// A panel's command run once to its end (a reading, an action): `sh -c` in its own process group, its standard output kept
+// apart from what it says on standard error, both bounded. Past its deadline the group is asked to stop, and made to two
+// seconds later; once `signal` aborts (the module closing) it is made to at once.
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const ansi = /\x1b\[[0-9;]*[A-Za-z]/g;
+// The last thing a failed command said, for the one line the user sees.
+export const lastLine = text => text.replace(ansi, '').split('\n').map(line => line.trim()).filter(Boolean).at(-1)?.slice(0, 200) ?? '';
+
+export function runCommand(command, { env, timeoutMs, signal: aborted, maxBytes = 64 * 1024 }) {
+  return new Promise(resolve => {
+    const child = spawn('/bin/sh', ['-c', command], { cwd: tmpdir(), env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const out = [], err = [];
+    let sizes = [0, 0], overflow = false, timedOut = false, finished = false, hard = null;
+    const signal = name => { try { process.kill(-child.pid, name); } catch {} };
+    const stop = () => { signal('SIGTERM'); hard = setTimeout(() => signal('SIGKILL'), 2000); };
+    const due = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+    const abort = () => { if (!finished) signal('SIGKILL'); };
+    aborted?.addEventListener('abort', abort, { once: true });
+    const keep = (chunks, i) => chunk => {
+      if (sizes[i] + chunk.length > maxBytes) { if (i === 0 && !overflow) { overflow = true; stop(); } return; }
+      sizes[i] += chunk.length; chunks.push(chunk);
+    };
+    child.stdout.on('data', keep(out, 0));
+    child.stderr.on('data', keep(err, 1));
+    const finish = (code, error) => {
+      if (finished) return;
+      finished = true; clearTimeout(due); clearTimeout(hard); aborted?.removeEventListener('abort', abort);
+      // Whatever it left behind in its group goes with it.
+      if (child.pid) signal('SIGKILL');
+      resolve({ code, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'), timedOut, overflow, ...(error ? { error } : {}) });
+    };
+    child.on('error', error => finish(null, error.message));
+    child.on('close', code => finish(code));
+  });
+}
+// A command ended well: by itself, with 0. One stopped for its deadline or its output may still say 0 on the way out.
+export const ended = result => result.code === 0 && !result.timedOut && !result.overflow;
+// Why a command did not end well, in one line.
+export function outcome(result, what) {
+  if (result.timedOut) return `${what}超时`;
+  if (result.overflow) return '输出过长';
+  if (result.error) return `${what}没有开始：${result.error}`;
+  return lastLine(result.stderr) || lastLine(result.stdout) || `${what}没有完成（退出码 ${result.code ?? '无'}）`;
+}

package/check/coda/resources/plugins/resources/panels/panels.mjs

@@ -0,0 +1,225 @@
+// The panels installed plugins bring to this machine's resources page (docs/plugins.md「面板」), read and acted on here, in
+// the resources plugin's module: what each plugin declares comes from Coda's collection of the installed plugins
+// (`coda.watch("plugins")`), and each command runs with that plugin's own environment (`coda.environment(null, { plugin })`),
+// as Coda gives every process of the plugin's. A panel is read only when a page asks (opening it, refreshing), never in
+// the background, and no reading is kept on disk. What every panel gets from here and not from its plugin: one reading
+// at a time (a second ask joins it), the last good reading shown again within the panel's `maxAge` and listed with the
+// panel, and on failure the last good one kept and marked as such. The machine keeps the panels it hides, in this
+// plugin's state; their order is their plugins' (docs/resources-page.md「顺序」).
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCommand, ended, outcome } from './command.mjs';
+import { PanelError, panelEntries, panelItems, actionArgs, shownItems, displayOptions, keepMissingMetrics } from './rules.mjs';
+import { SignIn, authorizationLink, deviceCode } from './sign-in.mjs';
+
+const fail = (code, message) => { throw new PanelError(code, message); };
+
+export class Panels {
+  // `onChange(key)`: a panel moved (its reading, its login, whether it is hidden); none for the list as a whole.
+  // `run`: how a command runs (panels/command.mjs runCommand); `now()`: the time, as readings are dated by it.
+  constructor(coda, { run = runCommand, now = Date.now, readTimeoutMs = 30_000, actionTimeoutMs = 10 * 60_000 } = {}) {
+    this.coda = coda; this.run = run; this.now = now; this.readTimeoutMs = readTimeoutMs; this.actionTimeoutMs = actionTimeoutMs;
+    // `last`: each panel's last good items, for a failed reading to show again; `shown`: what its last reading answered.
+    this.plugins = new Map(); this.last = new Map(); this.shown = new Map(); this.reading = new Map(); this.acting = new Map(); this.failures = new Map();
+    this.logins = new Map(); this.envs = new Map(); this.listeners = new Set(); this.closing = new AbortController();
+    this.file = join(coda.plugin.state ?? tmpdir(), 'hidden.json');
+    this.hides = Promise.resolve();
+  }
+  listen(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+  // Nothing is told before the plugins' environments are there (`ready`): what a login says of whether its program is
+  // installed is checked with its plugin's own.
+  changed(key = null) { if (this.ready) for (const fn of this.listeners) try { fn(key); } catch {} }
+  // Once: the installed plugins watched, what this machine hides, and the environment of each plugin whose panels sign in.
+  start() {
+    this.started ??= (async () => {
+      this.hidden = this.readHidden();
+      const watched = await this.coda.watch('plugins', ({ type, id, object }) => {
+        if (type === 'DELETED') this.plugins.delete(id); else this.plugins.set(id, object);
+        // Another version (another directory, another environment): what was checked with the last is checked again.
+        this.envs.delete(id);
+        for (const [key, login] of this.logins) if (key.startsWith(`${id}/`)) login.recheck();
+        // A login of a panel gone (its plugin removed, or a version without it) goes with it.
+        const keys = new Set(this.installed().map(e => e.key));
+        for (const [key, login] of this.logins) if (!keys.has(key)) { login.close(); this.logins.delete(key); }
+        if (this.ready) this.prepare().then(() => this.changed());
+      });
+      this.unwatch = () => watched.dispose();
+      await this.prepare();
+      this.ready = true;
+    })();
+    return this.started;
+  }
+  // What the machine hides, as it was kept: none when nothing is, or what is cannot be read.
+  readHidden() {
+    try { return new Set(JSON.parse(readFileSync(this.file, 'utf8'))); } catch { return new Set(); }
+  }
+  keepHidden(hidden) {
+    const next = `${this.file}.next`;
+    writeFileSync(next, JSON.stringify([...hidden].sort()));
+    renameSync(next, this.file);
+  }
+  // The installed plugins' panels, by plugin id, each plugin's in the order it declares them. A project disabling a plugin
+  // does not take its panels away: the page is the machine's, not a project's. One Coda cannot read is kept with why.
+  installed() {
+    return [...this.plugins.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).flatMap(plugin =>
+      panelEntries(plugin.contributes?.panels, plugin.name).map(entry => {
+        const panel = entry.panel ?? { id: entry.invalid.id, title: entry.invalid.title, actions: {} };
+        return { plugin, panel, key: `${plugin.id}/${panel.id}`, ...(entry.invalid ? { invalid: entry.invalid.error } : {}) };
+      }));
+  }
+  find(key) {
+    return this.installed().find(e => e.key === key) ?? fail('not_found', `没有面板 ${key}`);
+  }
+  // Before a list is shown: the environment of each plugin whose panels sign in, for whether what they sign in to is there.
+  async prepare() {
+    const plugins = new Set(this.installed().filter(e => e.panel.signIn && !this.envs.has(e.plugin.id)).map(e => e.plugin.id));
+    await Promise.all([...plugins].map(id => this.env(id).catch(() => {})));
+  }
+  // What a page shows of a panel: what it is, whether the machine hides it, what was last read and how that stands now.
+  view(entry, index) {
+    const { plugin, panel, key } = entry, shown = this.shown.get(key);
+    return { plugin: plugin.id, pluginName: plugin.name, panel: panel.id, title: panel.title, version: plugin.version ?? '', source: plugin.source ?? { kind: 'builtin' },
+      actions: Object.fromEntries(Object.entries(panel.actions ?? {}).map(([name, a]) => [name, a.confirm ? { confirm: a.confirm } : {}])),
+      configurable: !!panel.displaySetting, signsIn: !!panel.signIn, hidden: this.hidden.has(key), index,
+      signIn: panel.signIn ? this.login(entry).view() : null,
+      reading: shown ? this.present(entry, shown) : null,
+      busy: this.reading.has(key), failure: entry.invalid ? `声明无效：${entry.invalid}` : this.failures.get(key) ?? null,
+      acting: this.acting.get(key)?.button ?? null, actionError: this.acting.get(key)?.error ?? null };
+  }
+  list() { return this.installed().map((entry, index) => [entry.key, this.view(entry, index)]); }
+  // One panel's, as `list` has it; none for one no longer installed.
+  viewOf(key) {
+    const listed = this.installed(), index = listed.findIndex(e => e.key === key);
+    return index < 0 ? null : this.view(listed[index], index);
+  }
+  // The plugin's environment, as Coda gives every process of it, read again for each command: what it holds (its
+  // settings, the concurrency groups now) is of the moment.
+  async env(plugin, extra = {}) {
+    const env = { ...(await this.coda.environment(null, { plugin })), ...extra };
+    this.envs.set(plugin, env);
+    return env;
+  }
+  settingsOf(plugin) {
+    try { return JSON.parse(this.envs.get(plugin)?.CODA_PLUGIN_SETTINGS ?? '{}'); } catch { return {}; }
+  }
+  present({ plugin, panel }, reading) {
+    if (!panel.displaySetting) return reading;
+    const values = this.settingsOf(plugin.id)[panel.displaySetting] ?? {};
+    return { ...reading, items: shownItems(reading.items, values), display: { setting: panel.displaySetting, options: displayOptions(reading.items, values) } };
+  }
+  // `{ items, readAt }`, or with `error` when this reading failed: then the last good items with `stale`, or none.
+  read(key, { force = false } = {}) {
+    const entry = this.find(key);
+    if (entry.invalid) return Promise.resolve({ items: [], error: `声明无效：${entry.invalid}` });
+    const pending = this.reading.get(key);
+    if (pending) return pending;
+    const last = this.last.get(key);
+    if (!force && last && entry.panel.maxAgeMs && this.now() - last.at < entry.panel.maxAgeMs && !this.shown.get(key)?.error) return Promise.resolve(this.present(entry, { items: last.items, readAt: last.at }));
+    const reading = this.fetch(entry).finally(() => { this.reading.delete(key); this.changed(key); });
+    this.reading.set(key, reading);
+    this.changed(key);
+    return reading;
+  }
+  async fetch(entry) {
+    const { plugin, panel, key } = entry;
+    let failure;
+    try {
+      const result = await this.run(panel.command, { env: await this.env(plugin.id), timeoutMs: this.readTimeoutMs, signal: this.closing.signal });
+      if (ended(result)) {
+        const parsed = panelItems(result.stdout, panel, plugin.views ?? []), at = this.now();
+        const items = panel.displaySetting ? keepMissingMetrics(parsed, this.last.get(key)?.items ?? []) : parsed;
+        this.last.set(key, { items, at }); this.failures.delete(key);
+        this.shown.set(key, { items, readAt: at });
+        return this.present(entry, { items, readAt: at });
+      }
+      failure = outcome(result, '读取');
+    } catch (e) {
+      if (!(e instanceof PanelError)) { this.failures.set(key, e.message); throw e; }
+      failure = `输出无效：${e.message}`;
+    }
+    const last = this.last.get(key);
+    const reading = last ? { items: last.items, readAt: last.at, stale: true, error: failure } : { items: [], error: failure };
+    this.shown.set(key, reading);
+    return this.present(entry, reading);
+  }
+  // Runs one of a panel's actions with what its button sent, then reads the panel again. One action of a panel at a time;
+  // one under way goes on to its end even when whoever asked has gone.
+  async act(key, name, args, button = name) {
+    const entry = this.find(key), { plugin, panel } = entry;
+    if (this.acting.get(key)?.button) fail('panel_busy', `${panel.title} 正在进行另一项操作`);
+    // What went wrong is said under the panel, whatever it was.
+    try {
+      const action = panel.actions?.[name] ?? fail('not_found', `面板 ${panel.title} 没有动作 ${name}`);
+      const given = actionArgs(args);
+      this.acting.set(key, { button }); this.changed(key);
+      const result = await this.run(action.command, { env: await this.env(plugin.id, { CODA_PANEL_ARGS: JSON.stringify(given) }),
+        timeoutMs: this.actionTimeoutMs, signal: this.closing.signal });
+      if (!ended(result)) fail('action_failed', outcome(result, '操作'));
+      this.acting.delete(key);
+    } catch (e) {
+      this.acting.set(key, { error: e.message }); this.changed(key);
+      throw e;
+    }
+    // A reading that began before the action ended may not show what it did.
+    await this.reading.get(key);
+    return this.read(key, { force: true });
+  }
+  // One panel hidden or shown again on this machine, the others as they were: one change at a time.
+  hide(key, hidden) {
+    const change = this.hides.then(() => {
+      const next = new Set(this.hidden);
+      if (hidden) next.add(key); else next.delete(key);
+      this.keepHidden(next);
+      this.hidden = next;
+      this.changed(key);
+    });
+    this.hides = change.catch(() => {});
+    return change;
+  }
+  // A panel's login from Coda (docs/plugins.md「面板的登录」), one per panel at a time. Signed in, the panel is read anew;
+  // its CLI installed, the plugin's setup is run again (docs/plugins.md「准备运行环境」), which done well has Coda read its
+  // agents again: what they offer may be readable now.
+  login(entry) {
+    const { plugin, panel, key } = entry, known = this.logins.get(key);
+    const declared = panel.signIn ?? fail('not_found', `${panel.title} 不能从 Coda 登录`);
+    if (known?.declared === JSON.stringify(declared)) return known;
+    known?.close();
+    const env = () => this.envs.get(plugin.id) ?? process.env;
+    // Whether it is there: a quick check with the plugin's own environment, asked again after a moment at most. Without
+    // one, it always is; without the environment yet, it is not checked, and nothing is kept of it.
+    let checkedAt = 0, there = false;
+    const installed = (fresh = false) => {
+      if (!declared.installed) return true;
+      const given = this.envs.get(plugin.id);
+      if (!given) return false;
+      if (fresh || Date.now() - checkedAt > 2000) { there = spawnSync('/bin/sh', ['-c', declared.installed], { cwd: tmpdir(), env: given, stdio: 'ignore', timeout: 2000 }).status === 0; checkedAt = Date.now(); }
+      return there;
+    };
+    const login = new SignIn({ provider: key, name: panel.title, command: declared.command, installed, install: declared.install ?? null,
+      readCode: declared.input ? authorizationLink : deviceCode, input: !!declared.input, note: declared.note ?? null },
+    { env, onChange: () => this.changed(key),
+      onSignedIn: () => { this.read(key, { force: true }).catch(() => {}); },
+      onInstalled: () => { checkedAt = 0; this.coda.api(`plugins/${encodeURIComponent(plugin.id)}/setup`, {}).catch(() => {}); } });
+    login.declared = JSON.stringify(declared);
+    login.recheck = () => { checkedAt = 0; };
+    this.logins.set(key, login);
+    return login;
+  }
+  async signIn(key, what, body = {}) {
+    const entry = this.find(key);
+    // The command runs with the plugin's environment as it is now.
+    await this.env(entry.plugin.id);
+    const login = this.login(entry);
+    switch (what) {
+      case 'signIn': return login.start();
+      case 'install': return login.install();
+      case 'cancelSignIn': return login.cancel();
+      case 'submitSignIn': return login.submit(body);
+      default: return login.view();
+    }
+  }
+  // The module going (the plugin host stopping): what runs in a process group of its own is made to end, as nothing would later.
+  close() { this.closing.abort(); this.unwatch?.(); for (const login of this.logins.values()) login.close('SIGKILL'); }
+}

package/check/coda/resources/plugins/resources/panels/rules.mjs

@@ -0,0 +1,242 @@
+// What a panel is (docs/plugins.md「面板」): how a plugin declares one (`contributes.panels`) and what its command may
+// print, checked here, where the panels are read, the way a task's card is drawn from its fields. Nothing here knows what
+// a panel is about: CPU, an account's quota and a disk are all meters and figures.
+
+// What is not as it must be: the panel says so where it would show.
+export class PanelError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+function check(condition, code, message) {
+  if (!condition) throw new PanelError(code, message);
+  return condition;
+}
+// An ISO 8601 duration as panels write their `maxAge` (`PT5M`, `P1D`): weeks, days and time, not years or months.
+const DURATION = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+export function isDuration(text) {
+  const m = typeof text === 'string' && text.length <= 200 && DURATION.exec(text);
+  return !!m && text !== 'P' && !text.endsWith('T');
+}
+export function durationMs(text) {
+  const [, w = 0, d = 0, h = 0, min = 0, s = 0] = DURATION.exec(text);
+  return ((((+w * 7 + +d) * 24 + +h) * 60 + +min) * 60 + +s) * 1000;
+}
+
+const NAME = /^[a-z][a-z0-9-]{0,63}$/;
+export const ITEM_TYPES = ['card', 'meter', 'stat', 'markdown', 'button', 'error'];
+// What a panel's command may print: past these, the reading fails rather than being cut short.
+export const OUTPUT_LIMIT = 64 * 1024;
+export const ARGS_LIMIT = 4 * 1024;
+const ITEMS = 50, CARD_ITEMS = 20, TITLE = 40, LABEL = 80, IDENTITY = 200, MARKDOWN = 4000, ERROR = 500, CONFIRM = 200;
+const fail = (code, message) => check(false, code, message);
+const keys = (value, allowed, where, code) => {
+  const extra = Object.keys(value).filter(k => !allowed.includes(k));
+  check(!extra.length, code, `${where} 里有 Coda 不支持的键：${extra.join('、')}`);
+};
+const text = (value, max, where, code, { need = true, line = true } = {}) => {
+  if (value === undefined && !need) return undefined;
+  check(typeof value === 'string' && value.trim() && [...value].length <= max && !value.includes('\0') && (!line || !/[\r\n]/.test(value)), code,
+    `${where} 须为不超过 ${max} 字的${line ? '一行' : ''}文本`);
+  return value;
+};
+const object = (value, where, code) => check(value && typeof value === 'object' && !Array.isArray(value), code, `${where} 须为对象`);
+
+// ---- Declarations (`contributes.panels`) ----
+// One panel as the plugin declares it: what it is called, the command that reads it, how long a reading may be shown
+// again without asking, the actions its buttons may take, each a command of its own with what to ask first, and how to
+// sign in to what it shows from Coda.
+function declaration(raw, where) {
+  const code = 'invalid_plugin';
+  object(raw, where, code);
+  keys(raw, ['id', 'title', 'command', 'maxAge', 'actions', 'signIn', 'displaySetting'], where, code);
+  check(typeof raw.id === 'string' && NAME.test(raw.id), code, `${where} 的 id 只能用小写字母、数字和「-」，以字母开头`);
+  const at = `面板 ${raw.id}`;
+  check(raw.maxAge === undefined || (typeof raw.maxAge === 'string' && isDuration(raw.maxAge)), code, `${at} 的 maxAge 须为 ISO 8601 时长，如 PT5M`);
+  const actions = {};
+  if (raw.actions !== undefined) {
+    object(raw.actions, `${at} 的 actions`, code);
+    for (const [name, action] of Object.entries(raw.actions)) {
+      check(NAME.test(name), code, `${at} 的动作名只能用小写字母、数字和「-」，以字母开头：${name}`);
+      object(action, `${at} 的动作 ${name}`, code);
+      keys(action, ['command', 'confirm'], `${at} 的动作 ${name}`, code);
+      actions[name] = { command: text(action.command, 4000, `${at} 的动作 ${name} 的 command`, code),
+        ...(action.confirm !== undefined ? { confirm: text(action.confirm, CONFIRM, `${at} 的动作 ${name} 的 confirm`, code, { line: false }) } : {}) };
+    }
+  }
+  return { id: raw.id, title: text(raw.title, TITLE, `${at} 的 title`, code), command: text(raw.command, 4000, `${at} 的 command`, code),
+    ...(raw.maxAge !== undefined ? { maxAge: raw.maxAge, maxAgeMs: durationMs(raw.maxAge) } : {}), actions,
+    ...(raw.displaySetting !== undefined ? { displaySetting: text(raw.displaySetting, LABEL, `${at} 的 displaySetting`, code) } : {}),
+    ...(raw.signIn !== undefined ? { signIn: signIn(raw.signIn, `${at} 的 signIn`) } : {}) };
+}
+// Signing in from Coda (adapters/sign-in.mjs): a login command that prints a link to
+// confirm on any device (with a code, or asking for the authorization code the page shows, which goes to its standard
+// input), and where Coda may install what it needs, a quick check that it is there and the command that installs it.
+function signIn(raw, where) {
+  const code = 'invalid_plugin';
+  object(raw, where, code);
+  keys(raw, ['command', 'installed', 'install', 'input', 'note'], where, code);
+  check(raw.input === undefined || raw.input === 'authorizationCode', code, `${where} 的 input 只能是 authorizationCode`);
+  check(raw.install === undefined || raw.installed !== undefined, code, `${where}：写了 install 就要写 installed，Coda 才知道装没装好`);
+  return { command: text(raw.command, 4000, `${where} 的 command`, code),
+    ...(raw.installed !== undefined ? { installed: text(raw.installed, 4000, `${where} 的 installed`, code) } : {}),
+    ...(raw.install !== undefined ? { install: text(raw.install, 4000, `${where} 的 install`, code) } : {}),
+    ...(raw.input ? { input: raw.input } : {}),
+    ...(raw.note !== undefined ? { note: text(raw.note, CONFIRM, `${where} 的 note`, code, { line: false }) } : {}) };
+}
+// A plugin's panels as it declares them, each on its own: one Coda cannot read is kept with why, under the id and title it
+// wrote (or its place and the plugin's name), for the page to say so where it would show.
+export function panelEntries(raw, pluginName) {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) return [{ invalid: { id: 'panels', title: pluginName, error: 'contributes.panels 须为数组' } }];
+  const seen = new Set();
+  return raw.map((item, i) => {
+    // An ID is the first one's that writes it, read or not; one whose ID is not one, or another's, goes by its place.
+    const named = typeof item?.id === 'string' && NAME.test(item.id), again = named && seen.has(item.id);
+    const id = named && !again ? item.id : `#${i + 1}`;
+    if (named) seen.add(item.id);
+    try {
+      check(!again, 'invalid_plugin', `contributes.panels 里有重复的 id：${item.id}`);
+      return { panel: declaration(item, `contributes.panels[${i}]`) };
+    } catch (e) {
+      if (!(e instanceof PanelError)) throw e;
+      return { invalid: { id, title: typeof item?.title === 'string' && item.title.trim() ? item.title.slice(0, 40) : pluginName, error: e.message } };
+    }
+  });
+}
+export function panelDeclarations(raw) {
+  if (raw === undefined) return [];
+  check(Array.isArray(raw), 'invalid_plugin', 'contributes.panels 须为数组');
+  const panels = raw.map((p, i) => declaration(p, `contributes.panels[${i}]`));
+  check(new Set(panels.map(p => p.id)).size === panels.length, 'invalid_plugin', 'contributes.panels 里有重复的 id');
+  return panels;
+}
+
+// ---- What a panel's command prints ----
+// `{ items: [...] }`, each item one of ITEM_TYPES; a card holds the others. A button names one of the panel's actions,
+// or one of its plugin's views for the client to open (docs/plugins.md「视图」). `scope`: `{ actions, views }`, what the
+// panel declares and the ids of its plugin's views. Returned as the clients get it: only the keys each type has.
+function item(raw, where, scope, inCard) {
+  object(raw, where, 'invalid_panel');
+  const { display, ...content } = raw;
+  const out = plainItem(content, where, scope, inCard);
+  if (display !== undefined) {
+    object(display, `${where}.display`, 'invalid_panel');
+    keys(display, ['id', 'default'], `${where}.display`, 'invalid_panel');
+    check(['meter', 'stat'].includes(out.type), 'invalid_panel', '只有数值项可以声明 display');
+    check(typeof display.default === 'boolean', 'invalid_panel', 'display.default 须为开或关');
+    out.display = { id: text(display.id, 200, 'display.id', 'invalid_panel'), default: display.default };
+  }
+  return out;
+}
+function plainItem(raw, where, scope, inCard) {
+  const code = 'invalid_panel';
+  object(raw, where, code);
+  check(ITEM_TYPES.includes(raw.type), code, `${where} 的 type 只能是 ${ITEM_TYPES.join('、')}`);
+  check(!(inCard && raw.type === 'card'), code, `${where}：卡片里不能再放卡片`);
+  switch (raw.type) {
+    case 'card': {
+      keys(raw, ['type', 'title', 'subtitle', 'identity', 'items'], where, code);
+      check(Array.isArray(raw.items) && raw.items.length <= CARD_ITEMS, code, `${where} 的 items 须为不超过 ${CARD_ITEMS} 项的数组`);
+      // The outside identity it shows (an account), compared and nothing else: a group view shows cards naming the same
+      // one once for the machines that have them.
+      return { type: 'card', title: text(raw.title, LABEL, `${where} 的 title`, code),
+        ...(raw.subtitle !== undefined ? { subtitle: text(raw.subtitle, LABEL, `${where} 的 subtitle`, code) } : {}),
+        ...(raw.identity !== undefined ? { identity: text(raw.identity, IDENTITY, `${where} 的 identity`, code) } : {}),
+        items: raw.items.map((r, i) => item(r, `${where}.items[${i}]`, scope, true)) };
+    }
+    case 'meter': {
+      keys(raw, ['type', 'label', 'value', 'fraction', 'note', 'time', 'timeLabel'], where, code);
+      // Unknown is said by leaving the fraction out, never by a zero.
+      check(raw.fraction === undefined || raw.fraction === null || (typeof raw.fraction === 'number' && raw.fraction >= 0 && raw.fraction <= 1), code,
+        `${where} 的 fraction 须在 0–1 之间，不知道时不写`);
+      check(raw.time === undefined || (typeof raw.time === 'string' && Number.isFinite(Date.parse(raw.time))), code, `${where} 的 time 须为 ISO 8601 时间`);
+      return { type: 'meter', label: text(raw.label, LABEL, `${where} 的 label`, code),
+        ...(raw.value !== undefined ? { value: text(raw.value, LABEL, `${where} 的 value`, code) } : {}),
+        ...(typeof raw.fraction === 'number' ? { fraction: raw.fraction } : {}),
+        ...(raw.note !== undefined ? { note: text(raw.note, LABEL, `${where} 的 note`, code) } : {}),
+        ...(raw.time !== undefined ? { time: new Date(raw.time).toISOString() } : {}),
+        ...(raw.timeLabel !== undefined ? { timeLabel: text(raw.timeLabel, LABEL, `${where} 的 timeLabel`, code) } : {}) };
+    }
+    case 'stat':
+      keys(raw, ['type', 'label', 'value'], where, code);
+      return { type: 'stat', label: text(raw.label, LABEL, `${where} 的 label`, code), value: text(raw.value, LABEL, `${where} 的 value`, code) };
+    case 'markdown':
+      keys(raw, ['type', 'text'], where, code);
+      return { type: 'markdown', text: text(raw.text, MARKDOWN, `${where} 的 text`, code, { line: false }) };
+    case 'error':
+      keys(raw, ['type', 'text'], where, code);
+      return { type: 'error', text: text(raw.text, ERROR, `${where} 的 text`, code, { line: false }) };
+    case 'button': {
+      keys(raw, ['type', 'label', 'action', 'view', 'args', 'disabled', 'confirm'], where, code);
+      // What it does: run one of the panel's actions here, or open one of its plugin's views in the client.
+      const opens = raw.view !== undefined;
+      check(opens !== (raw.action !== undefined), code, `${where} 须有 action 或 view 之一`);
+      if (opens) check(typeof raw.view === 'string' && scope.views.includes(raw.view), code, `${where} 的 view 须是插件声明的视图：${raw.view}`);
+      else check(typeof raw.action === 'string' && Object.hasOwn(scope.actions, raw.action), code, `${where} 的 action 须是面板声明的动作：${raw.action}`);
+      check(raw.args === undefined || (raw.args && typeof raw.args === 'object' && !Array.isArray(raw.args) && JSON.stringify(raw.args).length <= ARGS_LIMIT), code,
+        `${where} 的 args 须为不超过 ${ARGS_LIMIT} 字节的对象`);
+      check(raw.disabled === undefined || typeof raw.disabled === 'boolean', code, `${where} 的 disabled 须为开或关`);
+      // Its own question, for what this one button does (which account, which credit), in place of its action's.
+      return { type: 'button', label: text(raw.label, LABEL, `${where} 的 label`, code), ...(opens ? { view: raw.view } : { action: raw.action }),
+        ...(raw.args ? { args: raw.args } : {}), ...(raw.disabled ? { disabled: true } : {}),
+        ...(raw.confirm !== undefined ? { confirm: text(raw.confirm, CONFIRM, `${where} 的 confirm`, code, { line: false }) } : {}) };
+    }
+  }
+  return fail(code, `${where} 的 type 不受支持`);
+}
+// A panel's reading from what its command printed. Anything it cannot be fails the reading, with where. `views`: the ids
+// of its plugin's views, which a button may open.
+export function panelItems(output, panel, views = []) {
+  const code = 'invalid_panel';
+  check(Buffer.byteLength(output) <= OUTPUT_LIMIT, code, `输出超过 ${OUTPUT_LIMIT / 1024} KiB`);
+  let value;
+  try { value = JSON.parse(output); } catch { return fail(code, '输出不是 JSON'); }
+  object(value, '输出', code);
+  keys(value, ['items'], '输出', code);
+  check(Array.isArray(value.items) && value.items.length <= ITEMS, code, `输出的 items 须为不超过 ${ITEMS} 项的数组`);
+  const items = value.items.map((r, i) => item(r, `items[${i}]`, { actions: panel.actions, views }, false));
+  const ids = items.flatMap(i => i.type === 'card' ? i.items : [i]).filter(i => i.display).map(i => i.display.id);
+  check(!ids.length || panel.displaySetting, code, '数值项的 display 需要面板声明 displaySetting');
+  check(new Set(ids).size === ids.length, code, 'display.id 不能重复');
+  return items;
+}
+// What a button sends: an object the action's command reads as JSON.
+export function actionArgs(value) {
+  if (value === undefined || value === null) return {};
+  check(typeof value === 'object' && !Array.isArray(value) && JSON.stringify(value).length <= ARGS_LIMIT, 'invalid_input', `args 须为不超过 ${ARGS_LIMIT} 字节的对象`);
+  return value;
+}
+
+// A reading keeps all measurements in memory; display choices are ordinary plugin settings, applied at read time.
+export function shownItems(items, choices = {}) {
+  return items.flatMap(({ display, ...item }) => {
+    if (display && !(choices[display.id] ?? display.default)) return [];
+    if (item.type === 'card') {
+      item.items = shownItems(item.items, choices);
+      if (!item.items.length) return [];
+    }
+    return [item];
+  });
+}
+export function displayOptions(items, values = {}) {
+  return items.flatMap(item => (item.type === 'card' ? item.items : [item]).filter(i => i.display).map(i => ({
+    id: i.display.id, label: i.label, group: item.type === 'card' ? item.title : '',
+    enabled: values[i.display.id] ?? i.display.default, default: i.display.default,
+  })));
+}
+
+// A disconnected device keeps its place for this backend's lifetime, with no old number presented as current.
+export function keepMissingMetrics(items, previous) {
+  const ids = new Set(items.flatMap(i => i.type === 'card' ? i.items : [i]).flatMap(i => i.display ? [i.display.id] : []));
+  const result = [...items];
+  for (const old of previous) {
+    const missing = (old.type === 'card' ? old.items : [old]).filter(i => i.display && !ids.has(i.display.id))
+      .map(i => ({ type: 'stat', label: i.label, value: '暂不可读', display: i.display }));
+    if (!missing.length) continue;
+    if (old.type === 'card') {
+      const same = result.find(i => i.type === 'card' && i.title === old.title);
+      if (same) same.items = [...same.items, ...missing].slice(0, 20);
+      else if (result.length < 50) result.push({ ...old, items: missing });
+    } else if (result.length < 50) result.push(...missing);
+  }
+  return result;
+}