@evanbobo/colco 0.0.0-stage → 0.18.0

package/src/prompt.mjs

@@ -0,0 +1,83 @@
+import { createInterface } from "node:readline/promises";
+
+/*
+ * Minimal terminal prompts with no dependencies: a numbered multi-select, a single choice, free text and a
+ * hidden secret. Every prompt has a non-interactive equivalent flag, so agents and CI never need a TTY.
+ */
+
+/** Asks one line of text; Enter keeps the default. */
+export async function ask(question, fallback = "") {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(fallback ? `${question} (${fallback}): ` : `${question}: `)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Numbered multi-select. `options` are `{ value, label, hint, selected }`; the answer is a list such as
+ * "1,3" or "all", and Enter keeps the preselected ones.
+ */
+export async function multiSelect(question, options) {
+  process.stdout.write(`${question}\n`);
+  options.forEach((option, index) => {
+    process.stdout.write(`  ${option.selected ? "[x]" : "[ ]"} ${index + 1}. ${option.label}${option.hint ? `  ${option.hint}` : ""}\n`);
+  });
+  for (;;) {
+    const answer = (await ask("输入编号，逗号分隔；all 表示全部；回车保留已勾选")).toLowerCase();
+    if (!answer) return options.filter((option) => option.selected).map((option) => option.value);
+    if (answer === "all") return options.map((option) => option.value);
+    const picked = answer.split(/[\s,，]+/).filter(Boolean).map(Number);
+    if (picked.length > 0 && picked.every((n) => Number.isInteger(n) && n >= 1 && n <= options.length)) {
+      return [...new Set(picked)].map((n) => options[n - 1].value);
+    }
+    process.stdout.write("编号无效，请重试。\n");
+  }
+}
+
+/** Single choice among `options` (`{ value, label }`); Enter takes the first. */
+export async function choose(question, options) {
+  process.stdout.write(`${question}\n`);
+  options.forEach((option, index) => process.stdout.write(`  ${index + 1}. ${option.label}${index === 0 ? "（默认）" : ""}\n`));
+  for (;;) {
+    const answer = await ask("输入编号", "1");
+    const n = Number(answer);
+    if (Number.isInteger(n) && n >= 1 && n <= options.length) return options[n - 1].value;
+    process.stdout.write("编号无效，请重试。\n");
+  }
+}
+
+/** Reads a secret without echoing it. */
+export function askSecret(question) {
+  return new Promise((resolvePromise, reject) => {
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY) {
+      reject(new Error("需要在终端中输入 API Key，或先设置 COLCO_AGENT_TOKEN"));
+      return;
+    }
+    stdout.write(`${question}: `);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    let value = "";
+    const done = (error) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      stdout.write("\n");
+      if (error) reject(error);
+      else resolvePromise(value.trim());
+    };
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === "\r" || char === "\n") return done();
+        if (char === "\u0003") return done(new Error("已取消"));
+        if (char === "\u007f" || char === "\b") value = value.slice(0, -1);
+        else if (char >= " ") value += char;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}

package/src/usage/attribute.mjs

@@ -0,0 +1,79 @@
+/*
+ * Assigns each usage event of a session to a task. A session is a set of streams: the main conversation
+ * and one per subagent. In every stream the active task changes at its markers: in_progress starts a
+ * task (and ends the one before), any other status ends the active task. A subagent starts with the task
+ * that was active in its parent at the moment the parent started it, and its own markers take over from
+ * then on, without changing the parent. Events with no active task are unassigned.
+ *
+ * Stream: { id, parent, spawnAt, markers: [{ at, taskId, status }], events: [usage event] }
+ * Usage event: { id, at, model, input, output, cacheRead, cacheWrite, reasoning }; times are epoch ms.
+ */
+
+const FIELDS = ["input", "output", "cacheRead", "cacheWrite", "reasoning"];
+
+/** Empty per-model totals. */
+function emptyTotals() {
+  return { calls: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, firstAt: null, lastAt: null };
+}
+
+/** Adds one event to the per-model map. */
+function addEvent(models, event) {
+  const totals = models.get(event.model) ?? emptyTotals();
+  totals.calls += 1;
+  for (const field of FIELDS) totals[field] += event[field];
+  totals.firstAt = totals.firstAt === null ? event.at : Math.min(totals.firstAt, event.at);
+  totals.lastAt = totals.lastAt === null ? event.at : Math.max(totals.lastAt, event.at);
+  models.set(event.model, totals);
+}
+
+/** Applies one marker to the active task id. */
+function applyMarker(active, marker) {
+  if (marker.status === "in_progress") return marker.taskId;
+  return marker.taskId === active ? null : active;
+}
+
+/**
+ * Returns `{ tasks: Map<taskId, Map<model, totals>>, unassigned: Map<model, totals>, taskIds: Set }`.
+ * taskIds lists every task the session started, even one that used no tokens, so a report can clear it.
+ */
+export function attributeSession(streams) {
+  const byId = new Map(streams.map((stream) => [stream.id, stream]));
+  // A subagent's markers from before it started are history it replayed from its parent; they are ignored.
+  const ownMarkers = (stream) => stream.markers.filter((marker) => stream.parent === null || stream.spawnAt === null || marker.at >= stream.spawnAt);
+  const sortedMarkers = new Map(streams.map((stream) => [stream.id, ownMarkers(stream).sort((a, b) => a.at - b.at)]));
+  const memo = new Map();
+
+  /**
+   * The task active in `stream` just before time `at` (a marker in the same millisecond has not taken effect
+   * yet), following parents for the time before the stream's first marker.
+   */
+  function activeAt(stream, at, depth = 0) {
+    const key = `${stream.id}@${at}`;
+    if (memo.has(key)) return memo.get(key);
+    const parent = stream.parent !== null && depth < 1000 ? byId.get(stream.parent) : undefined;
+    let active = parent && stream.spawnAt !== null ? activeAt(parent, stream.spawnAt, depth + 1) : null;
+    for (const marker of sortedMarkers.get(stream.id)) {
+      if (marker.at >= at) break;
+      active = applyMarker(active, marker);
+    }
+    memo.set(key, active);
+    return active;
+  }
+
+  const tasks = new Map();
+  const unassigned = new Map();
+  const taskIds = new Set();
+  for (const stream of streams) {
+    for (const marker of sortedMarkers.get(stream.id)) if (marker.status === "in_progress") taskIds.add(marker.taskId);
+    for (const event of stream.events) {
+      const taskId = activeAt(stream, event.at);
+      if (taskId === null) {
+        addEvent(unassigned, event);
+      } else {
+        if (!tasks.has(taskId)) tasks.set(taskId, new Map());
+        addEvent(tasks.get(taskId), event);
+      }
+    }
+  }
+  return { tasks, unassigned, taskIds };
+}

package/src/usage/jsonl.mjs

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+
+/** Reads a JSONL file into objects, skipping blank and broken lines (agents append while we read). */
+export function readJsonl(path) {
+  const rows = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row && typeof row === "object") rows.push(row);
+    } catch {
+      // A half-written last line or a corrupt line carries no usable usage.
+    }
+  }
+  return rows;
+}
+
+/** Epoch milliseconds of an ISO timestamp, or null. */
+export function timeOf(value) {
+  if (typeof value !== "string") return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** A non-negative integer token count; anything else counts as 0. */
+export function count(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}

package/src/usage/markers.mjs

@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { colcoHome } from "../config.mjs";
+
+/*
+ * Task markers: the moments a session starts or ends work on a Colco task. `colco task start|done` writes
+ * each one to Colco's own file, never to the agent's files, so markers cannot change a session or its prompt
+ * cache. A marker carries a random id that the command also prints; that output lands in the log of whichever
+ * conversation ran it (the main one or a subagent), which is how a report finds where each marker belongs.
+ */
+
+export const TASK_STATUSES = new Set(["backlog", "todo", "in_progress", "blocked", "review", "done"]);
+/** Above this size the file is rewritten without markers older than KEEP_MS. */
+const PRUNE_BYTES = 512 * 1024;
+const KEEP_MS = 180 * 24 * 60 * 60 * 1000;
+
+/** Path of the marker file. */
+export function markersPath(env = process.env) {
+  return join(colcoHome(env), "markers.jsonl");
+}
+
+/** Whether a parsed line is a well-formed marker. */
+function isMarker(value) {
+  return Boolean(value) && typeof value === "object" && typeof value.id === "string" && typeof value.agent === "string"
+    && typeof value.session === "string" && Number.isFinite(value.at) && Number.isSafeInteger(value.taskId) && value.taskId > 0
+    && TASK_STATUSES.has(value.status);
+}
+
+/** Every well-formed marker in the file, oldest first; a broken line is skipped. */
+function readAll(env) {
+  const path = markersPath(env);
+  if (!existsSync(path)) return [];
+  const markers = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const value = JSON.parse(line);
+      if (isMarker(value)) markers.push(value);
+    } catch {
+      // A line cut short by a crash carries no usable marker.
+    }
+  }
+  return markers;
+}
+
+/** Drops markers older than KEEP_MS once the file grows past PRUNE_BYTES. */
+function prune(env, now) {
+  const path = markersPath(env);
+  if (!existsSync(path) || statSync(path).size < PRUNE_BYTES) return;
+  const kept = readAll(env).filter((marker) => marker.at >= now - KEEP_MS);
+  writeFileSync(path, kept.map((marker) => `${JSON.stringify(marker)}\n`).join(""), { mode: 0o600 });
+}
+
+/** Appends one marker for `agent` and `session` and returns it, with its new id. */
+export function recordMarker({ agent, session, taskId, status, at = Date.now() }, env = process.env) {
+  const marker = { id: randomUUID(), agent, session, at, taskId, status };
+  if (!isMarker(marker)) throw new Error("无效的任务标记");
+  const path = markersPath(env);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  prune(env, at);
+  appendFileSync(path, `${JSON.stringify(marker)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return marker;
+}
+
+/** The markers of one agent session, oldest first. */
+export function readMarkers({ agent, session }, env = process.env) {
+  return readAll(env).filter((marker) => marker.agent === agent && marker.session === session).sort((a, b) => a.at - b.at);
+}
+
+/**
+ * Gives each marker to the stream that ran it: a subagent whose log contains the marker's id and that was
+ * already running then (a child that replays its parent's history contains older ids too); the latest
+ * started such subagent wins, since a parent may quote its child's output. Anything else, including a marker
+ * whose output is not logged yet, belongs to the main stream. Streams need `path`, the log file to search.
+ */
+export function assignMarkers(streams, markers) {
+  const texts = new Map();
+  const textOf = (stream) => {
+    if (!texts.has(stream.id)) {
+      try {
+        texts.set(stream.id, stream.path ? readFileSync(stream.path, "utf8") : "");
+      } catch {
+        texts.set(stream.id, "");
+      }
+    }
+    return texts.get(stream.id);
+  };
+  const owned = new Map(streams.map((stream) => [stream.id, []]));
+  const main = streams.find((stream) => stream.parent === null) ?? streams[0];
+  for (const marker of markers) {
+    let owner = null;
+    for (const stream of streams) {
+      if (stream === main || stream.spawnAt === null || marker.at < stream.spawnAt) continue;
+      if (!textOf(stream).includes(marker.id)) continue;
+      if (!owner || stream.spawnAt > owner.spawnAt) owner = stream;
+    }
+    owned.get((owner ?? main).id).push({ at: marker.at, taskId: marker.taskId, status: marker.status });
+  }
+  return streams.map((stream) => ({ ...stream, markers: owned.get(stream.id) }));
+}
+
+/** The line the colco command prints after moving a task; the id ties the agent's log to the marker. */
+export function cliConfirmation(taskId, status, markerId) {
+  return markerId ? `colco: task ${taskId} ${status} (marker ${markerId})` : `colco: task ${taskId} ${status}`;
+}

package/src/usage/report.mjs

@@ -0,0 +1,52 @@
+import { attributeSession } from "./attribute.mjs";
+import { assignMarkers } from "./markers.mjs";
+import { callTool } from "../api.mjs";
+
+/*
+ * Turns a session and its markers into per-task reports and sends them. Every report covers the whole
+ * session as it is on disk now and replaces what was sent for it before, so running a report again only
+ * corrects numbers.
+ */
+
+/** The report_task_usage model entries for one task's per-model totals. */
+function modelEntries(models) {
+  return [...models.entries()]
+    .map(([model, totals]) => ({
+      model, calls: totals.calls, input_tokens: totals.input, output_tokens: totals.output, cache_read_tokens: totals.cacheRead,
+      cache_write_tokens: totals.cacheWrite, reasoning_tokens: Math.min(totals.reasoning, totals.output),
+      first_at: new Date(totals.firstAt).toISOString(), last_at: new Date(totals.lastAt).toISOString(),
+    }))
+    .sort((a, b) => a.model.localeCompare(b.model));
+}
+
+/** Builds one report per task the session's markers mention; `onlyTask` limits the reports to one task. */
+export function buildReports(session, markers, { onlyTask = null } = {}) {
+  const attributed = attributeSession(assignMarkers(session.streams, markers));
+  const taskIds = [...new Set([...attributed.taskIds, ...attributed.tasks.keys(), ...markers.map((marker) => marker.taskId)])]
+    .filter((id) => onlyTask === null || id === onlyTask)
+    .sort((a, b) => a - b);
+  return {
+    sessionId: session.sessionId,
+    reports: taskIds.map((taskId) => ({ taskId, models: modelEntries(attributed.tasks.get(taskId) ?? new Map()) })),
+    unassigned: modelEntries(attributed.unassigned),
+  };
+}
+
+/** Sends every report; one failing task does not stop the others. */
+export async function sendReports(connection, agentName, built, fetchImpl) {
+  const results = [];
+  for (const report of built.reports) {
+    try {
+      await callTool(connection, "report_task_usage", { task_id: report.taskId, agent: agentName, session_id: built.sessionId, models: report.models }, fetchImpl);
+      results.push({ taskId: report.taskId, ok: true });
+    } catch (error) {
+      results.push({ taskId: report.taskId, ok: false, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return results;
+}
+
+/** Sum of the four token kinds over model entries. */
+export function totalTokens(models) {
+  return models.reduce((sum, entry) => sum + entry.input_tokens + entry.output_tokens + entry.cache_read_tokens + entry.cache_write_tokens, 0);
+}