@chengchenccc/oh-my-agent 0.2.0-rc.4 → 0.2.0-rc.5

package/dist/cli/args.d.ts

@@ -20,6 +20,12 @@ export interface CliArgs {
     readOnly?: boolean;
     /** `oma gateway <command>`: the gateway domain (backend + web) verbs. */
     gateway?: GatewayCommand;
+    /** `oma update [--check] [--version <v>]`: the release updater. */
+    update?: boolean;
+    /** `oma update --check`: report only. */
+    updateCheck?: boolean;
+    /** `oma update --version <v>`: pin the target version. */
+    updateVersion?: string;
     /** `oma gateway up|fetch --version <v>`: pin the artifact version. */
     gatewayVersion?: string;
     /** `oma gateway up -d`: run detached. */

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

@@ -1 +1 @@
-{"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,GAAG,MAAM,CAAC;AAEtE,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,CA6G1D"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAoB,MAAM,uBAAuB,CAAC;AAG7F,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEtE,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,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,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;AAqCxC;6DAC6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAgH1D"}

package/dist/cli/args.js

@@ -1,4 +1,5 @@
 import { GATEWAY_USAGE, isGatewayCommand } from "./gateway-commands.js";
+import { UPDATE_USAGE } from "./update-command.js";
 export class UsageError extends Error {
 }
 const USAGE = `oma - Oma coding agent
@@ -11,6 +12,9 @@ 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 update                     update the CLI + gateway artifact to the
+                                 newest published version
+  oma update --check             report what is installed vs what is published
   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
@@ -47,6 +51,10 @@ export function parseArgs(argv) {
     // escape hatch when the word really is part of a prompt.
     if (argv[0] === "gateway")
         return parseGatewayArgs(argv.slice(1), args);
+    // Same reservation for `oma update` (the release updater): a bare `oma update`
+    // must not become the prompt "update".
+    if (argv[0] === "update")
+        return parseUpdateArgs(argv.slice(1), args);
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
@@ -163,6 +171,45 @@ export function parseArgs(argv) {
     args.prompt = positional.join(" ");
     return args;
 }
+/** Parse `oma update [--check] [--version <v>]`. Like the gateway surface it
+ *  takes no prompt, session or mode — the first position is a verb. */
+function parseUpdateArgs(rest, args) {
+    const first = rest[0];
+    if (first !== undefined && !first.startsWith("-")) {
+        throw new UsageError(`oma update takes no argument: ${first}\n\n${UPDATE_USAGE}`);
+    }
+    args.update = true;
+    let i = 0;
+    while (i < rest.length) {
+        const arg = rest[i] ?? "";
+        if (arg === "--check" || arg === "-c") {
+            args.updateCheck = true;
+            i += 1;
+            continue;
+        }
+        if (arg === "--version") {
+            const value = rest[i + 1];
+            if (!value || value.startsWith("-")) {
+                throw new UsageError("oma update --version needs a version like 0.2.0");
+            }
+            args.updateVersion = value;
+            i += 2;
+            continue;
+        }
+        if (arg.startsWith("--version=")) {
+            const value = arg.slice("--version=".length);
+            if (!value)
+                throw new UsageError("oma update --version needs a version like 0.2.0");
+            args.updateVersion = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h")
+            throw new UsageError(UPDATE_USAGE);
+        throw new UsageError(`unknown update option: ${arg}\n\n${UPDATE_USAGE}`);
+    }
+    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) {

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

@@ -17,6 +17,10 @@ export interface GatewayCommandOptions {
     quiet?: boolean;
     log?: (line: string) => void;
 }
+/** 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. */
+export declare function inMonorepoCheckout(): boolean;
 /** `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>;
@@ -35,6 +39,14 @@ export declare function runGatewayPasswd(opts?: GatewayCommandOptions): Promise<
 export declare function runGatewayDoctor(opts?: GatewayCommandOptions): Promise<number>;
 /** `oma gateway down`: stop whatever `up -d` started. */
 export declare function runGatewayDown(opts?: GatewayCommandOptions): Promise<number>;
+/** Relaunch this CLI in the background and wait until it answers, so the command
+ *  reports the truth instead of "started something, maybe". Also used by
+ *  `oma update` to put a running gateway onto the version it just installed. */
+export declare function startGatewayDetached(opts: GatewayCommandOptions & {
+    home: string;
+    version: string;
+    log: (line: string) => void;
+}): 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

@@ -1 +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,CA+BxF;AAmDD,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"}
+{"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;AAED;;eAEe;AACf,wBAAgB,kBAAkB,IAAI,OAAO,CAK5C;AAoBD;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,CA+BxF;AAmDD,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;AAED;;gFAEgF;AAChF,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,qBAAqB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC3F,OAAO,CAAC,MAAM,CAAC,CAuDjB;AAED,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

@@ -44,15 +44,19 @@ export function credentialLines(home, secrets, interactive) {
 }
 /** 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;
+ *  fetches. */
+export function inMonorepoCheckout() {
     // 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"));
 }
+/** `npm_lifecycle_event` is set while a package's postinstall runs. */
+function inMonorepoCheckoutPostinstall() {
+    if (process.env.npm_lifecycle_event !== "postinstall")
+        return false;
+    return inMonorepoCheckout();
+}
 function loggerFor(opts, stream) {
     if (opts.log)
         return opts.log;
@@ -299,8 +303,9 @@ export async function runGatewayDown(opts = {}) {
     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) {
+ *  reports the truth instead of "started something, maybe". Also used by
+ *  `oma update` to put a running gateway onto the version it just installed. */
+export async function startGatewayDetached(opts) {
     const entry = process.argv[1];
     if (!entry) {
         opts.log("cannot detach: no CLI entry path in argv");

package/dist/cli/update-command.d.ts

@@ -0,0 +1,57 @@
+import { type LatestRelease } from "../core/update/release.js";
+/** Who owns the running oma, i.e. which command updates it. `oma update` only
+ *  ever runs the installer it can identify: an unknown install (a hand-copied
+ *  binary, another package manager, a distro package) gets the command printed
+ *  instead of a guess that could fight the real owner. */
+export type InstallOwner = {
+    kind: "bun-global";
+    spec: string;
+} | {
+    kind: "source";
+} | {
+    kind: "unknown";
+};
+/** bun's global install root: `<BUN_INSTALL|~/.bun>/install/global/node_modules`.
+ *
+ *  `bun add -g` puts the package there and symlinks `bin/<name>` at it, so the
+ *  running entry's real path is the test: an entry inside this tree is ours to
+ *  reinstall, an entry anywhere else (project node_modules, a checkout) is not.
+ *  Same tree the install script documents, so the two agree. */
+export declare function bunGlobalRoot(env?: NodeJS.ProcessEnv): string;
+/** Classify the install. Pure: every ambient fact (the entry path, whether this
+ *  build lives in a checkout, the env) is passed in, so callers own detection
+ *  and tests are not at the mercy of where the suite runs. */
+export declare function detectInstallOwner(opts: {
+    entry?: string | undefined;
+    /** True when this build lives in a source checkout — either executed from
+     *  src, or a dist that still sits inside the repo. */
+    fromCheckout: boolean;
+    env?: NodeJS.ProcessEnv;
+    version: string;
+}): InstallOwner;
+export interface UpdateCommandOptions {
+    home?: string;
+    /** Pin the target version instead of asking the registry. */
+    version?: string;
+    /** Report state and stop; no download, no install, no restart. */
+    check?: boolean;
+    log?: (line: string) => void;
+    quiet?: boolean;
+    /** Test seam: replaces the registry lookup. */
+    fetchLatest?: () => Promise<LatestRelease>;
+    /** Test seam: replaces `bun add -g` (returns its exit code). */
+    runInstall?: (argv: readonly string[]) => Promise<number>;
+}
+export interface UpdateState {
+    cliVersion: string;
+    artifactVersion?: string;
+    target: LatestRelease;
+}
+/** `oma update`: bring the CLI and the gateway artifact to the newest published
+ *  version, and restart a detached gateway so it is not left on the old code.
+ *
+ *  Refuses to downgrade any axis unless `--version` pins it on purpose. */
+export declare function runUpdateCommand(opts?: UpdateCommandOptions): Promise<number>;
+/** `oma update` help text (the args module owns verb discovery). */
+export declare const UPDATE_USAGE = "oma update [--check] [--version <v>]\n\n  (no flags)      install the newest published CLI + gateway artifact, and\n                  restart a detached gateway onto the new version\n  --check         report what is installed vs what is published; exits 1 when\n                  an update is available, 0 when up to date\n  --version <v>   pin a version instead of asking the registry (also allows\n                  reinstalling a version older than the local one)\n\nNote: 'update' is a reserved first word. To send it as a prompt, use\n'oma -p \"update ...\"'.";
+//# sourceMappingURL=update-command.d.ts.map

package/dist/cli/update-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-command.d.ts","sourceRoot":"","sources":["../../src/cli/update-command.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AAGnC;;;0DAG0D;AAC1D,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;;gEAKgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG1E;AAED;;8DAE8D;AAC9D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;0DACsD;IACtD,YAAY,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,YAAY,CAkBf;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,gEAAgE;IAChE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;CACvB;AAwCD;;;2EAG2E;AAC3E,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,oBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8FvF;AA6CD,oEAAoE;AACpE,eAAO,MAAM,YAAY,yjBAUF,CAAC"}

package/dist/cli/update-command.js

@@ -0,0 +1,220 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, sep } from "node:path";
+import { currentVersion, fetchGatewayArtifact, gatewayPaths, omaHome, omaVersion, } from "../core/gateway/artifact.js";
+import { isProcessAlive, readDaemon, stopDetachedGateway } from "../core/gateway/daemon.js";
+import { fetchLatestRelease, isNewer, OMA_PACKAGE, } from "../core/update/release.js";
+import { inMonorepoCheckout, startGatewayDetached } from "./gateway-commands.js";
+/** bun's global install root: `<BUN_INSTALL|~/.bun>/install/global/node_modules`.
+ *
+ *  `bun add -g` puts the package there and symlinks `bin/<name>` at it, so the
+ *  running entry's real path is the test: an entry inside this tree is ours to
+ *  reinstall, an entry anywhere else (project node_modules, a checkout) is not.
+ *  Same tree the install script documents, so the two agree. */
+export function bunGlobalRoot(env = process.env) {
+    const install = env.BUN_INSTALL ?? join(homedir(), ".bun");
+    return join(install, "install", "global", "node_modules");
+}
+/** Classify the install. Pure: every ambient fact (the entry path, whether this
+ *  build lives in a checkout, the env) is passed in, so callers own detection
+ *  and tests are not at the mercy of where the suite runs. */
+export function detectInstallOwner(opts) {
+    const spec = `${OMA_PACKAGE}@${opts.version}`;
+    // A checkout is not updated by reinstalling the package: telling a developer
+    // to `bun add -g` the package they are editing would fight their working tree.
+    if (opts.fromCheckout)
+        return { kind: "source" };
+    if (!opts.entry)
+        return { kind: "unknown" };
+    let real;
+    let root;
+    try {
+        real = realpathSync(opts.entry);
+        root = realpathSync(bunGlobalRoot(opts.env ?? process.env));
+    }
+    catch {
+        return { kind: "unknown" };
+    }
+    if (real.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)) {
+        return { kind: "bun-global", spec };
+    }
+    return { kind: "unknown" };
+}
+/** What is installed right now, next to what the registry offers. Shared by
+ *  `--check` and the real update so the two reports cannot drift. */
+async function resolveState(opts) {
+    const home = opts.home ?? omaHome();
+    const target = opts.version
+        ? { version: opts.version, tag: opts.version }
+        : await (opts.fetchLatest ?? (() => fetchLatestRelease()))();
+    return { cliVersion: omaVersion(), artifactVersion: currentVersion(home), target };
+}
+/** Print the two axes separately: the CLI (npm package) and the gateway
+ *  artifact (the backend + web tarball) are installed by different steps and
+ *  routinely disagree — an up-to-date CLI next to a stale artifact is exactly
+ *  the state that produced a gateway which could not start. */
+function reportLines(state, home) {
+    const { cliVersion, artifactVersion, target } = state;
+    const lines = [];
+    const cliNote = isNewer(target.version, cliVersion)
+        ? "update available"
+        : cliVersion === target.version
+            ? "current"
+            : "newer than the registry (a local build?)";
+    lines.push(`oma CLI:           ${cliVersion}  (${cliNote})`);
+    lines.push(artifactVersion === undefined
+        ? `gateway artifact:  none installed (${gatewayPaths(home).versions})`
+        : `gateway artifact:  ${artifactVersion}${artifactVersion === target.version
+            ? "  (current)"
+            : isNewer(target.version, artifactVersion)
+                ? "  (update available)"
+                : "  (newer than the registry)"}`);
+    lines.push(`newest published:  ${target.version}  (dist-tag ${target.tag})`);
+    return lines;
+}
+/** `oma update`: bring the CLI and the gateway artifact to the newest published
+ *  version, and restart a detached gateway so it is not left on the old code.
+ *
+ *  Refuses to downgrade any axis unless `--version` pins it on purpose. */
+export async function runUpdateCommand(opts = {}) {
+    const home = opts.home ?? omaHome();
+    const log = loggerFor(opts);
+    let state;
+    try {
+        state = await resolveState(opts);
+    }
+    catch (err) {
+        log(`oma update failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const { cliVersion, artifactVersion, target } = state;
+    if (opts.check) {
+        log(`oma update --check (home: ${home})`);
+        for (const line of reportLines(state, home))
+            log(line);
+        const behind = isNewer(target.version, cliVersion) || isNewer(target.version, artifactVersion ?? "0.0.0");
+        if (!behind) {
+            log("");
+            log("up to date");
+            return 0;
+        }
+        log("");
+        log("run `oma update` to install it");
+        return 1;
+    }
+    // No silent downgrades. The registry is the newest *published* thing, not
+    // necessarily the newest thing this machine has: a checkout of the same
+    // version, or a locally built one, must not be replaced by an older release.
+    const pinned = opts.version !== undefined;
+    if (!pinned && isNewer(cliVersion, target.version)) {
+        log(`the CLI (${cliVersion}) is newer than the newest published version (${target.version}); nothing to do (pin with --version to force)`);
+        return 0;
+    }
+    log(`oma update: ${cliVersion} -> ${target.version} (dist-tag ${target.tag})`);
+    // 1. The artifact first: it is the half that can be broken while the CLI is
+    //    fine, and it is what `oma gateway up` needs. A failure here is fatal.
+    if (artifactVersion === target.version) {
+        log(`gateway artifact ${target.version} is already installed`);
+    }
+    else {
+        try {
+            const result = await fetchGatewayArtifact({ home, version: target.version, log });
+            log(result.downloaded
+                ? `gateway artifact ${target.version} installed`
+                : `gateway artifact ${target.version} was already unpacked`);
+        }
+        catch (err) {
+            log(`gateway artifact update failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 1;
+        }
+    }
+    // 2. The CLI itself. Not fatal: the artifact above is already in place, and
+    //    an install that cannot be identified gets instructions instead of a
+    //    guess (reinstalling through the wrong owner silently pins the version).
+    const owner = detectInstallOwner({
+        entry: process.argv[1],
+        // Two spellings of "a checkout": executed from src (.ts), or a built dist
+        // that still lives inside the repo.
+        fromCheckout: import.meta.filename.endsWith(".ts") || inMonorepoCheckout(),
+        version: target.version,
+    });
+    if (!isNewer(target.version, cliVersion)) {
+        log(`oma CLI ${cliVersion} is current`);
+    }
+    else if (owner.kind === "bun-global") {
+        const code = await (opts.runInstall ?? runBunInstall)([
+            process.execPath,
+            "add",
+            "-g",
+            owner.spec,
+        ]);
+        log(code === 0 ? `oma CLI updated to ${target.version}` : `oma CLI install exited ${code}`);
+        if (code !== 0)
+            log(`install it by hand: bun add -g ${owner.spec}`);
+    }
+    else if (owner.kind === "source") {
+        log("running from a checkout: update the code with git pull (the artifact above is current)");
+    }
+    else {
+        log("cannot tell how this oma was installed; update it with:");
+        log(`  bun add -g ${OMA_PACKAGE}@${target.version}`);
+    }
+    // 3. A detached gateway is still running the old artifact. Restart it onto
+    //    the version just installed; a foreground one is the user's to restart.
+    await restartRunningGateway({ ...opts, home, version: target.version, log });
+    log("");
+    log(`done. start it with: oma gateway up`);
+    return 0;
+}
+/** Restart the detached gateway when it is alive AND on a different version.
+ *  Never touches a foreground run (it has no pidfile — we do not own it). */
+async function restartRunningGateway(opts) {
+    const daemon = readDaemon(opts.home);
+    if (!daemon || !isProcessAlive(daemon.pid))
+        return;
+    if (daemon.version === opts.version) {
+        opts.log(`the running gateway is already on ${opts.version}`);
+        return;
+    }
+    opts.log(`restarting the detached gateway (pid ${daemon.pid}, ${daemon.version} -> ${opts.version})`);
+    const stopped = await stopDetachedGateway(opts.home);
+    if (!stopped.stopped && !stopped.reason?.startsWith("stale pidfile")) {
+        opts.log(`could not stop the old gateway: ${stopped.reason ?? "unknown reason"}`);
+        opts.log("stop it yourself, then: oma gateway up -d");
+        return;
+    }
+    const started = await startGatewayDetached({
+        home: opts.home,
+        version: opts.version,
+        log: opts.log,
+    });
+    if (started !== 0)
+        opts.log("the new version did not become healthy — check the log above");
+}
+/** `bun add -g`, inherited stdio so the user sees it. `process.execPath` is the
+ *  bun running this CLI, so no PATH lookup (and no wrong-bun surprise). */
+async function runBunInstall(argv) {
+    const proc = Bun.spawn([...argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+    return await proc.exited;
+}
+function loggerFor(opts) {
+    if (opts.log)
+        return opts.log;
+    if (opts.quiet)
+        return () => { };
+    return (line) => {
+        process.stdout.write(`${line}\n`);
+    };
+}
+/** `oma update` help text (the args module owns verb discovery). */
+export const UPDATE_USAGE = `oma update [--check] [--version <v>]
+
+  (no flags)      install the newest published CLI + gateway artifact, and
+                  restart a detached gateway onto the new version
+  --check         report what is installed vs what is published; exits 1 when
+                  an update is available, 0 when up to date
+  --version <v>   pin a version instead of asking the registry (also allows
+                  reinstalling a version older than the local one)
+
+Note: 'update' is a reserved first word. To send it as a prompt, use
+'oma -p "update ..."'.`;

package/dist/core/gateway/doctor.d.ts

@@ -14,8 +14,26 @@ export interface DoctorOptions {
     /** Seam for tests: replaces the release HEAD probe. Returns the HTTP status,
      *  or undefined when the host could not be reached. */
     probeRelease?: (url: string) => Promise<number | undefined>;
+    /** Seam for tests: replaces the Lark probe (cli version + backend surfaces). */
+    probeLark?: () => Promise<LarkProbe>;
+}
+/** What the Lark diagnosis needs: is lark-cli here, and what do the surfaces
+ *  the CONTROL PLANE owns say? The CLI reports; it does not become a second
+ *  Lark console (no `oma lark *` verbs on purpose). */
+export interface LarkProbe {
+    /** `lark-cli version X.Y.Z`, or null when the binary is not on PATH. */
+    cliVersion: string | null;
+    /** False when the backend did not answer: then there is nothing to report. */
+    reachable: boolean;
+    surfaces: Array<{
+        agentId: string;
+        agentName: string;
+        status: string;
+        lastError: string | null;
+    }>;
 }
 /** Diagnose why a gateway may not be able to run anything: artifact, tools,
  *  catalog source, runnable providers, ports, and the per-run oma binary. */
 export declare function diagnoseGateway(opts?: DoctorOptions): Promise<GatewayCheck[]>;
+export declare function defaultLarkProbe(home: string): () => Promise<LarkProbe>;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/core/gateway/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/core/gateway/doctor.ts"],"names":[],"mappings":"AAeA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACrD;2DACuD;IACvD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC7D;AAoED;6EAC6E;AAC7E,wBAAsB,eAAe,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA2UvF"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/core/gateway/doctor.ts"],"names":[],"mappings":"AAeA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACrD;2DACuD;IACvD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC5D,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;CACtC;AAED;;uDAEuD;AACvD,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,KAAK,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC,CAAC;CACJ;AAoED;6EAC6E;AAC7E,wBAAsB,eAAe,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAyXvF;AAgBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CA2CvE"}

package/dist/core/gateway/doctor.js

@@ -388,7 +388,52 @@ export async function diagnoseGateway(opts = {}) {
             // The backend answered /health but not this route (older artifact).
         }
     }
-    // 13. the binary the backend spawns per Run
+    // 13. the Lark surface: is it runnable here, and is anything wrong? The
+    // state itself lives in the backend (agent config + registry + heartbeat);
+    // this only summarizes it and points at where to fix it.
+    const lark = await (opts.probeLark ?? defaultLarkProbe(home))();
+    checks.push({
+        id: "lark-cli",
+        ok: true,
+        detail: lark.cliVersion === null
+            ? "lark-cli not found on PATH (no agent can be connected to Lark here)"
+            : `lark-cli ${lark.cliVersion}`,
+        ...(lark.cliVersion === null
+            ? { fix: "install lark-cli, then connect an agent from the web UI (agent -> Lark tab)" }
+            : {}),
+    });
+    if (!lark.reachable) {
+        checks.push({
+            id: "lark-surface",
+            ok: true,
+            detail: "no Lark state to report (the backend is not answering)",
+        });
+    }
+    else if (lark.surfaces.length === 0) {
+        checks.push({ id: "lark-surface", ok: true, detail: "no agent has a Lark surface" });
+    }
+    else {
+        const running = lark.surfaces.filter((s) => s.status === "running");
+        const broken = lark.surfaces.filter((s) => s.status === "degraded" || s.status === "error");
+        checks.push({
+            id: "lark-surface",
+            ok: broken.length === 0,
+            detail: broken.length === 0
+                ? `${lark.surfaces.length} configured, ${running.length} running`
+                : `${lark.surfaces.length} configured, ${running.length} running, ${broken.length} needing attention: ` +
+                    broken
+                        .map((s) => `${s.agentName} (${s.status}${s.lastError ? `: ${s.lastError}` : ""})`)
+                        .join("; "),
+            ...(broken.length > 0
+                ? {
+                    fix: broken
+                        .map((s) => `open http://127.0.0.1:3001/team/${s.agentId}?tab=lark`)
+                        .join(" | "),
+                }
+                : {}),
+        });
+    }
+    // 14. the binary the backend spawns per Run
     try {
         const entry = resolveOmaBin();
         checks.push({ id: "oma-bin", ok: true, detail: `runs will spawn ${entry}` });
@@ -403,3 +448,66 @@ export async function diagnoseGateway(opts = {}) {
     }
     return checks;
 }
+/** `lark-cli version X.Y.Z` -> "X.Y.Z". Absent binary is reported, not fatal:
+ *  Lark is optional, so a gateway without it still passes doctor. */
+function probeLarkCliVersion() {
+    try {
+        const out = Bun.spawnSync(["lark-cli", "--version"], { stdout: "pipe", stderr: "pipe" });
+        if (out.exitCode !== 0)
+            return null;
+        const text = out.stdout.toString().trim();
+        const match = text.match(/\d+\.\d+(?:\.\d+)?/);
+        return match ? match[0] : text.slice(0, 24) || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function defaultLarkProbe(home) {
+    return async () => {
+        const cliVersion = probeLarkCliVersion();
+        try {
+            const token = readSecrets(home).BACKEND_AUTH_TOKEN ?? "";
+            const res = await fetch("http://127.0.0.1:3000/api/ops/surfaces", {
+                headers: { "x-auth-token": token },
+                signal: AbortSignal.timeout(2000),
+            });
+            // A 401/500 body is not "no surfaces configured": without a readable
+            // answer the doctor must say it could not look, not that nothing exists.
+            if (!res.ok)
+                return { cliVersion, reachable: false, surfaces: [] };
+            const body = await res.json();
+            // The route returns a bare array today; accept a wrapped shape too so a
+            // future envelope does not silently read as "no Lark surfaces".
+            const items = Array.isArray(body)
+                ? body
+                : typeof body === "object" && body !== null && "surfaces" in body
+                    ? body.surfaces
+                    : undefined;
+            if (!Array.isArray(items))
+                return { cliVersion, reachable: true, surfaces: [] };
+            const surfaces = [];
+            for (const item of items) {
+                if (typeof item !== "object" || item === null)
+                    continue;
+                // The web chip matches on a substring (`lark-bot` and friends), so an
+                // exact "lark" comparison silently reported an empty deployment.
+                if (!("surface" in item) || typeof item.surface !== "string")
+                    continue;
+                if (!item.surface.toLowerCase().includes("lark"))
+                    continue;
+                const status = "status" in item && typeof item.status === "string" ? item.status : "unknown";
+                const agentId = "agentId" in item && typeof item.agentId === "string" ? item.agentId : "";
+                const agentName = "agentName" in item && typeof item.agentName === "string" ? item.agentName : agentId;
+                const lastError = "lastError" in item && typeof item.lastError === "string" ? item.lastError : null;
+                if (agentId === "")
+                    continue;
+                surfaces.push({ agentId, agentName, status, lastError });
+            }
+            return { cliVersion, reachable: true, surfaces };
+        }
+        catch {
+            return { cliVersion, reachable: false, surfaces: [] };
+        }
+    };
+}

package/dist/core/runtime/agent-event.d.ts

@@ -1,7 +1,14 @@
+import type { ToolPresentation } from "@chengchenccc/agent-contract";
 import type { TodoItem } from "../tools/todo-store.js";
 /** Pi-style typed lifecycle events per runtime/oma.md. */
 export type OmaLoopEvent = {
     type: "agent_start";
+}
+/** Liveness only: proves the loop is alive while it waits on something that
+ *  produces no events (a long tool, a slow model call, a subagent). Carries
+ *  no content, is never persisted, and every surface ignores it. */
+ | {
+    type: "heartbeat";
 } | {
     type: "agent_end";
     status: "completed" | "failed" | "stopped";
@@ -26,8 +33,17 @@ export type OmaLoopEvent = {
     toolName: string;
     kind?: "native" | "product";
     callId: string;
-    /** The tool's resolved input (model call args), for transcript display. */
+    /** The tool's resolved input (model call args), for transcript display.
+     *  oma-internal: this NEVER crosses the RPC boundary — surfaces get
+     *  `activity` instead. */
     input?: Readonly<Record<string, unknown>>;
+    /** User-visible one-line description of what the call is doing,
+     *  produced by the tool's describeStart and sanitized by
+     *  safeToolSummary. Absent means "the tool cannot describe itself" —
+     *  surfaces then fall back to the tool name. */
+    activity?: string;
+    /** Structured form of the same description (title/detail/icon). */
+    presentation?: ToolPresentation;
     /** Wall-clock timeout for this tool (ms, 0 = disabled). */
     timeoutMs?: number;
 } | {
@@ -36,6 +52,8 @@ export type OmaLoopEvent = {
     kind?: "native" | "product";
     callId: string;
     result?: Readonly<Record<string, unknown>>;
+    /** Result-side display metadata (resultSummary / errorSummary). */
+    presentation?: ToolPresentation;
 } | {
     /** Streaming partial output from a running tool (bash stdout). */
     type: "tool_output";