open-multi-agent-kit 0.78.0 → 0.78.1

package/dist/safety/tool-authority-gate.js

@@ -0,0 +1,108 @@
+/**
+ * Pure tool-authority decision primitive.
+ *
+ * Decides allow / ask / block for a tool operation given the provider's
+ * write/shell authority, the active approval policy, the sandbox mode, and
+ * whether a TTY is attached. The function is intentionally pure: no IO, no
+ * environment reads, no secrets, no side effects.
+ *
+ * STATUS (0.78.2 stabilization): this primitive is NOT wired into any live
+ * tool-dispatch path. It exists so 0.78.3 can wire it into
+ * `dispatchToolCallsByContract` (src/runtime/tool-dispatch-contracts.ts) and
+ * the kimi runner tool loop without re-deriving the policy. Zero behavior
+ * change to current execution.
+ *
+ * Design rules (authority outranks policy; fail-closed):
+ *  1. read ops are always allowed.
+ *  2. a read-only sandbox is a hard floor: any non-read op is blocked.
+ *  3. authority must be satisfied for the op before policy is consulted:
+ *       write  -> writeAuthority === "full"
+ *       shell  -> shellAuthority === "full"
+ *       merge  -> writeAuthority === "full" AND shellAuthority === "full"
+ *  4. once authority is satisfied, the approval policy decides:
+ *       block       -> block
+ *       yolo        -> allow
+ *       auto        -> allow
+ *       interactive -> ask when a TTY is present, otherwise block
+ *                      (ask in a non-TTY context = deny-by-default).
+ */
+/**
+ * Map a raw tool name to its coarse {@link ToolOp} class.
+ *
+ * Matching is case-insensitive. Unrecognized tools fail closed to the most
+ * restrictive sensible op (`shell` = arbitrary effect execution) rather than
+ * `read`, so an unknown tool is never silently treated as harmless.
+ */
+export function mapToolNameToOp(toolName) {
+    const name = toolName.trim().toLowerCase();
+    // Highest-risk git operations publish or rewrite history -> merge.
+    const mergeSignals = ["push", "merge", "cherry-pick", "cherrypick", "rebase", "tag"];
+    const looksLikeGit = name.startsWith("git") || /\bgit\b/.test(name);
+    if (looksLikeGit && mergeSignals.some((signal) => name.includes(signal))) {
+        return "merge";
+    }
+    // Bare verbs used directly as tool names (e.g. "merge", "rebase").
+    if (mergeSignals.some((signal) => name === signal)) {
+        return "merge";
+    }
+    // Shell / command execution.
+    if (name === "shell" || name === "bash" || name.includes("shell") || name.includes("bash")) {
+        return "shell";
+    }
+    // Write / mutation tools.
+    const writeSignals = ["write", "str_replace", "strreplace", "applydiff", "apply_diff", "edit"];
+    if (writeSignals.some((signal) => name.includes(signal))) {
+        return "write";
+    }
+    // Read-only tools (exact names to avoid accidental substring matches).
+    const readSignals = ["read", "grep", "glob", "ls", "cat"];
+    if (readSignals.includes(name)) {
+        return "read";
+    }
+    // Unknown / unrecognized -> most restrictive sensible op (fail-closed).
+    return "shell";
+}
+/** Returns true when provider authority is sufficient for the requested op. */
+function isAuthoritySatisfied(ctx) {
+    switch (ctx.op) {
+        case "read":
+            return true;
+        case "write":
+            return ctx.writeAuthority === "full";
+        case "shell":
+            return ctx.shellAuthority === "full";
+        case "merge":
+            return ctx.writeAuthority === "full" && ctx.shellAuthority === "full";
+    }
+}
+/**
+ * Decide allow / ask / block for a tool operation. Pure and fail-closed.
+ *
+ * @see ToolAuthorityContext for the decision inputs and ordering rules.
+ */
+export function decideToolAuthority(ctx) {
+    // Rule 1: reads are always allowed.
+    if (ctx.op === "read") {
+        return "allow";
+    }
+    // Rule 2: a read-only sandbox is a hard floor for any non-read op.
+    if (ctx.sandboxMode === "read-only") {
+        return "block";
+    }
+    // Rule 3: authority outranks policy. Insufficient authority => block.
+    if (!isAuthoritySatisfied(ctx)) {
+        return "block";
+    }
+    // Rule 4: authority satisfied -> apply approval policy.
+    if (ctx.approvalPolicy === "block") {
+        return "block";
+    }
+    if (ctx.approvalPolicy === "yolo") {
+        return "allow";
+    }
+    if (ctx.approvalPolicy === "auto") {
+        return "allow";
+    }
+    // interactive: ask only when a TTY is attached; non-TTY ask = deny-by-default.
+    return ctx.tty ? "ask" : "block";
+}

package/dist/schema/provider.schema.d.ts

@@ -47,16 +47,16 @@ export declare const ProviderCapabilitySchema: z.ZodObject<{
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     }, {
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     }>;
@@ -102,8 +102,8 @@ export declare const ProviderCapabilitySchema: z.ZodObject<{
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     };
@@ -130,8 +130,8 @@ export declare const ProviderCapabilitySchema: z.ZodObject<{
         cli: boolean;
         api: boolean;
         mcp: boolean;
-        streaming: boolean;
         tools: boolean;
+        streaming: boolean;
         screenshots: boolean;
         worktreeSafe: boolean;
     };

package/dist/util/first-run-star.d.ts

@@ -23,6 +23,7 @@ export interface StarPromptOptions {
     commandName?: string;
     prompt?: (repoUrl: string) => Promise<boolean>;
     starRepo?: (repoUrl: string) => Promise<void> | void;
+    openBrowser?: typeof openRepoInBrowser;
     now?: () => Date;
 }
 export declare function getStarPromptStatePath(homeDir?: string): string;
@@ -47,3 +48,11 @@ export declare function getStarPromptSummary(homeDir?: string): Promise<StarProm
 export declare function parseGitHubRepoSlug(repoUrl: string): string | null;
 export declare function checkGhAuth(): Promise<void>;
 export declare function starGitHubRepo(repoUrl: string): Promise<void>;
+export interface OpenRepoInBrowserOptions {
+    spawnFn?: typeof import("child_process").spawn;
+    platform?: NodeJS.Platform;
+    display?: string;
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function openRepoInBrowser(repoUrl: string, opts?: OpenRepoInBrowserOptions): Promise<boolean>;

package/dist/util/first-run-star.js

@@ -1,4 +1,4 @@
-import { execFile } from "child_process";
+import { execFile, spawn } from "child_process";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join } from "path";
@@ -72,6 +72,7 @@ export async function maybeAskForGitHubStar(options) {
                 console.error(style.gray(`GitHub star failed: ${starError}`));
                 if (slug)
                     console.error(style.gray(`Visit ${style.cream(`https://github.com/${slug}`)} to star manually.`));
+                await (options.openBrowser ?? openRepoInBrowser)(repoUrl);
             }
         }
         await writeStarPromptState({
@@ -124,6 +125,7 @@ export async function maybeAskForGitHubStarAfterCommand(options) {
                 console.error(style.gray(`GitHub star failed: ${starError}`));
                 if (slug)
                     console.error(style.gray(`Visit ${style.cream(`https://github.com/${slug}`)} to star manually.`));
+                await (options.openBrowser ?? openRepoInBrowser)(repoUrl);
             }
         }
         await writeStarPromptState({
@@ -221,3 +223,42 @@ export async function starGitHubRepo(repoUrl) {
         timeout: 10_000,
     });
 }
+export async function openRepoInBrowser(repoUrl, opts) {
+    try {
+        const isTTY = opts?.isTTY ?? process.stdout.isTTY;
+        const env = opts?.env ?? process.env;
+        const platform = opts?.platform ?? process.platform;
+        if (!isTTY)
+            return false;
+        if (env.CI || env.GITHUB_ACTIONS)
+            return false;
+        const display = opts?.display ?? env.DISPLAY;
+        let cmd;
+        let args;
+        if (platform === "darwin") {
+            cmd = "open";
+            args = [repoUrl];
+        }
+        else if (platform === "win32") {
+            cmd = "cmd";
+            args = ["/c", "start", "", repoUrl];
+        }
+        else if (platform === "linux" && display) {
+            cmd = "xdg-open";
+            args = [repoUrl];
+        }
+        else {
+            return false;
+        }
+        const spawnFn = opts?.spawnFn ?? spawn;
+        const child = spawnFn(cmd, args, {
+            stdio: "ignore",
+            detached: true,
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/util/terminal-input.d.ts

@@ -22,4 +22,24 @@ export interface TerminalInputState {
 }
 export declare function captureTerminalInputState(input?: TerminalInputLike): TerminalInputState;
 export declare function enableRawTerminalInput(input?: TerminalInputLike): TerminalInputState;
+/**
+ * Defensive re-validation of interactive stdin before a fresh readline takes
+ * ownership of the TTY.
+ *
+ * The first-run GitHub-star prompt (maybeAskForGitHubStarAtChatStart) and the
+ * update prompt (maybePromptForOmkUpdate) use @inquirer/prompts, which take
+ * over raw mode and run their own readline on process.stdin. On completion they
+ * can leave the shared interactive stdin explicitly paused
+ * (readableFlowing === false). A freshly created readline then observes an
+ * immediate EOF/'close' and the native chat loop exits with "Session ended".
+ *
+ * This helper only resumes a real TTY that was explicitly paused. Non-TTY
+ * stdin (pipes/EOF, CI, non-interactive callers) is intentionally left
+ * untouched so existing exit/EOF behavior is preserved. A fresh, never-started
+ * stream (readableFlowing === null) is also left alone so readline can manage
+ * its own initial resume without racing for the first byte.
+ *
+ * Returns true only when it actually resumed a paused interactive stream.
+ */
+export declare function resumeInteractiveInput(input?: TerminalInputLike): boolean;
 export declare function restoreTerminalInputState(input: TerminalInputLike | undefined, state: TerminalInputState): void;

package/dist/util/terminal-input.js

@@ -21,6 +21,38 @@ export function enableRawTerminalInput(input = process.stdin) {
     input.resume();
     return state;
 }
+/**
+ * Defensive re-validation of interactive stdin before a fresh readline takes
+ * ownership of the TTY.
+ *
+ * The first-run GitHub-star prompt (maybeAskForGitHubStarAtChatStart) and the
+ * update prompt (maybePromptForOmkUpdate) use @inquirer/prompts, which take
+ * over raw mode and run their own readline on process.stdin. On completion they
+ * can leave the shared interactive stdin explicitly paused
+ * (readableFlowing === false). A freshly created readline then observes an
+ * immediate EOF/'close' and the native chat loop exits with "Session ended".
+ *
+ * This helper only resumes a real TTY that was explicitly paused. Non-TTY
+ * stdin (pipes/EOF, CI, non-interactive callers) is intentionally left
+ * untouched so existing exit/EOF behavior is preserved. A fresh, never-started
+ * stream (readableFlowing === null) is also left alone so readline can manage
+ * its own initial resume without racing for the first byte.
+ *
+ * Returns true only when it actually resumed a paused interactive stream.
+ */
+export function resumeInteractiveInput(input = process.stdin) {
+    if (!input.isTTY)
+        return false;
+    if (input.readableFlowing !== false)
+        return false;
+    try {
+        input.resume();
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
 export function restoreTerminalInputState(input = process.stdin, state) {
     const externalDataOwnerAttached = input.listenerCount("data") > state.dataListenerCount;
     if (!externalDataOwnerAttached && state.wasTTY && typeof input.setRawMode === "function") {

package/dist/util/update-check.d.ts

@@ -21,9 +21,14 @@ export interface KimiUpdateStatus {
     fallbackInstallCmd: string;
     installScript: string;
 }
-export declare const OMK_NPM_PACKAGE_NAME = "@omk/cli";
+export declare const OMK_NPM_PACKAGE_NAME = "open-multi-agent-kit";
 type UpdatePromptEnv = Record<string, string | undefined>;
 export type OmkUpdatePromptChoice = "update-now" | "skip-version" | "remind-later";
+/**
+ * Returns true when `env.OMK_AUTO_UPDATE` is one of 1/true/yes/on/always
+ * (case-insensitive), indicating the user wants non-interactive auto-updates.
+ */
+export declare function resolveAutoUpdateMode(env: UpdatePromptEnv): boolean;
 export type OmkUpdatePromptDecisionReason = "disabled" | "ci" | "non-tty" | "not-outdated" | "missing-latest" | "skipped-version" | "remind-active" | "prompt";
 export type OmkUpdatePromptAction = Exclude<OmkUpdatePromptDecisionReason, "prompt"> | "suppressed" | "prompted-skip" | "prompted-remind" | "updated" | "update-failed" | "cancelled" | "timeout";
 export interface OmkUpdatePromptState {

package/dist/util/update-check.js

@@ -6,9 +6,17 @@ import { homedir } from "os";
 const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const DEFAULT_UPDATE_REMIND_HOURS = 24;
 const UPDATE_PROMPT_TIMEOUT_MS = 30_000;
-export const OMK_NPM_PACKAGE_NAME = "@omk/cli";
+export const OMK_NPM_PACKAGE_NAME = "open-multi-agent-kit";
 const OMK_UPDATE_INSTALL_CMD = `npm i -g ${OMK_NPM_PACKAGE_NAME}`;
 const FALLBACK_INSTALL_SCRIPT = "Set KIMI_API_KEY and optionally KIMI_MODEL for direct Moonshot API access.";
+/**
+ * Returns true when `env.OMK_AUTO_UPDATE` is one of 1/true/yes/on/always
+ * (case-insensitive), indicating the user wants non-interactive auto-updates.
+ */
+export function resolveAutoUpdateMode(env) {
+    const raw = env.OMK_AUTO_UPDATE?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on" || raw === "always";
+}
 function getCachePath() {
     return join(homedir(), ".omk", "update-cache.json");
 }
@@ -120,6 +128,32 @@ export async function maybePromptForOmkUpdate(options = {}) {
     const isTTY = options.isTTY ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
     const isCI = options.isCI ?? (isTruthyCiValue(env.CI) || isTruthyCiValue(env.GITHUB_ACTIONS));
     const log = options.onLog ?? ((message) => console.log(message));
+    const autoUpdate = resolveAutoUpdateMode(env);
+    if (autoUpdate && !isCI && getUpdatePromptMode(env) !== "off") {
+        let updateStatus;
+        try {
+            updateStatus = options.status ?? await (options.checkUpdatesFn ?? checkUpdates)();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { action: "suppressed", shouldExit: false, message };
+        }
+        const latestVersion = updateStatus.omk.latest;
+        if (updateStatus.omk.outdated && latestVersion) {
+            log(`Auto-updating OMK to ${normalizeVersionForPrompt(latestVersion)} ...`);
+            const runUpdate = options.runUpdate ?? (() => runShell("npm", ["i", "-g", OMK_NPM_PACKAGE_NAME], { timeout: 120_000 }));
+            const updateResult = await runUpdate();
+            if (updateResult.failed) {
+                const detail = updateResult.stderr.trim() || updateResult.stdout.trim() || `exit ${updateResult.exitCode}`;
+                log(`Auto-update failed: ${detail}`);
+                log(`Manual update command: ${OMK_UPDATE_INSTALL_CMD}`);
+                return { action: "update-failed", shouldExit: true, exitCode: 1, version: latestVersion, message: detail };
+            }
+            log("OMK auto-update completed successfully. Restart omk chat to use the new version.");
+            return { action: "updated", shouldExit: true, exitCode: 0, version: latestVersion };
+        }
+        return { action: "not-outdated", shouldExit: false };
+    }
     const preflight = resolveOmkUpdatePromptState({
         status: null,
         env,

package/docs/2026-06-08/critical-issues.md

@@ -0,0 +1,20 @@
+# 2026-06-08 Critical Issues
+
+## Critical Init Status
+- No critical init artifacts were missing when this daily file was generated.
+### Missing critical artifacts
+- None detected.
+
+
+## Critical Artifacts Present
+- ✅ `AGENTS.md` — top-level operating contract
+- ✅ `.kimi/AGENTS.md` — Kimi-specific operating rules
+- ✅ `.omk/config.toml` — OMK project runtime settings
+- ✅ `.omk/agents/root.yaml` — root coordinator agent
+- ✅ `.kimi/mcp.json` — Kimi project MCP registry
+- ✅ `.omk/hooks/pre-shell-guard.sh` — destructive shell guard
+- ✅ `.omk/hooks/protect-secrets.sh` — secret write guard
+- ✅ `.omk/memory/graph-state.json` — local ontology graph database
+
+## Escalation Rule
+- Treat missing shell/secret guards, root agent config, MCP registry, or ontology graph as critical until restored.

package/docs/2026-06-08/improvements.md

@@ -0,0 +1,14 @@
+# 2026-06-08 Improvements
+
+## Current Improvement Backlog
+### Optional init/support artifacts to add or refresh
+- None detected.
+
+### Critical init artifacts currently blocking reliable chat startup
+- None detected.
+
+
+## Suggested Focus
+- Keep `omk chat` startup idempotent and non-destructive.
+- Prefer local graph memory for default ontology state.
+- Keep generated daily docs small, dated, and safe to edit by hand.

package/docs/2026-06-08/init-checklist.md

@@ -0,0 +1,25 @@
+# 2026-06-08 Required Init Checklist
+
+**Run ID:** chat-2026-06-07T16-16-01-461Z-1315
+**Ontology graph:** `.omk/memory/graph-state.json`
+
+## Required Artifacts
+- ✅ `AGENTS.md` — critical; top-level operating contract
+- ✅ `.kimi/AGENTS.md` — critical; Kimi-specific operating rules
+- ✅ `DESIGN.md` — support; design/brand source of truth
+- ✅ `.omk/config.toml` — critical; OMK project runtime settings
+- ✅ `.omk/agents/root.yaml` — critical; root coordinator agent
+- ✅ `.kimi/mcp.json` — critical; Kimi project MCP registry
+- ✅ `.omk/mcp.json` — support; legacy OMK MCP fallback
+- ✅ `.omk/lsp.json` — support; bundled TypeScript/Python LSP config
+- ✅ `.omk/hooks/pre-shell-guard.sh` — critical; destructive shell guard
+- ✅ `.omk/hooks/protect-secrets.sh` — critical; secret write guard
+- ✅ `.omk/memory/graph-state.json` — critical; local ontology graph database
+- ✅ `.kimi/skills` — support; Kimi skill directory
+- ✅ `.agents/skills` — support; portable skill directory
+
+## Recovery Command
+```bash
+omk init
+omk doctor
+```

package/docs/2026-06-08/plan.md

@@ -0,0 +1,20 @@
+# 2026-06-08 OMK Chat Plan
+
+**Run ID:** chat-2026-06-07T16-16-01-461Z-1315
+**Generated by:** omk chat bootstrap
+
+## Purpose
+- Start every chat with a dated workspace for planning, issue triage, and verification evidence.
+- Keep ontology-backed memory available before the root coordinator starts.
+- Make required init state visible without overwriting user-authored docs.
+
+## Today Plan
+1. Review `init-checklist.md` and resolve missing critical init artifacts first.
+2. Use `improvements.md` as the active improvement backlog.
+3. Use `critical-issues.md` for blocking defects, safety risks, and verification gaps.
+4. Record command evidence before claiming work is complete.
+
+## Stop Condition
+- Critical init artifacts are present.
+- Ontology graph exists at `.omk/memory/graph-state.json`.
+- Any new code/docs changes have explicit verification evidence.

package/docs/getting-started.md

@@ -1,17 +1,17 @@
 # Getting Started
 
-Source release target: `@omk/cli@0.78.0`.
+Source release target: `open-multi-agent-kit@0.78.1` (`pre-1.0`).
 
 ## Prerequisites
 
 - Node.js 20+
 - Git
-- At least one supported provider or local runtime adapter (Codex CLI, Gemini CLI, Claude Code, OpenRouter, DeepSeek, Kimi, etc.)
+- At least one configured provider or local runtime adapter. Kimi is the most mature authority path; other lanes depend on local CLI/API availability and the provider-maturity contract.
 
 ## Install
 
 ```bash
-npm install -g @omk/cli
+npm install -g open-multi-agent-kit
 ```
 
 ## Initialize a project
@@ -35,3 +35,31 @@ omk chat
 omk plan "refactor auth module"
 omk run feature-dev "add user dashboard"
 ```
+
+## Updates
+
+On startup OMK checks npm for a newer release and, when one exists, shows an
+interactive prompt (Update now / Skip this version / Remind me later). Choosing
+"Update now" runs `npm i -g open-multi-agent-kit`.
+
+- **Automatic (non-interactive) updates:** set `OMK_AUTO_UPDATE=1` (also accepts
+  `true|yes|on|always`). When OMK is outdated it self-updates on startup without
+  prompting. CI is always skipped, and `OMK_UPDATE_PROMPT=off` disables update
+  checks entirely.
+- Manual check: `omk update check` (add `--refresh` to bypass the cache).
+
+## Adaptive runtime algorithms
+
+OMK embeds three adaptive control behaviors (all additive, safe defaults, non-fatal fallback):
+
+- **Topology-routed first run** — on the first DAG composition OMK derives structural features (width, critical depth, coupling, parallel ratio) and selects an execution topology (parallel / pipeline / map-reduce / hierarchical / hybrid / dag) with layered waves. Toggle with `OMK_ADAPTORCH_ROUTING=off`.
+- **Context guard before 90%** — before the context window crosses a threshold (default `0.90`) OMK compacts via [headroom](https://github.com/chopratejas/headroom) when available, otherwise its built-in budget optimizer. Tune with `OMK_HEADROOM_THRESHOLD` (0.50–0.99), `OMK_CONTEXT_WINDOW`, or disable with `OMK_HEADROOM=off`.
+- **Spec-first via Ouroboros** — goal/spec/orchestration intents prefer the embedded Ouroboros flow by default; when Ouroboros is not installed OMK degrades to the native path with no error. Modes: `OMK_OUROBOROS=always` (default) `| auto | off`. See [Ouroboros integration](integrations/ouroboros.md).
+
+## Support the project (GitHub star)
+
+First-time users get a one-time prompt to star the repository. If the GitHub CLI
+(`gh`) is authenticated the star is applied directly; otherwise OMK prints the
+repo URL and, on a desktop session, opens it in your browser so you can star in
+one click. You can star anytime with `omk star`, check status with
+`omk star --status`, and disable the prompt with `OMK_STAR_PROMPT=off`.

package/docs/integrations/ouroboros.md

@@ -0,0 +1,96 @@
+# Ouroboros integration (embedded in OMK)
+
+[Ouroboros](https://github.com/Q00/ouroboros) is a spec-first "Agent OS"
+(PyPI `ouroboros-ai`). OMK embeds it through the documented runtime-adapter
+surface that Ouroboros already supports for the `pi`-family CLI that OMK builds
+on:
+
+- an **MCP server** (`ouroboros mcp serve`, ~29 `ouroboros_*` tools) registered in OMK's MCP config,
+- the official **`ooo` bridge extension** installed into OMK's agent extensions dir, so `ooo ...` works inside interactive OMK sessions, and
+- the 20 Ouroboros **skills** (SKILL.md) installed namespaced as `ouroboros-*`.
+
+Ouroboros owns its own workflow engine; the OMK runtime CLI is selected as its
+`runtime_backend` (a `--mode json` subprocess). This follows the runtime guide
+in the Ouroboros repository.
+
+## Prerequisites
+
+- Python `>=3.12`, `uv` (or `pipx`), and the OMK runtime CLI on `PATH`.
+- OMK global agent dir at `~/.omk/agent` (extensions, skills, `mcp.json`).
+
+## Install (reproducible)
+
+```bash
+# 0. Back up the global MCP config (mode 600, contains secrets) before merging.
+ts=$(date +%Y%m%d-%H%M%S)
+cp -a ~/.omk/agent/mcp.json ~/.omk/agent/mcp.json.bak-$ts
+
+# 1. Install the package with MCP support.
+uv tool install 'ouroboros-ai[mcp,claude]'      # or: pipx install 'ouroboros-ai[mcp,claude]'
+
+# 2. Non-interactive runtime setup: writes ~/.ouroboros/config.yaml
+#    (runtime_backend) and generates the ooo bridge extension.
+ouroboros setup --runtime pi --non-interactive
+
+# 3. Mirror the generated ooo bridge into OMK's extension dir.
+#    (locate the file Ouroboros generated, regardless of upstream dir)
+BRIDGE_SRC=$(find "$HOME" -maxdepth 4 -name ouroboros-ooo-bridge.ts -not -path '*/.omk/*' 2>/dev/null | head -1)
+cp "$BRIDGE_SRC" ~/.omk/agent/extensions/ouroboros-ooo-bridge.ts
+
+# 4. Register the MCP server in OMK (additive jq merge; keep mode 600).
+OURO_BIN="$(command -v ouroboros)"
+jq --arg bin "$OURO_BIN" '.mcpServers.ouroboros = {command:$bin, args:["mcp","serve"], env:{}}' \
+  ~/.omk/agent/mcp.json > /tmp/omk-mcp.new \
+  && python3 -m json.tool < /tmp/omk-mcp.new >/dev/null \
+  && install -m600 /tmp/omk-mcp.new ~/.omk/agent/mcp.json && rm -f /tmp/omk-mcp.new
+
+# 5. Install the 20 Ouroboros skills (namespaced).
+git clone --depth 1 https://github.com/Q00/ouroboros.git /tmp/ouroboros-src
+for d in /tmp/ouroboros-src/skills/*/; do b=$(basename "$d");
+  mkdir -p ~/.omk/agent/skills/ouroboros-$b;
+  cp "$d/SKILL.md" ~/.omk/agent/skills/ouroboros-$b/SKILL.md; done
+```
+
+> The MCP entry uses the absolute `ouroboros` binary path because OMK sanitizes
+> the child environment; a bare `ouroboros`/`uvx` command may not resolve under
+> the sanitized `PATH`.
+
+## Verify
+
+```bash
+ouroboros --version
+ouroboros mcp serve --help                  # MCP entrypoint
+ouroboros dispatch --help                   # ooo bridge dispatch entrypoint
+test -f ~/.omk/agent/extensions/ouroboros-ooo-bridge.ts && echo "omk bridge OK"
+grep -q ouroboros ~/.omk/agent/mcp.json && echo "mcp registered"
+ls -d ~/.omk/agent/skills/ouroboros-* | wc -l   # expect 20
+grep runtime_backend ~/.ouroboros/config.yaml   # expect: pi
+```
+
+A successful MCP handshake reports `serverInfo: ouroboros-mcp` and ~29
+`ouroboros_*` tools. In an interactive OMK session, after restart or `/reload`:
+
+```text
+ooo status
+ooo auto build a small CLI
+```
+
+## Scope and safety notes
+
+- The `ouroboros` MCP server is registered in the **global** `~/.omk/agent/mcp.json`,
+  so it is available under all-scope MCP sessions. Default project-scope sessions
+  (`omk-project` only) are unaffected, so OMK startup is not slowed by Ouroboros.
+- `ouroboros setup` mutates `~/.ouroboros/config.yaml` and the upstream runtime's
+  global extensions dir; it does not touch the OMK repo.
+- First MCP cold start resolves the uv tool venv and can be slow; `omk mcp doctor
+  ouroboros` may need a longer timeout on first run.
+
+## Rollback
+
+```bash
+ts=<backup timestamp>
+rm -f ~/.omk/agent/extensions/ouroboros-ooo-bridge.ts
+[ -f ~/.omk/agent/mcp.json.bak-$ts ] && install -m600 ~/.omk/agent/mcp.json.bak-$ts ~/.omk/agent/mcp.json
+rm -rf ~/.omk/agent/skills/ouroboros-*
+uv tool uninstall ouroboros-ai                # or: pipx uninstall ouroboros-ai
+```

package/docs/provider-maturity.md

@@ -4,7 +4,7 @@ This page documents provider status for the current source tree.
 
 ## Current source target
 
-- Package version: `0.78.0`
+- Package version: `0.78.1`
 - Runtime contract family: `v1.2`
 - Release channel: `pre-1.0`
 

package/docs/versioning.md

@@ -4,11 +4,11 @@ OMK uses two version fields in release artifacts:
 
 | Field | Current value | Source | Meaning |
 | --- | --- | --- | --- |
-| Package version | `0.78.0` | `package.json`, `package-lock.json` | npm/package source version. |
+| Package version | `0.78.1` | `package.json`, `package-lock.json` | npm/package source version. |
 | Runtime version | `v1.2` | `src/version.ts`, JSON schemas | Contract/runtime family used by OMK envelopes. |
 | Release channel | `pre-1.0` | `src/version.ts` | Pre-1.0 package channel. |
 
-`0.78.0` is the package version for the `v1.2` runtime contract family.
+`0.78.1` is the package source version for the `v1.2` runtime contract family.
 Use `v1.2` only for runtime contracts; do not substitute it for the package version.
 
 ## Contract versions
@@ -44,6 +44,6 @@ The `version --json` command emits one `omk.contract.v1` envelope whose data pay
 
 ## Documentation rules
 
-- Use `0.78.0` when referring to the current package source version.
+- Use `0.78.1` when referring to the current package source version.
 - Use `v1.2` only for the runtime contract family.
 - Keep historical changelog entries unchanged unless the text is not clearly historical.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-multi-agent-kit",
-  "version": "0.78.0",
+  "version": "0.78.1",
   "description": "Provider-neutral multi-agent control plane for coding workflows: route agents, verify evidence, orchestrate MCP-aware DAGs, and control the loop from the omk CLI.",
   "type": "module",
   "bin": {