@citeark/agent 0.3.20

package/src/terminal/screen.mjs

@@ -0,0 +1,214 @@
+import { terminalKeys } from './input.mjs';
+import { createWriteStream } from 'node:fs';
+import { finished } from 'node:stream/promises';
+import { readFile } from 'node:fs/promises';
+import { format } from 'node:util';
+import { STAGES, Transcript, wrapText, cleanText } from './transcript.mjs';
+
+const ESC = '\x1b[';
+const muted = text => `${ESC}2m${text}${ESC}0m`;
+const bold = text => `${ESC}1m${text}${ESC}0m`;
+
+export class TerminalScreen {
+  constructor({ input = process.stdin, output = process.stdout, version = '', color = !process.env.NO_COLOR, onExit, onInput } = {}) {
+    this.input = input; this.output = output; this.version = version; this.color = color;
+    this.transcript = new Transcript(); this.expanded = false; this.pending = null;
+    this.startedAt = Date.now(); this.context = ''; this.buffer = ''; this.cursor = 0;
+    this.rawWrite = output.write.bind(output);
+    this.onExit = onExit; this.onInput = onInput;
+    this.onKey = this.onKey.bind(this); this.render = this.render.bind(this);
+  }
+  start() {
+    this.wasRaw = this.input.isRaw;
+    this.releaseKeys = terminalKeys(this.input, this.onKey);
+    this.input.setRawMode(true); this.input.resume();
+    this.output.on('resize', this.render);
+    this.rawWrite(`${ESC}?1049h${ESC}?25l${ESC}?1000h${ESC}?1006h${ESC}?2004h`);
+    this.savedLog = console.log; this.savedError = console.error; this.savedWarn = console.warn;
+    console.log = (...args) => this.event({ kind: 'status', text: format(...args) });
+    console.error = console.warn = (...args) => this.event({ kind: 'error', text: format(...args) });
+    this.timer = setInterval(this.render, 250); this.timer.unref(); this.render();
+  }
+  async attach(filename) {
+    const initial = [...this.transcript.entries];
+    let previous;
+    try { previous = await readFile(filename, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (previous) {
+      const fresh = this.transcript.entries;
+      this.transcript = new Transcript();
+      for (const line of previous.split('\n').filter(Boolean)) this.transcript.add(JSON.parse(line));
+      this.transcript.add({ kind: 'status', text: 'Session resumed' });
+      for (const event of fresh) this.transcript.add(event);
+      this.cached = null;
+    }
+    this.file = createWriteStream(filename, { flags: 'a', mode: 0o600 });
+    this.file.on('error', error => { this.fileError = error; });
+    for (const event of initial) this.file.write(`${JSON.stringify(event)}\n`);
+    this.event({ kind: 'status', text: `Transcript: ${filename}` });
+  }
+  async stopRecording() {
+    if (!this.file) return;
+    const file = this.file; this.file = null; file.end(); await finished(file);
+  }
+  async view(filename) {
+    const saved = await readFile(filename, 'utf8');
+    for (const line of saved.split('\n').filter(Boolean)) this.transcript.add(JSON.parse(line));
+    this.context = filename;
+    await this.finish('Saved conversation');
+  }
+  event(event) {
+    const value = { at: new Date().toISOString(), ...event };
+    this.transcript.add(value);
+    if (this.file && !this.fileError) this.file.write(`${JSON.stringify(value)}\n`);
+    this.dirty = true;
+  }
+  stage(stage, status = 'Running') { this.event({ kind: 'stage', stage, status }); }
+  async openResearch(options) {
+    this.event({ kind: 'assistant', text: 'Start with a paper, or continue a saved workspace.\nEnter a paper URL, file path, or CiteArk paper ID.\n\n/resume  Continue a workspace\n/cap     Open a research artifact\n/model   Choose a model\n/compute Choose compute\n/help    Show commands' });
+    while (true) {
+      const value = await this.ask('What would you like to research?');
+      if (!value) continue;
+      if (value === '/model' || value === '/compute') {
+        const { settingsMenu } = await import('../settings/command.mjs');
+        await settingsMenu(value.slice(1), this); continue;
+      }
+      if (value === '/help') {
+        this.event({ kind: 'status', text: '/resume · /cap · /model · /compute · /help\nAdd --repository, --guide, or --goal when starting from your shell.\nModel and compute settings are requested when needed.' });
+        continue;
+      }
+      if (value === '/resume') {
+        options['--resume'] = true;
+        options['--work-dir'] = await this.ask('Workspace directory');
+        return null;
+      }
+      if (value === '/cap' || value.endsWith('.cap')) {
+        options['--cap'] = value === '/cap' ? await this.ask('CAP file path') : value;
+        return null;
+      }
+      if (value.startsWith('/')) {
+        // Absolute file paths are also valid inputs.
+        if (!value.includes('.', 1) && !value.slice(1).includes('/')) {
+          this.event({ kind: 'error', text: `Unknown command: ${value}. Use /help for available commands.` });
+          continue;
+        }
+      }
+      if (/^[a-z0-9]{6}$/.test(value)) return value;
+      options['--paper'] = value;
+      return null;
+    }
+  }
+  async ask(label, { defaultValue = '', secret = false, choices } = {}) {
+    this.transcript.follow(); this.buffer = defaultValue; this.cursor = this.buffer.length;
+    return new Promise((resolve, reject) => {
+      this.pending = { label, secret, choices, selected: Math.max(0, choices?.findIndex(item => item.value === defaultValue) ?? 0), resolve, reject };
+      this.render();
+    });
+  }
+  choose(label, choices, defaultValue = choices[0]?.value) { return this.ask(label, { choices, defaultValue }); }
+  async confirm(label) {
+    return await this.choose(label, [{ value: 'yes', label: 'Continue' }, { value: 'no', label: 'Cancel' }], 'no') === 'yes';
+  }
+  onKey(text, key = {}) {
+    const page = Math.max(1, this.bodyHeight ?? 10);
+    const scroll = amount => { this.transcript.scroll(amount, this.lines?.length ?? 0, page); this.render(); };
+    const mouse = /^\x1b\[<(64|65);\d+;\d+[Mm]$/.exec(key.sequence ?? text ?? '');
+    if (mouse) { scroll(mouse[1] === '64' ? -3 : 3); return; }
+    if (key.name === 'pageup') { scroll(-page); return; }
+    if (key.name === 'pagedown') { scroll(page); return; }
+    if (key.name === 'end' && (!this.pending || this.transcript.offset !== null)) { this.transcript.follow(); this.render(); return; }
+    if (key.name === 'home' && !this.pending) { this.transcript.offset = 0; this.render(); return; }
+    if (key.ctrl && key.name === 'o') { this.expanded = !this.expanded; this.cached = null; this.render(); return; }
+    if (key.ctrl && key.name === 'c') {
+      if (this.pending) {
+        const pending = this.pending; this.pending = null;
+        pending.reject(Object.assign(Error('Operation cancelled.'), { exitCode: 130 }));
+      } else {
+        this.transcript.status = 'Disconnecting…';
+        this.onExit?.();
+        this.render();
+      }
+      return;
+    }
+    const question = this.pending ?? (this.onInput ? { label: 'Send an instruction · /pause · /resume · /cancel', live: true } : null);
+    if (!question) return;
+    if (question.choices && ['up', 'down'].includes(key.name)) {
+      question.selected = (question.selected + (key.name === 'up' ? -1 : 1) + question.choices.length) % question.choices.length;
+    } else if (key.name === 'return') {
+      const answer = question.choices ? question.choices[question.selected].value : this.buffer.trim();
+      const shown = question.choices ? question.choices[question.selected].label : question.secret ? '[hidden]' : answer;
+      this.pending = null; this.buffer = ''; this.cursor = 0;
+      this.event({ kind: 'user', text: `${question.label}\n${shown}` });
+      if (question.live) this.onInput(answer).catch(error => this.event({ kind: 'error', text: error.message }));
+      else question.resolve(answer);
+    } else if (!question.choices) {
+      if (key.name === 'backspace') {
+        const chars = Array.from(this.buffer.slice(0, this.cursor)); const removed = chars.pop() ?? '';
+        this.buffer = chars.join('') + this.buffer.slice(this.cursor); this.cursor -= removed.length;
+      } else if (key.name === 'delete') {
+        this.buffer = this.buffer.slice(0, this.cursor) + Array.from(this.buffer.slice(this.cursor)).slice(1).join('');
+      } else if (key.name === 'left') this.cursor -= Array.from(this.buffer.slice(0, this.cursor)).at(-1)?.length ?? 0;
+      else if (key.name === 'right') this.cursor += Array.from(this.buffer.slice(this.cursor))[0]?.length ?? 0;
+      else if (key.name === 'home' || key.ctrl && key.name === 'a') this.cursor = 0;
+      else if (key.name === 'end' || key.ctrl && key.name === 'e') this.cursor = this.buffer.length;
+      else if (key.ctrl && key.name === 'u') { this.buffer = this.buffer.slice(this.cursor); this.cursor = 0; }
+      else if (text && !key.ctrl && !key.meta && !text.startsWith('\x1b')) {
+        const value = cleanText(text.replaceAll('\r', ' ')).replaceAll('\n', ' ');
+        this.buffer = this.buffer.slice(0, this.cursor) + value + this.buffer.slice(this.cursor); this.cursor += value.length;
+      }
+    }
+    this.render();
+  }
+  render() {
+    if (this.closed) return;
+    const width = Math.max(12, (this.output.columns ?? 80) - 2);
+    const height = this.output.rows ?? 24;
+    const dim = this.color ? muted : text => text;
+    const strong = this.color ? bold : text => text;
+    const stage = this.transcript.stage;
+    const labels = width >= 115 ? STAGES : ['Paper', 'Research', 'Materials', 'Experiments', 'Delivery'];
+    const symbols = labels.map((name, index) => `${index < stage ? '✓' : index === stage ? this.done ? '✓' : '●' : '○'} ${name}`);
+    const steps = wrapText(symbols.join('  ·  '), width);
+    const header = [strong(`CiteArk Agent  ${this.version}`), dim(wrapText(this.context || 'Your independent research workspace', width)[0]), '', ...steps.map(dim), '─'.repeat(width)];
+    const question = this.pending ?? (this.onInput ? { label: 'Send an instruction · /pause · /resume · /cancel', live: true } : null);
+    const footer = [];
+    if (this.transcript.offset !== null) footer.push(...wrapText(`Viewing history · ${this.transcript.unseen} new events · End to follow`, width).map(dim));
+    footer.push('─'.repeat(width));
+    if (question) {
+      footer.push(...wrapText(question.label, width));
+      if (question.choices) {
+        const start = Math.max(0, question.selected - 3);
+        question.choices.slice(start, start + 5).forEach((choice, index) => footer.push(wrapText(`${index + start === question.selected ? '›' : ' '} ${choice.label}`, width)[0]));
+        footer.push(...wrapText('↑/↓ select · Enter confirm · PgUp/PgDn history', width).map(dim));
+      } else {
+        const before = this.buffer.slice(0, this.cursor), after = this.buffer.slice(this.cursor);
+        const displayed = question.secret ? `${'•'.repeat(Array.from(before).length)}▏${'•'.repeat(Array.from(after).length)}` : `${before}▏${after}`;
+        const rows = wrapText(`› ${displayed}`, width);
+        footer.push(...rows.slice(-3), ...wrapText('Enter submit · Ctrl+U clear · PgUp/PgDn history', width).map(dim));
+      }
+    } else footer.push(...wrapText('PgUp/PgDn scroll · End follow · Ctrl+O expand', width).map(dim),
+      ...wrapText('Ctrl+C exits CLI; compute may continue', width).map(dim),
+      ...wrapText(`${stage + 1}/5 ${STAGES[stage]} · ${this.transcript.status} · ${Math.floor((Date.now() - this.startedAt) / 1000)}s`, width).map(dim));
+    this.bodyHeight = Math.max(1, height - header.length - footer.length - 1);
+    const cacheKey = `${this.transcript.revision}:${width}:${this.expanded}`;
+    if (this.cached !== cacheKey) { this.lines = this.transcript.lines(width, this.expanded); this.cached = cacheKey; }
+    const start = this.transcript.offset === null ? Math.max(0, this.lines.length - this.bodyHeight) : Math.min(this.transcript.offset, Math.max(0, this.lines.length - this.bodyHeight));
+    const body = this.lines.slice(start, start + this.bodyHeight);
+    while (body.length < this.bodyHeight) body.push('');
+    const rows = [...header, ...body, ...footer].slice(0, height - 1);
+    const frame = `${ESC}H${rows.map(line => `${line}${ESC}K`).join('\r\n')}${ESC}J`;
+    if (frame !== this.lastFrame) { this.rawWrite(frame); this.lastFrame = frame; }
+  }
+  async finish(status = 'Completed') {
+    this.done = status === 'Completed'; this.transcript.status = status;
+    await this.ask(`${status}. Press Enter to return to your terminal.`);
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true; clearInterval(this.timer);
+    this.releaseKeys?.(); this.output.off('resize', this.render);
+    this.input.setRawMode(this.wasRaw ?? false); this.input.pause();
+    console.log = this.savedLog; console.error = this.savedError; console.warn = this.savedWarn;
+    this.rawWrite(`${ESC}?2004l${ESC}?1000l${ESC}?1006l${ESC}?25h${ESC}?1049l`);
+    if (this.file) { this.file.end(); await finished(this.file); }
+  }
+}

package/src/terminal/transcript.mjs

@@ -0,0 +1,69 @@
+import { stripVTControlCharacters } from 'node:util';
+
+export const STAGES = ['Get paper', 'Understand research', 'Prepare materials', 'Run experiments', 'Assess & deliver'];
+const stageIndex = { intake: 0, source_discovery: 0, research_compilation: 1, research_import: 1,
+  research_preparation: 1, reproduction_scheduling: 1, planning: 1, awaiting_selection: 1,
+  research_plan: 1, contract_creation: 2, compute_scheduling: 2,
+  asset_preparation: 2, reproduction: 3, executing: 3, evidence_parsing: 4, verification: 4,
+  research_card: 4, execution_handoff: 4, packaging: 4, archive: 4, publishing: 4, completed: 4 };
+export function workflowStage(stage) { return stageIndex[stage]; }
+export function cleanText(value) { return stripVTControlCharacters(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ''); }
+
+export class Transcript {
+  entries = [];
+  indices = new Map();
+  revision = 0;
+  offset = null;
+  unseen = 0;
+  stage = 0;
+  status = 'Ready';
+  add(event) {
+    const entry = { ...event, text: cleanText(event.text ?? '') };
+    if (event.kind === 'stage') {
+      const index = workflowStage(event.stage);
+      if (index !== undefined) this.stage = index;
+      this.status = event.status ?? 'Running';
+    }
+    if (!entry.text) return;
+    if (entry.id && this.indices.has(entry.id)) this.entries[this.indices.get(entry.id)] = entry;
+    else { if (entry.id) this.indices.set(entry.id, this.entries.length); this.entries.push(entry); }
+    this.revision++;
+    if (this.offset !== null) this.unseen++;
+  }
+  lines(width, expanded = false) {
+    const lines = [];
+    for (const entry of this.entries) {
+      const prefix = { assistant: '● ', user: '› ', tool: '→ ', error: '! ', status: '· ', stage: '◆ ' }[entry.kind] ?? '  ';
+      const raw = entry.text.split('\n');
+      const visible = !expanded && entry.kind === 'tool-output' && raw.length > 12 ? [...raw.slice(0, 8), `… ${raw.length - 8} more lines · Ctrl+O to expand`] : raw;
+      visible.forEach((line, index) => {
+        const text = (index ? '  ' : prefix) + line.replaceAll('\t', '    ');
+        lines.push(...wrapText(text, width));
+      });
+      lines.push('');
+    }
+    return lines;
+  }
+  scroll(delta, total, height) {
+    const bottom = Math.max(0, total - height);
+    this.offset = Math.max(0, Math.min(bottom, (this.offset ?? bottom) + delta));
+    if (this.offset >= bottom) this.follow();
+  }
+  follow() { this.offset = null; this.unseen = 0; }
+}
+
+export function characterWidth(char) {
+  const n = char.codePointAt(0);
+  if (/\p{Mark}/u.test(char) || n === 0x200d || n === 0xfe0f) return 0;
+  return n >= 0x1100 && (n <= 0x115f || n >= 0x2e80 && n <= 0xa4cf || n >= 0xac00 && n <= 0xd7a3 || n >= 0xf900 && n <= 0xfaff || n >= 0xfe10 && n <= 0xfe6f || n >= 0xff00 && n <= 0xff60 || n >= 0x1f300) ? 2 : 1;
+}
+export function wrapText(text, width) {
+  const lines = []; let line = ''; let size = 0;
+  for (const char of text) {
+    const count = characterWidth(char);
+    if (size + count > width && line) { lines.push(line); line = ''; size = 0; }
+    line += char; size += count;
+  }
+  lines.push(line);
+  return lines;
+}

package/src/util.mjs

@@ -0,0 +1,107 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export class CiteArkError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "CiteArkError";
+    this.exitCode = options.exitCode ?? 1;
+    this.retryable = options.retryable;
+    this.failureCode = options.failureCode;
+    this.failureCategory = options.failureCategory;
+    this.retryDisposition = options.retryDisposition;
+    this.failureOwner = options.failureOwner;
+    this.recoveryAction = options.recoveryAction;
+  }
+}
+
+export async function pathExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJson(target) {
+  let raw;
+  try {
+    raw = await readFile(target, "utf8");
+  } catch (error) {
+    throw new CiteArkError(`无法读取 JSON 文件：${target}`, { cause: error });
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new CiteArkError(`JSON 格式无效：${target}\n${error.message}`, {
+      cause: error,
+    });
+  }
+}
+
+export async function writeJson(target, value) {
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function createRunId(now = new Date()) {
+  const stamp = now.toISOString().replaceAll(/[-:.TZ]/g, "").slice(0, 14);
+  return `car_${stamp}_${randomBytes(4).toString("hex")}`;
+}
+
+export function createSessionId() {
+  return randomUUID();
+}
+
+export async function sha256File(target) {
+  const hash = createHash("sha256");
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(target);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", resolve);
+  });
+  return hash.digest("hex");
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(sortCanonical(value));
+}
+
+export function sha256Value(value) {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+
+function sortCanonical(value) {
+  if (Array.isArray(value)) return value.map(sortCanonical);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, sortCanonical(value[key])]),
+  );
+}
+
+export function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:=+-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+export function printableCommand(command, args) {
+  return [command, ...args].map(shellQuote).join(" ");
+}
+
+export function safeRelativePath(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  if (path.isAbsolute(value)) return false;
+  const normalized = path.normalize(value);
+  return normalized !== ".." && !normalized.startsWith(`..${path.sep}`);
+}