copyrun 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Copyrun, Inc.
+
+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/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# copyrun
 
-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.
+A copy of you that runs your agents. Copy. Run.
+
+Every time you allow or stop a step an agent wants to take, copyrun records the decision and your reason, on your machine. `npx copyrun copy` is the version of your judgment built from that record: it answers your agents the way you would where its own score proves it (repeating your refusals, never allowing migrations, auth, secrets, CI, dependencies or deletes alone), turns what you decide again and again into rules every agent reads (`copy rules --write`), and exports as one signed file you can take to your next job. `copy skills` counts how you solve problems with agents from the sessions on this machine (framing, decomposition, verification, recovery), and `copy compare @someone/slice` replays someone's published rules over your own decisions, or your team's.
+
+`npx copyrun on` puts every agent acting as you on one screen at copyrun.ai/mission, whoever made it: which agent, in which project, what it's doing this second, which one is waiting for you, and a Stop. Claude Code, Codex and Cursor report through their hooks; Gemini CLI, OpenCode, OpenClaw, Aider, Goose, Amp and Copilot CLI are seen by their process; anything else reports with `npx copyrun beat`. The hooks send the agent, the folder name and the kind of step, never a path, a prompt, code or output.
+
+When an agent reaches a step it shouldn't take alone (a migration, a change to auth, secrets or CI, a new dependency, a delete), `npx copyrun setup --ask` pauses it until you Allow or Stop from any browser, and no answer in time means Stop.
+
+The CLI also turns a coding-agent session (Claude Code, Codex, Cursor) into a signed record that shows what the agent actually did: the prompts, the commands it ran, the files it changed and whether the tests passed. Attach it to a pull request as the receipt so reviewers can check the work, and let your agent reuse what worked for you last time.
+
+## Install
+
+Requires Node.js 20 or later.
+
+```sh
+npx copyrun --help
+```
+
+Or install it globally:
+
+```sh
+npm install -g copyrun
+```
+
+## Usage
+
+```sh
+copyrun on                  # every agent acting as you on one screen (copyrun.ai/mission); copyrun off; copyrun watch; copyrun beat
+copyrun                     # the debrief: what your agent actually did in the last session here (claims vs test runs, where to look)
+copyrun why <file>:<line>   # which prompt wrote this line: git blame for agent code
+copyrun week                # your agents this week, from the sessions on this machine
+copyrun share               # share the latest session from this project
+copyrun pr                  # add it to this branch's pull request
+copyrun check               # check the agent's claims against what it ran
+copyrun resume --with codex # another agent picks up where the last session stopped
+copyrun search "<task>"     # find runs that did a similar task
+copyrun clone <id|url>      # install a run's recipe as a skill in this project
+copyrun worked <id|url>     # report that a cloned run worked (or: copyrun failed)
+```
+
+Run `copyrun help <command>` for a command's options, or `copyrun help --all` for the full list.
+
+### Sharing a session
+
+```sh
+copyrun share --dry-run
+```
+
+Before anything is uploaded, copyrun redacts the session on your machine: API keys, tokens, `.env` values, credentials in URLs, email addresses, home-directory paths and your username. It shows every removal, lists anything else that might identify you or your employer (company names, internal hosts, ticket ids) and asks before publishing. A session containing a private key is never uploaded.
+
+You choose who can see the run:
+
+| Flag | Visibility |
+| --- | --- |
+| `--private` | Only you. Requires `copyrun login`. |
+| `--unlisted` | Anyone with the link. |
+| `--public` | Listed and searchable. Never the default. |
+
+`--shape` shares the prompts, commands and results without file contents or diffs.
+
+### Pull requests
+
+`copyrun pr` adds a short block to the pull request description with a link to the run, whether it was signed by your device, which checks the session ran and how much of the diff it wrote. The diff comparison runs locally with git. It uses the [GitHub CLI](https://cli.github.com) to edit the PR; `copyrun pr --print` prints the block instead.
+
+Maintainers can install the [copyrun GitHub App](https://copyrun.ai/docs/github-app) to add a check to pull requests.
+
+### What did my agent actually do?
+
+`copyrun` with no arguments, inside a project an agent worked in, reads the last session on this machine and prints one screen: what you asked, what the agent said, its closing claims against the session's own test, build and lint runs, where to look before you ship (files changed after the last test, tests removed, sensitive changes), the files it changed, the files no prompt names, the times you corrected it, and the tokens it used. Nothing is uploaded and no account is needed. `copyrun last <session>` does the same for any session; the exit code is 2 when a claim is contradicted.
+
+`copyrun why <file>:<line>` is git blame for agent code: the session step that wrote the line, the prompt before it and what the agent said just before, from the sessions that ran in this repository. `copyrun why <file>` lists every stretch a session wrote. A line edited by hand since matches nothing, so "no session wrote this line" is a floor.
+
+`copyrun week` is your agents this week: sessions per agent, how often one said "tests pass" when the last run failed, changes that never ran a test, your corrections and tokens, against the week before. Counts only, nothing uploaded.
+
+### Checking claims
+
+`copyrun check` reads the latest session and flags claims that don't match what happened, such as "all tests pass" when the last test run failed. It runs entirely locally and needs no account. Add `--strict` to exit with a non-zero code for use in CI or git hooks.
+
+### Handing a session to another agent
+
+`copyrun resume --with <claude|codex|cursor>` takes the latest session in this folder (or a session id, or a run you can open) and starts the other agent with a handoff: your request, your corrections as rules, the files changed, the last checks, where it stopped and where to look. It's quoted as data and redacted like a share, the agent shows a plan before changing files, and nothing is uploaded. `--print` prints the handoff instead. Very long sessions are read from their start and their last 24 MB.
+
+### Signing in
+
+```sh
+copyrun login
+```
+
+Signing in links shares to your profile and signs them with a key stored on this machine, so the run page can show it as Verified.
+
+## Configuration
+
+| Variable | Description |
+| --- | --- |
+| `COPYRUN_API` | Server URL. Defaults to `https://copyrun.ai`. |
+| `COPYRUN_HOME` | State directory. Defaults to `~/.copyrun`. |
+
+## Documentation
+
+Full documentation is at [copyrun.ai/docs](https://copyrun.ai/docs). For questions and feedback, join the [community](https://copyrun.ai/community) or email hello@copyrun.ai.
+
+## License
+
+[MIT](LICENSE)

package/dist/archive-hook.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+// src/archive-hook.ts
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { dirname, join as join3 } from "path";
+import { fileURLToPath } from "url";
+
+// src/archive-logic.ts
+var ARCHIVE_WORKER_SCRIPT = "archive-worker.mjs";
+var ARCHIVE_SETTINGS_FILE = "archive.json";
+var ARCHIVE_SPAWN_FILE = "archive-spawn.json";
+var PENDING_DIR = "archive-pending";
+var IDLE_MS = 10 * 60 * 1e3;
+var SPAWN_THROTTLE_MS = 10 * 60 * 1e3;
+var MAX_BODY_BYTES = 25 * 1024 * 1024;
+var LOCK_STALE_MS = 15 * 60 * 1e3;
+var MAX_BACKOFF_MS = 6 * 60 * 60 * 1e3;
+var isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var archiveActive = (s) => !!s && s.available && s.archive.enabled;
+function hookShouldRecord(s, consented) {
+  if (!s) return true;
+  if (!(archiveActive(s) && s.archive.includeAll)) return false;
+  return !consented || consented.includeAll;
+}
+function safeId(s) {
+  return s.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || "unknown";
+}
+function pointerName(p, cwdKey2) {
+  const id = p.sessionId ? safeId(p.sessionId) : `cwd-${cwdKey2(p.cwd ?? "")}`;
+  return `${p.tool === "claude-code" ? "cc" : p.tool}-${id}.json`;
+}
+function claudeHookInput(raw) {
+  if (!isObj(raw)) return {};
+  const str = (v) => typeof v === "string" && v.length < 4096 ? v : void 0;
+  return { sessionId: str(raw.session_id), transcriptPath: str(raw.transcript_path), cwd: str(raw.cwd) };
+}
+function codexNotifyInput(raw) {
+  if (!isObj(raw)) return void 0;
+  if (raw.type !== void 0 && raw.type !== "agent-turn-complete") return void 0;
+  const str = (v) => typeof v === "string" && v.length < 4096 ? v : void 0;
+  return { sessionId: str(raw["thread-id"]) ?? str(raw["session-id"]) ?? str(raw.thread_id), cwd: str(raw.cwd) };
+}
+function mergePointer(prev, next, now) {
+  return {
+    v: 1,
+    ...prev,
+    ...Object.fromEntries(Object.entries(next).filter(([, v]) => v !== void 0)),
+    ended: !!prev?.ended || next.ended,
+    firstSeen: prev?.firstSeen ?? now,
+    updatedAt: now
+  };
+}
+
+// src/archive-hook-core.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/session-seal.ts
+import { createHash, createPrivateKey, sign } from "crypto";
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+var SEAL_QUEUE_DIR = "seal-queue";
+var SEAL_LOG_FILE = "session-seals.json";
+var HOOK_MAX_BYTES = 64 * 1024 * 1024;
+var SEAL_SPAWN_THROTTLE_MS = 5 * 60 * 1e3;
+var sessionSealMessage = (hex) => `copyrun-session-v1:${hex}`;
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function writeJsonAtomic(path, value) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value), { mode: 384 });
+  renameSync(tmp, path);
+}
+var safe = (s) => s.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || "unknown";
+function deviceOf(dir) {
+  const d = readJson(join(dir, "config.json"))?.device;
+  return d && typeof d.privateKey === "string" && typeof d.token === "string" && typeof d.api === "string" ? d : void 0;
+}
+function sealingEnabled(dir) {
+  const cfg = readJson(join(dir, "config.json"));
+  if (!cfg || cfg.sealSessions === false) return false;
+  return cfg.sealSessions === true || !!cfg.archive;
+}
+function fileSha256(path, max = Infinity) {
+  let fd;
+  try {
+    const st = statSync(path);
+    if (!st.isFile() || st.size > max) return void 0;
+    fd = openSync(path, "r");
+  } catch {
+    return void 0;
+  }
+  try {
+    const h = createHash("sha256");
+    const buf = Buffer.alloc(1 << 20);
+    let bytes = 0;
+    for (; ; ) {
+      const n = readSync(fd, buf, 0, buf.length, null);
+      if (!n) break;
+      h.update(buf.subarray(0, n));
+      bytes += n;
+    }
+    return { sha256: h.digest("hex"), bytes };
+  } catch {
+    return void 0;
+  } finally {
+    closeSync(fd);
+  }
+}
+function readSealLog(dir) {
+  const v = readJson(join(dir, SEAL_LOG_FILE));
+  return Array.isArray(v) ? v.filter((e) => e && typeof e.sha256 === "string") : [];
+}
+var signWith = (message, privateKeyPem) => sign(null, Buffer.from(message, "utf8"), createPrivateKey(privateKeyPem)).toString("base64");
+function queueSeal(dir, r, now = Date.now()) {
+  const qdir = join(dir, SEAL_QUEUE_DIR);
+  mkdirSync(qdir, { recursive: true, mode: 448 });
+  const name = `${r.kind}-${safe(r.kind === "session" && r.sessionId ? r.sessionId : r.sha256)}.json`;
+  const at = new Date(now).toISOString();
+  writeJsonAtomic(join(qdir, name), { v: 1, ...r, createdAt: at, attempts: 0, nextAttemptAt: at });
+  return join(qdir, name);
+}
+function queueSessionSeal(dir, s) {
+  if (!s.force && !sealingEnabled(dir)) return { queued: false, reason: "disabled" };
+  const device = deviceOf(dir);
+  if (!device) return { queued: false, reason: "not-logged-in" };
+  const f = fileSha256(s.transcriptPath, s.maxBytes ?? HOOK_MAX_BYTES);
+  if (!f) return { queued: false, reason: "unreadable" };
+  if (readSealLog(dir).some((e) => e.kind === "session" && e.sha256 === f.sha256 && e.api === device.api)) return { queued: false, reason: "already-sealed" };
+  const path = queueSeal(
+    dir,
+    { kind: "session", sha256: f.sha256, bytes: f.bytes, sessionId: s.sessionId, tool: s.tool, signature: signWith(sessionSealMessage(f.sha256), device.privateKey), publicKey: device.publicKey, api: device.api },
+    s.now
+  );
+  return { queued: true, sha256: f.sha256, bytes: f.bytes, path };
+}
+
+// src/archive-hook-core.ts
+function readJson2(path) {
+  try {
+    return JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function writeJsonAtomic2(path, value) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync2(tmp, JSON.stringify(value), { mode: 384 });
+  renameSync2(tmp, path);
+}
+var cwdKey = (cwd) => createHash2("sha256").update(cwd).digest("hex").slice(0, 16);
+function runHook(event, input, o) {
+  const now = o.now ?? Date.now();
+  const cfg = readJson2(join2(o.dir, "config.json"))?.archive;
+  if (!cfg || typeof cfg.org !== "string" || typeof cfg.api !== "string") return { spawned: false, skipped: "not-set-up" };
+  const cache = readJson2(join2(o.dir, ARCHIVE_SETTINGS_FILE))?.[`${cfg.api}|${cfg.org}`];
+  let pointer;
+  let skipped;
+  const fields = event === "codex" ? codexNotifyInput(input) : (() => {
+    const c = claudeHookInput(input);
+    return c.sessionId || c.transcriptPath ? c : void 0;
+  })();
+  if (!fields) skipped = event === "codex" ? "bad-input" : "no-session";
+  else if (!hookShouldRecord(cache, cfg.scope)) skipped = "not-archived";
+  else {
+    const tool = event === "codex" ? "codex" : "claude-code";
+    const dir = join2(o.dir, PENDING_DIR);
+    mkdirSync2(dir, { recursive: true, mode: 448 });
+    const name = pointerName({ tool, sessionId: fields.sessionId, cwd: fields.cwd }, cwdKey);
+    const path = join2(dir, name);
+    const prev = readJson2(path);
+    const next = mergePointer(
+      prev && prev.v === 1 ? prev : void 0,
+      { tool, org: cfg.org, api: cfg.api, sessionId: fields.sessionId, transcriptPath: fields.transcriptPath, cwd: fields.cwd, ended: event === "session-end" },
+      new Date(now).toISOString()
+    );
+    writeJsonAtomic2(path, next);
+    pointer = path;
+  }
+  let sealed;
+  const transcript = fields?.transcriptPath;
+  if (transcript && event !== "codex") {
+    try {
+      sealed = queueSessionSeal(o.dir, { transcriptPath: transcript, sessionId: fields?.sessionId, tool: "claude-code", now });
+    } catch {
+    }
+  }
+  const spawnPath = join2(o.dir, ARCHIVE_SPAWN_FILE);
+  const last = readJson2(spawnPath)?.at ?? 0;
+  const due = event === "session-end" || !(last <= now && now - last < SPAWN_THROTTLE_MS);
+  let spawned = false;
+  if (due) {
+    try {
+      writeJsonAtomic2(spawnPath, { at: now });
+    } catch {
+    }
+    o.spawnWorker();
+    spawned = true;
+  }
+  return { pointer, spawned, ...skipped ? { skipped } : {}, ...sealed ? { seal: sealed } : {} };
+}
+
+// src/archive-hook.ts
+var DIR = dirname(fileURLToPath(import.meta.url));
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve("");
+    let data = "";
+    const t = setTimeout(() => resolve(data), 500);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (d) => {
+      data += d;
+      if (data.length > 1e6) process.stdin.destroy();
+    });
+    process.stdin.on("end", () => (clearTimeout(t), resolve(data)));
+    process.stdin.on("error", () => (clearTimeout(t), resolve(data)));
+  });
+}
+function spawnWorker() {
+  const worker = join3(DIR, ARCHIVE_WORKER_SCRIPT);
+  if (!existsSync(worker)) return;
+  const child = spawn(process.execPath, [worker], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: { ...process.env, COPYRUN_HOME: DIR }
+  });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+async function main() {
+  const event = process.argv[2];
+  if (event !== "stop" && event !== "session-end" && event !== "codex") return;
+  const raw = event === "codex" ? process.argv[3] ?? "" : await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    input = void 0;
+  }
+  runHook(event, input, { dir: DIR, spawnWorker });
+}
+main().catch(() => {
+}).finally(() => process.exit(0));