|
1 | 1 | # @agent-smith/cli |
2 | 2 |
|
3 | 3 | ## Summary |
4 | | -Terminal REPL for Agent Smith. Provides a command-line interface (Commander.js) to interact with AI agents, execute workflows and actions, manage configuration, and run inference. Supports both interactive chat mode and one-shot command mode. |
| 4 | +Commander.js CLI (`lm` binary) providing an interactive REPL and one-shot command mode for executing AI agents, workflows, and actions, managing configuration, and running LLM inference with real-time streaming output. |
5 | 5 |
|
6 | 6 | ## Dependencies |
7 | | -- `@agent-smith/core` — DB operations, config, feature loading, agent/workflow/action execution. |
8 | | -- `@agent-smith/types` — shared interfaces. |
9 | | -- External: `commander` (CLI parsing), `@inquirer/prompts` (interactive prompts), `ansi-colors`, `ora` (spinners), `@vue/reactivity`. |
| 7 | +- `@agent-smith/core` — DB operations, config management, feature discovery, agent/workflow/action execution. |
| 8 | +- `@agent-smith/types` — shared TypeScript type definitions. |
| 9 | +- `@agent-smith/agent` — agent inference loop class. |
| 10 | +- External: `commander` (CLI argument parsing), `@inquirer/prompts` (interactive prompts), `ora` (terminal spinners), `ansi-colors` (styled output), `@vue/reactivity` (reactive refs), `yaml` (config parsing), `marked-terminal` (markdown rendering), `clipboardy` (clipboard I/O). |
10 | 11 |
|
11 | 12 | ## Used By |
12 | | -- End users via the `lm` CLI binary. |
13 | | -- Not imported by other packages (terminal client, not a library). |
| 13 | +- End users — terminal interaction via `lm` binary. |
| 14 | +- Plugins — feature registration (agents, workflows, actions) discovered at runtime. |
14 | 15 |
|
15 | 16 | ## Entry Point |
16 | | -- `bin/index.ts` — CLI entry: parses args, initializes state, builds commands via `buildCmds()`, routes to REPL or command mode. |
| 17 | +- `bin/index.ts` — CLI entry: parses CLI args, initializes state/DB, builds commands via `buildCmds()`, routes to REPL (`query`) or one-shot command mode (`parseCmd`). |
17 | 18 |
|
18 | 19 | ## Key Files |
19 | 20 | | File | Purpose | |
20 | 21 | |------|---------| |
21 | | -| `bin/cli.ts` | Interactive REPL query loop: prompts user, parses input as Commander args, executes commands | |
22 | | -| `bin/state.ts` | Reactive state (Vue `ref`): `runMode` (cmd/cli), `isChatMode`, chat inference params | |
23 | | -| `bin/options.ts` | CLI option definitions: display (verbose/debug), inference (model, temp, top_k, backend), IO (clipboard/file/md) | |
24 | | -| `bin/utils.ts` | Utilities: `parseCommandArgs`, `confirmToolUsage` (interactive prompt), `printToken` (styled output) | |
25 | | -| `bin/cmd/build.ts` | Command builder: assembles base commands + dynamic aliases + user commands from DB features | |
26 | | -| `bin/cmd/base.ts` | Built-in commands: exit, agents, agent, backend, conf, reset, regendb, update | |
27 | | -| `bin/cmd/aliases.ts` | Dynamic commands from DB alias definitions (agent/workflow types with inference options) | |
28 | | -| `bin/cmd/features.ts` | Feature execution: `executeWorkflowCmd`, `executeAgentCmd`, `executeTaskCmd`, `executeActionCmd` | |
| 22 | +| `bin/index.ts` | CLI entry point: arg dispatch, state init, command building, REPL/cmd routing | |
| 23 | +| `bin/cli.ts` | Interactive REPL loop: prompts user input, parses as Commander args, recurses for continuous interaction | |
| 24 | +| `bin/main.ts` | Library entry: re-exports options and utility functions for programmatic use | |
| 25 | +| `bin/state.ts` | Reactive state via Vue `ref`: `runMode` (cmd/cli), `isChatMode`, chat inference params | |
| 26 | +| `bin/options.ts` | CLI option definitions: display (verbose/debug), inference (model, temp, backend, mcp), IO (clipboard/file/output format) | |
| 27 | +| `bin/utils.ts` | Utilities: `parseCommandArgs`, `confirmToolUsage` (interactive tool approval), `printToken` (styled streaming output) | |
| 28 | +| `bin/cmd/build.ts` | Command builder: assembles base commands + DB alias commands + dynamic user command features | |
| 29 | +| `bin/cmd/base.ts` | Built-in commands: exit, agents, agent, backend, backends, conf, reset, regendb, update | |
| 30 | +| `bin/cmd/aliases.ts` | Dynamic command generation from DB aliases (agent and workflow types with inference options) | |
| 31 | +| `bin/cmd/features.ts` | Feature execution: `executeWorkflowCmd`, `executeAgentCmd`, `executeActionCmd` | |
29 | 32 | | `bin/cmd/callbacks.ts` | Inference event callbacks: token streaming, thinking spinner, tool call lifecycle UI | |
| 33 | +| `bin/cmd/cmds.ts` | Command handlers: `initUserCmds` (dynamic feature commands), `processAgentsCmd`, `processAgentCmd`, `resetDbCmd`, `recreateDbCmd` | |
30 | 34 | | `bin/cmd/read_cmds.ts` | Dynamic ESM module loader for user command files via `pathToFileURL` | |
| 35 | +| `bin/user_msgs.ts` | Runtime message helpers: `runtimeError`, `runtimeWarning`, `runtimeDataError`, `runtimeInfo` | |
31 | 36 |
|
32 | 37 | ## Architecture |
33 | | -- **Dynamic Command Building**: Commands assembled at runtime — base commands + DB aliases + feature-spec user commands. |
34 | | -- **Reactive State**: Vue `ref` tracks mode (cmd vs REPL), chat state, inference params across modules. |
35 | | -- **Hot-Reloadable Features**: Commands generated on-the-fly from DB; features can be added without restart. |
36 | | -- **Callback-Based UI**: Inference callbacks inject token streaming, thinking spinners, tool call progress into the agent executor. |
| 38 | +- **Dynamic Command Assembly**: Commands built at startup from three sources — static base commands, DB alias definitions, and feature-spec user commands (hot-reloadable). |
| 39 | +- **Reactive State Management**: Vue `ref` objects track `runMode`, `isChatMode`, and inference params across all modules without a centralized store. |
| 40 | +- **Callback-Driven UI**: Inference callbacks (`useInferenceCallbacks`) inject real-time token streaming, thinking-phase spinners, and tool call progress into the agent executor output. |
| 41 | +- **Two Execution Modes**: REPL mode (`query` loop for interactive chat) and one-shot command mode (`parseCmd` for scriptable invocations). |
37 | 42 |
|
38 | 43 | ## Related |
39 | | -- See `packages/core` — cli's execution layer delegates to core for agent/workflow/action running. |
40 | | -- See `packages/agent` — agent class provides the inference loop that cli wraps with callbacks. |
| 44 | +- See `packages/core` — cli delegates agent/workflow/action execution to core's executors. |
| 45 | +- See `packages/agent` — cli wraps the `Agent` class with inference callbacks for real-time output. |
| 46 | +- See `packages/wscli` — alternative WebSocket-based client for remote agent communication. |
0 commit comments