@chengchenccc/oh-my-agent 0.1.1-rc.2 → 0.2.0-rc.1

package/README.md

@@ -18,6 +18,7 @@ Product Backend → Agent Run → Adapter → spawn oma --mode rpc
 - mermaid fence 渲染为终端 ASCII 图
 - `/resume` 列表/恢复 session，`/fork <n>` 分支
 - 模型选择持久化到项目级 `.oma/settings.json`（standalone TUI 专用；backend→oma 仍以 `agent.yml` 为默认，可被 run 参数覆盖）
+- `.oma/settings.json` 里的 `prune` 块显式开启读侧工具输出裁剪（`protectTokens` / `minimumSavings` / `protectedTools`），不配就不裁
 - composer loader 实时摘要当前动作（tool intent / thinking 首行）
 
 | Real session | Tools | Mermaid |
@@ -33,7 +34,7 @@ Product Backend → Agent Run → Adapter → spawn oma --mode rpc
 | `json` | 一次 Run；stdout 全部事件 JSONL + 恰好一个 terminal outcome 行 |
 | `rpc` | 每 Run 一次 `execute` + 可选的 `steer`/`abort`；命令走 stdin，`event`/`outcome`/`response` 走 stdout（严格 LF JSONL，stdout 只承载协议） |
 
-`--mode rpc` 是 Adapter 使用的模式。协议 schema 与事件/outcome mapping 定义在契约包 `@chengchenccc/agent-backend`，两侧共用同一份。
+`--mode rpc` 是 Adapter 使用的模式。wire schema 归**本 app 所有**（`src/protocol/`），Adapter 侧保留一份独立的解析/映射副本（`packages/adapter-oma-agent/src/{protocol,event-mapper}.ts`）——两份靠 fixture + `src/protocol/drift.test.ts` 对齐，不共享包（ADR 0024）。改协议：先改这里，再改 adapter 那份，drift 测试会挡住漏改。
 
 ## Runtime
 
@@ -43,7 +44,7 @@ Product Backend → Agent Run → Adapter → spawn oma --mode rpc
 - `steer(input)` 注入 live loop；`stop()` 中止；
 - `close()` 拆除 MCP clients 与 SessionStore。
 
-Runtime 内部由 `packages/agent` 提供：OmaSession（model/tool loop、retry、compaction、插件、todo）与 in-memory SessionStore。seed 时把 **full Product history + meta + input** 原子写入，Run 结束即销毁。
+Runtime 主体就在本 app 的 `src/core/`：OmaSession（model/tool loop、retry、compaction、插件、todo、tool-result pruning）与 in-memory SessionStore（`core/store/`）。seed 时把 **full Product history + meta + input** 原子写入，Run 结束即销毁。
 
 ## 运行
 
@@ -75,5 +76,5 @@ src/
 
 ## 相关文档
 
-- [架构 Wiki — Oma](docs/architecture/runtime/oma.md)
-- [Agent Backend 协议](docs/architecture/execution/agent-backend.md)
+- [架构 Wiki — Oma](../../docs/architecture/runtime/oma.md)
+- [Agent Backend 协议](../../docs/architecture/execution/agent-backend.md)

package/dist/cli/args.d.ts

@@ -1,4 +1,6 @@
+import { type GatewayCommand } from "./gateway-commands.js";
 export type CliMode = "print" | "json" | "rpc" | "tui";
+export type PermissionFlag = "ask" | "auto" | "deny" | "off";
 export interface CliArgs {
     mode: CliMode;
     /** True when -p/--mode was given explicitly; a bare positional prompt
@@ -8,8 +10,20 @@ export interface CliArgs {
     listModels: boolean;
     /** Canonical `<provider>/<model>` id; undefined = first available model. */
     model?: string;
-    /** Resume a session file by id (TUI mode). */
+    /** Resume a session file by id (all modes; TUI and one-shot). */
     session?: string;
+    /** --continue: resume the workspace's most recent session. */
+    continueLast?: boolean;
+    /** Standalone permission gate; undefined = .oma/settings.json decides. */
+    permission?: PermissionFlag;
+    /** --read-only: run with no write/edit/bash/eval tools. */
+    readOnly?: boolean;
+    /** `oma gateway <command>`: the gateway domain (backend + web) verbs. */
+    gateway?: GatewayCommand;
+    /** `oma gateway up|fetch --version <v>`: pin the artifact version. */
+    gatewayVersion?: string;
+    /** `oma gateway up -d`: run detached. */
+    gatewayDetach?: boolean;
     /** Tool filter: comma-separated tool names or groups. Plain names form a
      *  whitelist (ONLY those tools run); `!name` entries form a blacklist
      *  (all but those). Applied to the FINAL tool table (native + MCP +

package/dist/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAEvD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,CAAC;IACd;yEACqE;IACrE,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;mCAG+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AA0BxC;6DAC6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA6E1D"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAoB,MAAM,uBAAuB,CAAC;AAE7F,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7D,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,CAAC;IACd;yEACqE;IACrE,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;mCAG+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAkCxC;6DAC6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAuG1D"}

package/dist/cli/args.js

@@ -1,3 +1,4 @@
+import { GATEWAY_USAGE, isGatewayCommand } from "./gateway-commands.js";
 export class UsageError extends Error {
 }
 const USAGE = `oma - Oma coding agent
@@ -10,11 +11,18 @@ Usage:
   oma --mode json "<prompt>"     json mode: all events + one outcome as JSONL
   oma --mode rpc                 rpc mode: stdin/stdout JSONL protocol
   oma --list-models              print the model catalog as JSON
+  oma gateway up                 start backend + web (foreground, Ctrl-C stops)
+  oma gateway up -d              same, detached (returns once healthy)
+  oma gateway down               stop a detached gateway
+  oma gateway status             installed version, running state, health
+  oma gateway fetch              download + verify the gateway artifact
+  oma --continue                 resume the most recent session
+  oma --session <id> -p "..."    one-shot follow-up on a session
+  oma --permission ask -p "..."  gate bash/write/mcp behind approval cards
+  oma --read-only -p "..."       research-only run (no mutating tools)
   oma --model <provider/model> -p "<prompt>"
                                           pick a model by canonical id
                                           (default: first available model)
-  oma --tools todo_write,read -p "..."    only these tools enter the Run
-  oma --tools '!todo_write' -p "..."      all tools except todo_write
 
 Piped stdin (print/json modes):
   cat file | oma -p "Review"
@@ -22,6 +30,7 @@ Piped stdin (print/json modes):
   cat error.log | oma -p          (stdin only)
 `;
 const MODES = ["print", "json", "rpc", "tui"];
+const PERMISSIONS = ["ask", "auto", "deny", "off"];
 /** Parse argv SYNTAX only: whether a run actually has an input (prompt or
  *  piped stdin) is decided in main() after stdin is read. */
 export function parseArgs(argv) {
@@ -33,11 +42,19 @@ export function parseArgs(argv) {
     };
     const positional = [];
     let modeFlag = null;
+    // `oma gateway <verb>` — a reserved first word, because the first positional
+    // is otherwise the prompt (`oma "explain this"`). `oma -p "gateway up"` is the
+    // escape hatch when the word really is part of a prompt.
+    if (argv[0] === "gateway")
+        return parseGatewayArgs(argv.slice(1), args);
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
         if (arg === "-p") {
-            modeFlag = "print";
+            // `-p` means "one-shot with this prompt", NOT "force print mode": an
+            // explicit --mode (either order) must win, or `--mode json -p x` would
+            // silently run print mode and print bare text where JSONL was expected.
+            modeFlag ??= "print";
             args.modeExplicit = true;
         }
         else if (arg === "--mode") {
@@ -88,6 +105,27 @@ export function parseArgs(argv) {
                 throw new UsageError("--session requires a session id");
             args.session = value;
         }
+        else if (arg === "--continue" || arg === "-c") {
+            args.continueLast = true;
+        }
+        else if (arg === "--read-only") {
+            args.readOnly = true;
+        }
+        else if (arg === "--permission") {
+            const value = argv[i + 1];
+            if (!value || !PERMISSIONS.includes(value)) {
+                throw new UsageError(`--permission requires one of: ${PERMISSIONS.join(" | ")}`);
+            }
+            args.permission = value;
+            i++;
+        }
+        else if (arg.startsWith("--permission=")) {
+            const value = arg.slice("--permission=".length);
+            if (!PERMISSIONS.includes(value)) {
+                throw new UsageError(`--permission requires one of: ${PERMISSIONS.join(" | ")}`);
+            }
+            args.permission = value;
+        }
         else if (arg === "--tools") {
             const value = argv[i + 1];
             if (!value || value.startsWith("-")) {
@@ -118,3 +156,43 @@ export function parseArgs(argv) {
     args.prompt = positional.join(" ");
     return args;
 }
+/** Parse `oma gateway <verb> [--version <v>]`. Kept separate from the main
+ *  loop: the gateway surface takes no prompt, session or mode. */
+function parseGatewayArgs(rest, args) {
+    const verb = rest[0];
+    if (verb === undefined || verb.startsWith("-")) {
+        throw new UsageError(`oma gateway needs a command\n\n${GATEWAY_USAGE}`);
+    }
+    if (!isGatewayCommand(verb)) {
+        throw new UsageError(`unknown gateway command: ${verb}\n\n${GATEWAY_USAGE}`);
+    }
+    args.gateway = verb;
+    let i = 1;
+    while (i < rest.length) {
+        const arg = rest[i] ?? "";
+        if (arg === "--version") {
+            const value = rest[i + 1];
+            if (!value || value.startsWith("-")) {
+                throw new UsageError("oma gateway --version needs a version like 0.2.0");
+            }
+            args.gatewayVersion = value;
+            i += 2;
+            continue;
+        }
+        if (arg.startsWith("--version=")) {
+            const value = arg.slice("--version=".length);
+            if (!value)
+                throw new UsageError("oma gateway --version needs a version like 0.2.0");
+            args.gatewayVersion = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--detach" || arg === "-d") {
+            args.gatewayDetach = true;
+            i += 1;
+            continue;
+        }
+        throw new UsageError(`unknown gateway option: ${arg}\n\n${GATEWAY_USAGE}`);
+    }
+    return args;
+}

package/dist/cli/gateway-commands.d.ts

@@ -0,0 +1,28 @@
+/** The gateway domain's verbs. `oma gateway <verb>` is the CLI surface for
+ *  backend + web: fetch their artifact, run it, report on it. */
+export declare const GATEWAY_VERBS: readonly ["up", "down", "fetch", "status"];
+export type GatewayCommand = (typeof GATEWAY_VERBS)[number];
+export declare const GATEWAY_USAGE = "oma gateway <command>\n\n  up        start backend + web; stays in the foreground (Ctrl-C stops it)\n  up -d     same, but detached: returns once it is healthy\n  down      stop a detached gateway\n  fetch     download, verify and unpack the gateway artifact for a version\n  status    which version is installed, is it running, is it answering\n\n  --version <v>   artifact version for up/fetch (default: oma's own)\n\nNote: 'gateway' is a reserved first word. To send it as a prompt, use\n'oma -p \"gateway ...\"'.";
+export declare function isGatewayCommand(value: string): value is GatewayCommand;
+export interface GatewayCommandOptions {
+    home?: string;
+    version?: string;
+    /** `up -d`: run detached, with a pidfile and a log file. */
+    detach?: boolean;
+    quiet?: boolean;
+    log?: (line: string) => void;
+}
+/** `oma gateway fetch`: download, verify and unpack the artifact for one
+ *  version (default: oma's own) so `up` can start it. Idempotent. */
+export declare function runGatewayFetch(opts?: GatewayCommandOptions): Promise<number>;
+/** `oma gateway status`: what is installed, which version is current, and
+ *  whether the gateway answers right now. Never mutates anything. */
+export declare function runGatewayStatus(opts?: GatewayCommandOptions): Promise<number>;
+/** `oma gateway up`: fetch the version if it is missing, then run the whole gateway in
+ *  the foreground (Ctrl-C stops it, children are signalled in reverse order). */
+export declare function runGatewayUp(opts?: GatewayCommandOptions): Promise<number>;
+/** `oma gateway down`: stop whatever `up -d` started. */
+export declare function runGatewayDown(opts?: GatewayCommandOptions): Promise<number>;
+/** `oma gateway <verb>`: single entry point so the CLI owns one code path. */
+export declare function runGatewayCommand(verb: GatewayCommand, opts?: GatewayCommandOptions): Promise<number>;
+//# sourceMappingURL=gateway-commands.d.ts.map

package/dist/cli/gateway-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-commands.d.ts","sourceRoot":"","sources":["../../src/cli/gateway-commands.ts"],"names":[],"mappings":"AAqBA;iEACiE;AACjE,eAAO,MAAM,aAAa,4CAA6C,CAAC;AACxE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,eAAO,MAAM,aAAa,ygBAWF,CAAC;AAEzB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAKvE;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAyBD;qEACqE;AACrE,wBAAsB,eAAe,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBvF;AAED;qEACqE;AACrE,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDxF;AAED;iFACiF;AACjF,wBAAsB,YAAY,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAkCpF;AAED,yDAAyD;AACzD,wBAAsB,cAAc,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAUtF;AA0DD,8EAA8E;AAC9E,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/dist/cli/gateway-commands.js

@@ -0,0 +1,242 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { currentVersion, fetchGatewayArtifact, gatewayPaths, installedVersions, omaHome, omaVersion, readSecrets, } from "../core/gateway/artifact.js";
+import { isProcessAlive, readDaemon, startDetachedGateway, stopDetachedGateway, tailDaemonLog, } from "../core/gateway/daemon.js";
+import { readGatewayManifest } from "../core/gateway/manifest.js";
+import { runGateway } from "../core/gateway/supervisor.js";
+/** The gateway domain's verbs. `oma gateway <verb>` is the CLI surface for
+ *  backend + web: fetch their artifact, run it, report on it. */
+export const GATEWAY_VERBS = ["up", "down", "fetch", "status"];
+export const GATEWAY_USAGE = `oma gateway <command>
+
+  up        start backend + web; stays in the foreground (Ctrl-C stops it)
+  up -d     same, but detached: returns once it is healthy
+  down      stop a detached gateway
+  fetch     download, verify and unpack the gateway artifact for a version
+  status    which version is installed, is it running, is it answering
+
+  --version <v>   artifact version for up/fetch (default: oma's own)
+
+Note: 'gateway' is a reserved first word. To send it as a prompt, use
+'oma -p "gateway ..."'.`;
+export function isGatewayCommand(value) {
+    for (const verb of GATEWAY_VERBS) {
+        if (verb === value)
+            return true;
+    }
+    return false;
+}
+/** A source checkout runs the gateway from the repo, so the release artifact it
+ *  would download is unused. Only stay quiet there: an explicit CLI call still
+ *  fetches. `npm_lifecycle_event` is set while a package's postinstall runs. */
+function inMonorepoCheckoutPostinstall() {
+    if (process.env.npm_lifecycle_event !== "postinstall")
+        return false;
+    // src/cli (dist/cli) is TWO levels under the package root — unlike
+    // core/gateway/*, which sits three. Getting this wrong made the guard a no-op.
+    const packageRoot = resolve(import.meta.dirname, "../..");
+    return existsSync(join(packageRoot, "..", "..", "turbo.json"));
+}
+function loggerFor(opts, stream) {
+    if (opts.log)
+        return opts.log;
+    if (opts.quiet)
+        return () => { };
+    const write = (line) => {
+        process[stream].write(`${line}\n`);
+    };
+    return write;
+}
+/** `oma gateway fetch`: download, verify and unpack the artifact for one
+ *  version (default: oma's own) so `up` can start it. Idempotent. */
+export async function runGatewayFetch(opts = {}) {
+    const log = loggerFor(opts, "stderr");
+    if (inMonorepoCheckoutPostinstall()) {
+        log("gateway fetch skipped: source checkout (the gateway runs from the repo here)");
+        return 0;
+    }
+    try {
+        const result = await fetchGatewayArtifact({
+            log,
+            ...(opts.home ? { home: opts.home } : {}),
+            ...(opts.version ? { version: opts.version } : {}),
+        });
+        log(`gateway ${result.version} ready at ${result.dir}`);
+        log("start it with: oma gateway up");
+        return 0;
+    }
+    catch (err) {
+        log(`gateway fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+/** `oma gateway status`: what is installed, which version is current, and
+ *  whether the gateway answers right now. Never mutates anything. */
+export async function runGatewayStatus(opts = {}) {
+    const home = opts.home ?? omaHome();
+    const paths = gatewayPaths(home);
+    const log = loggerFor(opts, "stdout");
+    const versions = installedVersions(home);
+    const current = currentVersion(home);
+    log(`gateway home: ${paths.home}`);
+    log(`versions:   ${versions.length > 0 ? versions.join(", ") : "(none installed)"}`);
+    log(`current:    ${current ?? "(none)"}`);
+    if (versions.length === 0) {
+        log(`install one: oma gateway fetch   (oma ${omaVersion()})`);
+        return 1;
+    }
+    const version = opts.version ?? current ?? versions[versions.length - 1] ?? "";
+    const dir = join(paths.versions, version);
+    const manifestPath = join(dir, "gateway.json");
+    if (!existsSync(manifestPath)) {
+        log(`version ${version} is incomplete at ${dir} — re-run: oma gateway fetch`);
+        return 1;
+    }
+    const daemon = readDaemon(home);
+    if (daemon && isProcessAlive(daemon.pid)) {
+        log(`running:    detached, pid ${daemon.pid}, since ${daemon.startedAt}`);
+        log(`log:        ${daemon.logPath}`);
+    }
+    else if (daemon) {
+        log(`running:    no (stale pidfile for pid ${daemon.pid}; 'oma gateway down' clears it)`);
+    }
+    else {
+        log("running:    no pidfile (started in the foreground, or not started)");
+    }
+    const manifest = readGatewayManifest(manifestPath);
+    let allUp = true;
+    for (const component of manifest.components) {
+        if (!component.healthUrl)
+            continue;
+        let state = "down";
+        try {
+            const res = await fetch(component.healthUrl, { signal: AbortSignal.timeout(2000) });
+            if (res.ok)
+                state = "up";
+        }
+        catch {
+            // down
+        }
+        if (state === "down")
+            allUp = false;
+        log(`${component.name.padEnd(8)} ${state.padEnd(4)} ${component.healthUrl}`);
+    }
+    const password = readSecrets(home).MOCK_PASSWORD;
+    if (allUp) {
+        log(`login: http://127.0.0.1:3001/login  (user-001 / ${password ?? "?"})`);
+        return 0;
+    }
+    log("start it with: oma gateway up");
+    return 1;
+}
+/** `oma gateway up`: fetch the version if it is missing, then run the whole gateway in
+ *  the foreground (Ctrl-C stops it, children are signalled in reverse order). */
+export async function runGatewayUp(opts = {}) {
+    const home = opts.home ?? omaHome();
+    const log = loggerFor(opts, "stdout");
+    const version = opts.version ?? currentVersion(home) ?? omaVersion();
+    const dir = join(gatewayPaths(home).versions, version);
+    if (!existsSync(join(dir, "gateway.json"))) {
+        log(`gateway ${version} is not installed yet — fetching it`);
+        const code = await runGatewayFetch({ ...opts, version, log });
+        if (code !== 0)
+            return code;
+    }
+    if (opts.detach)
+        return startGatewayDetached({ ...opts, home, version, log });
+    try {
+        return await runGateway({
+            home,
+            version,
+            log,
+            onReady: (handle) => {
+                const web = handle.manifest.components.find((component) => component.port === 3001);
+                log("");
+                log(`gateway ${handle.manifest.version} is up (${handle.manifest.components.length} processes)`);
+                log(`open http://127.0.0.1:${web?.port ?? 3001}/login`);
+                if (handle.secrets.MOCK_PASSWORD)
+                    log(`login: user-001 / ${handle.secrets.MOCK_PASSWORD}`);
+                log("Ctrl-C stops the gateway");
+            },
+        });
+    }
+    catch (err) {
+        log(`gateway failed to start: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+/** `oma gateway down`: stop whatever `up -d` started. */
+export async function runGatewayDown(opts = {}) {
+    const home = opts.home ?? omaHome();
+    const log = loggerFor(opts, "stdout");
+    const result = await stopDetachedGateway(home);
+    if (result.stopped) {
+        log(`gateway stopped${result.reason ? ` (${result.reason})` : ""}`);
+        return 0;
+    }
+    log(`nothing stopped: ${result.reason ?? "unknown reason"}`);
+    return result.reason?.startsWith("stale pidfile") ? 0 : 1;
+}
+/** Relaunch this CLI in the background and wait until it answers, so the command
+ *  reports the truth instead of "started something, maybe". */
+async function startGatewayDetached(opts) {
+    const entry = process.argv[1];
+    if (!entry) {
+        opts.log("cannot detach: no CLI entry path in argv");
+        return 1;
+    }
+    const command = [process.execPath, entry, "gateway", "up"];
+    if (opts.version)
+        command.push("--version", opts.version);
+    const daemon = await startDetachedGateway({
+        home: opts.home,
+        version: opts.version,
+        command,
+    });
+    opts.log(`gateway ${opts.version} starting detached (pid ${daemon.pid})`);
+    opts.log(`log: ${daemon.logPath}`);
+    const manifest = readGatewayManifest(join(gatewayPaths(opts.home).versions, opts.version, "gateway.json"));
+    const web = manifest.components.find((component) => component.port === 3001);
+    const healthUrl = web?.healthUrl;
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(daemon.pid))
+            break;
+        if (healthUrl) {
+            try {
+                const res = await fetch(healthUrl, { signal: AbortSignal.timeout(2000) });
+                if (res.ok) {
+                    const password = readSecrets(opts.home).MOCK_PASSWORD;
+                    opts.log("");
+                    opts.log(`gateway ${opts.version} is up in the background (pid ${daemon.pid})`);
+                    opts.log(`open http://127.0.0.1:${web?.port ?? 3001}/login`);
+                    if (password)
+                        opts.log(`login: user-001 / ${password}`);
+                    opts.log("stop it with: oma gateway down");
+                    return 0;
+                }
+            }
+            catch {
+                // not listening yet
+            }
+        }
+        await new Promise((res) => {
+            setTimeout(res, 500);
+        });
+    }
+    opts.log("gateway did not become healthy in 60s — last log lines:");
+    for (const line of tailDaemonLog(opts.home))
+        opts.log(`  ${line}`);
+    opts.log("stop it with: oma gateway down");
+    return 1;
+}
+/** `oma gateway <verb>`: single entry point so the CLI owns one code path. */
+export async function runGatewayCommand(verb, opts = {}) {
+    if (verb === "up")
+        return runGatewayUp(opts);
+    if (verb === "down")
+        return runGatewayDown(opts);
+    if (verb === "fetch")
+        return runGatewayFetch(opts);
+    return runGatewayStatus(opts);
+}

package/dist/cli/initial-input.d.ts

@@ -28,5 +28,14 @@ export declare function buildCliRunInput(opts: {
     modelRuntime: ModelRuntime;
     /** Canonical `<provider>/<model>` id; undefined = first available. */
     modelId?: string;
+    /** Standalone permission gate. undefined = ungated (legacy default). */
+    permissionMode?: "ask" | "auto" | "deny";
+    /** --read-only: advertise no write/edit/bash/eval to the model. */
+    readOnly?: boolean;
+    /** Clipboard/pasted images riding this prompt (vision input). */
+    images?: ReadonlyArray<{
+        mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+        base64: string;
+    }>;
 }): Promise<BackendRunInput<"oma">>;
 //# sourceMappingURL=initial-input.d.ts.map

package/dist/cli/initial-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initial-input.d.ts","sourceRoot":"","sources":["../../src/cli/initial-input.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD;;;;;wDAKwD;AACxD,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,CAqC3E;AAMD;;yCAEyC;AACzC,wBAAsB,cAAc,CAClC,MAAM,GAAE,cAAc,CAAC,UAAU,CAAsB,GACtD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsB7B;AAED;;iDAEiD;AACjD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAKpF;AAED;;;wBAGwB;AACxB,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAqClC"}
+{"version":3,"file":"initial-input.d.ts","sourceRoot":"","sources":["../../src/cli/initial-input.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAUrD;;;;;wDAKwD;AACxD,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,CA+C3E;AAMD;;yCAEyC;AACzC,wBAAsB,cAAc,CAClC,MAAM,GAAE,cAAc,CAAC,UAAU,CAAsB,GACtD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsB7B;AAED;;iDAEiD;AACjD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAKpF;AA0BD;;;wBAGwB;AAExB,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,cAAc,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,MAAM,CAAC,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,YAAY,CAAC;QACnE,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ,GAAG,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAyClC"}

package/dist/cli/initial-input.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { managedSkillsDir } from "../core/memory/managed-skills.js";
 import { enabledPluginSkillRoots } from "../core/plugins/plugin-marketplace.js";
 import { buildSystemPrompt, readMemorySummary } from "../core/runtime/prompts.js";
 import { agentDir } from "../core/session/session-file.js";
@@ -45,6 +46,18 @@ export function resolveStandaloneSkillRoots(workspaceRoot) {
         if (!roots.includes(dir))
             roots.push(dir);
     }
+    // Managed skills (learn-tool minted) resolve DEAD-LAST: any authored skill
+    // of the same name shadows them (omp managed-skills semantics).
+    const managed = managedSkillsDir();
+    if (!roots.includes(managed)) {
+        try {
+            if (statSync(managed).isDirectory())
+                roots.push(managed);
+        }
+        catch {
+            /* absent managed dir */
+        }
+    }
     return roots;
 }
 /** One-shot CLI stdin bound: a hostile `cat huge-file | oma -p`
@@ -86,6 +99,24 @@ export function mergeInitialInput(input) {
     const parts = [input.piped?.trim(), input.prompt?.trim()].filter((part) => Boolean(part));
     return parts.join("\n\n");
 }
+/** User message with optional vision images: blocks form when images ride
+ *  along (the providers map user image blocks natively); plain text otherwise. */
+function buildUserMessage(prompt, images) {
+    if (!images || images.length === 0)
+        return { role: "user", text: prompt };
+    return {
+        role: "user",
+        text: prompt,
+        blocks: [
+            { type: "text", text: prompt },
+            ...images.map((img) => ({
+                type: "image",
+                mediaType: img.mediaType,
+                base64: img.base64,
+            })),
+        ],
+    };
+}
 /** Build the BackendRunInput for a one-shot CLI run: current cwd as the
  *  workspace, empty Product history, the requested model (canonical
  *  `<provider>/<model>` id) or the first available model, no Product Tools,
@@ -110,7 +141,7 @@ export async function buildCliRunInput(opts) {
     const input = {
         input: {
             inputId: `cli-in-${randomUUID()}`,
-            message: { role: "user", text: opts.prompt },
+            message: buildUserMessage(opts.prompt, opts.images),
         },
         run: {
             runId,
@@ -122,10 +153,13 @@ export async function buildCliRunInput(opts) {
             }),
             configRevision: 0,
         },
-        workspace: { root: opts.workspaceRoot, access: "read_write" },
+        workspace: { root: opts.workspaceRoot, access: opts.readOnly ? "read_only" : "read_write" },
         // Standalone agent: no product conversation/agent/branch identity.
     };
-    if (skillRoots.length === 0)
-        return input;
-    return { ...input, run: { ...input.run, skillRoots } };
+    const run = {
+        ...input.run,
+        ...(skillRoots.length > 0 ? { skillRoots } : {}),
+        ...(opts.permissionMode ? { permissionMode: opts.permissionMode } : {}),
+    };
+    return { ...input, run };
 }

package/dist/core/coordination/hub-tool.d.ts

@@ -0,0 +1,30 @@
+import type { PluginTool } from "../index.js";
+import type { EntryRow, RegistryEntry } from "./registry.js";
+export interface HubToolDeps {
+    readonly scope: string;
+    readonly list: (scope: string) => EntryRow[];
+    readonly get: (id: string) => RegistryEntry | undefined;
+    readonly wait: (opts: {
+        ids?: readonly string[];
+        scope: string;
+        timeoutMs: number;
+    }) => Promise<{
+        settled: EntryRow[];
+        timedOut: boolean;
+    }>;
+    readonly stop: (id: string) => {
+        ok: boolean;
+        error?: string;
+    };
+    readonly steer: (handle: string, prompt: string) => {
+        ok: boolean;
+        error?: string;
+    };
+    /** Delivery suppression: ack settled ids this tool result showed. */
+    readonly acknowledge?: (ids: readonly string[]) => void;
+    /** True when a job's result already reached the model through an earlier
+     *  tool result (inline task batch) or a previous hub fetch. */
+    readonly isDelivered?: (id: string) => boolean;
+}
+export declare function createHubTool(deps: HubToolDeps): readonly PluginTool[];
+//# sourceMappingURL=hub-tool.d.ts.map

package/dist/core/coordination/hub-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-tool.d.ts","sourceRoot":"","sources":["../../../src/core/coordination/hub-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE;QACpB,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpF,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IACxD;mEAC+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAsHD,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,UAAU,EAAE,CAsItE"}