@carljia/omd-dsh 0.1.2 → 0.1.3

package/README.md

@@ -38,15 +38,15 @@ tier 差异化子代理委派（等价 OMD 的 task(category=…)）。仅限 pr
 omd-dsh <command> [--harness <路径>] [--dry-run]
 ```
 
-- `omd-dsh sync` — 把 presets/ 与 vendored 行模块同步到 `<DSH_HOME>/.agent-presets/`（hash 保护、orphan 报告、非管理目录零操作）。每个 preset 的 omd-mode / omd-task 行由 `omd-matrix.json` 渲染。
-- `omd-dsh setup` — 交互式向导：先读取 DSH 已有模型，再引导逐模式/逐 tier 选择模型，写回 `omd-matrix.json` 并可选立即同步。
+- `omd-dsh sync` — 把 presets/ 与 vendored 行模块同步到 `<DSH_HOME>/.agent-presets/`（hash 保护、orphan 报告、非管理目录零操作）。每个 preset 的 omd-mode / omd-task 行由用户矩阵 `<DSH_HOME>/omd-matrix.json` 渲染。
+- `omd-dsh setup` — 交互式向导：先读取 DSH 已有模型，再引导逐模式/逐 tier 选择模型，写回 `<DSH_HOME>/omd-matrix.json` 并可选立即同步。
 - `omd-dsh models` — 打印发现的 DSH 模型目录（非交互）。
 
 细节见 docs/ARCHITECTURE.md 的「vendored 分发与跨树符号风险」。
 
-## 集中配置：omd-matrix.json
+## 集中配置：<DSH_HOME>/omd-matrix.json
 
-所有模式的模型路由（provider/model/reasoningEffort）与 omd_task 各 tier 的模型集中在一个 `omd-matrix.json` 里：`omd-dsh setup` 生成/更新它，`omd-dsh sync` 读取它并渲染进各 preset。preset 里 `# [omd-dsh:mode:start] / [omd-dsh:mode:end]` 与 `# [omd-dsh:task:start] / [omd-dsh:task:end]` 之间的区域是自动生成的——改模型请改矩阵后跑 sync，不要手改 fence 之间的内容。
+所有模式的模型路由（provider/model/reasoningEffort）与 omd_task 各 tier 的模型集中在用户矩阵 `<DSH_HOME>/omd-matrix.json`（默认 `~/.dsh/omd-matrix.json`）：`omd-dsh sync` 首次运行把随包的 deepseek 默认矩阵 `omd-matrix.default.json` 复制为默认配置（或从旧版本包内位置迁移一次），`omd-dsh setup` 更新它，`omd-dsh sync` 读取它并渲染进各 preset。仓库与 npm 包只携带默认矩阵文件，**不含任何个人模型配置**——个人模型配置只留在本机。preset 里 `# [omd-dsh:mode:start] / [omd-dsh:mode:end]` 与 `# [omd-dsh:task:start] / [omd-dsh:task:end]` 之间的区域是自动生成的——改模型请改矩阵后跑 sync，不要手改 fence 之间的内容。
 
 ## 开发
 

package/lib/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { promises as fs, existsSync, realpathSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { promises as fs, existsSync, mkdirSync, realpathSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, join, relative, resolve, basename } from "node:path";
 import { homedir } from "node:os";
@@ -10,25 +10,34 @@ import { createInterface } from "node:readline/promises";
  * omd-dsh CLI
  *
  *   omd-dsh sync    materialize presets into <DSH_HOME>/.agent-presets,
- *                   rendering each preset's omd-mode / omd-task rows from
- *                   omd-matrix.json (the single source for model routing and
- *                   tier delegation).
+ *                   rendering each preset's omd-mode / omd-task rows from the
+ *                   user's model matrix at <DSH_HOME>/omd-matrix.json. On
+ *                   first run the shipped deepseek default matrix
+ *                   (omd-matrix.default.json) is copied there; personal
+ *                   model settings stay on the user's machine and are never
+ *                   shipped or uploaded.
  *   omd-dsh setup   interactive wizard: discover the models DSH already has,
  *                   then guide per-mode and per-tier model selection.
  *   omd-dsh models  print the discovered model catalog (non-interactive).
  *
  * Distribution model (vendored + harness-anchored imports) is unchanged from
  * the original omd-dsh sync: presets/omd-* are copied into .agent-presets/;
- * their omd-mode/omd-task rows reference ../.omd-vendor/omd-mode.mjs /
- * omd-task.mjs by relative path; the vendored modules are copied into
- * .agent-presets/.omd-vendor/ with bare @deepseek-ai/* imports rewritten to
- * absolute file:// URLs into the harness node_modules tree.
+ * their omd-mode / omd-task / omd-plan / omd-start-work / omd-mode-switch
+ * rows reference ../.omd-vendor/*.mjs by relative path; the vendored modules
+ * are copied into .agent-presets/.omd-vendor/ with bare @deepseek-ai/*
+ * imports rewritten to absolute file:// URLs into the harness node_modules
+ * tree.
  */
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const VENDOR_SOURCES = ["omd-mode.mjs", "omd-task.mjs", "omd-ulw.mjs"];
-const MATRIX_PATH = join(PACKAGE_ROOT, "omd-matrix.json");
+const VENDOR_SOURCES = ["omd-mode.mjs", "omd-task.mjs", "omd-ulw.mjs", "omd-plan.mjs", "omd-start-work.mjs", "omd-mode-switch.mjs"];
+/** User-owned model matrix: lives under DSH_HOME, never inside the package or the repo. */
+const MATRIX_PATH = join(dshHome(), "omd-matrix.json");
+/** Pre-migration location (package root) — migrated to MATRIX_PATH once when present. */
+const LEGACY_MATRIX_PATH = join(PACKAGE_ROOT, "omd-matrix.json");
 const MODE_FENCE = { start: "# [omd-dsh:mode:start]", end: "# [omd-dsh:mode:end]" };
 const TASK_FENCE = { start: "# [omd-dsh:task:start]", end: "# [omd-dsh:task:end]" };
+/** Presets that were renamed: old directory name -> new preset name. */
+const RENAMED_FROM = { "omd-architect": "omd-ultraworker" };
 function usage() {
     return [
         "omd-dsh <command> [options]",
@@ -251,15 +260,66 @@ async function collectSourceFiles(rootDir) {
     return out;
 }
 // ── matrix ──
-function loadMatrix() {
-    if (!existsSync(MATRIX_PATH))
-        throw new Error("omd-dsh: missing " + MATRIX_PATH + " (run `omd-dsh setup` to create it, or restore it from source control)");
-    const parsed = JSON.parse(readFileSync(MATRIX_PATH, "utf8"));
-    if (parsed === null || typeof parsed !== "object" || parsed.modes === null || typeof parsed.modes !== "object")
-        throw new Error("omd-dsh: malformed " + MATRIX_PATH);
+/**
+ * The shipped default matrix (deepseek models) copied to
+ * <DSH_HOME>/omd-matrix.json on first run. The repo and the npm package
+ * ship ONLY this defaults file — personal model settings live exclusively
+ * in the user's <DSH_HOME>/omd-matrix.json and are never uploaded.
+ */
+const DEFAULT_MATRIX_PATH = join(PACKAGE_ROOT, "omd-matrix.default.json");
+/** Parse matrix text; undefined when it is not a usable matrix document. */
+function parseMatrix(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === "object" && parsed.modes !== null && typeof parsed.modes === "object")
+            return parsed;
+    }
+    catch { /* fall through */ }
+    return undefined;
+}
+/** Read the shipped default matrix, failing loud when the package is broken. */
+function readDefaultMatrix() {
+    if (!existsSync(DEFAULT_MATRIX_PATH))
+        throw new Error("omd-dsh: missing default matrix file " + DEFAULT_MATRIX_PATH + " (broken package — reinstall @carljia/omd-dsh)");
+    const parsed = parseMatrix(readFileSync(DEFAULT_MATRIX_PATH, "utf8"));
+    if (parsed === undefined)
+        throw new Error("omd-dsh: malformed default matrix file " + DEFAULT_MATRIX_PATH + " (broken package — reinstall @carljia/omd-dsh)");
+    return parsed;
+}
+/** Write a matrix file, creating its parent directory when needed. */
+function writeMatrixFile(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+/**
+ * Load the user's model matrix from <DSH_HOME>/omd-matrix.json, creating it
+ * on first run: a still-valid package-root matrix (previous versions) is
+ * migrated over, otherwise the shipped deepseek default matrix is written.
+ * Dry runs never touch the filesystem and use the shipped defaults in memory.
+ */
+function loadMatrix(flags) {
+    if (!existsSync(MATRIX_PATH)) {
+        if (flags.dryRun)
+            return JSON.parse(JSON.stringify(readDefaultMatrix()));
+        const legacyText = existsSync(LEGACY_MATRIX_PATH) ? readFileSync(LEGACY_MATRIX_PATH, "utf8") : undefined;
+        if (legacyText !== undefined && parseMatrix(legacyText) !== undefined) {
+            writeMatrixFile(MATRIX_PATH, legacyText);
+            console.log("omd-dsh: migrated omd-matrix.json: " + LEGACY_MATRIX_PATH + " -> " + MATRIX_PATH);
+            console.log("omd-dsh: customize the model matrix any time with `omd-dsh setup`.");
+        }
+        else {
+            const defaults = readDefaultMatrix();
+            writeMatrixFile(MATRIX_PATH, JSON.stringify(defaults, null, 2) + "\n");
+            console.log("omd-dsh: generated " + MATRIX_PATH + " from the shipped deepseek default matrix; customize it any time with `omd-dsh setup`.");
+        }
+    }
+    const text = readFileSync(MATRIX_PATH, "utf8");
+    const parsed = parseMatrix(text);
+    if (parsed === undefined)
+        throw new Error("omd-dsh: malformed " + MATRIX_PATH + " (restore it, or delete it and run omd-dsh setup)");
     return parsed;
 }
-function saveMatrix(m) { writeFileSync(MATRIX_PATH, JSON.stringify(m, null, 2) + "\n", "utf8"); }
+function saveMatrix(m) { writeMatrixFile(MATRIX_PATH, JSON.stringify(m, null, 2) + "\n"); }
 // ── row rendering (relative indents; the splice prepends the fence indent) ──
 function q(s) { return JSON.stringify(s); }
 function renderModeRow(modeId, cfg) {
@@ -370,14 +430,14 @@ function discoverModels() {
 }
 // ── sync ──
 async function runSync(flags, harnessNodeModules) {
-    const matrix = loadMatrix();
+    const matrix = loadMatrix(flags);
     const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
     const sourceVersion = manifest.version;
     const presetsSourceDir = join(PACKAGE_ROOT, "presets");
     const vendorSourceDir = join(PACKAGE_ROOT, "lib", "vendor");
     const agentPresetsRoot = join(dshHome(), ".agent-presets");
     const presetNames = (await fs.readdir(presetsSourceDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
-    const report = { synced: [], updated: [], conflicts: [], skipped: [], orphan: [] };
+    const report = { synced: [], updated: [], conflicts: [], skipped: [], orphan: [], removed: [] };
     const log = (kind, text) => report[kind].push(text);
     for (const presetName of presetNames) {
         const modeId = presetName.replace(/^omd-/, "");
@@ -488,19 +548,67 @@ async function runSync(flags, harnessNodeModules) {
                 continue;
             if (presetNames.includes(entry.name))
                 continue;
-            if (readMeta(join(agentPresetsRoot, entry.name)) !== undefined)
+            const orphanDir = join(agentPresetsRoot, entry.name);
+            const meta = readMeta(orphanDir);
+            if (meta === undefined)
+                continue;
+            const renamedTo = RENAMED_FROM[entry.name];
+            if (renamedTo !== undefined && presetNames.includes(renamedTo)) {
+                const dirty = await locallyModified(orphanDir, meta);
+                if (dirty === undefined) {
+                    if (!flags.dryRun)
+                        await fs.rm(orphanDir, { recursive: true, force: true });
+                    log("removed", entry.name + "/ (renamed to " + renamedTo + " and unmodified -- removed" + (flags.dryRun ? ", dry-run" : "") + ")");
+                }
+                else {
+                    log("conflicts", entry.name + "/ (renamed to " + renamedTo + " but locally modified -- keeping your version: " + dirty + ")");
+                }
+            }
+            else {
                 log("orphan", entry.name + "/ (was installed by omd-dsh but no longer ships with v" + sourceVersion + " -- left untouched)");
+            }
         }
     }
     console.log("omd-dsh sync: DSH_HOME=" + dshHome());
+    console.log("omd-dsh sync: matrix=" + MATRIX_PATH + " (customize the model matrix any time with `omd-dsh setup`)");
     console.log("omd-dsh sync: harness node_modules=" + harnessNodeModules);
     console.log("omd-dsh sync: source version=" + sourceVersion + (flags.dryRun ? " (dry-run)" : ""));
-    for (const key of ["synced", "updated", "skipped", "conflicts", "orphan"])
+    for (const key of ["synced", "updated", "skipped", "conflicts", "orphan", "removed"])
         for (const line of report[key])
             console.log("  [" + key + "] " + line);
-    const summary = ["synced", "updated", "conflicts", "orphan"].map((key) => report[key].length + " " + key).join(", ");
+    const summary = ["synced", "updated", "conflicts", "orphan", "removed"].map((key) => report[key].length + " " + key).join(", ");
     console.log("omd-dsh sync: " + summary + (flags.dryRun ? " (dry-run)" : ""));
 }
+/**
+ * Whether one omd-dsh-managed preset directory differs from the hashes its
+ * .omd-meta.json recorded. Returns a description of the first discrepancy,
+ * or undefined when every recorded file is present and unmodified and no
+ * extra files exist.
+ */
+async function locallyModified(dir, meta) {
+    const recorded = meta.files ?? {};
+    const current = {};
+    const walk = async (d) => {
+        for (const entry of await fs.readdir(d, { withFileTypes: true })) {
+            const full = join(d, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.name !== ".omd-meta.json") {
+                const rel = relative(dir, full).split("\\").join("/");
+                current[rel] = sha256(await fs.readFile(full, "utf8"));
+            }
+        }
+    };
+    await walk(dir);
+    for (const rel of new Set([...Object.keys(recorded), ...Object.keys(current)])) {
+        if (current[rel] === undefined)
+            return "missing file " + rel;
+        const recordedHash = recorded[rel] !== undefined && typeof recorded[rel] === "object" && recorded[rel] !== null ? recorded[rel].sha256 : undefined;
+        if (typeof recordedHash !== "string" || recordedHash !== current[rel])
+            return "modified file " + rel;
+    }
+    return undefined;
+}
 // ── setup (interactive) ──
 function splitModel(answer) {
     const a = answer.trim();
@@ -511,7 +619,7 @@ function splitModel(answer) {
     return { provider: "deepseek-official", model: a };
 }
 async function runSetup(flags, harnessNodeModules) {
-    const matrix = loadMatrix();
+    const matrix = loadMatrix(flags);
     const { models, currentDefault } = discoverModels();
     console.log("omd-dsh setup: 发现 DSH 已有模型：");
     for (const m of models)
@@ -521,7 +629,7 @@ async function runSetup(flags, harnessNodeModules) {
     console.log("");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ask = async (question) => (await rl.question(question)).trim();
-    const modeOrder = ["executor", "architect", "planner", "reviewer", "explorer", "librarian", "chat"];
+    const modeOrder = ["executor", "ultraworker", "planner", "reviewer", "explorer", "librarian", "chat"];
     for (const modeId of modeOrder) {
         const cfg = matrix.modes[modeId] ?? {};
         const cur = cfg.provider && cfg.model ? cfg.provider + "/" + cfg.model : "";

package/lib/mode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module @carljia/omd-dsh/mode
+ *
+ * omd-mode-switch: human-facing `/mode` command -- switch the CURRENT
+ * session to another OMD agent preset, including mid-conversation.
+ *
+ * DSH's native `agentPreset.select` host API refuses to recompose a
+ * session that has already started (its preset is fixed at the UI level),
+ * and the AgentPresets.recompose method itself performs no history check
+ * ("the CALLER owns that check"). This row deliberately performs the
+ * in-session recompose, then keeps the log honest:
+ *   - appends `agent-preset/selected`, so resume/fork rebuild the same
+ *     composition ("model-visible <-> logged" rule);
+ *   - appends `plan/mode { active: false }` when plan mode is still
+ *     active, since the switch itself is a mode decision;
+ *   - steers a notice message so the model knows the tool set changed.
+ *
+ * Mitigations for the swapped tool catalog: the omd-planner catalog is a
+ * subset of omd-executor's (the executor preset also mounts the plan-mode
+ * row), so logged planner tool calls stay renderable under the executor
+ * composition. Switching between other omd presets follows the same rule
+ * and the model simply receives the new catalog on the next request.
+ */
+/** Cordis plugin name. */
+declare const name = "omd-mode-switch";
+/**
+ * No mount-time injection: the roster service is resolved at runtime so a
+ * rosterless deployment fails only the /mode command, never the preset
+ * mount itself.
+ */
+declare const inject: never[];
+declare function apply(ctx: any): void;
+export { apply, inject, name };

package/lib/mode.js

@@ -0,0 +1,145 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { scopeOf } from "@deepseek-ai/dsh-scope";
+/**
+ * @module @carljia/omd-dsh/mode
+ *
+ * omd-mode-switch: human-facing `/mode` command -- switch the CURRENT
+ * session to another OMD agent preset, including mid-conversation.
+ *
+ * DSH's native `agentPreset.select` host API refuses to recompose a
+ * session that has already started (its preset is fixed at the UI level),
+ * and the AgentPresets.recompose method itself performs no history check
+ * ("the CALLER owns that check"). This row deliberately performs the
+ * in-session recompose, then keeps the log honest:
+ *   - appends `agent-preset/selected`, so resume/fork rebuild the same
+ *     composition ("model-visible <-> logged" rule);
+ *   - appends `plan/mode { active: false }` when plan mode is still
+ *     active, since the switch itself is a mode decision;
+ *   - steers a notice message so the model knows the tool set changed.
+ *
+ * Mitigations for the swapped tool catalog: the omd-planner catalog is a
+ * subset of omd-executor's (the executor preset also mounts the plan-mode
+ * row), so logged planner tool calls stay renderable under the executor
+ * composition. Switching between other omd presets follows the same rule
+ * and the model simply receives the new catalog on the next request.
+ */
+/** Cordis plugin name. */
+const name = "omd-mode-switch";
+/**
+ * No mount-time injection: the roster service is resolved at runtime so a
+ * rosterless deployment fails only the /mode command, never the preset
+ * mount itself.
+ */
+const inject = [];
+/** The OMD presets /mode may switch to. */
+const OMD_PRESET_IDS = [
+    "omd-executor",
+    "omd-ultraworker",
+    "omd-planner",
+    "omd-reviewer",
+    "omd-explorer",
+    "omd-librarian",
+    "omd-chat",
+];
+/** Normalize the command input to a valid omd preset id, or undefined. */
+function normalizeTarget(rawInput) {
+    const trimmed = String(rawInput).trim().toLowerCase();
+    if (trimmed === "")
+        return undefined;
+    const candidate = trimmed.startsWith("omd-") ? trimmed : "omd-" + trimmed;
+    return OMD_PRESET_IDS.includes(candidate) ? candidate : undefined;
+}
+/** Fold the session's plan/mode events (last one wins). */
+function planModeActive(events) {
+    let active = false;
+    for (const event of events ?? []) {
+        if (event !== undefined && event.type === "plan/mode") {
+            active = event.data !== undefined && event.data !== null && event.data.active === true;
+        }
+    }
+    return active;
+}
+/** Execute one /mode invocation through the roster service. */
+async function executeSwitch(ctx, invocation) {
+    const agent = invocation.agent;
+    const target = normalizeTarget(invocation.rawInput);
+    if (target === undefined) {
+        return {
+            kind: "error",
+            text: "Usage: /mode <preset> — valid: " + OMD_PRESET_IDS.join(", "),
+        };
+    }
+    let presets;
+    try {
+        presets = ctx.get("agentPresets");
+    }
+    catch {
+        presets = undefined;
+    }
+    if (presets === undefined || presets === null) {
+        return {
+            kind: "error",
+            text: "/mode is unavailable: this deployment composes no agent presets.",
+        };
+    }
+    let current;
+    try {
+        current = presets.composedPreset(agent.ctx);
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === target) {
+        return { kind: "success", text: "Already running " + target + "." };
+    }
+    try {
+        const preset = await presets.recompose(agent.ctx, target);
+        agent.session.append("agent-preset/selected", { agentPreset: preset.id });
+        if (planModeActive(agent.session.events)) {
+            agent.session.append("plan/mode", { active: false });
+        }
+        agent.steer(createUserMessage({
+            content: [
+                {
+                    type: "text",
+                    text: "The session switched to the " +
+                        preset.id +
+                        " agent preset. Continue in this mode with its tool set, persona, and model routing.",
+                },
+            ],
+            source: {
+                kind: "plugin",
+                plugin: "omd-mode-switch",
+                form: "notice",
+                summary: "Session mode switched to " + preset.id,
+            },
+        }));
+        return {
+            kind: "success",
+            text: "Session preset switched to " + preset.id + " — the next turn runs with that mode's tools and model.",
+        };
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            text: "/mode failed: " + (error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+function apply(ctx) {
+    if (scopeOf(ctx) === undefined) {
+        throw new Error("omd-mode-switch: refusing to mount outside a scoped context; mount this row inside an agent preset");
+    }
+    ctx.inject(["commands"], (commandCtx) => {
+        commandCtx.commands.register({
+            name: "mode",
+            description: "switch this session to another omd agent preset (tool set + model)",
+            input: {
+                hint: "<omd-* preset id>",
+                images: false,
+            },
+            handler: (invocation) => executeSwitch(ctx, invocation),
+        });
+    });
+}
+export { apply, inject, name };

package/lib/plan.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module @carljia/omd-dsh/plan
+ *
+ * omd-plan: plan persistence for the OMD planner mode. It wraps the
+ * `tools/post-execute` waterfall and intercepts a successful
+ * `exit_plan_mode` approval: the approved plan text is written into the
+ * workspace's plan directory (a fixed, code-level convention -- never
+ * mentioned in any persona/prompt text), and the tool result content is
+ * enriched with the saved file name so the planner's fixed Start Work
+ * final step can hand it to the user.
+ *
+ * Plan directory convention (hardcoded here and in omd-start-work only):
+ *   <session cwd>/.omd/plans/<slug>-<timestamp>.md
+ * The slug derives from the plan's first markdown heading; a timestamp
+ * suffix keeps repeated interviews from overwriting each other.
+ */
+/** Cordis plugin name. */
+declare const name = "omd-plan";
+/** No service injection: this row only registers a scoped event listener. */
+declare const inject: never[];
+declare function apply(ctx: any): void;
+export { apply, inject, name };

package/lib/plan.js

@@ -0,0 +1,146 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { scopeOf } from "@deepseek-ai/dsh-scope";
+/**
+ * @module @carljia/omd-dsh/plan
+ *
+ * omd-plan: plan persistence for the OMD planner mode. It wraps the
+ * `tools/post-execute` waterfall and intercepts a successful
+ * `exit_plan_mode` approval: the approved plan text is written into the
+ * workspace's plan directory (a fixed, code-level convention -- never
+ * mentioned in any persona/prompt text), and the tool result content is
+ * enriched with the saved file name so the planner's fixed Start Work
+ * final step can hand it to the user.
+ *
+ * Plan directory convention (hardcoded here and in omd-start-work only):
+ *   <session cwd>/.omd/plans/<slug>-<timestamp>.md
+ * The slug derives from the plan's first markdown heading; a timestamp
+ * suffix keeps repeated interviews from overwriting each other.
+ */
+/** Cordis plugin name. */
+const name = "omd-plan";
+/** No service injection: this row only registers a scoped event listener. */
+const inject = [];
+/** Plan directory segments relative to the session workspace root (cwd). */
+const PLAN_DIR_SEGMENTS = [".omd", "plans"];
+/** The exit tool whose approved plan we persist. */
+const EXIT_PLAN_MODE = "exit_plan_mode";
+/** Maximum slug length (characters). */
+const SLUG_MAX = 48;
+/** The plan's first markdown heading (any level), or undefined when it has none. */
+function firstHeading(plan) {
+    for (const line of plan.split("\n")) {
+        const match = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+/** Derive a filesystem-safe slug from the plan title. */
+function slugify(title) {
+    const slug = String(title)
+        .normalize("NFKD")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX);
+    return slug === "" ? "plan" : slug;
+}
+/** Compact local-ish UTC timestamp for the file name: YYYYMMDD-HHmmss. */
+function timestamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return (d.getUTCFullYear() +
+        pad(d.getUTCMonth() + 1) +
+        pad(d.getUTCDate()) +
+        "-" +
+        pad(d.getUTCHours()) +
+        pad(d.getUTCMinutes()) +
+        pad(d.getUTCSeconds()));
+}
+/** Write the plan into <cwd>/.omd/plans/ and return the absolute file path. */
+async function savePlan(cwd, plan) {
+    const dir = join(cwd, ...PLAN_DIR_SEGMENTS);
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, slugify(firstHeading(plan) ?? "") + "-" + timestamp() + ".md");
+    await writeFile(file, plan, "utf8");
+    return file;
+}
+/** Display path used in result enrichment and messages (forward slashes). */
+function displayPath(saved) {
+    return PLAN_DIR_SEGMENTS.join("/") + "/" + basename(saved);
+}
+/** Subagents never own the plan review -- only the top-level planner does. */
+function isSubagent(agent) {
+    return (agent !== undefined &&
+        agent !== null &&
+        agent.options !== undefined &&
+        agent.options !== null &&
+        typeof agent.options.subagentDepth === "number" &&
+        agent.options.subagentDepth > 0);
+}
+function apply(ctx) {
+    if (scopeOf(ctx) === undefined) {
+        throw new Error("omd-plan: refusing to mount outside a scoped context; mount this row inside an agent preset");
+    }
+    ctx.on("tools/post-execute", async (exec, result, next) => {
+        const decision = await next();
+        if (decision.kind !== "accept" || decision.value !== undefined)
+            return decision;
+        if (exec === undefined || exec.name !== EXIT_PLAN_MODE)
+            return decision;
+        if (result.isError)
+            return decision;
+        const agent = exec.agent;
+        if (agent === undefined || isSubagent(agent))
+            return decision;
+        const args = exec.arguments;
+        const plan = args !== undefined && args !== null && typeof args.plan === "string" ? args.plan : undefined;
+        if (plan === undefined)
+            return decision;
+        const cwd = agent.session !== undefined &&
+            agent.session.header !== undefined &&
+            typeof agent.session.header.cwd === "string"
+            ? agent.session.header.cwd
+            : "";
+        if (cwd === "") {
+            // No workspace root to save into: fail closed but tell the model, so
+            // the planner does not promise a file name it never produced.
+            return withNotice(decision, result, {
+                type: "text",
+                text: "The approved plan could NOT be saved automatically: this session has no workspace directory. Ask the user how to proceed.",
+            });
+        }
+        try {
+            const saved = await savePlan(cwd, plan);
+            return withNotice(decision, result, {
+                type: "text",
+                text: "Plan saved to " +
+                    displayPath(saved) +
+                    ". Start work: run /start-work " +
+                    basename(saved) +
+                    " in an omd-executor session, or switch this session with /mode omd-executor and continue here.",
+            });
+        }
+        catch (error) {
+            return withNotice(decision, result, {
+                type: "text",
+                text: "The approved plan could NOT be saved automatically: " +
+                    (error instanceof Error ? error.message : String(error)) +
+                    ". Ask the user how to proceed.",
+            });
+        }
+    });
+}
+/** Keep the accepted decision, appending one text block to its content. */
+function withNotice(decision, result, block) {
+    const base = Array.isArray(decision.content) ? decision.content : result.content ?? [];
+    return {
+        kind: "accept",
+        content: [...base, block],
+        ...(decision.additionalContexts !== undefined
+            ? { additionalContexts: decision.additionalContexts }
+            : {}),
+    };
+}
+export { apply, inject, name };

package/lib/startwork.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module @carljia/omd-dsh/startwork
+ *
+ * omd-start-work: human-facing `/start-work` command -- the "start work"
+ * trigger at the end of the OMD planning workflow. It resolves the named
+ * plan file inside the workspace's plan directory (a fixed, code-level
+ * convention -- never mentioned in any persona/prompt text), arms a goal
+ * whose objective references the plan's absolute path, and goal
+ * auto-continuation then drives the agent to execute the plan without
+ * further input.
+ */
+/** Cordis plugin name. */
+declare const name = "omd-start-work";
+/** The goal domain is already required by tool-goal in the same preset. */
+declare const inject: string[];
+declare function apply(ctx: any): void;
+export { apply, inject, name };