@evanbobo/colco 0.0.0-stage → 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 evanbobo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,9 @@
+@evanbobo/colco
+
+The rules for reading Claude Code and Codex session logs (which lines carry usage, how repeated lines,
+mirrored token_count notifications and subagent replays of a parent's history are deduplicated, and how
+each agent's token fields relate to cache and reasoning tokens) follow the documentation and behaviour of
+Tokei (https://github.com/cclank/tokei), published under the MIT License. No Tokei source code is included.
+
+The skill folder layout and agent names follow the skills CLI (https://github.com/vercel-labs/skills),
+MIT License.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @evanbobo/colco
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Colco (叩叩) collaboration skill for coding agents. It also records which models and how many
+tokens each task used, counted from the agent's own session log on your machine.
+
+## Install
+
+```bash
+npx @evanbobo/colco add
+```
+
+The installer lists the supported agents, preselects the ones it finds, and asks:
+
+1. **Agents:** Claude Code (`claude-code`) and Codex (`codex`).
+2. **Scope:** global, for every project (the default), or only the current project.
+3. **Method:** link each agent's skills folder to one shared copy (the default), or copy the files.
+4. **Colco server address**, and an **API key** created on Colco's Agent page (sidebar, Collaboration
+   group). The key is checked with `whoami` and saved in `~/.colco/config.json`, readable only by you. If
+   `COLCO_AGENT_TOKEN` is set, it is used instead and nothing is saved.
+
+Without prompts (CI, scripts, or an agent installing it for you):
+
+```bash
+COLCO_AGENT_TOKEN=colco_… npx @evanbobo/colco add -a claude-code -a codex --server https://colco.example.com -y
+```
+
+| Agent | Skill folder (global) | Skill folder (project) |
+|---|---|---|
+| Claude Code | `~/.claude/skills/colco` (link) | `.claude/skills/colco` |
+| Codex | `~/.agents/skills/colco` (the shared copy) | `.agents/skills/colco` |
+
+Restart the agent after installing. `colco list` shows what is installed, and `colco remove` uninstalls it.
+
+## Task usage
+
+The skill tells the agent to start and finish tasks with the CLI:
+
+```bash
+colco task start 12     # task 12 → in progress
+colco task done 12      # task 12 → done, then report this session's models and tokens
+colco report --dry-run  # preview without sending
+```
+
+How the numbers are counted:
+
+1. **Task boundaries come from the `colco task` commands.** `colco task start` and `colco task done` record
+   each moment in `~/.colco/markers.jsonl` (readable only by you), with the agent and its session. A task's
+   span runs from its start to its done, or until another task starts. Changing a status anywhere else (the
+   web page, `colco call update_task`) does not move the span. Tokens outside any span are reported as
+   unassigned and not counted toward a task.
+2. **Subagents** count toward the task that was active in their parent when they were started. A subagent
+   that runs `colco task start` itself counts toward that task from then on: the command prints a marker id,
+   and the report finds it in the subagent's own log.
+3. **Repeated reports never add up.** Each report rescans the whole session, including subagents, and
+   replaces what was sent for that task and session before.
+4. **Nothing is written into the agent's files.** The CLI only reads the agent's logs, so it cannot affect a
+   session or its prompt cache.
+
+Token fields: `input` excludes cache reads and writes, `output` includes reasoning, and `total` is input,
+output, cache read and cache write added together.
+
+## Finding the project for a code directory
+
+```bash
+colco project          # projects that use this directory's repository; * marks the current branch
+colco project --json   # the same as JSON
+```
+
+The command reads the directory's git remote (`origin`, or the first remote when there is no origin) and
+the current branch, removes any user name, password or token from the remote, and asks Colco which of your
+projects use that repository. Projects that use the current branch come first. Repositories belong to the
+whole organization, so one repository can serve several projects, each on its own branch. A project owner
+links them on the project's 仓库 tab or with `link_repository`. When nothing matches, the command says so
+and points to `list_projects`.
+
+## Other commands
+
+```bash
+colco whoami                                  # check the connection
+colco call get_task_usage '{"task_id": 12}'   # run any Colco tool with the saved key
+```
+
+Requires Node.js 20 or later, and Codex 0.163 or later (earlier versions do not log per-response usage). MIT License; see NOTICE for credits.

package/bin/colco.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@evanbobo/colco",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.18.0",
+  "description": "Colco (叩叩) collaboration skill for coding agents, with per-task model and token reporting from local session logs",
+  "type": "module",
+  "bin": {
+    "colco": "bin/colco.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "colco",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "token-usage"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/agents/claude-code.mjs

@@ -0,0 +1,135 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { homeDir } from "../home.mjs";
+import { count, readJsonl, timeOf } from "../usage/jsonl.mjs";
+
+/*
+ * Claude Code. A session is `<config>/projects/<project>/<session>.jsonl`, with each subagent in
+ * `<session>/subagents/agent-<id>.jsonl` next to `agent-<id>.meta.json`, whose toolUseId names the call that
+ * started it. Every assistant line carries `message.usage`; one response is written once per content block,
+ * so lines are counted once per message id and request id, and a subagent's copies of its parent's
+ * messages are dropped (rules follow tokei's CALCULATION.md). `input_tokens` excludes cache reads and writes;
+ * thinking is part of `output_tokens`.
+ */
+
+/** Claude Code's configuration directory. */
+function configDir(env) {
+  return env.CLAUDE_CONFIG_DIR || join(homeDir(env), ".claude");
+}
+
+export const claudeCode = {
+  name: "claude-code",
+  displayName: "Claude Code",
+  /** Whether Claude Code is installed for this user. */
+  detect: (env = process.env) => existsSync(configDir(env)),
+  /** Where its skills live, globally and inside a project. */
+  globalSkillsDir: (env = process.env) => join(configDir(env), "skills"),
+  projectSkillsDir: ".claude/skills",
+  /** The current session's transcript, when this runs inside Claude Code. */
+  currentSession(env = process.env) {
+    const id = env.CLAUDE_CODE_SESSION_ID;
+    return id ? findTranscript(id, env) : null;
+  },
+  findSession: (id, env = process.env) => findTranscript(id, env),
+  /** The session id is the transcript's file name. */
+  sessionId: (path) => basename(path, ".jsonl"),
+  read: (path) => readClaudeSession(path),
+};
+
+/** Finds `<session>.jsonl` under any project folder. */
+function findTranscript(sessionId, env) {
+  if (!/^[A-Za-z0-9-]{8,80}$/.test(sessionId)) return null;
+  const projects = join(configDir(env), "projects");
+  if (!existsSync(projects)) return null;
+  for (const project of readdirSync(projects)) {
+    const candidate = join(projects, project, `${sessionId}.jsonl`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Reads one transcript file into a stream (without parent information); `spawns` maps tool calls to their time. */
+function readStream(path, id) {
+  const events = [];
+  const spawns = new Map();
+  for (const row of readJsonl(path)) {
+    const at = timeOf(row.timestamp);
+    if (at === null) continue;
+    const message = row.message && typeof row.message === "object" ? row.message : null;
+    const content = Array.isArray(message?.content) ? message.content : [];
+    if (row.type === "assistant" && message) {
+      for (const block of content) {
+        if (block?.type === "tool_use" && typeof block.id === "string") spawns.set(block.id, at);
+      }
+      const usage = message.usage;
+      if (usage && typeof message.model === "string" && message.model !== "<synthetic>") {
+        events.push({
+          id: `${message.id ?? row.uuid}|${row.requestId ?? ""}`,
+          at, model: message.model, sidechain: row.isSidechain === true,
+          input: count(usage.input_tokens), output: count(usage.output_tokens),
+          cacheRead: count(usage.cache_read_input_tokens), cacheWrite: count(usage.cache_creation_input_tokens), reasoning: 0,
+        });
+      }
+    }
+  }
+  return { id, path, events: keepLargest(events), spawns };
+}
+
+/** Tokens of one event, for choosing among repeated lines. */
+const size = (event) => event.input + event.output + event.cacheRead + event.cacheWrite;
+
+/** One event per id; for repeated lines the largest usage wins (it is the most complete), the later on a tie. */
+function keepLargest(events) {
+  const byId = new Map();
+  for (const event of events) {
+    const existing = byId.get(event.id);
+    if (!existing || size(event) >= size(existing)) byId.set(event.id, event);
+  }
+  return [...byId.values()];
+}
+
+/** Reads a session and its subagents into streams for attributeSession. */
+export function readClaudeSession(path) {
+  const sessionId = basename(path, ".jsonl");
+  const main = readStream(path, "main");
+  const streams = [main];
+  const subagentDir = join(dirname(path), sessionId, "subagents");
+  if (existsSync(subagentDir) && statSync(subagentDir).isDirectory()) {
+    for (const file of readdirSync(subagentDir).sort()) {
+      if (!file.endsWith(".jsonl")) continue;
+      const agentId = file.slice(0, -".jsonl".length);
+      const stream = readStream(join(subagentDir, file), agentId);
+      const meta = readMeta(join(subagentDir, `${agentId}.meta.json`));
+      stream.toolUseId = typeof meta?.toolUseId === "string" ? meta.toolUseId : null;
+      streams.push(stream);
+    }
+  }
+
+  const seen = new Set(main.events.map((event) => event.id));
+  for (const stream of streams) {
+    if (stream === main) {
+      stream.parent = null;
+      stream.spawnAt = null;
+      continue;
+    }
+    const owner = streams.find((candidate) => candidate !== stream && stream.toolUseId && candidate.spawns.has(stream.toolUseId));
+    stream.parent = owner ? owner.id : "main";
+    stream.spawnAt = owner ? owner.spawns.get(stream.toolUseId) : Math.min(...stream.events.map((event) => event.at), Infinity);
+    if (!Number.isFinite(stream.spawnAt)) stream.spawnAt = null;
+    stream.events = stream.events.filter((event) => {
+      if (seen.has(event.id)) return false;
+      seen.add(event.id);
+      return true;
+    });
+  }
+  return { sessionId, streams: streams.map(({ id, path, parent, spawnAt, events }) => ({ id, path, parent, spawnAt, markers: [], events })) };
+}
+
+/** Reads a subagent's meta.json, or null. */
+function readMeta(path) {
+  try {
+    return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : null;
+  } catch {
+    return null;
+  }
+}

package/src/agents/codex.mjs

@@ -0,0 +1,191 @@
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homeDir } from "../home.mjs";
+import { count, readJsonl, timeOf } from "../usage/jsonl.mjs";
+
+/*
+ * Codex. A session is `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<time>-<thread id>.jsonl`; a subagent or fork
+ * is its own rollout whose session_meta names the parent thread. Usage comes from `token_usage_record`, one
+ * per response, which Codex 0.163 and later write. A child rollout first replays its parent's history, so
+ * records owned by another thread are skipped (rules follow tokei's CALCULATION.md). `input_tokens`
+ * includes cached input and `output_tokens` includes reasoning.
+ */
+
+/** Codex's home directory. */
+function codexHome(env) {
+  return env.CODEX_HOME || join(homeDir(env), ".codex");
+}
+
+/** Folders that hold rollouts, live and archived. */
+function sessionRoots(env) {
+  return [join(codexHome(env), "sessions"), join(codexHome(env), "archived_sessions")];
+}
+
+export const codex = {
+  name: "codex",
+  displayName: "Codex",
+  /** Whether Codex is installed for this user. */
+  detect: (env = process.env) => existsSync(codexHome(env)) || existsSync("/etc/codex"),
+  /** Codex reads user skills from ~/.agents/skills and project skills from .agents/skills. */
+  globalSkillsDir: (env = process.env) => join(homeDir(env), ".agents", "skills"),
+  projectSkillsDir: ".agents/skills",
+  /** The current session's rollout, when this runs inside Codex (shell commands get CODEX_THREAD_ID). */
+  currentSession(env = process.env) {
+    const id = env.CODEX_THREAD_ID;
+    return id ? rootRollout(id, sessionRoots(env)) : null;
+  },
+  findSession: (id, env = process.env) => rootRollout(id, sessionRoots(env)),
+  /** The thread id in a rollout's file name. */
+  sessionId: (path) => /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i.exec(path)?.[1] ?? null,
+  read: (path, env = process.env) => readCodexSession(path, { sessionRoots: sessionRoots(env) }),
+};
+
+/** Every rollout file under the roots, newest folders first. */
+function listRollouts(roots) {
+  const files = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory() && depth < 5) walk(full, depth + 1);
+      else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name)) files.push(full);
+    }
+  };
+  for (const root of roots) walk(root, 0);
+  return files.sort().reverse();
+}
+
+/** Finds the rollout of one thread id. */
+function findRollout(threadId, roots) {
+  if (!/^[A-Za-z0-9-]{8,80}$/.test(threadId)) return null;
+  return listRollouts(roots).find((file) => file.endsWith(`-${threadId}.jsonl`)) ?? null;
+}
+
+/**
+ * The rollout of the top thread above `threadId`. A subagent's shell sees its own thread id; reporting
+ * from the top thread (which includes every child) keeps one session id per tree, so nothing counts twice.
+ */
+function rootRollout(threadId, roots) {
+  let path = findRollout(threadId, roots);
+  const seen = new Set();
+  while (path && !seen.has(path) && seen.size < 1000) {
+    seen.add(path);
+    const parent = parentOf(headMeta(path)?.meta);
+    const parentPath = parent ? findRollout(parent, roots) : null;
+    if (!parentPath) break;
+    path = parentPath;
+  }
+  return path;
+}
+
+/** The parent thread a session_meta payload names, if any. */
+function parentOf(meta) {
+  const spawn = meta?.source?.subagent?.thread_spawn;
+  return meta?.forked_from_id || meta?.parent_thread_id || (spawn && typeof spawn === "object" ? spawn.parent_thread_id : null) || null;
+}
+
+/** Reads only the session_meta line at the top of a rollout, without loading the whole file. */
+function headMeta(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+    const buffer = Buffer.alloc(256 * 1024);
+    const length = readSync(fd, buffer, 0, buffer.length, 0);
+    for (const line of buffer.subarray(0, length).toString("utf8").split("\n").slice(0, 20)) {
+      if (!line.includes('"session_meta"')) continue;
+      try {
+        const row = JSON.parse(line);
+        if (row.type === "session_meta") return { meta: row.payload ?? {}, at: timeOf(row.timestamp) };
+      } catch {
+        // The meta line can exceed the buffer when it embeds long instructions; then it is unreadable here.
+      }
+    }
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+  return null;
+}
+
+/** Usage of one Codex token record, in the shared shape. */
+function usageOf(usage) {
+  const input = count(usage.input_tokens);
+  const cacheRead = count(usage.cached_input_tokens);
+  // cache_write_input_tokens has been 0 in every log seen so far; it is treated as part of input_tokens like cached.
+  const cacheWrite = count(usage.cache_write_input_tokens);
+  return { input: Math.max(0, input - cacheRead - cacheWrite), output: count(usage.output_tokens), cacheRead, cacheWrite, reasoning: count(usage.reasoning_output_tokens) };
+}
+
+/**
+ * Reads one rollout into a stream. Codex logs each response as a `token_usage_record` keyed by response_id
+ * (it also writes a legacy `token_count` copy, which is ignored). A child rollout first replays its parent's
+ * history, whose records name the parent's thread_id, so only this thread's own records count.
+ */
+function readStream(path) {
+  const rows = readJsonl(path);
+  const metaRow = rows.find((row) => row.type === "session_meta");
+  const meta = metaRow?.payload ?? {};
+  const id = meta.id || meta.session_id || path;
+  const events = [];
+  const responses = new Set();
+  let model = "unknown";
+  for (const row of rows) {
+    const at = timeOf(row.timestamp);
+    const payload = row.payload && typeof row.payload === "object" ? row.payload : {};
+    if (at === null) continue;
+    if (row.type === "turn_context") {
+      model = payload.model || payload.collaboration_mode?.settings?.model || model;
+    } else if (row.type === "token_usage_record") {
+      if (payload.thread_id && payload.thread_id !== id) continue;
+      if (!payload.usage || typeof payload.usage !== "object") continue;
+      const key = payload.response_id ? String(payload.response_id) : `${at}|${events.length}`;
+      if (responses.has(key)) continue;
+      responses.add(key);
+      events.push({ id: key, at, model, ...usageOf(payload.usage) });
+    }
+  }
+  return { id, path, parent: parentOf(meta), spawnAt: timeOf(metaRow?.timestamp), markers: [], events };
+}
+
+/**
+ * Reads a session and every subagent or fork below it into streams for attributeSession. Children are
+ * found by scanning rollouts written after the session started for a session_meta naming a known thread.
+ */
+export function readCodexSession(path, { sessionRoots: roots }) {
+  const main = readStream(path);
+  const streams = [{ ...main, parent: null, spawnAt: null }];
+  const known = new Set([main.id]);
+  const startedAt = main.spawnAt ?? 0;
+  const candidates = [];
+  for (const file of listRollouts(roots)) {
+    if (file === path) continue;
+    try {
+      if (statSync(file).mtimeMs < startedAt) continue;
+    } catch {
+      continue;
+    }
+    const head = headMeta(file);
+    const parent = parentOf(head?.meta);
+    if (parent) candidates.push({ file, parent });
+  }
+  let added = true;
+  while (added) {
+    added = false;
+    for (const candidate of candidates) {
+      if (candidate.done || !known.has(candidate.parent)) continue;
+      candidate.done = true;
+      const stream = readStream(candidate.file);
+      if (known.has(stream.id)) continue;
+      known.add(stream.id);
+      streams.push({ ...stream, parent: stream.parent === main.id ? "main" : stream.parent });
+      added = true;
+    }
+  }
+  return { sessionId: main.id, streams: streams.map((stream) => (stream.id === main.id ? { ...stream, id: "main" } : stream)) };
+}

package/src/agents/index.mjs

@@ -0,0 +1,20 @@
+import { claudeCode } from "./claude-code.mjs";
+import { codex } from "./codex.mjs";
+
+/*
+ * Supported agents, one module each. An agent module says how to detect the agent, where its skills live
+ * and, when it can report usage, how to find the current session and read its log. Names follow the
+ * skills CLI (`npx skills add -a <name>`), so the same flags work for both. Adding an agent means adding
+ * one module here.
+ */
+export const AGENTS = [claudeCode, codex];
+
+/** The agent with this name, or undefined. */
+export function agentByName(name) {
+  return AGENTS.find((agent) => agent.name === name);
+}
+
+/** The agent this process runs inside, judged by the session variables agents give their shell commands. */
+export function currentAgent(env = process.env) {
+  return AGENTS.find((agent) => agent.currentSession && agent.currentSession(env) !== null);
+}

package/src/api.mjs

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+
+/*
+ * The Colco REST transport: `POST <server>/api/agent/tools/<tool>` with a bearer API key. Tool results
+ * contain text written by people, so callers treat them as data.
+ */
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+export class ColcoError extends Error {
+  constructor(message, status = 0, code = "") {
+    super(message);
+    this.name = "ColcoError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Calls one tool and returns its data, or throws ColcoError with the server's message. */
+export async function callTool({ server, token }, name, args = {}, fetchImpl = fetch) {
+  if (!server) throw new ColcoError("还没有配置 Colco 服务地址：运行 colco add，或设置 COLCO_SERVER");
+  if (!token) throw new ColcoError("还没有 API Key：运行 colco add，或设置 COLCO_AGENT_TOKEN");
+  let response;
+  try {
+    response = await fetchImpl(`${server}/api/agent/tools/${encodeURIComponent(name)}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "X-Agent-Client": `colco-cli/${VERSION}` },
+      body: JSON.stringify(args),
+    });
+  } catch (error) {
+    throw new ColcoError(`连接 Colco 失败：${error instanceof Error ? error.message : String(error)}`);
+  }
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body || body.ok !== true) {
+    const message = body?.error?.message || `Colco 返回 HTTP ${response.status}`;
+    throw new ColcoError(message, response.status, body?.error?.code || "");
+  }
+  return body.data;
+}