@aigne/cli 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.2.0](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.1.0...cli-v1.2.0) (2025-04-15)
+
+
+### Features
+
+* add TerminalTracer for better UX in terminal ([#56](https://github.com/AIGNE-io/aigne-framework/issues/56)) ([9875a5d](https://github.com/AIGNE-io/aigne-framework/commit/9875a5d46abb55073340ffae841fed6bd6b83ff4))
+* **cli:** support run agents from remote URL ([#60](https://github.com/AIGNE-io/aigne-framework/issues/60)) ([5f49920](https://github.com/AIGNE-io/aigne-framework/commit/5f4992089d36f9e780ba55a912a1d35508cad28e))
+
+
+### Bug Fixes
+
+* remove usage of new Node.js exists API for compatibility ([#57](https://github.com/AIGNE-io/aigne-framework/issues/57)) ([c10cc08](https://github.com/AIGNE-io/aigne-framework/commit/c10cc086d8ecd0744f38cdb1367d4c8816b723b3))
+
 ## [1.1.0](https://github.com/AIGNE-io/aigne-framework/compare/cli-v1.0.0...cli-v1.1.0) (2025-04-08)
 
 

package/dist/cli.js

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
+import PrettyError from "pretty-error";
 import { createAIGNECommand } from "./commands/aigne.js";
-createAIGNECommand().parse();
+createAIGNECommand()
+    .parseAsync()
+    .catch((error) => {
+    console.error(new PrettyError().render(error));
+    process.exit(1);
+});

package/dist/commands/run.js

@@ -1,35 +1,57 @@
-import { isAbsolute, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 import { ExecutionEngine } from "@aigne/core";
-import { runChatLoopInTerminal } from "@aigne/core/utils/run-chat-loop.js";
 import { Command } from "commander";
+import { downloadAndExtract } from "../utils/download.js";
+import { runChatLoopInTerminal } from "../utils/run-chat-loop.js";
 export function createRunCommand() {
     return new Command("run")
         .description("Run a chat loop with the specified agent")
-        .argument("[path]", "Path to the agents directory", ".")
+        .argument("[path]", "Path to the agents directory or URL to aigne project", ".")
         .option("--agent <agent>", "Name of the agent to use (defaults to the first agent found)")
         .action(async (path, options) => {
-        const absolutePath = isAbsolute(path) ? path : resolve(process.cwd(), path);
-        const engine = await ExecutionEngine.load({ path: absolutePath });
-        let agent;
-        if (options.agent) {
-            agent = engine.agents[options.agent];
-            if (!agent) {
-                console.error(`Agent "${options.agent}" not found.`);
-                console.log("Available agents:");
-                for (const agent of engine.agents) {
-                    console.log(`- ${agent.name}`);
-                }
-                throw new Error(`Agent "${options.agent}" not found`);
-            }
+        if (path.startsWith("http")) {
+            await downloadAndRunPackage(path, options);
+            return;
         }
-        else {
-            agent = engine.agents[0];
-            if (!agent)
-                throw new Error("No agents found in the specified path");
-        }
-        const user = engine.call(agent);
-        await runChatLoopInTerminal(user, {});
+        const absolutePath = isAbsolute(path) ? path : resolve(process.cwd(), path);
+        await runEngine(path, absolutePath, options);
     })
         .showHelpAfterError(true)
         .showSuggestionAfterError(true);
 }
+async function runEngine(originalPath, path, options) {
+    const engine = await ExecutionEngine.load({ path });
+    let agent;
+    if (options.agent) {
+        agent = engine.agents[options.agent];
+        if (!agent) {
+            console.error(`Agent "${options.agent}" not found in ${originalPath}`);
+            console.log("Available agents:");
+            for (const agent of engine.agents) {
+                console.log(`- ${agent.name}`);
+            }
+            throw new Error(`Agent "${options.agent}" not found in ${originalPath}`);
+        }
+    }
+    else {
+        agent = engine.agents[0];
+        if (!agent)
+            throw new Error(`No agents found in ${originalPath}`);
+    }
+    const user = engine.call(agent);
+    await runChatLoopInTerminal(user, {});
+}
+async function downloadAndRunPackage(url, options) {
+    const dir = join(tmpdir(), randomUUID());
+    try {
+        await mkdir(dir, { recursive: true });
+        await downloadAndExtract(url, dir);
+        await runEngine(url, dir, options);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

package/dist/tracer/terminal.d.ts

@@ -0,0 +1,52 @@
+import { type Agent, type Context, type Message } from "@aigne/core";
+import type { ContextUsage } from "@aigne/core/execution-engine/usage";
+import { type DefaultRenderer, Listr, type ListrRenderer, type ListrTaskWrapper } from "@aigne/listr2";
+export interface TerminalTracerOptions {
+    verbose?: boolean;
+}
+export declare class TerminalTracer {
+    readonly context: Context;
+    readonly options: TerminalTracerOptions;
+    constructor(context: Context, options?: TerminalTracerOptions);
+    private spinner;
+    private tasks;
+    run(agent: Agent, input: Message): Promise<{
+        result: any;
+        context: Context;
+    }>;
+    protected newListr(): MyListr;
+    formatAgentStartedOutput(agent: Agent, data: Message): string;
+    formatAgentSucceedOutput(agent: Agent, data: Message): string;
+    formatAgentFailedOutput(agent: Agent, data: Error): string;
+    formatMessage(data: unknown): string;
+    formatTokenUsage(usage: Partial<ContextUsage>, extra?: {
+        [key: string]: string;
+    }): string;
+    formatTimeUsage(startTime: number, endTime: number): string;
+    formatTaskTitle(agent: Agent, { task, usage, time }?: {
+        task?: Task;
+        usage?: boolean;
+        time?: boolean;
+    }): string;
+}
+type Task = ReturnType<typeof Promise.withResolvers<void>> & {
+    listr: ReturnType<typeof Promise.withResolvers<{
+        ctx: object;
+        subtask: Listr;
+        taskWrapper: ListrTaskWrapper<unknown, typeof DefaultRenderer, typeof ListrRenderer>;
+    }>>;
+    startTime?: number;
+    endTime?: number;
+    usage?: Partial<ContextUsage>;
+    extraTitleMetadata?: {
+        [key: string]: string;
+    };
+};
+declare class MyListr extends Listr {
+    private taskPromise;
+    private isTaskPromiseResolved;
+    resolveWaitingTask(): void;
+    add(...args: Parameters<Listr["add"]>): ReturnType<Listr["add"]>;
+    waitTaskAndRun(ctx?: unknown): Promise<any>;
+}
+export {};

package/dist/tracer/terminal.js

@@ -0,0 +1,179 @@
+import { inspect } from "node:util";
+import { ChatModel, } from "@aigne/core";
+import { Listr, ListrDefaultRendererLogLevels, Spinner, figures, } from "@aigne/listr2";
+import chalk from "chalk";
+import { z } from "zod";
+import { parseDuration } from "../utils/time.js";
+const DEBUG_DEPTH = z.number().int().default(2).safeParse(Number(process.env.DEBUG_DEPTH)).data;
+export class TerminalTracer {
+    context;
+    options;
+    constructor(context, options = {}) {
+        this.context = context;
+        this.options = options;
+    }
+    spinner = new Spinner();
+    tasks = {};
+    async run(agent, input) {
+        try {
+            this.spinner.start();
+            const context = this.context.newContext({ reset: true });
+            const listr = this.newListr();
+            context.on("agentStarted", async ({ contextId, parentContextId, agent, input, timestamp }) => {
+                const task = {
+                    ...Promise.withResolvers(),
+                    listr: Promise.withResolvers(),
+                    startTime: timestamp,
+                };
+                this.tasks[contextId] = task;
+                const listrTask = {
+                    title: this.formatTaskTitle(agent),
+                    task: (ctx, taskWrapper) => {
+                        const subtask = taskWrapper.newListr([{ task: () => task.promise }]);
+                        task.listr.resolve({ subtask, taskWrapper, ctx });
+                        return subtask;
+                    },
+                    rendererOptions: {
+                        persistentOutput: true,
+                        outputBar: Number.POSITIVE_INFINITY,
+                        bottomBar: Number.POSITIVE_INFINITY,
+                    },
+                };
+                const parentTask = parentContextId ? this.tasks[parentContextId] : undefined;
+                if (parentTask) {
+                    parentTask.listr.promise.then(({ subtask }) => {
+                        subtask.add(listrTask);
+                    });
+                }
+                else {
+                    listr.add(listrTask);
+                }
+                const { taskWrapper } = await task.listr.promise;
+                if (this.options.verbose) {
+                    taskWrapper.output = this.formatAgentStartedOutput(agent, input);
+                }
+            });
+            context.on("agentSucceed", async ({ agent, contextId, parentContextId, output, timestamp }) => {
+                const task = this.tasks[contextId];
+                if (!task)
+                    return;
+                task.endTime = timestamp;
+                const { taskWrapper, ctx } = await task.listr.promise;
+                if (agent instanceof ChatModel) {
+                    const { usage, model } = output;
+                    task.usage = usage;
+                    task.extraTitleMetadata ??= {};
+                    if (model)
+                        task.extraTitleMetadata.model = model;
+                }
+                taskWrapper.title = this.formatTaskTitle(agent, { task, usage: true, time: true });
+                if (this.options.verbose) {
+                    taskWrapper.output = this.formatAgentSucceedOutput(agent, output);
+                }
+                if (!parentContextId || !this.tasks[parentContextId]) {
+                    Object.assign(ctx, output);
+                }
+                task.resolve();
+            });
+            context.on("agentFailed", async ({ agent, contextId, error, timestamp }) => {
+                const task = this.tasks[contextId];
+                if (!task)
+                    return;
+                task.endTime = timestamp;
+                const { taskWrapper } = await task.listr.promise;
+                taskWrapper.title = this.formatTaskTitle(agent, { task, usage: true, time: true });
+                taskWrapper.output = this.formatAgentFailedOutput(agent, error);
+                task.reject(error);
+            });
+            const [result] = await Promise.all([
+                listr.waitTaskAndRun(),
+                context.call(agent, input).finally(() => {
+                    listr.resolveWaitingTask();
+                }),
+            ]);
+            return { result, context };
+        }
+        finally {
+            this.spinner.stop();
+        }
+    }
+    newListr() {
+        return new MyListr([], {
+            concurrent: true,
+            rendererOptions: {
+                collapseSubtasks: false,
+                writeBottomBarDirectly: true,
+                icon: {
+                    [ListrDefaultRendererLogLevels.PENDING]: () => this.spinner.fetch(),
+                    [ListrDefaultRendererLogLevels.OUTPUT_WITH_BOTTOMBAR]: "",
+                },
+            },
+        });
+    }
+    formatAgentStartedOutput(agent, data) {
+        return `\
+${chalk.grey(figures.pointer)} call agent ${agent.name} started with input:
+${this.formatMessage(data)}`;
+    }
+    formatAgentSucceedOutput(agent, data) {
+        return `\
+${chalk.grey(figures.tick)} call agent ${agent.name} succeed with output:
+${this.formatMessage(data)}`;
+    }
+    formatAgentFailedOutput(agent, data) {
+        return `\
+${chalk.grey(figures.cross)} call agent ${agent.name} failed with error:
+${this.formatMessage(data)}`;
+    }
+    formatMessage(data) {
+        return inspect(data, { colors: true, depth: DEBUG_DEPTH });
+    }
+    formatTokenUsage(usage, extra) {
+        const items = [
+            [chalk.yellow(usage.inputTokens), chalk.grey("input tokens")],
+            [chalk.cyan(usage.outputTokens), chalk.grey("output tokens")],
+            usage.agentCalls ? [chalk.magenta(usage.agentCalls), chalk.grey("agent calls")] : undefined,
+        ];
+        const content = items.filter((i) => !!i).map((i) => i.join(" "));
+        if (extra) {
+            content.unshift(...Object.entries(extra)
+                .filter(([k, v]) => k && v)
+                .map(([k, v]) => `${chalk.grey(k)}: ${v}`));
+        }
+        return `${chalk.grey("(")}${content.join(chalk.green(", "))}${chalk.grey(")")}`;
+    }
+    formatTimeUsage(startTime, endTime) {
+        const duration = endTime - startTime;
+        return chalk.grey(`[${parseDuration(duration)}]`);
+    }
+    formatTaskTitle(agent, { task, usage, time } = {}) {
+        let title = `call agent ${agent.name}`;
+        if (usage && task?.usage)
+            title += ` ${this.formatTokenUsage(task.usage, task.extraTitleMetadata)}`;
+        if (time && task?.startTime && task.endTime)
+            title += ` ${this.formatTimeUsage(task.startTime, task.endTime)}`;
+        return title;
+    }
+}
+class MyListr extends Listr {
+    taskPromise = Promise.withResolvers();
+    isTaskPromiseResolved = false;
+    resolveWaitingTask() {
+        if (!this.isTaskPromiseResolved) {
+            this.taskPromise.resolve();
+            this.isTaskPromiseResolved = true;
+        }
+    }
+    add(...args) {
+        const result = super.add(...args);
+        this.resolveWaitingTask();
+        return result;
+    }
+    async waitTaskAndRun(ctx) {
+        if (!this.tasks.length)
+            await this.taskPromise.promise;
+        if (!this.tasks.length)
+            return ctx;
+        return super.run(ctx);
+    }
+}

package/dist/utils/download.d.ts

@@ -0,0 +1 @@
+export declare function downloadAndExtract(url: string, dir: string): Promise<void>;

package/dist/utils/download.js

@@ -0,0 +1,21 @@
+import { Readable } from "node:stream";
+import { finished } from "node:stream/promises";
+import { x } from "tar";
+export async function downloadAndExtract(url, dir) {
+    const response = await fetch(url).catch((error) => {
+        throw new Error(`Failed to download package from ${url}: ${error.message}`);
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to download package from ${url}: ${response.statusText}`);
+    }
+    if (!response.body) {
+        throw new Error(`Failed to download package from ${url}: Unexpected to get empty response`);
+    }
+    try {
+        await finished(Readable.fromWeb(response.body).pipe(x({ C: dir })));
+    }
+    catch (error) {
+        error.message = `Failed to extract package from ${url}: ${error.message}`;
+        throw error;
+    }
+}

package/dist/utils/run-chat-loop.d.ts

@@ -0,0 +1,9 @@
+import { type Message, type UserAgent as input } from "@aigne/core";
+export interface ChatLoopOptions {
+    initialCall?: Message | string;
+    welcome?: string;
+    defaultQuestion?: string;
+    inputKey?: string;
+    verbose?: boolean;
+}
+export declare function runChatLoopInTerminal(userAgent: input, options?: ChatLoopOptions): Promise<void>;

package/dist/utils/run-chat-loop.js

@@ -0,0 +1,73 @@
+import { inspect } from "node:util";
+import { MESSAGE_KEY, createMessage } from "@aigne/core";
+import { logger } from "@aigne/core/utils/logger.js";
+import { figures } from "@aigne/listr2";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { TerminalTracer } from "../tracer/terminal.js";
+export async function runChatLoopInTerminal(userAgent, options = {}) {
+    options.verbose ??= logger.enabled("aigne:core");
+    // Disable the logger, use TerminalTracer instead
+    logger.disable();
+    let prompt;
+    if (options?.welcome)
+        console.log(options.welcome);
+    if (options?.initialCall) {
+        await callAgent(userAgent, options.initialCall, { ...options });
+    }
+    for (let i = 0;; i++) {
+        prompt = inquirer.prompt([
+            {
+                type: "input",
+                name: "question",
+                message: "💬",
+                default: i === 0 ? options?.defaultQuestion : undefined,
+            },
+        ]);
+        let question;
+        try {
+            question = (await prompt).question;
+        }
+        catch {
+            // ignore abort error from inquirer
+        }
+        if (!question?.trim())
+            continue;
+        const cmd = COMMANDS[question.trim()];
+        if (cmd) {
+            const result = cmd();
+            if (result.message)
+                console.log(result.message);
+            if (result?.exit)
+                break;
+            continue;
+        }
+        await callAgent(userAgent, question, { ...options });
+    }
+}
+async function callAgent(userAgent, input, options) {
+    const tracer = new TerminalTracer(userAgent.context, { verbose: options.verbose });
+    const { result, context } = await tracer.run(userAgent, options.inputKey && typeof input === "string"
+        ? { [options.inputKey]: input }
+        : createMessage(input));
+    console.log(`
+${chalk.grey(figures.tick)} 💬 ${inspect(input, { colors: true })}
+${chalk.grey(figures.tick)} 🤖 ${tracer.formatTokenUsage(context.usage)}
+${formatAIResponse(result)}
+`);
+}
+const COMMANDS = {
+    "/exit": () => ({ exit: true }),
+    "/help": () => ({
+        message: `\
+Commands:
+  /exit - exit the chat loop
+  /help - show this help message
+`,
+    }),
+};
+function formatAIResponse({ [MESSAGE_KEY]: msg, ...message } = {}) {
+    const text = msg && typeof msg === "string" ? msg : undefined;
+    const json = Object.keys(message).length > 0 ? inspect(message, { colors: true }) : undefined;
+    return [text, json].filter(Boolean).join("\n");
+}

package/dist/utils/time.d.ts

@@ -0,0 +1 @@
+export declare function parseDuration(duration: number): string;

package/dist/utils/time.js

@@ -0,0 +1,12 @@
+export function parseDuration(duration) {
+    const milliseconds = duration % 1000;
+    const seconds = Math.floor(duration / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const ms = Math.round(milliseconds / 10)
+        .toString()
+        .padStart(2, "0");
+    const s = `${Number.parseFloat(`${seconds % 60}.${ms}`)}s`;
+    if (minutes === 0)
+        return s;
+    return `${minutes}m${s}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "cli for AIGNE framework",
   "publishConfig": {
     "access": "public"
@@ -34,27 +34,31 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@aigne/listr2": "^1.0.7",
+    "@modelcontextprotocol/sdk": "^1.9.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "express": "^5.1.0",
     "gradient-string": "^3.0.0",
-    "inquirer": "^12.5.0",
-    "openai": "^4.91.1",
+    "inquirer": "^12.5.2",
+    "openai": "^4.93.0",
+    "pretty-error": "^4.0.0",
+    "tar": "^7.4.3",
     "zod": "^3.24.2",
-    "@aigne/core": "^1.6.0"
+    "@aigne/core": "^1.7.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.8",
+    "@types/archiver": "^6.0.3",
+    "@types/bun": "^1.2.9",
     "@types/express": "^5.0.1",
     "@types/gradient-string": "^1.1.6",
     "@types/node": "^22.14.0",
+    "archiver": "^7.0.1",
     "detect-port": "^2.1.0",
     "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
-    "typescript": "^5.8.2",
-    "ufo": "^1.6.0",
-    "@aigne/test-utils": "^1.0.0"
+    "typescript": "^5.8.3",
+    "ufo": "^1.6.1"
   },
   "scripts": {
     "lint": "tsc --noEmit",