@ccmsg/cli 0.3.5 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "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/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/sessions/dump.ts

@@ -1,25 +1,47 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import type { InstanceId, SessionDumpWriteArgs, SessionDumpWriteResult } from "@ccmsg/protocol";
+import type {
+  DumpPreset,
+  InstanceId,
+  SessionDumpFile,
+  SessionDumpWriteArgs,
+  SessionDumpWriteResult,
+} from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
-import { readRecord, type TranscriptFiles, type TranscriptRecord } from "../transcript/index.ts";
+import { classify, type Item, ledger, select, selection } from "../transcript/items/index.ts";
+import type { TranscriptFiles } from "../transcript/index.ts";
 
 /** Where dumps land: one directory under this instance's own state, named
  * after the config home it answers for like every other per-instance path
  * (§8.1). The caller never supplies a path, so there is none to contain. */
 export const DUMPS = "dumps";
 
+/** What a dump file is called. Two extensions rather than one so that a reader
+ * knows both that it is JSON and that it is JSON of a shape the contract
+ * states — the file travels by its path, outliving the request that made it,
+ * and is opened by whoever was handed that path. */
+export const DUMP_SUFFIX = ".dump.json";
+
 export interface DumpDeps {
   readonly self: InstanceId;
   readonly stateDir: string;
   readonly files: TranscriptFiles;
+  /** The selections this instance is configured with, which is what a `preset`
+   * name and an `@name` inside a selection are resolved against. */
+  readonly presets: readonly DumpPreset[];
 }
 
 /** Write a session's dump and answer with where it went.
  *
  * What this adds over reading the transcript is a durable artifact whose path
  * can be handed to a successor session, rather than a payload that would
- * travel out through a client and back in again. */
+ * travel out through a client and back in again.
+ *
+ * The subject is the session, or one agent below it when the request names
+ * one. Every item type is read from wherever the subject stands — an agent's
+ * `message:user:in` is the brief its parent gave it — so one selection carries
+ * unchanged down a chain of agents, which is what makes the ledger's agent ids
+ * a way to descend rather than just a list. */
 export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDumpWriteResult {
   if (args.since_at !== undefined && args.since_uuid !== undefined) {
     throw new OpError("invalid_args", "a lower bound is a time or a record, not both");
@@ -27,79 +49,95 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
   if (args.until_at !== undefined && args.until_uuid !== undefined) {
     throw new OpError("invalid_args", "an upper bound is a time or a record, not both");
   }
-  const file = deps.files.session(args.sid);
+  const preset = presetFor(args.preset, deps.presets);
+  const file = deps.files.locate(
+    args.sid,
+    args.agent_id === undefined ? {} : { agent_id: args.agent_id },
+  );
   let text: string;
   try {
     text = readFileSync(file, "utf8");
   } catch {
     throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
   }
-  const entries = collect(text, args);
-  const document = {
+  // The whole file is classified before the range is applied, so a result
+  // inside the range still names the call that fell before it. Cutting first
+  // would leave `parent_item` pointing at something the reader never saw.
+  const keep = selection(
+    {
+      ...(args.types === undefined ? {} : { types: args.types }),
+      ...(preset === undefined ? {} : { preset }),
+      ...(args.no_thinking === undefined ? {} : { no_thinking: args.no_thinking }),
+      ...(args.no_agent === undefined ? {} : { no_agent: args.no_agent }),
+    },
+    deps.presets,
+  );
+  const { items, entries } = select(within(classify(text.split("\n")), args), keep);
+  const ids = ledger(items);
+  const written_at = Date.now();
+  // The file repeats what it was asked for. A dump outlives the request that
+  // made it and is read by whoever was handed the path, so it has to say on
+  // its own what it is a dump of and what was left out — which is why the
+  // selection is written as applied, with the presets already expanded.
+  const document: SessionDumpFile = {
     sid: args.sid,
-    instance: deps.self,
-    source: file,
-    generated_at: Date.now(),
-    entries,
+    ...(args.agent_id === undefined ? {} : { agent_id: args.agent_id }),
+    written_at,
+    types: [...keep.elements],
+    items,
+    ids,
   };
   const dir = join(deps.stateDir, DUMPS);
   mkdirSync(dir, { recursive: true });
-  const path = join(dir, `${args.sid}-${document.generated_at}.json`);
+  const named = args.agent_id === undefined ? args.sid : `${args.sid}-agent-${args.agent_id}`;
+  const path = join(dir, `${named}-${written_at}${DUMP_SUFFIX}`);
   const body = `${JSON.stringify(document, undefined, 2)}\n`;
   writeFileSync(path, body);
-  return {
-    path,
-    instance: deps.self,
-    entries: entries.length,
-    bytes: Buffer.byteLength(body),
-  };
+  return { path, instance: deps.self, entries, ids, bytes: Buffer.byteLength(body) };
 }
 
-/** One record of a dump: what was said, by whom, when.
+/** The named selection a request asked for.
  *
- * The fields are the record's own, taken from the type that reads a transcript
- * line rather than restated here — a dump reports what was read, and a second
- * spelling of those fields would be a second interpretation of the file. */
-type DumpEntry = Pick<TranscriptRecord, "uuid" | "said_at" | "said_by" | "text" | "thinking">;
+ * A name this instance does not have is refused rather than ignored: a dump
+ * silently wider than what was asked for is the failure a selection exists to
+ * prevent. */
+function presetFor(
+  name: string | undefined,
+  presets: readonly DumpPreset[],
+): DumpPreset | undefined {
+  if (name === undefined) return undefined;
+  const found = presets.find((one) => one.name === name);
+  if (found === undefined) throw new OpError("invalid_args", `no preset is configured as ${name}`);
+  return found;
+}
 
-/** The records within the bounds, in the order the transcript holds them.
+/** The items within the bounds, in the order the transcript holds them.
  *
  * A record bound cuts at that record's position rather than at its clock, so
  * records sharing an instant stay on their own side of the cut — which is the
- * whole reason the contract offers both kinds of bound. */
-function collect(text: string, args: SessionDumpWriteArgs): DumpEntry[] {
-  const entries: DumpEntry[] = [];
-  // A lower bound by record starts the dump closed: it opens at the record it
-  // names, which is included.
+ * whole reason the contract offers both kinds of bound. Every item a record
+ * became carries that record's id, so a bound by record keeps a turn's
+ * thinking, words and calls together. */
+function within(items: readonly Item[], args: SessionDumpWriteArgs): Item[] {
+  const kept: Item[] = [];
+  // A lower bound by record starts closed: it opens at the record it names,
+  // which is included.
   let open = args.since_uuid === undefined;
-  for (const line of text.split("\n")) {
-    if (line === "") continue;
-    const record = readRecord(line);
-    if (record === undefined) continue;
+  for (let at = 0; at < items.length; at += 1) {
+    const item = items[at];
+    if (item === undefined) continue;
     if (!open) {
-      if (record.uuid !== args.since_uuid) continue;
+      if (item.uuid !== args.since_uuid) continue;
       open = true;
     }
-    if (args.since_at !== undefined && (record.said_at ?? 0) < args.since_at) continue;
-    if (args.until_at !== undefined && (record.said_at ?? 0) > args.until_at) break;
-    // The machinery of in-process agents: their turns interleave into the
-    // session's own file, and a successor resuming the session is resuming the
-    // session rather than them.
-    if (args.no_agent === true && record.sidechain) {
-      if (record.uuid !== undefined && record.uuid === args.until_uuid) break;
-      continue;
+    if (args.since_at !== undefined && item.at < args.since_at) continue;
+    if (args.until_at !== undefined && item.at > args.until_at) break;
+    kept.push(item);
+    // An upper bound by record is inclusive and cuts after the last item that
+    // record became, so the rest of the same record is still let through.
+    if (args.until_uuid !== undefined && item.uuid === args.until_uuid) {
+      if (items[at + 1]?.uuid !== item.uuid) break;
     }
-    entries.push({
-      ...(record.uuid === undefined ? {} : { uuid: record.uuid }),
-      ...(record.said_at === undefined ? {} : { said_at: record.said_at }),
-      ...(record.said_by === undefined ? {} : { said_by: record.said_by }),
-      ...(record.text === undefined ? {} : { text: record.text }),
-      ...(args.no_thinking === true || record.thinking === undefined
-        ? {}
-        : { thinking: record.thinking }),
-    });
-    // An upper bound by record is inclusive, so the cut is after it.
-    if (record.uuid !== undefined && record.uuid === args.until_uuid) break;
   }
-  return entries;
+  return kept;
 }

package/src/sessions/handlers.ts

@@ -1,5 +1,7 @@
 import {
   type Capability,
+  type DumpPreset,
+  type DumpPresetsReadResult,
   type InstanceId,
   type SessionDumpWriteArgs,
   type SessionEnvReadArgs,
@@ -57,9 +59,11 @@ export interface SessionOpsDeps {
    * instance last saw them. The sessions domain owns the list; this op only
    * asks it to forget a row. */
   readonly forget: (sid: Sid) => boolean;
+  /** The named selections this instance is configured with (§3.6). */
+  readonly presets: readonly DumpPreset[];
 }
 
-/** The eight ops that observe and operate on sessions.
+/** The ops that observe and operate on sessions.
  *
  * None of them decides who may call it: dispatch has settled that from the
  * attribute table. The one that narrows by role is `transcript_read`, and it
@@ -104,8 +108,17 @@ export function sessionHandlers(deps: SessionOpsDeps) {
         self: deps.self,
         stateDir: deps.stateDir,
         files: deps.files,
+        presets: deps.presets,
       }),
 
+    /** Which selections a dump may be asked for by name.
+     *
+     * Nothing else states them, so a client without this could only offer a
+     * free-text field and let the instance refuse. A preset that references
+     * another is answered as written: the expansion, and the refusal of a
+     * cycle, happen where the config is read. */
+    dump_presets_read: (): DumpPresetsReadResult => ({ presets: [...deps.presets] }),
+
     session_fork_origin: (input: HandlerInput): SessionForkOriginResult => {
       const args = input.args as unknown as SessionForkOriginArgs;
       const origin = forkOrigin(args.sid, deps.files);

package/src/sessions/index.ts

@@ -1,5 +1,5 @@
 export * from "./classify.ts";
-export { DUMPS, dumpWrite } from "./dump.ts";
+export { DUMP_SUFFIX, DUMPS, dumpWrite } from "./dump.ts";
 export { forkOrigin } from "./fork.ts";
 export * from "./harness.ts";
 export { sessionCapabilities, sessionHandlers, type SessionOpsDeps } from "./handlers.ts";