@mininglamp-oss/octo-runtime 1.0.1 → 1.1.0

package/apps/cli/dist/help.js

@@ -1,5 +1,4 @@
 import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 // Read the public release package, rather than the private CLI workspace version.
 const releasePackage = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8"));
 export const cliVersion = releasePackage.version;
@@ -22,155 +21,75 @@ const validBuildTime = typeof buildTime === "string" &&
         (buildTime.includes(".") ? buildTime : buildTime.replace("Z", ".000Z"));
 const cliBuildInfo = `build:${validBuildTime ? buildTime : "unknown"}`;
 export const cliVersionInfo = `${cliVersion}\n${cliCommitInfo}\n${cliBuildInfo}`;
-const commands = {
-    description: "Manage the local Agent runtime, provider adapters, and background service.\nBuilt-in adapters work by default; no adapter configuration is required.",
-    children: {
-        adapter: {
-            description: "Inspect provider adapters",
-            children: {
-                list: { description: "List available provider adapters" },
-                probe: { description: "Check whether a provider adapter is ready", usage: "<type>" }
-            }
-        },
-        daemon: {
-            description: "Manage the background runtime service",
-            children: {
-                start: {
-                    description: "Start the service in the background",
-                    details: "Installs a missing current-user service and waits for local IPC readiness."
-                },
-                stop: { description: "Stop the background service" },
-                restart: { description: "Restart the background service" },
-                status: { description: "Show native service and local daemon status" },
-                install: {
-                    description: "Install the current-user service",
-                    flags: {
-                        "--no-autostart": "Disable automatic start at login",
-                        "--logs-dir <path>": "Enable metadata logs in this explicit directory"
-                    }
-                },
-                uninstall: {
-                    description: "Stop and remove the current-user service",
-                    details: "Preserves Runtime Home, identity, credentials, and logs."
-                },
-                run: {
-                    description: "Run the daemon in the foreground",
-                    flags: {
-                        "--quiet": "Suppress terminal lifecycle output",
-                        "--logs-dir <path>": "Enable metadata logs in this explicit directory"
-                    }
-                }
-            }
-        },
-        doctor: {
-            description: "Check local configuration, service, and daemon health",
-            flags: { "--json": "Output diagnostic checks as JSON (default)" }
-        },
-        extraset: {
-            description: "Save a complete Extra plugin configuration from stdin",
-            usage: "<name> < config.json",
-            details: "Reads {module, enabled?, config}. Saves to <home>/extras/<name>/config.json, shared by all profiles.\nRestart the daemon to apply changes. Credentials are never echoed."
-        },
-        extraget: {
-            description: "Print a saved Extra plugin configuration as complete JSON",
-            usage: "<name>",
-            details: "Reads <home>/extras/<name>/config.json without loading the plugin; profile directories are ignored.\nPrints the configuration file path to stderr; stdout contains only JSON."
-        },
-        status: { description: "Show local runtime status" },
-        version: { description: "Print the installed CLI version" },
-        help: { description: "Help about any command", usage: "[command]" },
-        playboard: {
-            description: "Run a development request from stdin and stream events",
-            usage: "< request.json",
-            details: "Starts a temporary daemon using real providers. For development and integration debugging.\nUses built-in adapters by default; no adapter configuration is required.\nRequires an installed, authenticated provider. Outputs NDJSON; diagnostics go to stderr.\nDefaults: codex, current directory, approval ask, 120-second timeout.\nOverride execution settings with contexts.items. Pending interactions fail explicitly.",
-            flags: { "--manifest PATH": "Optional advanced override; not required for built-in adapters" }
-        }
-    }
+const componentDescriptions = {
+    "executor-kernel": `Local Agent execution service. Runs requests through Provider adapters and
+supervises the execution worker used by Gateway, WeCom, WebUI and SDK clients.
+Install and authenticate your chosen Provider before running Agent tasks.
+
+Get started: octo-runtime executor-kernel start
+Check readiness: octo-runtime executor-kernel status`,
+    "channel-gateway": `Connects Octo IM Bots to local Agent execution. Receives messages, invokes
+the Executor Kernel and sends Agent replies back to Octo IM.
+
+Configure Bots: octo-runtime extraset channel-gateway < gateway.json
+Start: octo-runtime channel-gateway start
+Agent tasks also need: octo-runtime executor-kernel start`,
+    "channel-wecom": `Connects WeCom Bots to local Agent execution. Receives WeCom messages,
+invokes the Executor Kernel and sends Agent replies back to WeCom.
+
+Configure Bots: octo-runtime extraset channel-wecom < wecom.json
+Start: octo-runtime channel-wecom start
+Agent tasks also need: octo-runtime executor-kernel start`,
+    webui: `Local browser workspace for Agent conversations and projects.
+Uses the Executor Kernel for Agent execution; default URL: http://127.0.0.1:13888/.
+
+Configure port and sessionStorePath: octo-runtime extraset webui < webui.json
+Start: octo-runtime webui start
+Agent tasks also need: octo-runtime executor-kernel start`
 };
-const globalFlags = {
-    "--home PATH": "Runtime Home directory",
-    "--profile NAME": "Runtime profile (default: default)",
-    "--verbose": "Write detailed diagnostics to stderr"
-};
-for (const command of Object.values(commands.children.daemon.children)) {
-    if (command !== commands.children.daemon.children.run) {
-        command.flags = { ...command.flags, "--json": "Output JSON without progress messages" };
-    }
-}
-export function commandAt(path) {
-    let command = commands;
-    for (const [index, name] of path.entries()) {
-        const next = command.children?.[name];
-        if (!next)
-            throw new Error(`unknown command '${name}' for '${["octo-runtime", ...path.slice(0, index)].join(" ")}'; run octo-runtime help`);
-        command = next;
-    }
-    return command;
-}
-function rows(entries) {
-    const width = Math.max(...Object.keys(entries).map((key) => key.length));
-    return Object.entries(entries)
-        .map(([key, description]) => `  ${key.padEnd(width + 2)}${description}`)
-        .join("\n");
-}
-export function helpText(path = []) {
-    const command = commandAt(path);
-    const invocation = ["octo-runtime", ...path].join(" ");
-    const sections = [
-        ...(path.length ? [] : [`Octo Runtime CLI (${cliVersion})\n${cliCommitInfo}\n${cliBuildInfo}`]),
-        command.description,
-        ...(command.details ? [command.details] : []),
-        `Usage:\n  ${invocation}${command.children ? " [command]" : command.usage ? ` ${command.usage}` : ""} [flags]`,
-        ...(command.children
-            ? [
-                `Available Commands:\n${rows(Object.fromEntries(Object.entries(command.children).map(([name, child]) => [name, child.description])))}`
-            ]
-            : []),
-        // --manifest 保留解析和执行支持，只在开发者文档说明，不展示在普通帮助中。
-        `Flags:\n${rows({ ...Object.fromEntries(Object.entries(command.flags ?? {}).filter(([flag]) => flag !== "--manifest PATH")), "-h, --help": `Help for ${invocation}`, ...(path.length ? {} : { "-v, --version": "Print the installed CLI version" }) })}`,
-        `Global Flags:\n${rows(globalFlags)}`,
-        ...(path[0] === "playboard"
-            ? [
-                `Examples:\n  # Run a minimal request with Codex (bash/zsh)\n  octo-runtime playboard <<'JSON'\n  {\n    "inputs": [{"type": "text", "text": "Reply OK"}],\n    "contexts": {"schema": "octo.context-envelope/v3", "items": []},\n    "protocol_mode": "canonical"\n  }\nJSON\n\n  # Run a saved request\n  octo-runtime playboard < request.json`,
-                `Input:\n  inputs          Required ModelInputPart[] (text or image)\n  contexts        Required Context v3 envelope; empty items are valid\n  protocol_mode   native (default) or canonical\n  providerSession Optional provider binding for continuation\n  continuityMode  fresh or continue (requires providerSession)\n  sessionId       Optional caller session identity\n  agentSource     provisioned or preset`,
-                `Reference:\n  ${fileURLToPath(new URL("../README.md", import.meta.url))}`
-            ]
-            : []),
-        ...(command.children
-            ? [`Use "${invocation} [command] --help" for more information about a command.`]
-            : [])
-    ];
-    return sections.join("\n\n");
-}
-export function validateCommand(positionals, flags) {
-    const help = flags.help === true || positionals[0] === "help";
-    const requested = positionals[0] === "help" ? positionals.slice(1) : positionals;
-    const path = requested.slice(0, ["adapter", "daemon"].includes(requested[0]) ? 2 : 1);
-    const command = commandAt(path);
-    if (!help && ["extraset", "extraget"].includes(path[0]) && flags.profile !== undefined) {
-        throw new Error("Extra configuration belongs to Runtime Home; --profile is not supported for extraset or extraget");
-    }
-    if (help && requested.length > path.length && command.children)
-        throw new Error("unexpected arguments for help");
-    const allowed = new Set([
-        "help",
-        "version",
-        "home",
-        "profile",
-        "verbose",
-        ...Object.keys(command.flags ?? {}).map((flag) => flag
-            .split(" ")[0]
-            .slice(2)
-            .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()))
-    ]);
-    for (const key of Object.keys(flags)) {
-        if (!allowed.has(key) || (key === "version" && path.length))
-            throw new Error(`unknown option --${key}`);
-    }
-    if (!help && !command.children) {
-        const expected = ["extraset", "extraget"].includes(path[0]) || path.join(" ") === "adapter probe" ? 1 : 0;
-        if (requested.length !== path.length + expected)
-            throw new Error(`invalid arguments; run ${["octo-runtime", ...path, "--help"].join(" ")}`);
-    }
-    return { path, help: help || Boolean(command.children) };
+export function helpText(component) {
+    if (component)
+        return `Octo Runtime: ${component}
+
+${componentDescriptions[component] ?? `Configured Extra service "${component}". Runs its registered module independently.\nConfiguration: octo-runtime extraget ${component}`}
+
+Usage: octo-runtime ${component} <command> [flags]
+
+Commands:
+  install       Register and enable this service (autostart on by default)
+  uninstall     Remove this service, preserving configuration and data
+  start         Install if needed, then start this service and wait for readiness
+  restart       Restart this service and wait for local readiness
+  stop          Stop this service, preserving its autostart setting
+  status        Show native service, IPC and component status
+  run           Run this component in the foreground
+
+Flags: --home <path> --profile <name> --manifest <path> --json --help
+Install: --autostart=true|false
+Kernel and Extras have independent services and autostart settings.
+An Extra may start before Kernel and connect when Kernel becomes available.`;
+    return `Octo Runtime CLI (${cliVersion})
+${cliVersionInfo.split("\n").slice(1).join("\n")}
+Manage the local Agent runtime and independent services.
+
+Usage:
+octo-runtime executor-kernel uninstall|install|start|restart|stop|status|run
+octo-runtime <extra-name> uninstall|install|start|restart|stop|status|run
+octo-runtime status [--json]
+octo-runtime adapter list
+octo-runtime adapter probe <type>
+octo-runtime doctor
+octo-runtime extraset <name> < config.json
+octo-runtime extraget <name>
+octo-runtime playboard < request.json
+
+Flags: --home <path> --profile <name> --manifest <path> --json
+Install: --autostart=true|false (defaults to true)
+Extras: channel-gateway, channel-wecom, webui, or a name saved by extraset.
+Components:
+  executor-kernel  Local Agent execution and worker supervision
+  channel-gateway Octo IM Bot messaging and Agent replies
+  channel-wecom   WeCom Bot messaging and Agent replies
+  webui           Local browser workspace for Agent conversations
+Use octo-runtime <component> --help for component commands.`;
 }

package/apps/cli/dist/index.js

@@ -1,9 +1,20 @@
 #!/usr/bin/env node
 import { runCli } from "./main.js";
+let componentRun = false;
 try {
-    process.exitCode = await runCli(process.argv.slice(2));
+    process.exitCode = await runCli(process.argv.slice(2), {
+        onComponentRun: () => {
+            componentRun = true;
+        }
+    });
 }
 catch (error) {
     console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
     process.exitCode = 1;
 }
+finally {
+    // 仅前台组件需要残留句柄退出兜底；数据命令必须自然等待管道输出完整刷新。
+    // unref 不延长正常退出，SDK 和可导入的 runCli 不终止调用进程。
+    if (componentRun)
+        setTimeout(() => process.exit(), 250).unref();
+}

package/apps/cli/dist/main.d.ts

@@ -1,19 +1,11 @@
-import type { ServiceBackend } from "@mininglamp-oss/octo-runtime-cross-service";
 import { type ServiceControlOptions } from "./service-control.js";
-interface CliRequest {
-    method: string;
-    params?: Record<string, unknown>;
-}
 export interface CliDependencies extends ServiceControlOptions {
     env?: NodeJS.ProcessEnv;
-    fetchImplementation?: typeof fetch;
     input?: NodeJS.ReadableStream;
-    output?: (value: string) => void;
-    errorOutput?: (value: string) => void;
-    sleep?: (milliseconds: number) => Promise<void>;
-    runForegroundDaemon?: (args: string[]) => Promise<number | void>;
+    output?: (line: string) => void;
+    errorOutput?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    /** CLI 入口选择前台组件的退出策略；仅确认命令类型，不表示服务 ready。 */
+    onComponentRun?: () => void;
 }
 export declare function runCli(args: string[], dependencies?: CliDependencies): Promise<number>;
-export declare function callDaemon<T = unknown>(socketPath: string, request: CliRequest): Promise<T>;
-export declare function runtimeFingerprint(): string;
-export type { ServiceBackend };