@coda-console/claude 0.0.0 → 1.4.0

package/agent/auth.mjs

@@ -0,0 +1,37 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+
+// Variables that make the Claude CLI use something other than the user's normal login.
+export const authOverrides = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_CUSTOM_HEADERS',
+  'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_OAUTH_REFRESH_TOKEN', 'CLAUDE_CODE_OAUTH_SCOPES',
+  'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY'];
+
+// Read only in the SDK driver, never in the product service or host journal.
+export async function sdkEnvironment(env = process.env) {
+  const path = env.CODA_CLAUDE_OAUTH_TOKEN_FILE;
+  // Let the SDK use the user's normal login or provider configuration. A token
+  // file is an explicit override, never a dependency on a maintainer's machine.
+  if (path === undefined) return { ...env };
+  const fail = reason => new Error(`Claude SDK setup token: ${reason}`);
+  if (!isAbsolute(path)) throw fail('file path must be absolute');
+  let file;
+  try {
+    file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await file.stat();
+    if (!info.isFile() || info.uid !== process.getuid() || (info.mode & 0o7777) !== 0o600)
+      throw fail('file must be a regular file owned by the current user with mode 0600');
+    const buffer = Buffer.alloc(8193);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    const token = buffer.subarray(0, bytesRead).toString('utf8').replace(/\r?\n$/, '');
+    if (bytesRead > 8192 || !/^sk-ant-oat01-[A-Za-z0-9_-]+$/.test(token))
+      throw fail('file must contain one subscription OAuth token');
+    const result = { ...env };
+    for (const key of authOverrides) delete result[key];
+    result.CLAUDE_CODE_OAUTH_TOKEN = token;
+    return result;
+  } catch (error) {
+    if (error.message.startsWith('Claude SDK setup token:')) throw error;
+    throw fail('cannot read CODA_CLAUDE_OAUTH_TOKEN_FILE; choose a readable token file or remove this override to use your normal login');
+  } finally { await file?.close(); }
+}

package/agent/entry.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// The Claude agent as Coda starts it (the plugin's `contributes.agents`): Claude Code through the plugin's own Claude Agent SDK
+// (its `@anthropic-ai/claude-agent-sdk` dependency), speaking ACP and Coda's waits over standard input and output
+// (session.mjs). It ends when Coda's side of the pipe closes, when it is told to, or when its session ends.
+import { Readable, Writable } from 'node:stream';
+import { ndJsonStream } from '@agentclientprotocol/sdk';
+import { ClaudeSession } from './session.mjs';
+
+if (process.argv.includes('--help')) {
+  process.stdout.write('coda-claude: Claude Code as an ACP agent for Coda over standard input and output; no terminal UI.\n');
+} else {
+  const sdk = await import('@anthropic-ai/claude-agent-sdk');
+  for (const name of ['query', 'getSessionInfo', 'renameSession']) {
+    if (typeof sdk[name] !== 'function') throw new Error(`Claude SDK 缺少所需接口：${name}`);
+  }
+  let stopping = false;
+  const stop = async (code = 0) => {
+    if (stopping) return;
+    stopping = true;
+    // A Claude process must not outlive this one even if closing the SDK hangs; the session host has a shorter grace of its own.
+    setTimeout(() => process.exit(code || 1), 5000).unref();
+    try { await session.close(); } finally { process.stdout.write('', () => process.exit(code)); }
+  };
+  const session = new ClaudeSession({ sdk, onEnded: () => void stop(1) });
+  session.connect(ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin))).closed.then(() => stop());
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.once(signal, () => void stop());
+}

package/agent/limits.mjs

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+
+// The quota of the account Claude sessions run as, read from what the sessions themselves report. A setup token has no
+// profile scope, so /usage cannot be asked with it; but the CLI sends a `rate_limit_event` whenever a window's rounded
+// percentage or reset time moves, with the fraction of the window used and when it resets (SDKRateLimitInfo). Each
+// session's entry (session.mjs) writes it to `limits.json` in this plugin's state; the「Claude」panel reads it
+// (scripts/panel.mjs, docs/plugins.md「内置插件：Claude」).
+// `unifiedWindows`, an internal field of newer CLIs, carries every window each time; the top-level fields, which every
+// CLI sends, only the one that limits now.
+const labels = { five_hour: '5 小时', seven_day: '7 天', seven_day_opus: 'Opus · 7 天', seven_day_sonnet: 'Sonnet · 7 天', seven_day_overage_included: 'Fable · 7 天' };
+const used = fraction => Math.round(fraction * 100);
+
+function reported(info) {
+  const windows = info?.unifiedWindows && typeof info.unifiedWindows === 'object' ? { ...info.unifiedWindows } : {};
+  if (info?.rateLimitType && !windows[info.rateLimitType]) windows[info.rateLimitType] = info;
+  return Object.entries(windows);
+}
+
+// The latest each window was reported at, kept across restarts: events come only as a window moves, so a backend that
+// started just now would otherwise show nothing until one does. A window past its reset is no longer known, not full:
+// what was used since is not seen from here.
+// The account they are of is kept beside them, as a hash of its email (`account`): what Coda's group view compares across
+// machines, the email itself staying here. The file is the account the latest session started as (session.mjs); none
+// where Claude runs on an API key or a cloud provider, or the login does not say.
+export const accountHash = email => createHash('sha256').update(email.trim().toLowerCase()).digest('hex').slice(0, 32);
+export class ClaudeSessionLimits {
+  constructor({ path = null, now = Date.now } = {}) {
+    this.path = path; this.now = now; this.windows = new Map(); this.account = null; this.stamp = null;
+    this.read();
+  }
+  read() {
+    if (!this.path) return;
+    let stamp;
+    try { stamp = statSync(this.path).mtimeMs; } catch { return; }
+    if (stamp === this.stamp) return;
+    this.stamp = stamp; this.windows = new Map(); this.account = null;
+    try {
+      const saved = JSON.parse(readFileSync(this.path, 'utf8'));
+      for (const [key, w] of Object.entries(saved.windows)) this.take(key, w?.utilization, w?.resetsAt);
+      if (typeof saved.account === 'string' && /^[0-9a-f]{32}$/.test(saved.account)) this.account = saved.account;
+    }
+    catch { /* Not readable now: read again when it next changes. */ this.stamp = null; }
+  }
+  known() { this.read(); return this.windows.size > 0; }
+  take(key, utilization, resetsAt) {
+    if (!Object.hasOwn(labels, key) || !(Number.isFinite(utilization) && utilization >= 0) || !(Number.isSafeInteger(resetsAt) && resetsAt > 0)) return false;
+    const was = this.windows.get(key);
+    if (was?.resetsAt === resetsAt && used(was.utilization) === used(utilization)) return false;
+    this.windows.set(key, { utilization, resetsAt });
+    return true;
+  }
+  // The account a session started as, a hash or null when it is not known: from then on the file is that one's. Another
+  // than before starts the windows afresh, as another account's say nothing of it; an unknown one names none.
+  startedAs(account) {
+    if (account === this.account) return;
+    this.windows = new Map(); this.account = account;
+    this.save();
+  }
+  // What a session reports, as of the account it started as: one that started as another (still running from before a
+  // switch) says nothing of the account the file is now.
+  observe(info, account = null) {
+    if (account !== this.account) return;
+    let changed = false;
+    for (const [key, w] of reported(info)) changed = this.take(key, w?.utilization, w?.resetsAt) || changed;
+    if (changed) this.save();
+  }
+  save() {
+    if (!this.path) return;
+    try {
+      // Every Claude session writes it: a temporary file of each writer's own.
+      const temp = `${this.path}.${process.pid}.tmp`;
+      writeFileSync(temp, JSON.stringify({ version: 1, windows: Object.fromEntries(this.windows), ...(this.account ? { account: this.account } : {}) }), { mode: 0o600 });
+      renameSync(temp, this.path);
+    } catch { /* Not written: the next window that moves writes again. */ }
+  }
+  // The windows still to reset, in a fixed order: what is left of each and when it resets. None when all have passed.
+  quota() {
+    this.read();
+    const now = this.now();
+    return Object.keys(labels).flatMap(key => {
+      const w = this.windows.get(key);
+      return w && w.resetsAt * 1000 > now ? [{ id: key, label: labels[key], remainingPercent: Math.max(0, 100 - used(w.utilization)),
+        resetsAt: new Date(w.resetsAt * 1000).toISOString() }] : [];
+    });
+  }
+}

package/agent/models.mjs

@@ -0,0 +1,41 @@
+// Claude's settings as ACP config options. A model is named by the concrete ID it runs as, never by an alias: each row the
+// SDK lists is its resolved wire ID with the context variant it selects (`[1m]`), or its own value when it resolves to
+// none, and rows that come to the same ID are one model. What the row is called is kept, the ID beside it when the name
+// does not say it.
+export const MODES = [['default', '人工审批'], ['acceptEdits', '自动接受编辑'], ['plan', '规划'], ['dontAsk', '未预先允许则拒绝'], ['auto', '自动审批'],
+  ['bypassPermissions', '跳过所有审批']].map(([id, name]) => ({ id, name }));
+
+export function claudeModels(rows = []) {
+  const models = new Map();
+  for (const row of rows) {
+    if (typeof row?.value !== 'string' || !row.value) continue;
+    const variant = row.value.match(/\[[^\]]+\]$/)?.[0] ?? '', resolved = row.resolvedModel?.trim();
+    const id = resolved ? resolved + (resolved.endsWith(variant) ? '' : variant) : row.value;
+    const label = row.displayName || row.value, name = label.includes(id) ? label : `${label} (${id})`;
+    const known = models.get(id);
+    // The SDK's `default` row is the model it would pick: the row naming that model says what it is.
+    if (!known) models.set(id, { id, name, efforts: row.supportedEffortLevels ?? [], from: row.value });
+    else if (known.from === 'default') Object.assign(known, { name, from: row.value });
+  }
+  return [...models.values()];
+}
+
+// The model a native init reports: one of the list, keeping the context variant chosen when its base is the one reported.
+export function reportedModel(models, current, model) {
+  if (typeof model !== 'string' || !model) return current;
+  if (current === model || current?.replace(/\[[^\]]+\]$/, '') === model) return current;
+  return models.find(m => m.id === model)?.id ?? model;
+}
+
+const select = (id, name, category, currentValue, choices) => ({ id, name, category, type: 'select', currentValue,
+  options: choices.map(c => ({ value: c.id, name: c.name, ...(c._meta ? { _meta: c._meta } : {}) })) });
+// The effort that leaves it to the model, marked as the agent's own default (docs/agent-protocol.md): what Coda goes back to
+// when the session's effort is taken off.
+export const MODEL_EFFORT = 'default';
+// `current`: { mode, model, effort }. An effort not chosen is null: the model's own default.
+export function configOptions(models, current) {
+  const efforts = models.find(m => m.id === current.model)?.efforts ?? [];
+  return [select('mode', '审批模式', 'mode', current.mode, MODES), select('model', '模型', 'model', current.model, models),
+    ...(efforts.length ? [select('effort', '推理强度', 'thought_level', efforts.includes(current.effort) ? current.effort : MODEL_EFFORT,
+      [{ id: MODEL_EFFORT, name: '模型默认', _meta: { coda: { default: true } } }, ...efforts.map(id => ({ id, name: id }))])] : [])];
+}

package/agent/permissions.mjs

@@ -0,0 +1,68 @@
+// A tool Claude asks to use, as an ACP permission request: allow once, each rule Claude suggests to stop asking (its whole
+// sentence the option's name, the rule kept here), and deny. Why it asks is the tool call's content. Only an option offered
+// can change Claude's permissions.
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+
+const deny = { behavior: 'deny', message: '用户未批准此操作' };
+
+export function permissionRequest({ sessionId, toolName, input, context = {} }) {
+  // Identical suggestions would be two options that do the same thing.
+  const suggestions = [...new Map((context.suggestions ?? []).map(change => [JSON.stringify(change), change])).values()];
+  const options = [{ optionId: 'allow-once', name: '仅允许本次', kind: 'allow_once' },
+    ...suggestions.map((change, i) => ({ optionId: `suggestion-${i}`, name: describeChange(change, input), kind: 'allow_always' })),
+    { optionId: 'deny', name: '拒绝', kind: 'reject_once' }];
+  const params = { sessionId, options, toolCall: { toolCallId: context.toolUseID ?? randomUUID(), title: toolName, rawInput: input, status: 'pending',
+    ...(context.decisionReason ? { content: [{ type: 'content', content: { type: 'text', text: context.decisionReason } }] } : {}) } };
+  const answer = response => {
+    const { outcome, optionId } = response?.outcome ?? {};
+    if (outcome !== 'selected') return deny;
+    if (optionId === 'allow-once') return { behavior: 'allow', updatedInput: input };
+    const change = suggestions[/^suggestion-(\d+)$/.exec(optionId ?? '')?.[1]];
+    return change ? { behavior: 'allow', updatedInput: input, updatedPermissions: [change] } : deny;
+  };
+  return { params, answer };
+}
+
+// Two suggestions for the same tool are different grants; the name says what each allows, and where it is kept.
+const scopes = { session: '本会话', cliArg: '本进程', localSettings: '本项目 · 本机', projectSettings: '本项目 · 共享', userSettings: '所有项目' };
+const verbs = { allow: '允许', deny: '拒绝', ask: '每次询问' };
+const modes = { default: '默认', acceptEdits: '自动允许修改文件', bypassPermissions: '跳过所有审批', plan: '计划', dontAsk: '不询问' };
+const readTools = new Set(['Read', 'Glob', 'Grep']), editTools = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+const shortPath = path => { const home = homedir(); return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path; };
+
+function describeRule({ toolName, ruleContent }, input, verb) {
+  if (ruleContent === undefined) return [`${verb}所有 ${toolName} 操作`];
+  if (toolName === 'Bash') {
+    if (ruleContent === input?.command) return [`${verb}这条完全相同的命令`];
+    if (ruleContent.endsWith(':*')) return [`${verb}以此开头的命令`, ruleContent.slice(0, -2)];
+    return [`${verb}命令`, ruleContent];
+  }
+  // Claude writes absolute paths in rules as `//abs/path`.
+  const path = shortPath(ruleContent.replace(/^\/\//, '/'));
+  if (readTools.has(toolName)) return [`${verb}读取`, path];
+  if (editTools.has(toolName)) return [`${verb}修改`, path];
+  if (toolName === 'WebFetch' && ruleContent.startsWith('domain:')) return [`${verb}访问`, ruleContent.slice(7)];
+  return [`${verb} ${toolName}`, ruleContent];
+}
+
+export function describeChange(change, input) {
+  const scope = scopes[change.destination] ?? change.destination ?? 'Agent 建议的范围', verb = verbs[change.behavior] ?? '允许';
+  const rules = change.rules ?? [], listed = rules.map(r => `${r.toolName}(${r.ruleContent ?? ''})`).join('、');
+  const directories = (change.directories ?? []).map(shortPath).join('、');
+  const [what, target] = (() => {
+    switch (change.type) {
+      case 'addRules': case 'replaceRules': {
+        const [added, target] = rules.length === 1 ? describeRule(rules[0], input, verb) : [`${verb} ${rules.length} 条规则`, listed];
+        // Replacing drops the scope's existing rules of this behavior.
+        return [change.type === 'replaceRules' ? `替换现有规则为：${added}` : added, target];
+      }
+      case 'removeRules': return [`移除${verb}规则`, listed];
+      case 'addDirectories': return ['允许访问目录', directories];
+      case 'removeDirectories': return ['移除目录', directories];
+      case 'setMode': return [`切换为「${modes[change.mode] ?? change.mode}」模式`];
+      default: return ['应用 Agent 建议的权限调整'];
+    }
+  })();
+  return `${what}${target ? ` ${target}` : ''}（${scope}）`;
+}

package/agent/providers.mjs

@@ -0,0 +1,53 @@
+// The model service chosen in Coda (`claude.modelProvider`, Coda's docs/plugins.md「模型服务」): another plugin's service that
+// speaks Anthropic Messages, from CODA_MODEL_PROVIDERS. The models its address lists (`<地址>/models`) join Claude's own, each
+// named by the service and the model; a session on one runs Claude Code with the service as its API (`serviceSettings`), set
+// for that session's process only.
+import { readFileSync } from 'node:fs';
+import { authOverrides } from './auth.mjs';
+
+export const SETTING = 'claude.modelProvider';
+const log = text => process.stderr.write(`[claude-agent] ${text}\n`);
+const parse = text => { try { return JSON.parse(text || '{}'); } catch { return {}; } };
+const LIST_TIMEOUT = 8000;
+
+// The chosen service: its address, title and key (read from the file Coda keeps it in). Null when none is chosen, or the
+// one chosen is not on this machine or speaks another API.
+export function chosenService(env = process.env) {
+  const ref = parse(env.CODA_PLUGIN_SETTINGS)[SETTING];
+  if (!ref) return null;
+  const provided = parse(env.CODA_MODEL_PROVIDERS)[ref];
+  if (!provided?.url) { log(`模型服务 ${ref} 在这台机器上没有`); return null; }
+  if (provided.api !== 'anthropic-messages') { log(`模型服务 ${ref} 讲 ${provided.api}，Claude 只接 anthropic-messages 的`); return null; }
+  let key;
+  try { key = provided.keyFile ? readFileSync(provided.keyFile, 'utf8').trim() || undefined : undefined; }
+  catch (e) { log(`读不到模型服务 ${ref} 的 Key：${e.message}`); }
+  return { ref, title: provided.title || ref, url: provided.url, key };
+}
+
+// The models the service lists, asked as an Anthropic client asks (Coda's「检查可用模型」): `<服务>/<模型>`, named by the
+// model and the service. They have no effort to choose.
+export async function serviceModels({ ref, title, url, key }, fetcher = fetch) {
+  const at = `${url.replace(/\/+$/, '')}/models?limit=1000`;
+  const response = await fetcher(at, { headers: key ? { 'x-api-key': key, 'anthropic-version': '2023-06-01' } : {}, signal: AbortSignal.timeout(LIST_TIMEOUT) });
+  if (!response.ok) throw new Error(`${at} 回答 ${response.status}`);
+  const body = await response.json();
+  return (Array.isArray(body?.data) ? body.data : []).filter(model => typeof model?.id === 'string' && model.id)
+    .map(model => ({ id: `${ref}/${model.id}`, name: `${model.id} (${title})`, efforts: [], model: model.id }));
+}
+
+// The flag settings Claude Code runs a service's model with (above the machine's and the project's settings, its environment
+// beneath them): the service as its API, a token of the service's own (`none` without one), and the model for every role,
+// subagents' and background work's included. None of the machine's own ways to the API goes with it: an API key, a key
+// helper, an OAuth token or custom headers would be sent to the service, a cloud provider's would take the requests away.
+export function serviceSettings({ url, key }, model) {
+  return { apiKeyHelper: '', env: { ...Object.fromEntries(authOverrides.map(name => [name, ''])), ANTHROPIC_BASE_URL: url, ANTHROPIC_AUTH_TOKEN: key ?? 'none',
+    ANTHROPIC_MODEL: model, ANTHROPIC_DEFAULT_OPUS_MODEL: model, ANTHROPIC_DEFAULT_SONNET_MODEL: model, ANTHROPIC_DEFAULT_HAIKU_MODEL: model,
+    CLAUDE_CODE_SUBAGENT_MODEL: model } };
+}
+
+// The service's models, listed with Claude's own: none when it cannot list them now.
+export async function listedModels(service) {
+  if (!service) return [];
+  try { return await serviceModels(service); }
+  catch (e) { log(`模型服务 ${service.ref} 列不出模型：${e.message}`); return []; }
+}

package/agent/questions.mjs

@@ -0,0 +1,39 @@
+// What Claude asks the user, as ACP forms in plain JSON Schema: its own questions (AskUserQuestion) and those of the MCP
+// servers it runs (a form, or a link to open).
+import { randomUUID } from 'node:crypto';
+
+// The choice that says the answer is the one written beside it: ACP forms carry no rule that one of two fields be filled,
+// so the question stays required and this is one of its choices.
+export const OTHER = 'coda:other';
+
+export function questionForm({ sessionId, toolCallId, input }) {
+  const questions = Array.isArray(input?.questions) ? input.questions : [];
+  const properties = {};
+  questions.forEach((q, i) => {
+    const choices = [...(q.options ?? []).map(o => ({ const: o.label, title: o.label + (o.description ? ` — ${o.description}` : '') })),
+      { const: OTHER, title: '其他（写在下面）' }];
+    properties[`q${i}`] = { title: q.question, description: q.header ?? '', ...(q.multiSelect
+      ? { type: 'array', items: { anyOf: choices }, minItems: 1 } : { type: 'string', oneOf: choices }) };
+    properties[`q${i}_other`] = { type: 'string', title: '其他' };
+  });
+  const params = { sessionId, ...(toolCallId ? { toolCallId } : {}), mode: 'form', message: 'Claude 需要你的回答',
+    requestedSchema: { type: 'object', properties, required: questions.map((_, i) => `q${i}`) } };
+  const answer = response => {
+    if (response?.action !== 'accept') return { behavior: 'deny', message: '用户取消了问答' };
+    const content = response.content ?? {};
+    return { behavior: 'allow', updatedInput: { ...input, answers: Object.fromEntries(questions.map((q, i) => {
+      const other = String(content[`q${i}_other`] ?? '').trim() || '其他', pick = value => value === OTHER ? other : value;
+      const value = content[`q${i}`];
+      return [q.question, Array.isArray(value) ? value.map(pick).join(', ') : pick(value)];
+    })) } };
+  };
+  return { params, answer };
+}
+
+// An MCP server's request (SDK onElicitation): its form as it is, or its link with nothing to fill in.
+export function elicitationForm({ sessionId, request }) {
+  if (request.mode === 'url') return { params: { sessionId, mode: 'url', message: request.message ?? '', url: request.url,
+    elicitationId: request.elicitationId ?? randomUUID() }, answer: response => ({ action: response?.action ?? 'cancel' }) };
+  return { params: { sessionId, mode: 'form', message: request.message ?? '', requestedSchema: request.requestedSchema ?? { type: 'object', properties: {} } },
+    answer: response => ['accept', 'decline', 'cancel'].includes(response?.action) ? response : { action: 'cancel' } };
+}