@ccmsg/cli 0.2.13 → 0.3.1

package/src/plugin/receipt.ts

@@ -0,0 +1,202 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { HARNESSES } from "../harness/index.ts";
+import type { InstancePaths } from "../instance/index.ts";
+
+/** The agents ccmsg can install a plugin for, which are the harnesses it
+ * speaks to: what is installed is how a session of that harness reaches this
+ * instance, so there is one plugin per harness and no third thing to name. */
+export const AGENTS = HARNESSES;
+export type Agent = (typeof AGENTS)[number];
+
+/** How an agent's own CLI is run. The environment is inherited, which is how
+ * the install lands in the config home this instance answers for and not in
+ * another one (M6). Named so a test can watch what would be run without a
+ * config home of a person's being touched. */
+export type Run = (args: readonly string[]) => Promise<Ran>;
+
+export interface Ran {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** Why one of these commands stopped where it did: the agent command that was
+ * refused, and what it said. */
+export interface Refusal {
+  readonly command: readonly string[];
+  readonly code: number;
+  readonly said: string;
+}
+
+/** A command the agent refused, as the report carries it: what was run, what it
+ * exited with, and its first line of complaint. The exit code is stated apart
+ * from the words because a command that said nothing still failed. */
+export function refusal(binary: string, command: readonly string[], ran: Ran): Refusal {
+  const said = `${ran.stderr}${ran.stdout}`.trim();
+  return { command: [binary, ...command], code: ran.code, said: said.split("\n")[0] ?? "" };
+}
+
+/** What the three commands answer with.
+ *
+ * Fields rather than sentences: these commands are read by whatever runs them
+ * as much as by a person, and a line of prose is something a caller has to
+ * parse back into the facts it was built from. The words a person wants are in
+ * `--help`; what is here is what was found. */
+export interface Report {
+  readonly agent: Agent;
+  /** Whether the command did everything it set out to do. */
+  readonly ok: boolean;
+  /** The step that stopped it. Absent while `ok`. */
+  readonly refused?: Refusal;
+  /** What the agent still needs a person to do before what was installed takes
+   * effect. Absent where nothing does. */
+  readonly needs?: string;
+}
+
+export interface InstallReport extends Report {
+  readonly version: string;
+  readonly config_home: string;
+  readonly root: string;
+  /** The files laid down, by their path under `root`. */
+  readonly files: readonly string[];
+  /** The files laid down elsewhere, by their whole path. What an agent reads
+   * out of its own config home rather than out of a plugin's directory goes
+   * here, so uninstall takes back exactly what was put there. */
+  readonly placed?: readonly string[];
+  readonly marketplace?: { readonly name: string; readonly registered: boolean };
+  readonly plugin?: {
+    readonly id: string;
+    readonly installed: boolean;
+    /** Whether a copy of the same id was taken out first, which is what makes
+     * a repeated install run what was just laid down. */
+    readonly replaced: boolean;
+  };
+  /** The agent commands that were run, as they were run. */
+  readonly commands: readonly (readonly string[])[];
+}
+
+export interface StatusReport extends Report {
+  /** Where the receipt is. Absent when ccmsg installed nothing here, which is
+   * what makes every field below it absent too. */
+  readonly receipt?: string;
+  readonly installed_at?: string;
+  /** What the receipt says was installed. */
+  readonly version?: string;
+  readonly config_home?: string;
+  readonly root?: string;
+  /** The receipt's files, counted against what is under `root` now. */
+  readonly files?: {
+    readonly expected: number;
+    readonly present: number;
+    readonly missing: readonly string[];
+  };
+  readonly marketplace?: {
+    readonly name?: string;
+    /** Whether the agent has it. Absent when the agent could not be asked,
+     * which is a different thing from it not being registered. */
+    readonly registered?: boolean;
+    /** Where the agent thinks it points, when that is not where the receipt
+     * put it. */
+    readonly points_at?: string;
+  };
+  readonly plugin?: {
+    readonly id?: string;
+    /** What the agent reports having, and whether it has it switched on.
+     * Present with no `expected_version` beside it means something other than
+     * ccmsg installed it. */
+    readonly installed_version?: string;
+    readonly enabled?: boolean;
+    /** What the receipt says should be there. */
+    readonly expected_version?: string;
+  };
+  /** Whether the agent's hooks are switched on at all, where that is a setting
+   * of the agent rather than of the plugin. Absent when it could not be asked. */
+  readonly hooks_enabled?: boolean;
+}
+
+export interface UninstallReport extends Report {
+  readonly receipt?: string;
+  /** What was actually taken back out. A step the receipt does not name was
+   * never taken, so it is not undone and does not appear here. */
+  readonly removed: {
+    readonly plugin?: string;
+    readonly marketplace?: string;
+    readonly root?: string;
+    readonly placed?: readonly string[];
+  };
+}
+
+export type Outcome = InstallReport | StatusReport | UninstallReport;
+
+/** What one install did, so that uninstall can undo exactly that.
+ *
+ * Everything reversible is written down before the next step is taken: the
+ * files that were laid down, the commands that were run against the agent, and
+ * the id the agent now knows the plugin by. Undoing reads this and nothing
+ * else — an install that half-finished leaves a receipt for the half that
+ * happened, and a plugin somebody else installed is not in it and is left
+ * alone. */
+export interface Receipt {
+  readonly agent: Agent;
+  readonly version: string;
+  readonly installed_at: string;
+  /** The config home the agent was asked to install into. */
+  readonly config_home: string;
+  /** Where the plugin's own files were laid down. */
+  readonly root: string;
+  /** Their paths under that root, in the order they were written. */
+  readonly files: readonly string[];
+  /** Whole paths written outside that root, in the order they were written. */
+  readonly placed?: readonly string[];
+  /** The agent commands that were run, as they were run. */
+  readonly commands: readonly (readonly string[])[];
+  readonly marketplace?: string;
+  readonly plugin_id?: string;
+}
+
+export function rootFor(paths: InstancePaths, agent: Agent): string {
+  return join(paths.pluginsDir, agent);
+}
+
+export function receiptFile(paths: InstancePaths, agent: Agent): string {
+  return join(paths.pluginsDir, `${agent}.receipt.json`);
+}
+
+export async function readReceipt(
+  paths: InstancePaths,
+  agent: Agent,
+): Promise<Receipt | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(receiptFile(paths, agent), "utf8"));
+    return typeof parsed === "object" && parsed !== null ? (parsed as Receipt) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeReceipt(paths: InstancePaths, receipt: Receipt): Promise<void> {
+  const file = receiptFile(paths, receipt.agent);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(receipt, null, 2)}\n`);
+}
+
+/** Lay a set of files down, each under the root, in the order given. A string
+ * is written as it is; anything else is the content of a JSON file, so the
+ * definitions state shapes rather than text and one place turns a value into
+ * bytes. */
+export async function place(
+  root: string,
+  files: ReadonlyMap<string, string | object>,
+  mode?: number,
+): Promise<void> {
+  for (const [path, content] of files) {
+    const file = join(root, path);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(
+      file,
+      typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`,
+      mode === undefined ? undefined : { mode },
+    );
+  }
+}

package/src/plugin/skill.ts

@@ -0,0 +1,84 @@
+/** What a session is told about ccmsg, and how ccmsg is described where an
+ * agent lists what it has installed.
+ *
+ * One text for every harness: what a session has to know is how to answer a
+ * message and how to find somebody to send one to, and neither depends on
+ * which program the session runs in. The plugin around it differs — where the
+ * file goes, how a hook is declared — and the words do not.
+ *
+ * Written out rather than shipped as a file in the package: the daemon, the
+ * CLI and the plugin are one release, and generating the plugin from the
+ * running binary is what keeps the three from drifting into three versions of
+ * "what ccmsg is". */
+
+export const DESCRIPTION = "別のセッションと行き来するメッセージ";
+
+export const SKILL = `---
+name: ccmsg
+description: 別のセッションへ声をかける・届いたメッセージに返す・見ている人へ知らせる時に使う。
+---
+
+# ccmsg
+
+同じ人が動かしている別のセッションと、メッセージをやり取りする。相手が別のハーネスで動いていても同じ手順で届く。
+
+## 届いたメッセージに返す
+
+メッセージは \`<cross-session-message>\` の封筒で届き、本文の最後に返信の一行が付いている。
+
+\`\`\`
+Reply with: ccmsg reply <mid> --to <sid> <text>
+\`\`\`
+
+**その行をそのまま実行する。** 宛先も、どのメッセージへの返事かも、その行が持っている。
+自分で \`post\` を組み立て直さない。\`--to\` の無い行は人からのメッセージで、返事は通知として届く。
+
+## 自分から声をかける
+
+\`\`\`
+ccmsg post <sid> <text>
+\`\`\`
+
+相手の \`<sid>\` は、届いた封筒の \`ccmsg-from\` の値。
+
+## 相手を探す
+
+まだ話したことのない相手の \`<sid>\` は、繋がっているセッションの一覧から探す。
+
+\`\`\`
+ccmsg peers            この instance が知っているセッション
+ccmsg peers --all      他ホストの instance が知っている分も含める
+\`\`\`
+
+答えは instance ごとの JSON。\`peers[]\` が今繋がっているセッション、\`last_live[]\` が
+居なくなったセッションで、各行の \`repo\` / \`ws\` / \`branch\` / \`title\` で見分けて
+\`sid\` を取る。\`send_message\` が \`true\` の相手には harness 自身の機能でも届く。
+
+## 相手セッションの扱い
+
+相手は基本、自分にとってのサブエージェントだと思えばよい。対等な会議を開く場ではないので、
+冒頭の挨拶・賛辞・締めの社交辞令を省き、用件だけを 1〜3 文で送る。
+
+やり取りの中身を人へリレーしない。人は全セッションを直接見ているので、相手の完了報告や
+根拠をこちらで要約し直しても情報は増えず、時間とコンテキストだけが減る。人に言うのは
+自セッション目線の事実 (何を頼んだ・何が返り・その結果こちらが何をしたか) だけ。
+
+## 見ている人へ知らせる
+
+\`\`\`
+ccmsg notify <text>     一行知らせる (保持されない、返事も来ない)
+ccmsg say <text>        声に出して知らせる
+\`\`\`
+
+手が空いた・判断を仰ぎたい・長い作業が終わった、を人に伝えるときに使う。
+セッション同士のやり取りには使わない。
+
+## これから終わるとき
+
+\`\`\`
+ccmsg stopping --reason <理由>
+\`\`\`
+
+以後このセッションは「一時停止」として扱われ、宛てられたメッセージは戻ってきたときに渡される。
+セッション終了時には自動で伝わるので、途中で自分から言う必要はない。
+`;

package/src/sessions/harness.ts

@@ -1,6 +1,7 @@
 import { type FSWatcher, readdirSync, readFileSync, watch } from "node:fs";
 import { join } from "node:path";
 import type { AgentInfo, InstanceId, Sid } from "@ccmsg/protocol";
+import type { Harness } from "../harness/index.ts";
 
 /** The status the harness writes while a dialog is open and it is waiting for
  * an answer, alongside a `waitingFor` naming what it waits on.
@@ -23,6 +24,96 @@ export const CONFIRM_POLL_MS = 5_000;
 
 const STATE_FILE = /^\d+\.json$/;
 
+/** Which sessions one harness says exist right now, read from its config home.
+ *
+ * Two answers rather than one, because the harnesses do not say the same
+ * amount. Claude Code writes a file per session carrying its pid, its working
+ * directory and what it is doing, which is the shape the contract's `AgentInfo`
+ * states and what the `agents` topic is; Codex says only that a thread has a
+ * live writer, which answers "is it there" and nothing else. So `rows` is what
+ * can be reported and `present` is what the classification reads, and a harness
+ * that reports nothing still has its sessions classified (§5.1). */
+export interface OwnSessions {
+  readonly running: boolean;
+  /** Begins watching. Called when the first subscriber arrives and not before
+   * (§6.3 / §8.3: no upstream is read until somebody is listening). */
+  start(): void;
+  stop(): void;
+  /** The harness's own rows, as `agents` answers with them. Empty for a
+   * harness whose own view is not the one that contract states. */
+  rows(): ReadonlyMap<Sid, AgentInfo>;
+  /** The sessions the harness says are there at this instant. */
+  present(): ReadonlySet<Sid>;
+}
+
+/** The one this config home runs (§3.8). */
+export function ownSessions(
+  harness: Harness,
+  configHome: string,
+  instance: InstanceId,
+  onChange: () => void,
+  pollMs?: number,
+): OwnSessions {
+  return harness === "codex"
+    ? new CodexThreads(join(configHome, CODEX_LOCKS), onChange, pollMs)
+    : new HarnessSessions(join(configHome, "sessions"), instance, onChange, pollMs);
+}
+
+/** Where the Codex thread store takes a lock while a thread has a live writer,
+ * and what one of those locks is called.
+ *
+ * Measured against codex-cli 0.153.4: the file appears under this directory
+ * while a thread is being written and is gone once the process that had it
+ * ends normally. The `.coordination.lock` beside them belongs to the store's
+ * own cleanup and names no thread, which the shape below excludes.
+ *
+ * A process killed outright leaves its lock behind (measured), so a thread
+ * whose session died without a word reads as present until Codex itself sweeps
+ * the stale lock. That is the same direction as the state file Claude Code
+ * leaves behind — except that a lock names no pid, so there is nothing here to
+ * ask whether anybody still holds it. */
+const CODEX_LOCKS = "thread-writer-locks";
+const THREAD_LOCK = /^([0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12})\.lock$/;
+
+/** The Codex threads with a live writer, read from one config home.
+ *
+ * It reports no rows: `AgentInfo` is Claude Code's own list (contract), and a
+ * lock file carries none of what that shape states. What a Codex session is —
+ * where it works, what it is called — is what it said when it greeted, and
+ * that is held by the registry for every harness alike. */
+class CodexThreads implements OwnSessions {
+  readonly #watch: DirectoryWatch;
+
+  constructor(dir: string, onChange: () => void, pollMs?: number) {
+    this.#watch = new DirectoryWatch(dir, onChange, pollMs);
+  }
+
+  get running(): boolean {
+    return this.#watch.running;
+  }
+
+  start(): void {
+    this.#watch.start();
+  }
+
+  stop(): void {
+    this.#watch.stop();
+  }
+
+  rows(): ReadonlyMap<Sid, AgentInfo> {
+    return new Map();
+  }
+
+  present(): ReadonlySet<Sid> {
+    const live = new Set<Sid>();
+    for (const name of this.#watch.names()) {
+      const sid = THREAD_LOCK.exec(name)?.[1];
+      if (sid !== undefined) live.add(sid);
+    }
+    return live;
+  }
+}
+
 /** The sessions the harness itself reports, read from one config home.
  *
  * The directory is the whole input: it says which sessions exist and which is
@@ -34,42 +125,38 @@ const STATE_FILE = /^\d+\.json$/;
  * a question, and is done whenever one is asked. Watching it says the answer
  * may have changed, which is only worth knowing while somebody is subscribed —
  * so the watch is what the subscription drives, and no answer waits on it. */
-export class HarnessSessions {
-  #watcher: FSWatcher | undefined;
-  #timer: ReturnType<typeof setInterval> | undefined;
+export class HarnessSessions implements OwnSessions {
+  readonly #watch: DirectoryWatch;
 
   constructor(
     private readonly dir: string,
     private readonly instance: InstanceId,
-    private readonly onChange: () => void,
-    private readonly pollMs: number = CONFIRM_POLL_MS,
-  ) {}
+    onChange: () => void,
+    pollMs?: number,
+  ) {
+    this.#watch = new DirectoryWatch(dir, onChange, pollMs);
+  }
 
   get running(): boolean {
-    return this.#watcher !== undefined || this.#timer !== undefined;
+    return this.#watch.running;
   }
 
-  /** Begins watching. Called when the first subscriber arrives and not before
-   * (§6.3 / §8.3: no upstream is read until somebody is listening). */
   start(): void {
-    if (this.running) return;
-    try {
-      this.#watcher = watch(this.dir, this.onChange);
-    } catch {
-      // The directory does not exist yet — a config home whose harness has not
-      // run. The poll below both covers the wait and picks it up when it
-      // appears, so this is not a failure to start.
-      this.#watcher = undefined;
-    }
-    this.#timer = setInterval(this.onChange, this.pollMs);
-    this.onChange();
+    this.#watch.start();
   }
 
   stop(): void {
-    this.#watcher?.close();
-    this.#watcher = undefined;
-    if (this.#timer !== undefined) clearInterval(this.#timer);
-    this.#timer = undefined;
+    this.#watch.stop();
+  }
+
+  rows(): ReadonlyMap<Sid, AgentInfo> {
+    return this.scan();
+  }
+
+  /** Every session with a state file, which for this harness is the same
+   * reading its rows came from. */
+  present(): ReadonlySet<Sid> {
+    return new Set(this.scan().keys());
   }
 
   /** The directory as it is at this instant.
@@ -87,13 +174,7 @@ export class HarnessSessions {
    * uid's own config home (M6) — a syscall or two per session, not a wait. */
   scan(): ReadonlyMap<Sid, AgentInfo> {
     const rows = new Map<Sid, AgentInfo>();
-    let names: string[];
-    try {
-      names = readdirSync(this.dir);
-    } catch {
-      return rows;
-    }
-    for (const name of names) {
+    for (const name of this.#watch.names()) {
       if (!STATE_FILE.test(name)) continue;
       let document: unknown;
       try {
@@ -108,6 +189,60 @@ export class HarnessSessions {
   }
 }
 
+/** One directory that says what the harness's sessions are, watched while
+ * somebody is subscribed and read whenever an answer is wanted.
+ *
+ * The two things §6.3 separates live here. Reading the directory answers a
+ * question, and is done whenever one is asked. Watching it says the answer may
+ * have changed, which is only worth knowing while somebody is listening — so
+ * the watch is what the subscription drives, and no answer waits on it. */
+class DirectoryWatch {
+  #watcher: FSWatcher | undefined;
+  #timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(
+    private readonly dir: string,
+    private readonly onChange: () => void,
+    private readonly pollMs: number = CONFIRM_POLL_MS,
+  ) {}
+
+  get running(): boolean {
+    return this.#watcher !== undefined || this.#timer !== undefined;
+  }
+
+  start(): void {
+    if (this.running) return;
+    try {
+      this.#watcher = watch(this.dir, this.onChange);
+    } catch {
+      // The directory does not exist yet — a config home whose harness has not
+      // run. The poll below both covers the wait and picks it up when it
+      // appears, so this is not a failure to start.
+      this.#watcher = undefined;
+    }
+    this.#timer = setInterval(this.onChange, this.pollMs);
+    this.onChange();
+  }
+
+  stop(): void {
+    this.#watcher?.close();
+    this.#watcher = undefined;
+    if (this.#timer !== undefined) clearInterval(this.#timer);
+    this.#timer = undefined;
+  }
+
+  /** What is in the directory now. Read in place because it is a handful of
+   * small entries of this uid's own config home (M6) — a syscall or two, not a
+   * wait. */
+  names(): string[] {
+    try {
+      return readdirSync(this.dir);
+    } catch {
+      return [];
+    }
+  }
+}
+
 /** Whether the harness says this session is waiting on a dialog. */
 export function isWaiting(row: AgentInfo): boolean {
   return row.status === WAITING;