@carljia/omd-dsh 0.1.4 → 0.1.7

package/lib/plan.d.ts

@@ -1,13 +1,19 @@
 /**
  * @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.
+ * omd-plan: plan persistence + plan-mode activation + write scope for the OMD
+ * planner mode. Three jobs, all scoped to the planner preset:
+ *   1. auto-activate plan mode for the top-level agent, so the plan:policy
+ *      section renders and exit_plan_mode works (DSH leaves plan state
+ *      inactive until /plan or a programmatic set);
+ *   2. enforce a .md-only write guard so the planner stays read-only except
+ *      for markdown files;
+ *   3. wrap `tools/post-execute` and intercept 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
@@ -16,7 +22,7 @@
  */
 /** Cordis plugin name. */
 declare const name = "omd-plan";
-/** No service injection: this row only registers a scoped event listener. */
+/** No service injection: this row only registers scoped event listeners. */
 declare const inject: never[];
 declare function apply(ctx: any): void;
 export { apply, inject, name };

package/lib/plan.js

@@ -4,13 +4,19 @@ 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.
+ * omd-plan: plan persistence + plan-mode activation + write scope for the OMD
+ * planner mode. Three jobs, all scoped to the planner preset:
+ *   1. auto-activate plan mode for the top-level agent, so the plan:policy
+ *      section renders and exit_plan_mode works (DSH leaves plan state
+ *      inactive until /plan or a programmatic set);
+ *   2. enforce a .md-only write guard so the planner stays read-only except
+ *      for markdown files;
+ *   3. wrap `tools/post-execute` and intercept 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
@@ -19,7 +25,7 @@ import { scopeOf } from "@deepseek-ai/dsh-scope";
  */
 /** Cordis plugin name. */
 const name = "omd-plan";
-/** No service injection: this row only registers a scoped event listener. */
+/** No service injection: this row only registers scoped event listeners. */
 const inject = [];
 /** Plan directory segments relative to the session workspace root (cwd). */
 const PLAN_DIR_SEGMENTS = [".omd", "plans"];
@@ -79,10 +85,57 @@ function isSubagent(agent) {
         typeof agent.options.subagentDepth === "number" &&
         agent.options.subagentDepth > 0);
 }
+/** Fold the session's plan/mode events (last one wins); mirror mode.ts. */
+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;
+}
 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");
     }
+    // Scoped .md-only write guard: the planner may write/edit only markdown
+    // files, keeping it read-only for every other path. The plan file itself is
+    // written by this row via node:fs (not through the model's write/edit tools),
+    // so plan persistence is unaffected by the guard. Implemented on the
+    // tools/pre-execute gate (the row's existing ctx.on style) so no service
+    // injection is required.
+    ctx.on("tools/pre-execute", async (exec, next) => {
+        const toolName = exec !== undefined && exec !== null ? exec.name : undefined;
+        if (toolName !== "write" && toolName !== "edit")
+            return await next();
+        const filePath = exec.arguments !== undefined &&
+            exec.arguments !== null &&
+            typeof exec.arguments.file_path === "string"
+            ? exec.arguments.file_path
+            : undefined;
+        if (filePath !== undefined && filePath.toLowerCase().endsWith(".md"))
+            return await next();
+        return {
+            kind: "deny",
+            reason: "omd-plan: the planner preset may write or edit only .md files (refusing " +
+                toolName +
+                " on a non-.md path)",
+        };
+    });
+    // Auto-activate plan mode for the top-level planner agent. DSH leaves plan
+    // state inactive until /plan or a programmatic set, so without this the
+    // plan:policy section never renders and exit_plan_mode fails with "only
+    // available in plan mode". Mirror mode.ts's direct log append (no narration)
+    // so the planner session is in plan mode from its first request onward.
+    ctx.on("agent/pre-step", async ({ agent }, next) => {
+        if (agent !== undefined && agent !== null && !isSubagent(agent) && agent.session !== undefined && agent.session !== null) {
+            if (!planModeActive(agent.session.events)) {
+                agent.session.append("plan/mode", { active: true });
+            }
+        }
+        return await next();
+    });
     ctx.on("tools/post-execute", async (exec, result, next) => {
         const decision = await next();
         if (decision.kind !== "accept" || decision.value !== undefined)

package/lib/shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module @carljia/omd-dsh/shared
+ *
+ * Per-agent transient state shared between the omd-mode and omd-task rows.
+ *
+ * Why this module exists: cordis scoped contexts are proxies — assigning an
+ * undeclared property throws ("cannot set property ... without provide"), and
+ * two rows in one preset are sibling contexts that cannot see each other's
+ * declared properties either. Both rows therefore import this module, and the
+ * sync ships it next to them (`.omd-vendor/shared.js`), so the two vendored
+ * rows resolve the SAME module instance and share one WeakMap. The override is
+ * keyed by the top-level agent object (stable across a session's turns; a
+ * resumed session mints a new agent and starts clean; subagents are distinct
+ * objects and simply miss the map, which is exactly the documented passthrough
+ * semantics).
+ */
+/** One user model pick, recorded when omd-mode yields to it. */
+export interface ModeOverride {
+    provider: string;
+    model: string;
+}
+/** Record (or clear, with `undefined`) the user's model pick for one agent. */
+export declare function setModeOverride(agent: object, override: ModeOverride | undefined): void;
+/** The user's recorded model pick for one agent, or undefined. */
+export declare function modeOverrideFor(agent: object): ModeOverride | undefined;

package/lib/shared.js

@@ -0,0 +1,28 @@
+/**
+ * @module @carljia/omd-dsh/shared
+ *
+ * Per-agent transient state shared between the omd-mode and omd-task rows.
+ *
+ * Why this module exists: cordis scoped contexts are proxies — assigning an
+ * undeclared property throws ("cannot set property ... without provide"), and
+ * two rows in one preset are sibling contexts that cannot see each other's
+ * declared properties either. Both rows therefore import this module, and the
+ * sync ships it next to them (`.omd-vendor/shared.js`), so the two vendored
+ * rows resolve the SAME module instance and share one WeakMap. The override is
+ * keyed by the top-level agent object (stable across a session's turns; a
+ * resumed session mints a new agent and starts clean; subagents are distinct
+ * objects and simply miss the map, which is exactly the documented passthrough
+ * semantics).
+ */
+const modeOverrides = new WeakMap();
+/** Record (or clear, with `undefined`) the user's model pick for one agent. */
+export function setModeOverride(agent, override) {
+    if (override === undefined)
+        modeOverrides.delete(agent);
+    else
+        modeOverrides.set(agent, override);
+}
+/** The user's recorded model pick for one agent, or undefined. */
+export function modeOverrideFor(agent) {
+    return modeOverrides.get(agent);
+}

package/lib/sync.d.ts

@@ -0,0 +1,62 @@
+/**
+ * omd-dsh sync core — materialize the OMD presets into <DSH_HOME>/.agent-presets.
+ *
+ * Shared by the CLI (\`omd-dsh sync\`) and the bundle boot row (\`dsh plugin add\`
+ * + restart): locate the DSH harness node_modules, render each preset's
+ * omd-mode / omd-task rows from the user's model matrix, copy the presets and
+ * vendored row modules into .agent-presets, and rewrite the vendored modules'
+ * bare @deepseek-ai/* imports to absolute file:// URLs into the harness tree so
+ * the rows share ONE module instance with the harness (scope symbols etc.).
+ */
+export type SyncFlags = {
+    harness?: string;
+    dryRun: boolean;
+    verbose: boolean;
+};
+export interface TierConfig {
+    provider: string;
+    model: string;
+    hint?: string;
+    persona?: string;
+    maxTokens?: number;
+    toolFilter?: {
+        allow?: string[];
+        deny?: string[];
+        denyShell?: boolean;
+    };
+}
+export interface ModeConfig {
+    provider?: string;
+    model?: string;
+    reasoningEffort?: string;
+    tiers?: Record<string, TierConfig>;
+}
+export interface Matrix {
+    version: number;
+    defaults?: {
+        provider?: string;
+    };
+    modes: Record<string, ModeConfig>;
+}
+export declare const PACKAGE_ROOT: string;
+export declare const VENDOR_SOURCES: string[];
+/** User-owned model matrix: lives under DSH_HOME, never inside the package or the repo. */
+export declare const MATRIX_PATH: string;
+export declare function dshHome(): string;
+/**
+ * Resolve the DSH harness node_modules:
+ *   1. --harness flag (and cache it for later);
+ *   2. auto-detect via the dsh executable on PATH;
+ *   3. fall back to the locally cached value.
+ */
+export declare function resolveHarness(flags: SyncFlags): string | undefined;
+/**
+ * Resolve the harness node_modules from THIS module's own location, walking up
+ * the Node resolution path for @deepseek-ai/dsh-scope. This is the reliable
+ * anchor when the package runs as a bundle inside a DSH profile: the profile's
+ * flat module fallback (or its hoisted node_modules) exposes the harness tree.
+ */
+export declare function resolveHarnessFromSelf(): string | undefined;
+export declare function loadMatrix(flags: SyncFlags, log?: (msg: string) => void): Matrix;
+export declare function saveMatrix(m: Matrix): void;
+export declare function runSync(flags: SyncFlags, harnessNodeModules: string, log?: (msg: string) => void): Promise<void>;