@aigne/cli 1.53.1-beta.2 → 1.53.1-beta.3

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [1.53.1-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.53.1-beta.2...cli-v1.53.1-beta.3) (2025-11-04)
+
+
+### Bug Fixes
+
+* **cli:** optimize app startup by restructuring CLI application loading ([#698](https://github.com/AIGNE-io/aigne-framework/issues/698)) ([20c5059](https://github.com/AIGNE-io/aigne-framework/commit/20c50591bbd9a958b29409eca3ede5e341db2b7d))
+* update package to latest ([#699](https://github.com/AIGNE-io/aigne-framework/issues/699)) ([9877f6d](https://github.com/AIGNE-io/aigne-framework/commit/9877f6d1975362338db4eb47a2bf3564114c3cf8))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs-system-fs bumped to 1.0.4-beta.3
+    * @aigne/agent-library bumped to 1.21.51-beta.2
+    * @aigne/agentic-memory bumped to 1.0.51-beta.2
+    * @aigne/aigne-hub bumped to 0.10.5-beta.2
+    * @aigne/core bumped to 1.65.1-beta.2
+    * @aigne/default-memory bumped to 1.2.14-beta.2
+    * @aigne/observability-api bumped to 0.11.5-beta.1
+    * @aigne/openai bumped to 0.16.5-beta.2
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.58-beta.2
+
 ## [1.53.1-beta.2](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.53.1-beta.1...cli-v1.53.1-beta.2) (2025-11-04)
 
 

package/dist/commands/app/agent.d.ts

@@ -0,0 +1,26 @@
+import type { Agent, AIGNE, Message } from "@aigne/core";
+import type { CLIAgent } from "@aigne/core/utils/agent-utils.js";
+import type { CommandModule } from "yargs";
+import { type AgentRunCommonOptions } from "../../utils/yargs.js";
+export declare const serveMcpCommandModule: ({ aigne, name, }: {
+    aigne: AIGNE;
+    name: string;
+}) => CommandModule<unknown, {
+    host: string;
+    port?: number;
+    pathname: string;
+}>;
+export declare const agentCommandModule: ({ aigne, agent, chat, }: {
+    aigne: AIGNE;
+    agent: Agent;
+    chat?: boolean;
+}) => CommandModule<unknown, AgentRunCommonOptions>;
+export declare const cliAgentCommandModule: ({ aigne, cliAgent, }: {
+    aigne: AIGNE;
+    cliAgent: CLIAgent<Agent>;
+}) => CommandModule<unknown, AgentRunCommonOptions>;
+export declare function invokeAgent(options: {
+    aigne: AIGNE;
+    agent: Agent;
+    input: Message & AgentRunCommonOptions;
+}): Promise<void>;

package/dist/commands/app/agent.js

@@ -0,0 +1,102 @@
+import assert from "node:assert";
+import { logger } from "@aigne/core/utils/logger.js";
+import { runAgentWithAIGNE } from "../../utils/run-with-aigne.js";
+import { parseAgentInput, withAgentInputSchema, } from "../../utils/yargs.js";
+import { serveMCPServerFromDir } from "../serve-mcp.js";
+export const serveMcpCommandModule = ({ aigne, name, }) => ({
+    command: "serve-mcp",
+    describe: `Serve ${name} a MCP server (streamable http)`,
+    builder: (yargs) => {
+        return yargs
+            .option("host", {
+            describe: "Host to run the MCP server on, use 0.0.0.0 to publicly expose the server",
+            type: "string",
+            default: "localhost",
+        })
+            .option("port", {
+            describe: "Port to run the MCP server on",
+            type: "number",
+        })
+            .option("pathname", {
+            describe: "Pathname to the service",
+            type: "string",
+            default: "/mcp",
+        });
+    },
+    handler: async (options) => {
+        await serveMCPServerFromDir({
+            ...options,
+            aigne,
+        });
+    },
+});
+export const agentCommandModule = ({ aigne, agent, chat, }) => {
+    return {
+        command: agent.name,
+        aliases: agent.alias || [],
+        describe: agent.description || "",
+        builder: async (yargs) => {
+            return withAgentInputSchema(yargs, { inputSchema: agent.inputSchema });
+        },
+        handler: async (options) => {
+            if (options.logLevel)
+                logger.level = options.logLevel;
+            await invokeAgent({
+                aigne,
+                agent,
+                input: { ...options, chat: chat ?? options.chat },
+            });
+        },
+    };
+};
+export const cliAgentCommandModule = ({ aigne, cliAgent, }) => {
+    const { agent, agents } = cliAgent;
+    const name = cliAgent.name || agent?.name;
+    assert(name, "CLI agent must have a name");
+    return {
+        command: name,
+        aliases: cliAgent.alias || agent?.alias || [],
+        describe: cliAgent.description || agent?.description || "",
+        builder: async (yargs) => {
+            if (agent) {
+                withAgentInputSchema(yargs, { inputSchema: agent.inputSchema });
+            }
+            if (agents?.length) {
+                for (const cmd of agents) {
+                    yargs.command(cliAgentCommandModule({
+                        aigne,
+                        cliAgent: cmd,
+                    }));
+                }
+            }
+            if (!agent)
+                yargs.demandCommand();
+            return yargs;
+        },
+        handler: async (options) => {
+            if (!agent)
+                throw new Error("CLI agent is not defined");
+            if (options.logLevel)
+                logger.level = options.logLevel;
+            await invokeAgent({
+                aigne,
+                agent,
+                input: options,
+            });
+        },
+    };
+};
+export async function invokeAgent(options) {
+    const { agent, aigne } = options;
+    try {
+        const input = await parseAgentInput(options.input, agent);
+        await runAgentWithAIGNE(aigne, agent, {
+            ...options.input,
+            input,
+            chat: options.input.chat,
+        });
+    }
+    finally {
+        await aigne.shutdown();
+    }
+}

package/dist/commands/app/app.d.ts

@@ -0,0 +1,7 @@
+export declare function runAppCLI({ appName, appPackageName, appDescription, appUseBetaVersion, ...options }?: {
+    argv?: string[];
+    appName?: string;
+    appPackageName?: string;
+    appDescription?: string;
+    appUseBetaVersion?: boolean;
+}): Promise<void>;

package/dist/commands/app/app.js

@@ -0,0 +1,90 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { LogLevel, logger } from "@aigne/core/utils/logger.js";
+import chalk from "chalk";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { highlightUrl } from "../../utils/string-utils.js";
+import { withRunAgentCommonOptions } from "../../utils/yargs.js";
+import { agentCommandModule, cliAgentCommandModule, serveMcpCommandModule } from "./agent.js";
+import { loadApplication, NeedReinstallBetaError, NeedReinstallError, upgradeCommandModule, } from "./upgrade.js";
+export async function runAppCLI({ appName = process.env.AIGNE_APP_NAME, appPackageName = process.env.AIGNE_APP_PACKAGE_NAME, appDescription = process.env.AIGNE_APP_DESCRIPTION, appUseBetaVersion = process.env.AIGNE_APP_USE_BETA_APPS === "1" ? true : undefined, ...options } = {}) {
+    const [scriptName, ...argv] = options.argv || hideBin(process.argv);
+    if (!appName || !appPackageName)
+        throw new Error("AIGNE_APP_NAME or AIGNE_APP_PACKAGE_NAME is not defined");
+    try {
+        // Parse model options for loading application
+        const options = withRunAgentCommonOptions(yargs(argv).help(false).version(false).strict(false)).parseSync();
+        logger.level = options.logLevel;
+        const dir = join(homedir(), ".aigne", "registry.npmjs.org", appPackageName);
+        const y = yargs()
+            .scriptName(`aigne ${scriptName}`)
+            .usage(`aigne ${scriptName}\n\n${appDescription || ""}`)
+            .command(upgradeCommandModule({ packageName: appPackageName, dir }));
+        if (!isUpgradeCommand(argv)) {
+            const { aigne, version } = await loadApplication({
+                packageName: appPackageName,
+                beta: appUseBetaVersion,
+                dir,
+                install: true,
+                modelOptions: options,
+                imageModelOptions: { model: options.imageModel },
+                skipModelLoading: (options.help || options.h || options.version || options.v) === true,
+            });
+            if (aigne.cli?.chat) {
+                y.command({
+                    ...agentCommandModule({
+                        aigne,
+                        agent: aigne.cli.chat,
+                        chat: true,
+                    }),
+                    command: "$0",
+                });
+            }
+            for (const cliAgent of aigne.cli?.agents ?? []) {
+                y.command(cliAgentCommandModule({ aigne, cliAgent }));
+            }
+            y.option("model", {
+                type: "string",
+                description: "Model to use for the application, example: openai:gpt-4.1 or google:gemini-2.5-flash",
+            }).command(serveMcpCommandModule({ aigne, name: appName }));
+            y.version(`${appName} v${version}`);
+        }
+        await y
+            .alias("v", "version")
+            .alias("h", "help")
+            .demandCommand()
+            .fail((message, error, yargs) => {
+            // We catch all errors below, here just print the help message non-error case like demandCommand
+            if (!error) {
+                yargs.showHelp();
+                console.error(`\n${message}`);
+                process.exit(1);
+            }
+        })
+            .parseAsync(argv);
+        process.exit(0);
+    }
+    catch (error) {
+        if (error instanceof NeedReinstallError || error instanceof NeedReinstallBetaError) {
+            logger.warn(error.message);
+            process.exit(error instanceof NeedReinstallBetaError
+                ? NeedReinstallBetaError.code
+                : NeedReinstallError.code);
+        }
+        if (error.name !== "ExitPromptError") {
+            console.log(""); // Add an empty line for better readability
+            if (logger.enabled(LogLevel.ERROR)) {
+                console.error(chalk.red(error.stack));
+            }
+            else {
+                console.error(`${chalk.red("Error:")} ${highlightUrl(error.message)}`);
+            }
+        }
+        process.exit(1);
+    }
+}
+function isUpgradeCommand(argv) {
+    const skipGlobalOptions = ["-v", "--version", "-h", "--help"];
+    return argv[0] === "upgrade" && !argv.some((arg) => skipGlobalOptions.includes(arg));
+}

package/dist/commands/app/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/app/cli.js

@@ -0,0 +1,2 @@
+import { runAppCLI } from "./app.js";
+await runAppCLI();

package/dist/commands/app/upgrade.d.ts

@@ -0,0 +1,54 @@
+import type { LoadCredentialOptions } from "@aigne/cli/utils/aigne-hub/type.js";
+import type { AIGNE, ChatModelInputOptions, ImageModelInputOptions } from "@aigne/core";
+import type { CommandModule } from "yargs";
+export declare const upgradeCommandModule: ({ packageName, dir, }: {
+    packageName: string;
+    dir: string;
+}) => CommandModule<unknown, {
+    beta?: boolean;
+    targetVersion?: string;
+    force?: boolean;
+}>;
+interface LoadApplicationOptions {
+    packageName: string;
+    dir: string;
+    install?: boolean;
+    skipModelLoading?: boolean;
+    modelOptions?: ChatModelInputOptions & LoadCredentialOptions;
+    imageModelOptions?: ImageModelInputOptions & LoadCredentialOptions;
+    beta?: boolean;
+}
+interface LoadApplicationResult {
+    aigne: AIGNE;
+    version: string;
+    isCache?: boolean;
+}
+export declare class NeedReinstallError extends Error {
+    static code: number;
+}
+export declare class NeedReinstallBetaError extends Error {
+    static code: number;
+}
+export declare function loadApplication(options: LoadApplicationOptions & {
+    install: true;
+}): Promise<LoadApplicationResult>;
+export declare function loadApplication(options: LoadApplicationOptions & {
+    install?: false;
+}): Promise<LoadApplicationResult | null>;
+export declare function getNpmTgzInfo(name: string, { version, beta }?: {
+    version?: string;
+    beta?: boolean;
+}): Promise<{
+    version: string;
+    url: string;
+}>;
+export declare function installApp({ dir, packageName, beta, version, }: {
+    dir: string;
+    packageName: string;
+    beta?: boolean;
+    version?: string;
+}): Promise<{
+    url: string;
+    version: string;
+}>;
+export {};

package/dist/commands/app/upgrade.js

@@ -0,0 +1,234 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fetch } from "@aigne/core/utils/fetch.js";
+import { Listr, PRESET_TIMER } from "@aigne/listr2";
+import { joinURL } from "ufo";
+import { downloadAndExtract } from "../../utils/download.js";
+import { loadAIGNE } from "../../utils/load-aigne.js";
+import { withSpinner } from "../../utils/spinner.js";
+const NPM_PACKAGE_CACHE_TIME_MS = 1000 * 60 * 60 * 24; // 1 day
+/**
+ * Check if beta applications should be used based on environment variables
+ */
+function shouldUseBetaApps() {
+    const envVar = process.env.AIGNE_USE_BETA_APPS;
+    return envVar === "true" || envVar === "1";
+}
+export const upgradeCommandModule = ({ packageName, dir, }) => ({
+    command: "upgrade",
+    describe: `Upgrade ${packageName} to the latest version`,
+    builder: (yargs) => {
+        return yargs
+            .option("beta", {
+            type: "boolean",
+            describe: "Use beta versions if available",
+        })
+            .option("target-version", {
+            type: "string",
+            describe: "Specify a version to upgrade to (default is latest)",
+            alias: ["to", "target"],
+        })
+            .option("force", {
+            type: "boolean",
+            describe: "Force upgrade even if already at latest version",
+            default: false,
+        });
+    },
+    handler: async ({ beta, targetVersion, force }) => {
+        beta ??= shouldUseBetaApps();
+        const npm = await withSpinner("", async () => {
+            if (force)
+                await rm(dir, { force: true, recursive: true });
+            return await getNpmTgzInfo(packageName, { beta, version: targetVersion });
+        });
+        const check = await checkInstallation(dir);
+        if (force || !check || npm.version !== check.version) {
+            await installApp({ packageName, dir, beta, version: targetVersion });
+        }
+        const app = await loadApplication({ dir, packageName, install: true, skipModelLoading: true });
+        if (force || check?.version !== app.version) {
+            console.log(`\n✅ Upgraded ${packageName} to version ${app.version}`);
+        }
+        else {
+            console.log(`\n✅ ${packageName} is already at the latest version (${app.version})`);
+        }
+    },
+});
+export class NeedReinstallError extends Error {
+    static code = 244;
+}
+export class NeedReinstallBetaError extends Error {
+    static code = 245;
+}
+export async function loadApplication(options) {
+    const { dir, packageName } = options;
+    const check = await checkInstallation(dir);
+    const beta = options.beta ?? check?.version?.includes("beta");
+    if (check) {
+        let needUpdate = check.expired;
+        if (check.expired) {
+            await withSpinner("Checking updates...", async () => {
+                const tgz = await getNpmTgzInfo(packageName, { beta });
+                if (tgz.version === check.version) {
+                    await writeInstallationMetadata(dir, { installedAt: Date.now() });
+                    needUpdate = false;
+                }
+            });
+        }
+        if (!needUpdate) {
+            const aigne = await loadAIGNE({
+                path: dir,
+                skipModelLoading: options.skipModelLoading,
+                modelOptions: options.modelOptions,
+                imageModelOptions: options.imageModelOptions,
+                metadata: {
+                    appName: packageName,
+                    appVersion: check?.version,
+                },
+            }).catch(async (error) => {
+                await withSpinner("", async () => {
+                    await rm(options.dir, { recursive: true, force: true });
+                    await mkdir(options.dir, { recursive: true });
+                });
+                const message = `⚠️ Failed to load ${packageName}, trying to reinstall: ${error.message}`;
+                throw beta ? new NeedReinstallBetaError(message) : new NeedReinstallError(message);
+            });
+            if (aigne) {
+                return { aigne, version: check.version, isCache: true };
+            }
+        }
+    }
+    if (!options.install)
+        return null;
+    const result = await installApp({ dir, packageName, beta });
+    return {
+        aigne: await loadAIGNE({
+            path: dir,
+            skipModelLoading: true,
+            metadata: {
+                appName: packageName,
+                appVersion: result.version,
+            },
+        }),
+        version: result.version,
+    };
+}
+export async function getNpmTgzInfo(name, { version, beta } = {}) {
+    const res = await fetch(joinURL("https://registry.npmjs.org", name));
+    const data = await res.json();
+    let targetVersion;
+    if (version) {
+        if (!data.versions[version]) {
+            throw new Error(`Version ${version} of package ${name} not found`);
+        }
+        targetVersion = version;
+    }
+    else if (beta && data["dist-tags"].beta) {
+        // Use beta version if available and beta flag is set
+        targetVersion = data["dist-tags"].beta;
+    }
+    else {
+        // Fall back to latest version
+        targetVersion = data["dist-tags"].latest;
+    }
+    const url = data.versions[targetVersion].dist.tarball;
+    return {
+        version: targetVersion,
+        url,
+    };
+}
+async function readInstallationMetadata(dir) {
+    return safeParseJSON(await readFile(join(dir, ".aigne-cli.json"), "utf-8").catch(() => "{}"));
+}
+async function writeInstallationMetadata(dir, metadata) {
+    await writeFile(join(dir, ".aigne-cli.json"), JSON.stringify(metadata, null, 2));
+}
+async function checkInstallation(dir, { cacheTimeMs = NPM_PACKAGE_CACHE_TIME_MS } = {}) {
+    const s = await stat(join(dir, "package.json")).catch(() => null);
+    if (!s)
+        return null;
+    const version = safeParseJSON(await readFile(join(dir, "package.json"), "utf-8"))?.version;
+    if (!version)
+        return null;
+    const installedAt = (await readInstallationMetadata(dir))?.installedAt;
+    if (!installedAt)
+        return null;
+    const now = Date.now();
+    const expired = now - installedAt > cacheTimeMs;
+    return { version, expired };
+}
+export async function installApp({ dir, packageName, beta, version, }) {
+    return await new Listr([
+        {
+            title: `Fetching ${packageName} metadata`,
+            task: async (ctx, task) => {
+                if (beta) {
+                    task.title = `Fetching ${packageName} metadata (using beta version)`;
+                }
+                const info = await getNpmTgzInfo(packageName, { beta, version });
+                Object.assign(ctx, info);
+            },
+        },
+        {
+            title: `Downloading ${packageName}`,
+            task: async (ctx, task) => {
+                task.title = `Downloading ${packageName} (v${ctx.version})`;
+                await mkdir(dir, { recursive: true });
+                await downloadAndExtract(ctx.url, dir, { strip: 1 });
+            },
+        },
+        {
+            title: "Installing dependencies",
+            task: async (_, task) => {
+                await installDependencies(dir, {
+                    log: (log) => {
+                        const last = log.split("\n").findLast((i) => !!i);
+                        if (last)
+                            task.output = last;
+                    },
+                });
+                await writeInstallationMetadata(dir, { installedAt: Date.now() });
+            },
+        },
+    ], {
+        rendererOptions: {
+            collapseSubtasks: false,
+            showErrorMessage: false,
+            timer: PRESET_TIMER,
+        },
+    }).run();
+}
+async function installDependencies(dir, { log } = {}) {
+    await new Promise((resolve, reject) => {
+        const child = spawn("npm", ["install", "--omit", "dev", "--verbose", "--legacy-peer-deps"], {
+            cwd: dir,
+            stdio: "pipe",
+            shell: process.platform === "win32",
+        });
+        child.stdout.on("data", (data) => {
+            log?.(data.toString());
+        });
+        let stderr = "";
+        child.stderr.on("data", (data) => {
+            const str = data.toString();
+            log?.(str);
+            stderr += str;
+        });
+        child.on("error", (error) => reject(error));
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else {
+                console.error(stderr);
+                reject(new Error(`npm install failed with code ${code}`));
+            }
+        });
+    });
+}
+function safeParseJSON(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch { }
+}

package/dist/commands/app.d.ts

@@ -1,53 +1,4 @@
 import type { CommandModule } from "yargs";
-import { type AgentInChildProcess, type CLIAgentInChildProcess, type LoadAIGNEInChildProcessResult } from "../utils/workers/run-aigne-in-child-process.js";
-import { type AgentRunCommonOptions } from "../utils/yargs.js";
 export declare function createAppCommands({ argv }?: {
     argv?: string[];
 }): CommandModule[];
-export declare const agentCommandModule: ({ dir, agent, chat, version, packageName, }: {
-    dir: string;
-    agent: AgentInChildProcess;
-    chat?: boolean;
-    version?: string;
-    packageName?: string;
-}) => CommandModule<unknown, AgentRunCommonOptions>;
-export declare const cliAgentCommandModule: ({ dir, parent, cliAgent, version, packageName, }: {
-    dir: string;
-    parent?: string[];
-    cliAgent: CLIAgentInChildProcess;
-    version?: string;
-    packageName?: string;
-}) => CommandModule<unknown, AgentRunCommonOptions>;
-interface LoadApplicationOptions {
-    packageName: string;
-    dir: string;
-    install?: boolean;
-}
-interface LoadApplicationResult {
-    aigne: LoadAIGNEInChildProcessResult;
-    version: string;
-    isCache?: boolean;
-}
-export declare function loadApplication(options: LoadApplicationOptions & {
-    install: true;
-}): Promise<LoadApplicationResult>;
-export declare function loadApplication(options: LoadApplicationOptions & {
-    install?: false;
-}): Promise<LoadApplicationResult | null>;
-export declare function installApp({ dir, packageName, beta, version, }: {
-    dir: string;
-    packageName: string;
-    beta?: boolean;
-    version?: string;
-}): Promise<{
-    url: string;
-    version: string;
-}>;
-export declare function getNpmTgzInfo(name: string, { version, beta }?: {
-    version?: string;
-    beta?: boolean;
-}): Promise<{
-    version: string;
-    url: string;
-}>;
-export {};