@ccmsg/cli 0.3.5 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.3.5",
+  "version": "0.4.2",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",
@@ -20,7 +20,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ccmsg/protocol": "1.10.0"
+    "@ccmsg/protocol": "1.12.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/cli.ts

@@ -1,5 +1,12 @@
 #!/usr/bin/env bun
-import { type MessageSendArgs, type NotifySendArgs, PROTOCOL_VERSION } from "@ccmsg/protocol";
+import {
+  type MessageSendArgs,
+  type NotifySendArgs,
+  PROTOCOL_VERSION,
+  type SessionDumpFile,
+  type SessionDumpWriteArgs,
+  type SessionDumpWriteResult,
+} from "@ccmsg/protocol";
 import {
   add as addToConfig,
   ask,
@@ -24,8 +31,10 @@ import {
   type Target,
   targetFor,
 } from "./daemon/index.ts";
+import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { document } from "./transcript/items/index.ts";
 import { currentSession, DEFAULT_HARNESS, HARNESS, HARNESSES, isHarness } from "./harness/index.ts";
 
 /** The variables a session is named by, for the help and for the message a
@@ -357,6 +366,40 @@ const ROOT: Command = {
       ],
       run: (args) => agents(args),
     },
+    {
+      name: "dump",
+      summary: "セッション (か配下の worker 1 体) の transcript を型ごとの表示で書き出す",
+      usage: "ccmsg dump <sid>[/agent-<id>] [--preset <名前>] [--types <選択>]",
+      options: [
+        ["--preset <名前>", "instance が持つ選択 (ccmsg dump presets で一覧)"],
+        ["--types <選択>", "型をカンマ区切りで。prefix 可、-で除外、@名前で preset 展開"],
+        ["--since <at|uuid>", "下限。時刻 (ISO か epoch ミリ秒) か record の uuid"],
+        ["--until <at|uuid>", "上限。同上"],
+        ["--max-chars <n>", "1 アイテムの本文をこの文字数で切る (既定は切らない)"],
+        ["--json", "markdown ではなく dump file の中身をそのまま出す"],
+        ["--out <path>", "標準出力ではなくこの path に書く"],
+      ],
+      notes: [
+        {
+          title: "別のセッションのやり方を読む:",
+          docs: [
+            ["1", "ccmsg dump <sid> --preset howto で親を読む"],
+            ["2", "末尾の ids 台帳から良さそうな worker の agent id を選ぶ"],
+            ["3", "ccmsg dump <sid>/agent-<id> --preset howto で主語を移して掘る"],
+          ],
+        },
+      ],
+      children: [
+        {
+          name: "presets",
+          summary: "この instance が持つ preset の名前と中身を並べる",
+          usage: "ccmsg dump presets",
+          bare: true,
+          run: () => instanceAsk({ op: "dump_presets_read" }),
+        },
+      ],
+      run: (args) => dump(args),
+    },
     {
       name: "post",
       summary: "別のセッションへメッセージを送る",
@@ -857,6 +900,115 @@ async function topic(
   }
 }
 
+/** `ccmsg dump <sid>[/agent-<id>]`: read how a session worked.
+ *
+ * The instance writes the file — it is the one that can read a transcript, and
+ * a path that outlives the request is the point of the op — and this reads it
+ * back and draws it. Which means the two halves stay where they belong: what
+ * an item is settled by whoever read the file, and how an item reads is
+ * settled here, where somebody is looking at it.
+ *
+ * `--json` hands over the file as it stands, for a reader that is a program. */
+async function dump(args: readonly string[]): Promise<unknown> {
+  const parsed = options(args, ["preset", "types", "since", "until", "out", "max-chars"], ["json"]);
+  const subject = parsed.rest[0];
+  if (subject === undefined) {
+    throw new CommandError(
+      "invalid_args",
+      "使い方: ccmsg dump <sid>[/agent-<id>] [--preset <名前>] [--types <選択>]",
+    );
+  }
+  const written = (await instanceAsk({
+    op: "session_dump_write",
+    ...dumpArgs(subject, parsed.named),
+  })) as unknown as SessionDumpWriteResult;
+  const body = readFileSync(written.path, "utf8");
+  const since = parsed.named.get("since");
+  const until = parsed.named.get("until");
+  const limit = parsed.named.get("max-chars");
+  const text = parsed.flags.has("json")
+    ? body
+    : document(JSON.parse(body) as SessionDumpFile, {
+        instance: written.instance,
+        ...(since === undefined ? {} : { since }),
+        ...(until === undefined ? {} : { until }),
+        ...(limit === undefined ? {} : { max_chars: chars(limit) }),
+      });
+  const out = parsed.named.get("out");
+  if (out === undefined) {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    return undefined;
+  }
+  writeFileSync(out, text);
+  return {
+    path: out,
+    bytes: Buffer.byteLength(text),
+    dump: written.path,
+    instance: written.instance,
+    entries: written.entries,
+    ids: written.ids,
+  };
+}
+
+/** What a person typed, as the op's arguments.
+ *
+ * `<sid>/agent-<id>` is split here and nowhere else: the contract keeps the
+ * two apart so that a sid stays a validated sid, and the joined spelling is
+ * the CLI's own convenience — it is how the file the agent's records live in
+ * is named, which is what makes the two halves tellable apart by eye. */
+export function dumpArgs(
+  subject: string,
+  named: ReadonlyMap<string, string> = new Map(),
+): SessionDumpWriteArgs {
+  const at = subject.indexOf(AGENT_MARK);
+  const sid = at === -1 ? subject : subject.slice(0, at);
+  const agent = at === -1 ? undefined : subject.slice(at + AGENT_MARK.length);
+  const types = named.get("types");
+  const preset = named.get("preset");
+  return {
+    sid,
+    ...(agent === undefined || agent === "" ? {} : { agent_id: agent }),
+    ...(preset === undefined ? {} : { preset }),
+    ...(types === undefined
+      ? {}
+      : {
+          types: types
+            .split(",")
+            .map((one) => one.trim())
+            .filter((one) => one !== ""),
+        }),
+    ...bound("since", named.get("since")),
+    ...bound("until", named.get("until")),
+  };
+}
+
+const AGENT_MARK = "/agent-";
+
+/** One bound, as whichever of the two kinds it was written in.
+ *
+ * A time and a record id cannot be confused for one another — one parses as a
+ * moment and the other does not — so the caller writes what they have rather
+ * than saying which it is. */
+function bound(kind: "since" | "until", value: string | undefined): Record<string, unknown> {
+  if (value === undefined || value === "") return {};
+  const at = moment(value);
+  return at === undefined ? { [`${kind}_uuid`]: value } : { [`${kind}_at`]: at };
+}
+
+function moment(value: string): number | undefined {
+  if (/^\d+$/.test(value)) return Number(value);
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+function chars(value: string): number {
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new CommandError("invalid_args", "--max-chars は 1 以上の整数です");
+  }
+  return limit;
+}
+
 /** `ccmsg post <sid> <text>`: start a conversation with another session. */
 function post(args: readonly string[]): Promise<unknown> {
   const parsed = options(args, ["sid"]);
@@ -1106,6 +1258,26 @@ async function call(
       `自分のセッション ID が分かりません (--sid か ${SESSION_ENV.join(" / ")})`,
     );
   }
+  return await exchange(
+    { op: "hello", role: "session", sid, protocol_version: PROTOCOL_VERSION, ...meta },
+    request,
+  );
+}
+
+/** One op, spoken as the person at the keyboard.
+ *
+ * Which is who is asking: reading a transcript is not something a session is a
+ * party to, and the ops that do it are open to a person and to nobody else. */
+function instanceAsk(request: Record<string, unknown>): Promise<unknown> {
+  return exchange({ op: "hello", role: "user", protocol_version: PROTOCOL_VERSION }, request);
+}
+
+/** Greet this config home's instance, ask it one thing, and answer with what
+ * it said. */
+async function exchange(
+  greeting: Record<string, unknown>,
+  request: Record<string, unknown>,
+): Promise<unknown> {
   const paths = resolvePaths();
   const conn = await connect(paths.socket);
   if (conn === undefined) {
@@ -1115,15 +1287,9 @@ async function call(
     );
   }
   try {
-    const greeting = await conn.ask({
-      op: "hello",
-      role: "session",
-      sid,
-      protocol_version: PROTOCOL_VERSION,
-      ...meta,
-    });
-    if (greeting["ok"] !== true) {
-      throw new CommandError("forbidden", `hello が拒否されました: ${JSON.stringify(greeting)}`);
+    const greeted = await conn.ask(greeting);
+    if (greeted["ok"] !== true) {
+      throw new CommandError("forbidden", `hello が拒否されました: ${JSON.stringify(greeted)}`);
     }
     const answer = await conn.ask(request);
     if (answer["ok"] !== true) {

package/src/daemon/registry.ts

@@ -95,10 +95,54 @@ export function registered(env: Env): Target[] {
   return loadShared(paths.configFile).instances.map((entry) => targetFor(env, entry.dir));
 }
 
+/** The selections the shared file starts with.
+ *
+ * Presets are the operator's to name — what one names is an interest, and this
+ * instance has no opinion on which interests a person has — so these are
+ * written into the file as examples to edit rather than built in. A default
+ * that lived in the code would be invisible in the file and would come back
+ * after being deleted.
+ *
+ * They also show the two things a person would otherwise have to be told: that
+ * a prefix takes a family, and that `@name` puts one selection inside
+ * another. */
+const STARTING_PRESETS = [
+  {
+    name: "file",
+    description: "ファイル操作。読み書きと探索をひとまとめに",
+    opts: { types: ["tool:Read", "tool:Write", "tool:Edit", "tool:Glob", "tool:Grep"] },
+  },
+  {
+    name: "howto",
+    description: "調査のノウハウだけ。何を考えて何を叩いて何を読み書きしたか",
+    opts: { types: ["thinking", "message:user", "message:sub", "tool:Bash", "@file"] },
+  },
+  {
+    name: "journal",
+    description: "日記用。人との往復と worker の答え、思考は要点だけ",
+    opts: { types: ["message:user", "message:sub:in", "thinking"] },
+  },
+  {
+    name: "handoff",
+    description: "後継セッションへの引き継ぎ。直近の会話と、走っているものの台帳",
+    opts: { types: ["message", "system:task", "ids"] },
+  },
+  {
+    name: "audit",
+    description: "何をしたかの追跡。会話は落として操作と通知だけ",
+    opts: { types: ["@file", "tool:Bash", "notice", "ids"] },
+  },
+];
+
 /** Add a config home to the shared file. The settings it will run with are the
  * defaults until somebody edits its entry, so the entry starts empty — save
  * for the harness, which is written down when it is not the default because it
- * is the one setting the directory itself cannot be asked for (§3.8). */
+ * is the one setting the directory itself cannot be asked for (§3.8).
+ *
+ * The dump presets above go to `defaults`, and only where the file names none:
+ * they are the same for every instance and are examples to edit, so writing
+ * them per entry would repeat them and re-adding a config home would bring
+ * back what somebody deleted. */
 export function add(env: Env, dir: string, harness: Harness = DEFAULT_HARNESS): InstanceRow {
   const home = configHome(dir, harness);
   const file = resolvePaths(env).configFile;
@@ -110,7 +154,11 @@ export function add(env: Env, dir: string, harness: Harness = DEFAULT_HARNESS):
     dir: home,
     settings: harness === DEFAULT_HARNESS ? {} : { harness },
   };
-  saveShared(file, { ...shared, instances: [...shared.instances, entry] });
+  const defaults =
+    shared.defaults["dump"] === undefined
+      ? { ...shared.defaults, dump: { presets: STARTING_PRESETS } }
+      : shared.defaults;
+  saveShared(file, { defaults, instances: [...shared.instances, entry] });
   const target = targetFor(env, home);
   // The id is made here rather than at the first start, so that what `add`
   // prints is what the instance will answer to and so that a person can write

package/src/instance/config.ts

@@ -1,6 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute } from "node:path";
-import type { Endpoint } from "@ccmsg/protocol";
+import type { DumpPreset, Endpoint } from "@ccmsg/protocol";
 import { DEFAULT_HARNESS, type Harness, HARNESSES, isHarness } from "../harness/index.ts";
 import { parseCidr } from "./client.ts";
 
@@ -91,6 +91,17 @@ export interface UpstreamConfig {
   readonly sandbox_origin?: string;
 }
 
+/** The named selections a person dumps by.
+ *
+ * Configured rather than fixed in the contract because what a preset names is
+ * an interest — how the work was done, what to hand over — and an interest is
+ * not a property of the wire. A type name stays one to one with what a record
+ * is, and the groupings people reach for are made by naming a set of them. */
+export interface DumpConfig {
+  /** In configured order, which is the order `dump_presets_read` answers in. */
+  readonly presets: readonly DumpPreset[];
+}
+
 export interface InstanceConfig {
   /** Which harness this config home runs (§3.8).
    *
@@ -118,6 +129,7 @@ export interface InstanceConfig {
    * one that does not never pays for it. The `fork` capability follows this,
    * so a client learns which it is from `hello`. */
   readonly fork_origin: boolean;
+  readonly dump: DumpConfig;
 }
 
 /** A config file that could not be understood.
@@ -146,6 +158,7 @@ export const DEFAULT_CONFIG: InstanceConfig = {
   upstream: {},
   direct_delivery: true,
   fork_origin: false,
+  dump: { presets: [] },
 };
 
 /** Read the config, once, at startup (DV-Q8).
@@ -258,6 +271,11 @@ export const MERGE_RULES: Readonly<Record<string, MergeRule>> = {
   "upstream.launcher.templates": "replace",
   "upstream.launcher.clean_env": "replace",
   "upstream.launcher.keep_env": "replace",
+  dump: "merge",
+  // A preset list is a whole vocabulary: an instance that names its own means
+  // to dump by those and not by the defaults' as well, since a name it did not
+  // write could shadow or be referenced by one it did.
+  "dump.presets": "replace",
 };
 
 function ruleFor(path: string): MergeRule {
@@ -308,9 +326,92 @@ export function parseConfig(file: string, fields: Record<string, unknown>): Inst
       DEFAULT_CONFIG.direct_delivery,
     ),
     fork_origin: flagOf(file, "fork_origin", fields["fork_origin"], DEFAULT_CONFIG.fork_origin),
+    dump: dumpOf(file, fields["dump"]),
   };
 }
 
+/** One element of a selection, as the contract spells it: a type name, a
+ * prefix of one, either negated with `-`, or `@name` for a preset. */
+const SELECTOR = /^-?(?:@[A-Za-z0-9][A-Za-z0-9_-]*|[a-z]+(?::[A-Za-z0-9_.-]+)*)$/;
+
+function dumpOf(file: string, raw: unknown): DumpConfig {
+  if (raw === undefined) return { presets: [] };
+  const fields = objectOf(file, "dump", raw);
+  const presets = presetsOf(file, fields["presets"]);
+  // A reference is resolved here rather than at each dump: a cycle or a name
+  // nobody configured would otherwise be found once per request, long after
+  // the file that holds the mistake was last looked at.
+  for (const preset of presets) resolvable(file, preset, presets, []);
+  return { presets };
+}
+
+function presetsOf(file: string, raw: unknown): DumpPreset[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    throw new ConfigError(file, "dump.presets must be an array of named selections");
+  }
+  const names = new Set<string>();
+  return raw.map((entry, index) => {
+    const at = `dump.presets[${index}]`;
+    const fields = objectOf(file, at, entry);
+    const name = fields["name"];
+    if (typeof name !== "string" || name === "") {
+      throw new ConfigError(file, `${at}.name must be a name for the selection`);
+    }
+    if (names.has(name)) throw new ConfigError(file, `${at}.name repeats ${name}`);
+    names.add(name);
+    const description = fields["description"];
+    if (description !== undefined && typeof description !== "string") {
+      throw new ConfigError(file, `${at}.description must be a string`);
+    }
+    const opts = objectOf(file, `${at}.opts`, fields["opts"]);
+    const types = stringsOf(file, `${at}.opts.types`, opts["types"]);
+    const wrong = types.filter((element) => !SELECTOR.test(element));
+    if (wrong.length > 0) {
+      throw new ConfigError(
+        file,
+        `${at}.opts.types must be item types, prefixes, exclusions or @presets, got ${wrong.join(", ")}`,
+      );
+    }
+    return {
+      name,
+      ...(description === undefined ? {} : { description }),
+      opts: { types: [...types] },
+    };
+  });
+}
+
+/** Every `@name` a preset reaches, down through the presets it names.
+ *
+ * The path is carried so a cycle is named where it closes rather than as a
+ * stack that ran out — an operator reading the refusal has to be able to find
+ * which two presets point at each other. */
+function resolvable(
+  file: string,
+  preset: DumpPreset,
+  presets: readonly DumpPreset[],
+  path: readonly string[],
+): void {
+  if (path.includes(preset.name)) {
+    throw new ConfigError(
+      file,
+      `dump.presets reference each other in a cycle: ${[...path, preset.name].join(" -> ")}`,
+    );
+  }
+  for (const element of preset.opts.types) {
+    const name = element.startsWith("-") ? element.slice(1) : element;
+    if (!name.startsWith("@")) continue;
+    const referenced = presets.find((one) => one.name === name.slice(1));
+    if (referenced === undefined) {
+      throw new ConfigError(
+        file,
+        `dump.presets[${preset.name}] names ${name}, which is not configured`,
+      );
+    }
+    resolvable(file, referenced, presets, [...path, preset.name]);
+  }
+}
+
 function harnessOf(file: string, raw: unknown): Harness {
   if (raw === undefined) return DEFAULT_HARNESS;
   if (!isHarness(raw)) {

package/src/instance/instance.ts

@@ -616,6 +616,7 @@ export class Instance {
           hostProcessDeps(() => this.#sessions.rowsNow(), config.upstream.terminal_gateway),
         ),
         forget: (sid) => this.#sessions.forget(sid),
+        presets: config.dump.presets,
       }),
       // The sandbox ops answer only where an origin is configured. Without one
       // there is nothing to serve a minted URL, and dispatch already refuses

package/src/plugin/skill.ts

@@ -63,6 +63,16 @@ ccmsg peers --all      他ホストの instance が知っている分も含め
 根拠をこちらで要約し直しても情報は増えず、時間とコンテキストだけが減る。人に言うのは
 自セッション目線の事実 (何を頼んだ・何が返り・その結果こちらが何をしたか) だけ。
 
+## 別のセッションのやり方を読む
+
+\`\`\`
+ccmsg dump <sid> --preset howto        親セッションが何を考えて何を叩いたか
+ccmsg dump <sid>/agent-<id> --preset howto   その worker 自身のやり口
+\`\`\`
+
+出力の末尾に ids 台帳があり、そこに出た \`agent\` の id が 2 行目の \`<id>\` になる。
+preset の一覧は \`ccmsg dump presets\`。
+
 ## 見ている人へ知らせる
 
 \`\`\`