@carljia/omd-dsh 0.1.1 → 0.1.3

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 };

package/lib/startwork.js

@@ -0,0 +1,147 @@
+import { access, readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { scopeOf } from "@deepseek-ai/dsh-scope";
+/**
+ * @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. */
+const name = "omd-start-work";
+/** The goal domain is already required by tool-goal in the same preset. */
+const inject = ["goals"];
+/** Plan directory segments relative to the session workspace root (cwd). */
+const PLAN_DIR_SEGMENTS = [".omd", "plans"];
+/** The prefix accepted when a user pastes the full relative plan path. */
+const PLAN_DIR_PREFIX = ".omd/plans/";
+/** Plan directory for one workspace root. */
+function plansDir(cwd) {
+    return join(cwd, ...PLAN_DIR_SEGMENTS);
+}
+/**
+ * Resolve the user's file-name input to a candidate path inside the plan
+ * directory. Accepts a bare file name ("foo.md" / "foo") or the full
+ * relative path (".omd/plans/foo.md"); rejects absolute paths and anything
+ * that would escape the plan directory.
+ */
+function resolveCandidate(cwd, input) {
+    const trimmed = String(input).trim().replace(/\\/g, "/");
+    if (trimmed === "" || isAbsolute(trimmed))
+        return undefined;
+    let name = trimmed.replace(/^\.\//, "");
+    if (name.includes("/")) {
+        if (!name.startsWith(PLAN_DIR_PREFIX))
+            return undefined;
+        name = name.slice(PLAN_DIR_PREFIX.length);
+    }
+    if (name === "" || name.includes("/") || name === "." || name === "..")
+        return undefined;
+    if (name.startsWith("."))
+        return undefined; // no hidden-file tricks
+    return join(plansDir(cwd), name);
+}
+/** One /start-work invocation through the goal domain. */
+async function executeStartWork(ctx, invocation) {
+    const agent = invocation.agent;
+    const cwd = agent !== undefined &&
+        agent.session !== undefined &&
+        agent.session.header !== undefined &&
+        typeof agent.session.header.cwd === "string"
+        ? agent.session.header.cwd
+        : "";
+    if (cwd === "") {
+        return {
+            kind: "error",
+            text: "This session has no workspace directory; /start-work needs one to find the plan file.",
+        };
+    }
+    const candidate = resolveCandidate(cwd, invocation.rawInput);
+    if (candidate === undefined) {
+        return {
+            kind: "error",
+            text: "Usage: /start-work <plan file name> — the file must live inside " + PLAN_DIR_SEGMENTS.join("/") + "/.",
+        };
+    }
+    let file = candidate;
+    const usable = async (path) => {
+        try {
+            await access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!(await usable(file)) && !file.endsWith(".md") && (await usable(file + ".md"))) {
+        file = file + ".md";
+    }
+    else if (!(await usable(file))) {
+        return {
+            kind: "error",
+            text: "Plan file not found: " + PLAN_DIR_SEGMENTS.join("/") + "/" + file.slice(plansDir(cwd).length + 1),
+        };
+    }
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            text: "Cannot read the plan file: " + (error instanceof Error ? error.message : String(error)),
+        };
+    }
+    if (text.trim() === "") {
+        return { kind: "error", text: "The plan file is empty." };
+    }
+    try {
+        const current = ctx.goals.get(agent);
+        if (current !== undefined && current.phase !== "complete") {
+            return {
+                kind: "error",
+                text: `A goal is already ${current.phase}. Run /goal clear first, then /start-work <plan file name>.`,
+            };
+        }
+        ctx.goals.create(agent, {
+            objective: "Execute the approved plan file at " +
+                file +
+                ". Read the file in full, then carry out every step autonomously: implement, verify, and iterate until the plan's goal and success criteria are met. Work through goal continuation rounds until done.",
+        });
+        return {
+            kind: "success",
+            text: "Start work armed — executing the plan to completion.\nPlan: " +
+                PLAN_DIR_SEGMENTS.join("/") +
+                "/" +
+                file.slice(plansDir(cwd).length + 1),
+        };
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            text: "start-work failed: " + (error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+function apply(ctx) {
+    if (scopeOf(ctx) === undefined) {
+        throw new Error("omd-start-work: refusing to mount outside a scoped context; mount this row inside an agent preset");
+    }
+    ctx.inject(["commands"], (commandCtx) => {
+        commandCtx.commands.register({
+            name: "start-work",
+            description: "start work: arm a goal that executes the named plan file to completion",
+            input: {
+                hint: "<plan file name>",
+                images: false,
+            },
+            handler: (invocation) => executeStartWork(ctx, invocation),
+        });
+    });
+}
+export { apply, inject, name };

package/lib/vendor/omd-mode-switch.mjs

@@ -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/vendor/omd-plan.mjs

@@ -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 };