@messenger-agent/client 0.24.0-alpha.2

package/dist/args.d.ts

@@ -0,0 +1,66 @@
+import { type ReleaseChannel } from "./runtime.js";
+export type InstallArgs = {
+    command: "install";
+    tunnelId?: string;
+    token?: string;
+    workspace?: string;
+    serverUrl?: string;
+    configPath: string;
+    dataDir: string;
+    workspaceId?: string;
+    workspaceName?: string;
+    channel?: ReleaseChannel;
+};
+export type UpgradeArgs = {
+    command: "upgrade";
+    version: string;
+    configPath: string;
+    delaySeconds?: number;
+    allowWaiting: boolean;
+    channel?: ReleaseChannel;
+};
+export type VersionArgs = {
+    command: "version";
+};
+export type SessionsArgs = {
+    command: "sessions";
+    json: boolean;
+    configPath: string;
+};
+export type MaintenanceArgs = {
+    command: "maintenance";
+    action: "status" | "cancel";
+    json: boolean;
+    configPath: string;
+};
+export type RunServiceArgs = {
+    command: "run-service";
+    configPath?: string;
+};
+export type StatusArgs = {
+    command: "status";
+};
+export type StartArgs = {
+    command: "start";
+};
+export type RestartArgs = {
+    command: "restart";
+    agent?: "codex" | "claude";
+    delaySeconds?: number;
+    allowWaiting: boolean;
+};
+export type StopArgs = {
+    command: "stop";
+    delaySeconds?: number;
+    allowWaiting: boolean;
+};
+export type UninstallArgs = {
+    command: "uninstall";
+    delaySeconds?: number;
+    allowWaiting: boolean;
+};
+export type CliArgs = InstallArgs | UpgradeArgs | VersionArgs | SessionsArgs | MaintenanceArgs | RunServiceArgs | StatusArgs | StartArgs | RestartArgs | StopArgs | UninstallArgs;
+export declare class UsageError extends Error {
+}
+export declare function parseCliArgs(argv: string[], env?: NodeJS.ProcessEnv): CliArgs;
+export declare function usage(): string;

package/dist/args.js

@@ -0,0 +1,303 @@
+import cac from "cac";
+import { defaultConfigPath, defaultDataDir, resolvePath } from "./paths.js";
+import { normalizeReleaseChannel } from "./runtime.js";
+const serverUrlEnvName = "CODING_AGENT_TUNNEL_SERVER_URL";
+const publicCommands = [
+    "install",
+    "upgrade",
+    "sessions",
+    "maintenance",
+    "status",
+    "start",
+    "restart",
+    "stop",
+    "uninstall",
+];
+const allCommands = [...publicCommands, "run-service"];
+export class UsageError extends Error {
+}
+export function parseCliArgs(argv, env = process.env) {
+    if (argv[0] === "--version" || argv[0] === "-v") {
+        if (argv.length > 1)
+            throw new UsageError(`Unknown option for version: ${argv[1]}`);
+        return { command: "version" };
+    }
+    const command = argv[0];
+    if (!command || command === "--help" || command === "-h") {
+        throw new UsageError(usage());
+    }
+    if (argv.includes("--")) {
+        throw new UsageError(`Unknown option for ${command}: --`);
+    }
+    assertKnownOptions(argv);
+    let parsedArgs;
+    const cli = createCli({
+        env,
+        includeInternalCommands: true,
+        onParsed(args) {
+            parsedArgs = args;
+        },
+    });
+    try {
+        cli.parse(["node", "coding-agent", ...argv]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new UsageError(normalizeCacError(message, argv));
+    }
+    if (!parsedArgs) {
+        throw new UsageError(`Unknown command: ${command}`);
+    }
+    return parsedArgs;
+}
+export function usage() {
+    const cli = createCli({ includeInternalCommands: false });
+    cli.help();
+    return `${captureConsoleInfo(() => cli.outputHelp())}\n\nGlobal Options:\n  -v, --version  Show the installed client version`;
+}
+function createCli(options) {
+    const cli = cac("coding-agent");
+    const env = options.env ?? process.env;
+    const onParsed = options.onParsed ?? (() => undefined);
+    cli
+        .command("install", "Install and configure the local coding-agent service")
+        .option("--tunnel-id <id>", "Tunnel id")
+        .option("--token <token>", "Tunnel token")
+        .option("--workspace <path>", "Workspace path (default: ~/messenger-workspace)")
+        .option("--server-url <wss-url>", "Tunnel server URL")
+        .option("--config <path>", "Config file path", { default: defaultConfigPath })
+        .option("--data-dir <path>", "Data directory", { default: defaultDataDir })
+        .option("--workspace-id <id>", "Workspace id")
+        .option("--workspace-name <name>", "Workspace display name")
+        .option("--channel <channel>", "Auto-upgrade release channel: latest, beta, or alpha")
+        .action((commandOptions) => {
+        const tunnelId = optionalString(commandOptions.tunnelId);
+        const token = optionalString(commandOptions.token);
+        const workspace = optionalString(commandOptions.workspace);
+        onParsed({
+            command: "install",
+            tunnelId,
+            token,
+            workspace: workspace ? resolvePath(workspace) : undefined,
+            serverUrl: optionalString(commandOptions.serverUrl) ?? env[serverUrlEnvName],
+            configPath: resolvePath(requiredString(commandOptions.config, "--config")),
+            dataDir: resolvePath(requiredString(commandOptions.dataDir, "--data-dir")),
+            workspaceId: optionalString(commandOptions.workspaceId),
+            workspaceName: optionalString(commandOptions.workspaceName),
+            channel: parseChannelOption(commandOptions.channel),
+        });
+    });
+    cli
+        .command("upgrade", "Upgrade the local coding-agent runtime")
+        .option("--version <version>", "Runtime version or release channel", { default: "latest" })
+        .option("--channel <channel>", "Auto-upgrade release channel: latest, beta, or alpha")
+        .option("--config <path>", "Config file path", { default: defaultConfigPath })
+        .option("--delay <seconds>", "Schedule the upgrade after a delay")
+        .option("--allow-waiting", "Allow upgrade while sessions wait for user input")
+        .action((commandOptions) => {
+        const delaySeconds = optionalDelay(commandOptions.delay);
+        const allowWaiting = commandOptions.allowWaiting === true;
+        assertAllowWaitingHasDelay(allowWaiting, delaySeconds);
+        onParsed({
+            command: "upgrade",
+            version: requiredString(commandOptions.version, "--version"),
+            configPath: resolvePath(requiredString(commandOptions.config, "--config")),
+            delaySeconds,
+            allowWaiting,
+            channel: parseChannelOption(commandOptions.channel),
+        });
+    });
+    cli
+        .command("sessions", "Show active and waiting client sessions")
+        .option("--json", "Print machine-readable JSON")
+        .option("--config <path>", "Config file path", { default: defaultConfigPath })
+        .action((commandOptions) => {
+        onParsed({
+            command: "sessions",
+            json: commandOptions.json === true,
+            configPath: resolvePath(requiredString(commandOptions.config, "--config")),
+        });
+    });
+    cli
+        .command("maintenance <action>", "Inspect or cancel scheduled maintenance")
+        .option("--json", "Print machine-readable JSON")
+        .option("--config <path>", "Config file path", { default: defaultConfigPath })
+        .action((action, commandOptions) => {
+        if (action !== "status" && action !== "cancel") {
+            throw new UsageError(`Unknown maintenance action: ${action}`);
+        }
+        onParsed({
+            command: "maintenance",
+            action,
+            json: commandOptions.json === true,
+            configPath: resolvePath(requiredString(commandOptions.config, "--config")),
+        });
+    });
+    for (const command of ["status", "start"]) {
+        cli.command(command, `${capitalize(command)} the local coding-agent service`).action(() => {
+            onParsed({ command });
+        });
+    }
+    cli
+        .command("restart [agent]", "Restart the local service or a specific agent")
+        .option("--delay <seconds>", "Schedule the restart after a delay")
+        .option("--allow-waiting", "Allow restart while sessions wait for user input")
+        .action((agent, commandOptions) => {
+        if (agent !== undefined && agent !== "codex" && agent !== "claude") {
+            throw new UsageError(`Unknown agent for restart: ${agent}`);
+        }
+        const delaySeconds = optionalDelay(commandOptions.delay);
+        const allowWaiting = commandOptions.allowWaiting === true;
+        assertAllowWaitingHasDelay(allowWaiting, delaySeconds);
+        onParsed({ command: "restart", agent, delaySeconds, allowWaiting });
+    });
+    for (const command of ["stop", "uninstall"]) {
+        cli
+            .command(command, `${capitalize(command)} the local coding-agent service`)
+            .option("--delay <seconds>", `Schedule the ${command} after a delay`)
+            .option("--allow-waiting", `Allow ${command} while sessions wait for user input`)
+            .action((commandOptions) => {
+            const delaySeconds = optionalDelay(commandOptions.delay);
+            const allowWaiting = commandOptions.allowWaiting === true;
+            assertAllowWaitingHasDelay(allowWaiting, delaySeconds);
+            onParsed({ command, delaySeconds, allowWaiting });
+        });
+    }
+    if (options.includeInternalCommands) {
+        cli
+            .command("run-service", "Run the managed service supervisor")
+            .option("--config <path>", "Config file path")
+            .action((commandOptions) => {
+            const configPath = optionalString(commandOptions.config);
+            onParsed({ command: "run-service", configPath: configPath ? resolvePath(configPath) : undefined });
+        });
+    }
+    return cli;
+}
+function requiredString(value, name) {
+    const text = optionalString(value);
+    if (!text)
+        throw new UsageError(`Missing value for ${name}`);
+    return text;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function parseChannelOption(value) {
+    const text = optionalString(value);
+    if (text === undefined)
+        return undefined;
+    try {
+        return normalizeReleaseChannel(text);
+    }
+    catch {
+        throw new UsageError(`Unknown release channel for --channel: ${text} (expected latest, beta, or alpha)`);
+    }
+}
+function optionalDelay(value) {
+    if (value === undefined)
+        return undefined;
+    const text = typeof value === "number" ? String(value) : requiredString(value, "--delay");
+    if (!/^\d+$/.test(text))
+        throw new UsageError("--delay must be an integer between 1 and 86400 seconds");
+    const delay = Number.parseInt(text, 10);
+    if (delay < 1 || delay > 86_400) {
+        throw new UsageError("--delay must be an integer between 1 and 86400 seconds");
+    }
+    return delay;
+}
+function assertAllowWaitingHasDelay(allowWaiting, delaySeconds) {
+    if (allowWaiting && delaySeconds === undefined) {
+        throw new UsageError("--allow-waiting requires --delay");
+    }
+}
+function normalizeCacError(message, argv) {
+    if (message.startsWith("Unknown option `")) {
+        const rawOption = findFirstUnknownOption(argv);
+        if (rawOption)
+            return `Unknown option for ${argv[0]}: ${rawOption}`;
+    }
+    if (message.startsWith("option `")) {
+        const match = /^option `([^` ]+)/.exec(message);
+        if (match)
+            return `Missing value for ${match[1]}`;
+    }
+    if (message.startsWith("Unused args:")) {
+        const firstUnusedArg = argv.slice(1).find((arg) => !arg.startsWith("-"));
+        if (firstUnusedArg)
+            return `Unknown option for ${argv[0]}: ${firstUnusedArg}`;
+    }
+    return message;
+}
+function findFirstUnknownOption(argv) {
+    const command = argv[0];
+    if (!command || !isKnownCommand(command))
+        return argv.find((arg) => arg.startsWith("-"));
+    const knownOptions = knownOptionsForCommand(command);
+    for (const arg of argv.slice(1)) {
+        if (!arg.startsWith("-"))
+            continue;
+        const optionName = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+        if (!knownOptions.has(optionName))
+            return optionName;
+    }
+    return undefined;
+}
+function assertKnownOptions(argv) {
+    const command = argv[0];
+    if (!command || !isKnownCommand(command))
+        return;
+    const unknownOption = findFirstUnknownOption(argv);
+    if (unknownOption) {
+        throw new UsageError(`Unknown option for ${command}: ${unknownOption}`);
+    }
+}
+function knownOptionsForCommand(command) {
+    switch (command) {
+        case "install":
+            return new Set([
+                "--tunnel-id",
+                "--token",
+                "--workspace",
+                "--server-url",
+                "--config",
+                "--data-dir",
+                "--workspace-id",
+                "--workspace-name",
+                "--channel",
+            ]);
+        case "upgrade":
+            return new Set(["--version", "--channel", "--config", "--delay", "--allow-waiting"]);
+        case "sessions":
+        case "maintenance":
+            return new Set(["--json", "--config"]);
+        case "restart":
+        case "stop":
+        case "uninstall":
+            return new Set(["--delay", "--allow-waiting"]);
+        case "run-service":
+            return new Set(["--config"]);
+        default:
+            return new Set();
+    }
+}
+function isKnownCommand(command) {
+    return allCommands.includes(command);
+}
+function captureConsoleInfo(callback) {
+    const originalInfo = console.info;
+    const output = [];
+    console.info = (...args) => {
+        output.push(args.map(String).join(" "));
+    };
+    try {
+        callback();
+    }
+    finally {
+        console.info = originalInfo;
+    }
+    return output.join("\n");
+}
+function capitalize(value) {
+    return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}

package/dist/assets/skills/manage-coding-agent-client/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: manage-coding-agent-client
+description: 管理本机 coding-agent client，包括查询版本和会话状态、升级、启动、停止、重启 Codex/Claude、查看日志和卸载。用户要求检查、升级、重启、停止、排查或卸载 coding-agent client 时使用。
+---
+
+# 管理 Coding Agent Client
+
+始终使用安装后生成的稳定命令：
+
+```bash
+~/.coding-agent/bin/coding-agent
+```
+
+## 检查状态
+
+查询版本和服务状态：
+
+```bash
+~/.coding-agent/bin/coding-agent --version
+~/.coding-agent/bin/coding-agent status
+```
+
+执行任何会中断 Agent 的操作前，先查询会话：
+
+```bash
+~/.coding-agent/bin/coding-agent sessions --json
+```
+
+按以下规则处理结果：
+
+- 当前管理请求也计入 `active`。`active` 为 0 或 1 时，没有其他活动会话。
+- `active` 大于 1 时，说明还有 `active - 1` 个其他活动会话。告知用户，并确认是否安排为全部空闲后执行。
+- 任一 Agent 为 `unavailable` 时，不要安排操作；说明无法可靠判断会话状态。
+- `waiting` 大于 0 时，说明升级或重启可能使等待回答或批准的交互失效。必须获得用户明确确认，确认后在调度命令中加入 `--allow-waiting`。
+
+## 延后执行
+
+升级、重启、停止和卸载必须交给 client supervisor 延后执行。不要使用 `sleep`、`nohup`、后台 shell，也不要在当前会话中立即执行这些操作。
+
+默认延后 10 秒：
+
+```bash
+~/.coding-agent/bin/coding-agent upgrade --delay 10
+~/.coding-agent/bin/coding-agent upgrade --version <version> --delay 10
+~/.coding-agent/bin/coding-agent restart --delay 10
+~/.coding-agent/bin/coding-agent restart codex --delay 10
+~/.coding-agent/bin/coding-agent restart claude --delay 10
+~/.coding-agent/bin/coding-agent stop --delay 10
+~/.coding-agent/bin/coding-agent uninstall --delay 10
+```
+
+存在 waiting 会话且用户已经确认时，追加：
+
+```bash
+--allow-waiting
+```
+
+调度命令必须是本轮的最后一个工具动作。确认命令返回 maintenance task id 后，立即回复用户，不再运行其他命令。升级时回复：
+
+> 客户端 Agent 已安排在最早 10 秒后升级并重启；如果届时仍有会话正在运行，将等待空闲后执行。
+
+重启、停止或卸载时，将“升级并重启”替换为对应操作。
+
+## 管理延后任务
+
+查询或取消任务：
+
+```bash
+~/.coding-agent/bin/coding-agent maintenance status
+~/.coding-agent/bin/coding-agent maintenance cancel
+```
+
+同一时间只能有一个延后任务。新会话中可使用 `maintenance status`、`--version` 和 `status` 验证升级结果。
+
+## 操作影响
+
+- `upgrade` 安装目标 runtime，并重启整个 client 服务。
+- `restart codex` 或 `restart claude` 只重启对应 Agent。
+- 不带 Agent 的 `restart` 重启整个 client 服务。
+- `stop` 停止服务，必须先获得用户确认。
+
+## 发布通道
+
+client 的自动升级默认跟踪稳定版本（`latest` 通道）。用户要求使用预发布版本或回到稳定版时，切换发布通道：
+
+```bash
+~/.coding-agent/bin/coding-agent upgrade --channel beta --delay 10
+~/.coding-agent/bin/coding-agent upgrade --channel alpha --delay 10
+~/.coding-agent/bin/coding-agent upgrade --channel latest --delay 10
+```
+
+切换通道会更新自动升级跟踪的 npm dist-tag，并把 runtime 升级到该通道的最新版本。之后自动升级会持续跟踪同一通道，直到用户再次切换。
+
+- `uninstall` 停止并移除用户服务，但保留配置、数据、工作空间和已下载的 runtime。执行前说明保留项并获得确认。
+- 不要使用全局 npm 安装代替内置升级命令。
+
+## 日志排查
+
+先判断系统类型，再读取最近 100 行，避免默认持续跟随日志。
+
+Linux：
+
+```bash
+journalctl --user -u coding-agent-client.service -n 100 --no-pager
+```
+
+macOS：
+
+```bash
+tail -n 100 ~/.coding-agent/data/logs/client-service.out.log
+tail -n 100 ~/.coding-agent/data/logs/client-service.err.log
+```
+
+提醒用户在分享日志前检查并隐藏 token、服务地址和敏感路径。

package/dist/auto-upgrade.d.ts

@@ -0,0 +1,43 @@
+import type { MaintenanceScheduler } from "./maintenance.js";
+import { type ReleaseChannel } from "./runtime.js";
+export type AutoUpgradeState = {
+    status: "up-to-date" | "pending" | "scheduled" | "failed";
+    currentVersion: string;
+    channel: ReleaseChannel;
+    latestVersion?: string;
+    lastCheckedAt?: string;
+    updatedAt: string;
+    message?: string;
+};
+type AutoUpgradeOptions = {
+    statePath: string;
+    maintenance: MaintenanceScheduler;
+    getChannel?: () => Promise<ReleaseChannel>;
+    checkIntervalMs?: number;
+    pendingRetryMs?: number;
+    now?: () => number;
+    getCurrentVersion?: () => Promise<string>;
+    getLatestVersion?: (channel: ReleaseChannel) => Promise<string>;
+};
+export declare class AutoUpgradeScheduler {
+    private readonly options;
+    private state;
+    private timer;
+    private readonly checkIntervalMs;
+    private readonly pendingRetryMs;
+    private readonly now;
+    private readonly getCurrentVersion;
+    private readonly getLatestVersion;
+    private readonly getChannel;
+    constructor(options: AutoUpgradeOptions);
+    start(): Promise<void>;
+    stop(): void;
+    getState(): AutoUpgradeState | undefined;
+    checkNow(): Promise<void>;
+    private arm;
+    private tick;
+    private updateState;
+    private readState;
+    private isoNow;
+}
+export {};