@ccmsg/cli 0.1.0

package/src/messaging/notify.ts

@@ -0,0 +1,117 @@
+import type {
+  InstanceId,
+  Notification,
+  NotifySendArgs,
+  NotifySendResult,
+  SayMarkReadArgs,
+  SayMarkReadResult,
+  SayPostArgs,
+  SayPostResult,
+  Sid,
+  Timestamp,
+} from "@ccmsg/protocol";
+import { type HandlerInput, OpError } from "../dispatch/index.ts";
+import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+
+/** The one topic a notification reaches a watcher on. */
+const NOTIFY = "notify";
+
+export interface NotifyDeps {
+  readonly self: InstanceId;
+  /** How a session is shown. The contract has the issuing instance resolve it,
+   * so the label is decided here rather than carried in the arguments. */
+  readonly label: (sid: Sid) => string;
+  /** The one way a value reaches subscribers (§6.1). No `to`: a notification is
+   * for whoever is watching, not for one session. */
+  readonly publish: (topic: string, data: unknown, instance: InstanceId) => void;
+}
+
+/** The `notify` topic and the three ops that speak on it.
+ *
+ * One object for all three because they are one thing seen from two sides: a
+ * line reaching a person watching. `notify_send` is somebody telling a person
+ * about a session; `say_post` is a session saying that it just spoke. Both end
+ * as the same frame, which is what keeps "a notification" from meaning two
+ * shapes depending on which op raised it.
+ *
+ * The topic is `event` granularity (§6.2): nothing is held, so there is no
+ * snapshot and no suppression — two identical notifications are two things
+ * that happened. */
+export class Notify implements UpstreamResource {
+  /** Sessions that have spoken and not been heard. Instance state the contract
+   * lets a restart forget, so it lives here and nowhere on disk. */
+  readonly #unread = new Set<Sid>();
+
+  constructor(private readonly deps: NotifyDeps) {}
+
+  /** `notify_send`. The subject is the argument when it names one and the
+   * caller otherwise, so a session notifying about itself says only the text. */
+  send = (input: HandlerInput): NotifySendResult => {
+    const args = input.args as unknown as NotifySendArgs;
+    this.#announce(args.sid ?? this.#caller(input), args.text);
+    return {};
+  };
+
+  /** `say_post`. What was said is already in the caller's transcript, so this
+   * pushes the occurrence and raises the unread mark; the instance keeps no log
+   * of its own. The op is open to sessions alone, so the subject is the caller
+   * and there is nothing to address. */
+  post = (input: HandlerInput): SayPostResult => {
+    const args = input.args as unknown as SayPostArgs;
+    const sid = this.#caller(input);
+    const posted_at = this.#announce(sid, args.text);
+    this.#unread.add(sid);
+    return { posted_at };
+  };
+
+  /** `say_mark_read`. One session's mark, or every one when none is named. */
+  markRead = (input: HandlerInput): SayMarkReadResult => {
+    const { sid } = input.args as unknown as SayMarkReadArgs;
+    if (sid === undefined) this.#unread.clear();
+    else this.#unread.delete(sid);
+    return {};
+  };
+
+  /** The sessions that have spoken unheard. Nothing in this generation of the
+   * contract carries the mark on the wire, so this is how the instance's own
+   * side reads what `say_mark_read` clears. */
+  unread(): readonly Sid[] {
+    return [...this.#unread];
+  }
+
+  // --- UpstreamResource (§6.3)
+
+  /** Nothing upstream to run: a notification exists because an op raised it. */
+  start(): void {}
+
+  stop(): void {}
+
+  /** An event topic has no current value, so a subscriber starts at the next
+   * thing that happens (§6.2). */
+  snapshot(): readonly TopicValue[] {
+    return [];
+  }
+
+  #announce(sid: Sid, text: string, now: Timestamp = Date.now()): Timestamp {
+    const notification: Notification = {
+      sid,
+      sid_label: this.deps.label(sid),
+      text,
+      sent_at: now,
+    };
+    this.deps.publish(NOTIFY, notification, this.deps.self);
+    return now;
+  }
+
+  /** The session the caller is. A person's connection names none, which is why
+   * `notify_send` takes the subject as an argument — one that omits it from a
+   * connection with no session has named nobody for the notification to be
+   * about. */
+  #caller(input: HandlerInput): Sid {
+    const sid = input.identity?.sid;
+    if (sid === undefined) {
+      throw new OpError("bad_request", "a notification is about a session, and this names none");
+    }
+    return sid;
+  }
+}

package/src/plugin/claude.ts

@@ -0,0 +1,148 @@
+/** The plugin ccmsg hands to Claude Code, as its files.
+ *
+ * Written out rather than shipped as a directory 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". `install` lays these down and registers them; nothing else
+ * writes into a config home.
+ *
+ * The plugin itself is thin on purpose. Messages reach a session through the
+ * harness's own socket, so nothing here listens, polls or holds a connection —
+ * the skill says how to speak, and the two hooks say hello and goodbye. */
+
+/** The plugin's name, the marketplace's name, and therefore the id Claude Code
+ * knows it by. One word for all three: there is one plugin here and a
+ * marketplace that exists only to carry it. */
+export const PLUGIN_NAME = "ccmsg";
+export const MARKETPLACE_NAME = "ccmsg";
+export const PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+
+const DESCRIPTION = "別の Claude Code セッションと行き来するメッセージ";
+
+/** How a hook reaches `ccmsg`.
+ *
+ * Through `PATH`, not through the plugin's own directory: the binary is
+ * installed by whoever installs ccmsg, and a plugin that carried its own copy
+ * would be a second version of it to keep current. A session whose `PATH` has
+ * no `ccmsg` is a session with nothing to say, so the hook leaves without
+ * saying it — silently, because a person who has not installed ccmsg has not
+ * asked to hear about it at every session start. */
+function throughPath(command: string): string {
+  return `if command -v ccmsg >/dev/null 2>&1; then ccmsg ${command}; fi`;
+}
+
+/** How long a greeting or a departure may take before the harness stops
+ * waiting on it. Both are one connection to a socket on this same host, and
+ * both give up on their own when there is no instance behind it. */
+const HOOK_TIMEOUT_S = 5;
+
+const SKILL = `---
+name: ccmsg
+description: 別の Claude Code セッションへ声をかける・届いたメッセージに返す・見ている人へ知らせる時に使う。
+---
+
+# 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 自身の機能でも届く。
+
+## 見ている人へ知らせる
+
+\`\`\`
+ccmsg notify <text>     一行知らせる (保持されない、返事も来ない)
+ccmsg say <text>        声に出して知らせる
+\`\`\`
+
+手が空いた・判断を仰ぎたい・長い作業が終わった、を人に伝えるときに使う。
+セッション同士のやり取りには使わない。
+
+## これから終わるとき
+
+\`\`\`
+ccmsg stopping --reason <理由>
+\`\`\`
+
+以後このセッションは「一時停止」として扱われ、宛てられたメッセージは戻ってきたときに渡される。
+セッション終了時には自動で伝わるので、途中で自分から言う必要はない。
+`;
+
+const HOOKS = {
+  hooks: {
+    SessionStart: [
+      {
+        matcher: "startup|resume|clear|compact",
+        hooks: [{ type: "command", command: throughPath("hello --hook"), timeout: HOOK_TIMEOUT_S }],
+      },
+    ],
+    SessionEnd: [
+      {
+        hooks: [
+          { type: "command", command: throughPath("stopping --hook"), timeout: HOOK_TIMEOUT_S },
+        ],
+      },
+    ],
+  },
+};
+
+/** Every file the plugin is made of, by its path under the plugin's root.
+ *
+ * A string is written as it is; anything else is the content of a JSON file
+ * and is serialized by whoever writes it, so this states shapes rather than
+ * text and there is one place that turns a value into bytes. */
+export function claudePluginFiles(version: string): Map<string, string | object> {
+  return new Map<string, string | object>([
+    [
+      ".claude-plugin/marketplace.json",
+      {
+        name: MARKETPLACE_NAME,
+        owner: { name: "kawaz" },
+        metadata: { description: DESCRIPTION, version },
+        plugins: [{ name: PLUGIN_NAME, description: DESCRIPTION, source: "./" }],
+      },
+    ],
+    [
+      ".claude-plugin/plugin.json",
+      {
+        name: PLUGIN_NAME,
+        description: DESCRIPTION,
+        version,
+        author: { name: "kawaz" },
+        license: "MIT",
+        repository: "https://github.com/kawaz/ccmsg",
+      },
+    ],
+    ["skills/ccmsg/SKILL.md", SKILL],
+    ["hooks/hooks.json", HOOKS],
+  ]);
+}

package/src/plugin/index.ts

@@ -0,0 +1,13 @@
+export { claudePluginFiles, MARKETPLACE_NAME, PLUGIN_ID, PLUGIN_NAME } from "./claude.ts";
+export {
+  type Agent,
+  AGENTS,
+  install,
+  type Outcome,
+  type Ran,
+  type Receipt,
+  type Run,
+  runClaude,
+  status,
+  uninstall,
+} from "./install.ts";

package/src/plugin/install.ts

@@ -0,0 +1,416 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { InstancePaths } from "../instance/index.ts";
+import { claudePluginFiles, MARKETPLACE_NAME, PLUGIN_ID } from "./claude.ts";
+
+/** The agents ccmsg can install a plugin for. One so far; the word is in the
+ * command because the second one is what the shape is for. */
+export const AGENTS = ["claude"] as const;
+export type Agent = (typeof AGENTS)[number];
+
+/** How the 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;
+}
+
+export const runClaude: Run = async (args) => {
+  let spawned: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    spawned = Bun.spawn({ cmd: ["claude", ...args], stdout: "pipe", stderr: "pipe" });
+  } catch {
+    return { code: 127, stdout: "", stderr: "claude が PATH にありません" };
+  }
+  const [stdout, stderr] = await Promise.all([
+    new Response(spawned.stdout).text(),
+    new Response(spawned.stderr).text(),
+  ]);
+  return { code: await spawned.exited, stdout, stderr };
+};
+
+/** 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;
+}
+
+/** 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. */
+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;
+}
+
+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[];
+  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;
+  };
+}
+
+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;
+  };
+}
+
+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[];
+  /** The agent commands that were run, as they were run. */
+  readonly commands: readonly (readonly string[])[];
+  readonly marketplace?: string;
+  readonly plugin_id?: string;
+}
+
+function rootFor(paths: InstancePaths, agent: Agent): string {
+  return join(paths.pluginsDir, agent);
+}
+
+function receiptFile(paths: InstancePaths, agent: Agent): string {
+  return join(paths.pluginsDir, `${agent}.receipt.json`);
+}
+
+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;
+  }
+}
+
+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 the plugin's files down under the instance's own state, register it
+ * with the agent, and write down what was done.
+ *
+ * The two agent commands are both safe to repeat — the agent answers "already
+ * there" and succeeds — so an install that is run twice is an install that
+ * finishes twice rather than one that fails the second time. What is not
+ * repeatable is the copy the agent takes: it snapshots the plugin at install,
+ * and a version already installed is not re-read. So an install that finds its
+ * own id already there removes it first, which is what makes "install" mean
+ * "what is running is what was just laid down". */
+export async function install(
+  paths: InstancePaths,
+  version: string,
+  run: Run = runClaude,
+): Promise<InstallReport> {
+  const root = rootFor(paths, "claude");
+  const files = claudePluginFiles(version);
+  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`,
+    );
+  }
+
+  // Kept as it grows rather than rebuilt per step: each step adds what it did
+  // to what the earlier ones did, and the file on disk is that running total.
+  // A receipt that named only the last step would undo only the last step.
+  let receipt: Receipt = {
+    agent: "claude",
+    version,
+    installed_at: new Date().toISOString(),
+    config_home: paths.configHome,
+    root,
+    files: [...files.keys()],
+    commands: [],
+  };
+  await writeReceipt(paths, receipt);
+
+  let replaced = false;
+  const so = (ok: boolean, refused?: Refusal): InstallReport => ({
+    agent: "claude",
+    ok,
+    version,
+    config_home: paths.configHome,
+    root,
+    files: receipt.files,
+    marketplace: { name: MARKETPLACE_NAME, registered: receipt.marketplace !== undefined },
+    plugin: { id: PLUGIN_ID, installed: receipt.plugin_id !== undefined, replaced },
+    commands: receipt.commands,
+    ...(refused === undefined ? {} : { refused }),
+  });
+
+  const step = async (args: string[], done: Partial<Receipt>): Promise<Refusal | undefined> => {
+    const ran = await run(args);
+    if (ran.code !== 0) return refusal(args, ran);
+    receipt = { ...receipt, ...done, commands: [...receipt.commands, args] };
+    await writeReceipt(paths, receipt);
+    return undefined;
+  };
+
+  const added = await step(["plugin", "marketplace", "add", root], {
+    marketplace: MARKETPLACE_NAME,
+  });
+  if (added !== undefined) return so(false, added);
+
+  if (await installed(run)) {
+    const args = ["plugin", "uninstall", PLUGIN_ID, "-y"];
+    const ran = await run(args);
+    if (ran.code !== 0) return so(false, refusal(args, ran));
+    replaced = true;
+  }
+
+  const put = await step(["plugin", "install", PLUGIN_ID], { plugin_id: PLUGIN_ID });
+  return put === undefined ? so(true) : so(false, put);
+}
+
+/** What the receipt says was done, beside what is actually there now.
+ *
+ * Reading it is what tells the two apart: every field the receipt states has
+ * the current reading of the same thing beside it, so drift — a file deleted, a
+ * marketplace pointed elsewhere, a version other than the one installed — is
+ * two fields that differ rather than a sentence about them. */
+export async function status(paths: InstancePaths, run: Run = runClaude): Promise<StatusReport> {
+  const receipt = await readReceipt(paths, "claude");
+  const here = await installedRow(run);
+  const registered = await marketplaces(run);
+  if (receipt === undefined) {
+    // No receipt, so there is nothing of ccmsg's to compare against. A plugin
+    // of the same id is still worth naming: it is there, and taking it out is
+    // not this command's to do.
+    return {
+      agent: "claude",
+      ok: true,
+      marketplace: known(registered, MARKETPLACE_NAME),
+      plugin:
+        here === undefined
+          ? {}
+          : { id: PLUGIN_ID, installed_version: here.version, enabled: here.enabled },
+    };
+  }
+  const missing: string[] = [];
+  for (const path of receipt.files) {
+    if (!(await Bun.file(join(receipt.root, path)).exists())) missing.push(path);
+  }
+  const market = known(registered, receipt.marketplace, receipt.root);
+  return {
+    agent: "claude",
+    ok: true,
+    receipt: receiptFile(paths, "claude"),
+    installed_at: receipt.installed_at,
+    version: receipt.version,
+    config_home: receipt.config_home,
+    root: receipt.root,
+    files: {
+      expected: receipt.files.length,
+      present: receipt.files.length - missing.length,
+      missing,
+    },
+    marketplace: market,
+    plugin: {
+      ...(receipt.plugin_id === undefined ? {} : { id: receipt.plugin_id }),
+      ...(here === undefined ? {} : { installed_version: here.version, enabled: here.enabled }),
+      expected_version: receipt.version,
+    },
+  };
+}
+
+/** One marketplace as the agent has it, against where it was put.
+ *
+ * An agent that could not be asked leaves `registered` unsaid, because "we do
+ * not know" and "it is not registered" lead to different next steps. */
+function known(
+  registered: Map<string, string> | undefined,
+  name: string | undefined,
+  root?: string,
+): StatusReport["marketplace"] {
+  const named = name === undefined ? {} : { name };
+  if (registered === undefined || name === undefined) return named;
+  const at = registered.get(name);
+  if (at === undefined) return { ...named, registered: false };
+  return {
+    ...named,
+    registered: true,
+    ...(root === undefined || at === root || at === "" ? {} : { points_at: at }),
+  };
+}
+
+/** Undo what the receipt says was done, and nothing else.
+ *
+ * In the order that leaves nothing dangling: the agent lets go of the plugin,
+ * then of the marketplace that offered it, and only then are the files it was
+ * reading taken away. A step the receipt does not name is a step that was
+ * never taken, so it is not undone. */
+export async function uninstall(
+  paths: InstancePaths,
+  run: Run = runClaude,
+): Promise<UninstallReport> {
+  const receipt = await readReceipt(paths, "claude");
+  if (receipt === undefined) return { agent: "claude", ok: true, removed: {} };
+  const file = receiptFile(paths, "claude");
+  let removed: UninstallReport["removed"] = {};
+  if (receipt.plugin_id !== undefined) {
+    const args = ["plugin", "uninstall", receipt.plugin_id, "-y"];
+    const ran = await run(args);
+    if (ran.code !== 0) {
+      return { agent: "claude", ok: false, receipt: file, removed, refused: refusal(args, ran) };
+    }
+    removed = { ...removed, plugin: receipt.plugin_id };
+  }
+  if (receipt.marketplace !== undefined) {
+    const args = ["plugin", "marketplace", "remove", receipt.marketplace];
+    const ran = await run(args);
+    if (ran.code !== 0) {
+      return { agent: "claude", ok: false, receipt: file, removed, refused: refusal(args, ran) };
+    }
+    removed = { ...removed, marketplace: receipt.marketplace };
+  }
+  await rm(receipt.root, { recursive: true, force: true });
+  await rm(file, { force: true });
+  return { agent: "claude", ok: true, receipt: file, removed: { ...removed, root: receipt.root } };
+}
+
+/** One installed plugin, as the agent lists it. */
+interface Installed {
+  readonly version: string;
+  readonly enabled: boolean;
+}
+
+async function installedRow(run: Run): Promise<Installed | undefined> {
+  const ran = await run(["plugin", "list", "--json"]);
+  if (ran.code !== 0) return undefined;
+  for (const row of rows(ran.stdout)) {
+    if (row["id"] !== PLUGIN_ID) continue;
+    const version = row["version"];
+    return {
+      version: typeof version === "string" ? version : "不明",
+      enabled: row["enabled"] !== false,
+    };
+  }
+  return undefined;
+}
+
+async function installed(run: Run): Promise<boolean> {
+  return (await installedRow(run)) !== undefined;
+}
+
+/** The marketplaces the agent knows, by name and by where each one points.
+ * Nothing when the agent could not be asked, which reads as "unknown" rather
+ * than as "none registered". */
+async function marketplaces(run: Run): Promise<Map<string, string> | undefined> {
+  const ran = await run(["plugin", "marketplace", "list", "--json"]);
+  if (ran.code !== 0) return undefined;
+  const known = new Map<string, string>();
+  for (const row of rows(ran.stdout)) {
+    const name = row["name"];
+    const path = row["path"] ?? row["installLocation"];
+    if (typeof name === "string") known.set(name, typeof path === "string" ? path : "");
+  }
+  return known;
+}
+
+function rows(output: string): Record<string, unknown>[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    return [];
+  }
+  return Array.isArray(parsed)
+    ? parsed.filter(
+        (row): row is Record<string, unknown> => typeof row === "object" && row !== null,
+      )
+    : [];
+}
+
+/** 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. */
+function refusal(command: readonly string[], ran: Ran): Refusal {
+  const said = `${ran.stderr}${ran.stdout}`.trim();
+  return { command: ["claude", ...command], code: ran.code, said: said.split("\n")[0] ?? "" };
+}

package/src/service/index.ts

@@ -0,0 +1 @@
+export * from "./service.ts";