@mininglamp-oss/octo-runtime 1.0.1 → 1.1.1

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

@@ -1,16 +1,3 @@
 export declare const cliVersion: string;
 export declare const cliVersionInfo: string;
-interface Command {
-    description: string;
-    usage?: string;
-    details?: string;
-    flags?: Record<string, string>;
-    children?: Record<string, Command>;
-}
-export declare function commandAt(path: string[]): Command;
-export declare function helpText(path?: string[]): string;
-export declare function validateCommand(positionals: string[], flags: Record<string, string | boolean>): {
-    path: string[];
-    help: boolean;
-};
-export {};
+export declare function helpText(component?: string): string;

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,78 @@ 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
+${component === "executor-kernel" ? "" : "  logs          Tail service status logs (no conversation content)\n"}
+
+Flags: --home <path> --profile <name> --manifest <path> --json --help
+Install: --autostart=true|false
+${component === "executor-kernel" ? "" : "Logs: --lines <1..10000> (default 200) --follow --json (NDJSON)\n"}
+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 <extra-name> logs [--lines 200] [--follow] [--json]
+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/logs.d.ts

@@ -0,0 +1,10 @@
+export declare function showExtraLogs(options: {
+    home: string;
+    extra: string;
+    lines: number;
+    follow: boolean;
+    json: boolean;
+    output: (line: string, signal?: AbortSignal) => void | Promise<void>;
+    errorOutput: (line: string) => void;
+    signal?: AbortSignal;
+}): Promise<void>;

package/apps/cli/dist/logs.js

@@ -0,0 +1,186 @@
+import { constants } from "node:fs";
+import { lstat, open, opendir } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { extraStatusRecord } from "@mininglamp-oss/octo-runtime-adapter-sdk";
+const MAX_READ = 4 * 1024 * 1024;
+const MAX_LINE = 4096;
+function record(line, extra) {
+    if (Buffer.byteLength(line) > MAX_LINE)
+        return;
+    try {
+        const value = JSON.parse(line);
+        if (value.source !== "extra" || value.extra_type !== extra || typeof value.time !== "string")
+            return;
+        return extraStatusRecord(extra, value.level, value.event, value.data, value.time);
+    }
+    catch {
+        return;
+    }
+}
+async function files(home, extra) {
+    const directory = join(home, "logs", "extras");
+    for (const path of [join(home, "logs"), directory]) {
+        try {
+            const stat = await lstat(path);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error("LOG_DIRECTORY_NOT_REGULAR");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    const pattern = new RegExp(`^${extra}-status-\\d{8}T\\d{2}\\.log$`);
+    // Keep only three candidates while scanning, without loading an unbounded directory listing.
+    const selected = [];
+    let count = 0;
+    for await (const entry of await opendir(directory)) {
+        if (++count > 10000)
+            throw new Error("LOG_SCAN_LIMIT");
+        if (!pattern.test(entry.name) || !entry.isFile() || entry.isSymbolicLink())
+            continue;
+        selected.push(join(directory, entry.name));
+        selected.sort();
+        if (selected.length > 3)
+            selected.shift();
+    }
+    return selected;
+}
+async function read(path, start, maximum) {
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error("LOG_NOT_REGULAR_FILE");
+        const offset = start === undefined ? Math.max(0, stat.size - maximum) : Math.min(start, stat.size);
+        const buffer = Buffer.alloc(Math.min(maximum, stat.size - offset));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+        return {
+            text: buffer.subarray(0, bytesRead).toString("utf8"),
+            offset,
+            end: offset + bytesRead,
+            identity: `${stat.dev}:${stat.ino}`,
+            size: stat.size
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function showExtraLogs(options) {
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(options.extra) ||
+        !Number.isInteger(options.lines) ||
+        options.lines < 1 ||
+        options.lines > 10000)
+        throw new Error("INVALID_ARGUMENTS");
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    if (options.follow) {
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        options.signal?.addEventListener("abort", stop, { once: true });
+        if (options.signal?.aborted)
+            stop();
+    }
+    const cursors = new Map();
+    const emit = async (value) => {
+        const text = options.json
+            ? JSON.stringify(value)
+            : `${value.time} ${value.level.toUpperCase()} ${value.extra_type} ${value.event}${Object.keys(value.data).length ? ` ${JSON.stringify(value.data)}` : ""}`;
+        await options.output(text, controller.signal);
+    };
+    try {
+        const selected = await files(options.home, options.extra);
+        let remaining = MAX_READ;
+        const chunks = [];
+        // Spend the shared byte budget newest-first, then emit complete records in file order.
+        for (const path of [...selected].reverse()) {
+            try {
+                const value = await read(path, undefined, remaining);
+                remaining -= Buffer.byteLength(value.text);
+                const lines = value.text.split("\n");
+                if (value.offset > 0)
+                    lines.shift();
+                const pending = lines.pop() ?? "";
+                cursors.set(path, {
+                    offset: value.end,
+                    identity: value.identity,
+                    pending: pending.length <= MAX_LINE ? pending : "",
+                    skipping: pending.length > MAX_LINE
+                });
+                chunks.unshift(lines
+                    .map((line) => record(line, options.extra))
+                    .filter((value) => !!value));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        const tail = chunks.flat().slice(-options.lines);
+        for (const value of tail)
+            await emit(value);
+        if (!tail.length)
+            options.errorOutput(`${options.extra}: no service status logs`);
+        if (!options.follow)
+            return;
+        while (!controller.signal.aborted) {
+            await delay(500, undefined, { signal: controller.signal });
+            const current = await files(options.home, options.extra);
+            for (const path of cursors.keys())
+                if (!current.includes(path))
+                    cursors.delete(path);
+            let budget = MAX_READ;
+            for (const path of current) {
+                if (controller.signal.aborted || budget <= 0)
+                    break;
+                try {
+                    // Inode/size changes reset the cursor; preserve partial records across appends.
+                    let cursor = cursors.get(path);
+                    let value = await read(path, cursor?.offset ?? 0, budget);
+                    if (!cursor || cursor.identity !== value.identity || cursor.offset > value.size) {
+                        cursor = { offset: 0, identity: value.identity, pending: "", skipping: false };
+                        if (value.offset !== 0)
+                            value = await read(path, 0, budget);
+                    }
+                    budget -= Buffer.byteLength(value.text);
+                    const lines = (cursor.pending + value.text).split("\n");
+                    if (cursor.skipping) {
+                        if (lines.length === 1) {
+                            cursors.set(path, { ...cursor, offset: value.end });
+                            continue;
+                        }
+                        lines.shift();
+                    }
+                    const pending = lines.pop() ?? "";
+                    for (const line of lines) {
+                        const value = record(line, options.extra);
+                        if (value)
+                            await emit(value);
+                    }
+                    cursors.set(path, {
+                        offset: value.end,
+                        identity: value.identity,
+                        pending: pending.length <= MAX_LINE ? pending : "",
+                        skipping: pending.length > MAX_LINE
+                    });
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            throw error;
+    }
+    finally {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+        options.signal?.removeEventListener("abort", stop);
+    }
+}

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

@@ -1,19 +1,12 @@
-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;
+    logsSignal?: AbortSignal;
 }
 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 };