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

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,40 @@
+/** 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", "doctor", "passwd"];
+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  doctor    why nothing can run: artifact, tools, catalog, keys, ports, oma bin\n  passwd    replace the login password with a fresh random one\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;
+/** What to tell the operator about logging in. The password is only echoed on
+ *  an interactive terminal: a detached run's stdout is redirected into a log
+ *  file, and a secret must not be filed away there. The pointer is always
+ *  printed, so a missed banner is never a dead end. */
+export declare function credentialLines(home: string, secrets: Record<string, string>, interactive: boolean): string[];
+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 passwd`: rotate the login password. Generated, never read from
+ *  argv — an argument would land in shell history and process listings.
+ *  Takes effect on the next start, because the web component reads it from its
+ *  environment. */
+export declare function runGatewayPasswd(opts?: GatewayCommandOptions): Promise<number>;
+/** `oma gateway doctor`: check the deployment and say how to fix what is wrong. */
+export declare function runGatewayDoctor(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":"AAwBA;iEACiE;AACjE,eAAO,MAAM,aAAa,gEAAiE,CAAC;AAC5F,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,eAAO,MAAM,aAAa,0pBAaF,CAAC;AAEzB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAKvE;AAED;;;uDAGuD;AACvD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,WAAW,EAAE,OAAO,GACnB,MAAM,EAAE,CAMV;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,CAgExF;AAED;iFACiF;AACjF,wBAAsB,YAAY,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAoCpF;AAED;;;mBAGmB;AACnB,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BxF;AA2BD,mFAAmF;AACnF,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBxF;AAED,yDAAyD;AACzD,wBAAsB,cAAc,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAUtF;AA+DD,8EAA8E;AAC9E,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/cli/gateway-commands.js

@@ -0,0 +1,337 @@
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { currentVersion, fetchGatewayArtifact, gatewayPaths, generatePassword, installedVersions, omaHome, omaVersion, readSecrets, } from "../core/gateway/artifact.js";
+import { isProcessAlive, readDaemon, startDetachedGateway, stopDetachedGateway, tailDaemonLog, } from "../core/gateway/daemon.js";
+import { diagnoseGateway } from "../core/gateway/doctor.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", "doctor", "passwd"];
+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
+  doctor    why nothing can run: artifact, tools, catalog, keys, ports, oma bin
+  passwd    replace the login password with a fresh random one
+
+  --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;
+}
+/** What to tell the operator about logging in. The password is only echoed on
+ *  an interactive terminal: a detached run's stdout is redirected into a log
+ *  file, and a secret must not be filed away there. The pointer is always
+ *  printed, so a missed banner is never a dead end. */
+export function credentialLines(home, secrets, interactive) {
+    const lines = [];
+    const password = secrets.MOCK_PASSWORD;
+    if (password && interactive)
+        lines.push(`login: user-001 / ${password}`);
+    lines.push(`login password: oma gateway status   (or read ${gatewayPaths(home).secrets})`);
+    return lines;
+}
+/** 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)"}`);
+    // Which catalog the gateway's children will read: product runs deliberately
+    // ignore ~/.oma/models.yml (the agent's own bash tool can write there), so a
+    // custom provider only counts when OMA_HOME points at its models.yml.
+    const catalogHome = process.env.OMA_HOME;
+    log(catalogHome
+        ? `catalog:    ${catalogHome}/models.yml via OMA_HOME`
+        : "catalog:    built-in providers only (OMA_HOME unset — a custom models.yml is not read)");
+    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`);
+                for (const line of credentialLines(home, handle.secrets, process.stdout.isTTY === true)) {
+                    log(line);
+                }
+                log("Ctrl-C stops the gateway");
+            },
+        });
+    }
+    catch (err) {
+        log(`gateway failed to start: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+/** `oma gateway passwd`: rotate the login password. Generated, never read from
+ *  argv — an argument would land in shell history and process listings.
+ *  Takes effect on the next start, because the web component reads it from its
+ *  environment. */
+export async function runGatewayPasswd(opts = {}) {
+    const home = opts.home ?? omaHome();
+    const log = loggerFor(opts, "stdout");
+    const secretsPath = gatewayPaths(home).secrets;
+    if (!existsSync(secretsPath)) {
+        log(`no secrets at ${secretsPath} — run 'oma gateway up' once first`);
+        return 1;
+    }
+    const password = generatePassword();
+    const secrets = { ...readSecrets(home), MOCK_PASSWORD: password };
+    await writeFile(secretsPath, `${JSON.stringify(secrets, null, 2)}\n`, { mode: 0o600 });
+    log(`login password replaced: user-001 / ${password}`);
+    // A password set in the console is stored as a hash and wins over this file,
+    // so push the new one there too when the gateway is up — otherwise rotating
+    // here would silently not take effect.
+    const pushed = await pushPasswordToRunningGateway(secrets, password);
+    if (pushed) {
+        log("the running gateway took it too (console-set password updated)");
+    }
+    else {
+        log("restart to apply: oma gateway down && oma gateway up -d");
+        log("note: a password set in the web console wins over this file — change it there if you used that");
+    }
+    return 0;
+}
+/** Update the console-set password (a hash in the backend's settings) when the
+ *  gateway is reachable. Returns false when it is not: the file value then
+ *  applies after the next start. */
+async function pushPasswordToRunningGateway(secrets, password) {
+    const token = secrets.BACKEND_AUTH_TOKEN;
+    if (!token)
+        return false;
+    try {
+        const res = await fetch(`${process.env.BACKEND_URL ?? "http://127.0.0.1:3000"}/api/auth/password`, {
+            method: "PUT",
+            headers: { "content-type": "application/json", "x-auth-token": token },
+            body: JSON.stringify({ password }),
+            signal: AbortSignal.timeout(2000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** `oma gateway doctor`: check the deployment and say how to fix what is wrong. */
+export async function runGatewayDoctor(opts = {}) {
+    const home = opts.home ?? omaHome();
+    const log = loggerFor(opts, "stdout");
+    const checks = await diagnoseGateway({ home });
+    log(`oma gateway doctor (home: ${home})`);
+    for (const check of checks) {
+        log(`${check.ok ? "✓" : "✗"} ${check.id.padEnd(9)} ${check.detail}`);
+        if (check.fix)
+            log(`  ${check.ok ? "note" : "fix"}: ${check.fix}`);
+    }
+    const failed = checks.filter((check) => !check.ok);
+    log("");
+    log(failed.length === 0
+        ? "no problems found"
+        : `${failed.length} problem(s): ${failed.map((c) => c.id).join(", ")}`);
+    return failed.length === 0 ? 0 : 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) {
+                    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`);
+                    for (const line of credentialLines(opts.home, readSecrets(opts.home), process.stdout.isTTY === true)) {
+                        opts.log(line);
+                    }
+                    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);
+    if (verb === "doctor")
+        return runGatewayDoctor(opts);
+    if (verb === "passwd")
+        return runGatewayPasswd(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"}