@agent-smith/cli 0.0.115 → 0.0.118

package/README.md

@@ -1,82 +1,322 @@
-# Agent Smith terminal client
+[![npm version](https://img.shields.io/npm/v/@agent-smith/cli)](https://www.npmjs.com/package/@agent-smith/cli)
 
-A terminal client to use language models
+# @agent-smith/cli — Terminal REPL for Agent Smith
 
-:books: Read the [documentation](https://synw.github.io/agent-smith/terminal_client/install)
+A command-line interface built with Commander.js for interacting with AI agents, executing workflows and actions, managing configuration, and running inference. Part of the [Agent Smith toolkit](https://github.com/lynxai-team/agent-smith).
 
-## Install
+## Features
 
-Install the Agent Smith terminal client globally:
+- 🚀 **Interactive REPL** — Chat mode for conversational agent interaction
+- ⚡ **One-shot Commands** — Run agents, workflows, and actions from the terminal
+- 🔧 **Dynamic Commands** — Auto-generated commands from database features (agents, actions, workflows, aliases)
+- 🎛️ **Configuration Management** — YAML-based config with SQLite backend for backends, plugins, and feature paths
+- 🌐 **Multi-Backend Support** — Llama.cpp, Koboldcpp, Ollama, OpenRouter, and any OpenAI-compatible API
+- 📋 **I/O Flexibility** — Clipboard input/output, file input, markdown output modes
+- 🔍 **Inference Control** — Fine-grained control over model parameters (temperature, top_k, top_p, min_p, etc.)
+- 🔄 **Hot-Reloadable Features** — Add agents and tools without restarting the CLI
+
+## Documentation
+
+### For AI Agents
+
+- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the CLI package
+- [Overview](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/2.overview.md) — Terminal client principles and feature types
+- [Install](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/1.install.md) — Installation and quickstart
+- [Config](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/3.config.md) — Configuration file format and backend setup
+- [Agents](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/agents/1.overview.md) — Agent YAML definitions and tool calling
+- [Tasks](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/4.tasks.md) — Running agents with variables and parameters
+- [Actions](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/6.actions.md) — Custom tool scripts (JS, Python, YAML)
+- [Workflows](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/7.workflows.md) — Chaining actions and agents in pipelines
+- [Commands](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/terminal_client/8.commands.md) — Custom terminal commands
+
+### For Humans
+
+- [Quickstart Guide](https://lynxai-team.github.io/agent-smith/terminal_client/quickstart) — Get up and running in minutes
+- [Terminal Client Overview](https://lynxai-team.github.io/agent-smith/terminal_client/overview) — Principles and feature types
+- [Installation](https://lynxai-team.github.io/agent-smith/terminal_client/install) — Install and initial configuration
+- [Configuration](https://lynxai-team.github.io/agent-smith/terminal_client/config) — Config file format, backends, and plugins
+- [Agent Definitions](https://lynxai-team.github.io/agent-smith/terminal_client/agents/overview) — Declaring agents with YAML
+- [Tasks & Variables](https://lynxai-team.github.io/agent-smith/terminal_client/tasks) — Parameterized agent execution
+- [Actions](https://lynxai-team.github.io/agent-smith/terminal_client/actions) — Writing custom tools
+- [Workflows](https://lynxai-team.github.io/agent-smith/terminal_client/workflows) — Building multi-step pipelines
+
+## Installation
 
 ```bash
 npm i -g @agent-smith/cli
 ```
 
-A global `lm` command is available once installed.
+This installs the `lm` command globally.
+
+## Quick Start
+
+### 1. Configure Your Backend
+
+Create a config file at `~/.config/agent-smith/config.yml`:
+
+```yaml
+backends:
+  default: "llamacpp"
+  llamacpp:
+    type: "openai"
+    url: "http://localhost:8080/v1"
+  openrouter:
+    type: "openai"
+    url: "https://openrouter.ai/api/v1"
+    apiKey: "$OPENROUTER_API_KEY"
+```
+
+### 2. Sync Configuration
+
+```bash
+lm conf ~/.config/agent-smith/config.yml
+```
+
+This processes the YAML config and populates the SQLite database at `~/.config/agent-smith/config.db`.
+
+### 3. Run a Quick Query
+
+```bash
+lm q list the planets of the solar system
+```
+
+With a specific model:
 
-## Quickstart
+```bash
+lm q list the planets of the solar system -m gemma4b
+```
 
-Install the inference and the vision plugin:
+### 4. Enter Interactive Chat Mode
 
 ```bash
-npm i -g @agent-smith/feat-inference @agent-smith/feat-vision
+lm
 ```
 
-Create a `config.yml` file with this content:
+Then type your queries interactively. Use `exit` to quit.
+
+## Usage
 
-```yml
-plugins:
-  - "@agent-smith/feat-inference"
-  - "@agent-smith/feat-vision"
-  - "@agent-smith/feat-models"
+### Listing Agents
+
+List all registered agents:
+
+```bash
+lm agents
 ```
 
-Run the conf command to initialize:
+View an agent definition:
 
 ```bash
-lm conf ~/path/to/config.yml
+lm agent myagent
 ```
 
-### Inference
+### Running Agents
 
-Run an inference query with the <kbd>q</kbd> command, using an Ollama model that you already have:
+Run a specific agent with a prompt:
 
 ```bash
-lm q list the planets of the solar system m="llama3.1:latest"
+lm myagent "Explain quantum computing"
 ```
 
-### Vision
+With variables (if the agent requires them):
 
-Run a vision query: pull `minicpm-v:8b-2.6-q8_0` from Ollama and run:
+```bash
+lm myagent "Analyze this code" --workspace /path/to/project
+```
+
+### Using Different Backends
+
+Change the default backend:
 
 ```bash
-lm vision imgs/img1.jpeg imgs/img2.jpeg "Compare the images"
+lm backend openrouter
 ```
 
-### Tasks
+Use a specific backend for one execution:
 
-List the available tasks:
+```bash
+lm myagent "Hello" -b llamacpp
+```
+
+List available backends:
 
 ```bash
-lm tasks
+lm backends
 ```
 
-Show a task:
+### Inference Parameters
+
+Control model behavior with command-line options:
 
 ```bash
-lm task think
+lm q "Write a poem" \
+  --model qwen4b \
+  --temperature 0.7 \
+  --top_k 20 \
+  --top_p 0.95 \
+  --max_tokens 1024
 ```
 
-### Models
+### Input/Output Modes
 
-Show available models:
+**Clipboard input:**
+```bash
+lm q "Summarize this" --clipboard-input
+```
 
+**File input:**
 ```bash
-lm models
+lm q "Analyze" --input-file
 ```
 
-Search for a model:
+**Markdown output:**
+```bash
+lm q "Generate a report" --markdown-output
+```
 
+**Clipboard output:**
 ```bash
-lm model qwen
-```
+lm q "Generate code" --clipboard-output
+```
+
+### Chat Mode for Tasks
+
+Enable chat mode for multi-turn task execution:
+
+```bash
+lm myagent "Start a project" -c
+```
+
+### Verbose and Debug Modes
+
+```bash
+lm q "Hello" --verbose    # Show detailed execution info
+lm q "Hello" --debug       # Show debug-level output
+```
+
+## Complete Example
+
+Here's a full workflow: configuring backends, creating an agent, and running it with custom parameters.
+
+### Step 1: Create Features Directory
+
+```bash
+mkdir -p ~/my-agents/features/agents
+mkdir -p ~/my-agents/features/actions
+```
+
+### Step 2: Configure Features Path
+
+Update `~/.config/agent-smith/config.yml`:
+
+```yaml
+features:
+  - ~/my-agents/features
+backends:
+  default: "llamacpp"
+  llamacpp:
+    type: "openai"
+    url: "http://localhost:8080/v1"
+```
+
+### Step 3: Create an Agent
+
+Create `~/my-agents/features/agents/shell-demo.yml`:
+
+```yaml
+name: shell-demo
+description: A demo agent with shell tool access
+prompt: |-
+    {prompt}
+model: qwen4b
+inferParams:
+  min_p: 0
+  top_k: 20
+  top_p: 0.95
+  temperature: 0.4
+toolsList:
+  - shell
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+```
+
+### Step 4: Register and Run
+
+```bash
+# Register the new agent
+lm update
+
+# Run with a prompt and variable
+lm shell-demo "List files in the current directory" --workspace /path/to/dir
+```
+
+## API Reference
+
+### CLI Entry Point
+
+The package exports utility functions for integration:
+
+```typescript
+import {
+    displayOptions,
+    ioOptions,
+    inferenceOptions,
+    allOptions,
+    parseCommandArgs
+} from "@agent-smith/cli";
+```
+
+### Options
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `displayOptions` | `Option[]` | CLI display options (`--verbose`, `--debug`) |
+| `ioOptions` | `Option[]` | I/O mode options (clipboard, file, markdown) |
+| `inferenceOptions` | `Option[]` | Inference parameter options (model, temperature, etc.) |
+| `allOptions` | `Option[]` | Combined options array |
+| `parseCommandArgs` | `Function` | Parse command-line arguments for Commander.js |
+
+### Inference Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--model <name>` | `-m` | Model name to use |
+| `--ctx` | `-x` | Context window size |
+| `--template <template>` | `--tpl` | Template to use |
+| `--max_tokens <number>` | `--mt` | Maximum tokens to generate |
+| `--top_k <number>` | `-k` | Limit results to top K |
+| `--top_p <number>` | `-p` | Cumulative probability filter |
+| `--min_p <number>` | `--mp` | Minimum token probability |
+| `--temperature <number>` | `-t` | Sampling randomness |
+| `--repeat_penalty <number>` | `-r` | Penalty for repeated tokens |
+| `--backend <name>` | `-b` | Backend to use (must be registered) |
+| `--mcp [args...]` | — | MCP server arguments |
+
+### I/O Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--input-file` | `--if` | Use promptfile input mode |
+| `--clipboard-input` | `--ic` | Use clipboard input mode |
+| `--manual-input` | `--im` | Manual input (default) |
+| `--clipboard-output` | `--oc` | Output to clipboard |
+| `--markdown-output` | `--omd` | Markdown output format |
+| `--text-output` | `--otxt` | Text output (default) |
+
+## Important Notes
+
+- **Node.js Required**: This package runs in Node.js environments only — it is not a browser library.
+- **Global Installation**: Designed for global installation via `npm i -g`. The `lm` binary is available system-wide.
+- **SQLite Database**: Configuration and features are stored in SQLite at `~/.config/agent-smith/config.db`.
+- **Dependencies**: Requires `@agent-smith/core` for feature execution and database operations.
+- **Backend Compatibility**: Supports any server with an OpenAI-compatible API (Llama.cpp, Ollama, Koboldcpp, OpenRouter, etc.).
+- **Related Packages**: 
+  - `@agent-smith/core` — Runtime engine for feature execution
+  - `@agent-smith/agent` — Agent inference loop
+  - `@agent-smith/wscli` — WebSocket client for server communication
+
+## License
+
+MIT

package/dist/cli.js

@@ -1,18 +1,14 @@
 import { input } from '@inquirer/prompts';
-import { chat } from './cmd/cmds.js';
-import { isChatMode } from './state/state.js';
-import { Agent } from '@agent-smith/agent';
-import { backend } from './state/backends.js';
 async function query(program) {
     const data = { message: "$", default: "" };
     const q = await input(data);
     //console.log("QUERY", q);
     const args = q.split(" ");
     await program.parseAsync(args, { from: "user" });
-    if (isChatMode.value) {
-        const agent = new Agent(backend.value, "chat");
-        await chat(program, {}, agent, []);
-    }
+    /*if (isChatMode.value) {
+        const agent = new Agent({ lm: state.backend.value!, name: "chat" })
+        await chat({}, agent, [])
+    }*/
     await query(program);
 }
 export { query };

package/dist/cmd/{clicmds/aliases.d.ts → aliases.d.ts}

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { AliasType, FeatureSpec, FeatureType } from "../../interfaces.js";
+import type { AliasType, FeatureSpec, FeatureType } from "@agent-smith/types";
 declare function initCommandsFromAliases(program: Command, aliases: {
     name: string;
     type: AliasType;

package/dist/cmd/{clicmds/aliases.js → aliases.js}

@@ -1,7 +1,5 @@
 import { allOptions } from "../options.js";
-import { executeTaskCmd } from "../lib/tasks/cmd.js";
-import { executeWorkflowCmd } from "../lib/workflows/cmd.js";
-import { executeAgentCmd } from "../lib/agents/cmd.js";
+import { executeWorkflowCmd, executeAgentCmd } from "./features.js";
 function initCommandsFromAliases(program, aliases, features) {
     aliases.forEach((alias) => {
         //console.log("A", alias)
@@ -29,29 +27,6 @@ function initCommandsFromAliases(program, aliases, features) {
                     }
                 }
                 break;
-            case "task":
-                const tcmd = program.command(`${alias.name} [prompt_and_vars...]`)
-                    .description("task: " + alias.name)
-                    .action(async (...args) => {
-                    await executeTaskCmd(alias.name, args);
-                });
-                allOptions.forEach(o => tcmd.addOption(o));
-                //console.log("TVARS", alias.name, features.task[alias.name]?.variables)
-                if (features.task[alias.name]?.variables) {
-                    const rtv = features.task[alias.name].variables?.required;
-                    if (rtv) {
-                        for (const name of Object.keys(rtv)) {
-                            tcmd.option(`--${name} <value>`);
-                        }
-                    }
-                    const otv = features.task[alias.name].variables?.optional;
-                    if (otv) {
-                        for (const name of Object.keys(otv)) {
-                            tcmd.option(`--${name} <value>`);
-                        }
-                    }
-                }
-                break;
             /*case "action":
                 const acmd = program.command(`${alias.name} [args...]`)
                     .description("action: " + alias.name)

package/dist/cmd/{clicmds/base.js → base.js}

@@ -1,8 +1,7 @@
 import { Option } from "commander";
-import { listBackends, setBackend } from "../../state/backends.js";
-import { parseCommandArgs } from "../lib/options_parsers.js";
-import { processTaskCmd, processTasksCmd, resetDbCmd } from "./cmds.js";
-import { updateConfCmd, updateFeaturesCmd } from "./updateconf.js";
+import { conf, state } from "@agent-smith/core";
+import { parseCommandArgs } from "../utils.js";
+import { processAgentCmd, processAgentsCmd, recreateDbCmd, resetDbCmd } from "./cmds.js";
 import { displayOptions, inferenceOptions } from "../options.js";
 function initBaseCommands(program) {
     /*program.command("ping")
@@ -11,50 +10,55 @@ function initBaseCommands(program) {
     program.command("exit")
         .description("exit the cli")
         .action(() => process.exit(0));
-    const tasksCmd = program.command("tasks")
-        .description("list all the tasks")
+    const agentsCmd = program.command("agents")
+        .description("list all the agents")
         .action(async (...args) => {
         const ca = parseCommandArgs(args);
-        await processTasksCmd(ca.args, ca.options);
+        await processAgentsCmd(ca.args, ca.options);
     });
-    tasksCmd.addOption(new Option("-c, --conf", "output the tasks config"));
-    const taskCmd = program.command("task <task>")
-        .description("read a task")
+    agentsCmd.addOption(new Option("-c, --conf", "output the agents config"));
+    const agentCmd = program.command("agent <agent>")
+        .description("view an agent")
         .action(async (...args) => {
         const ca = parseCommandArgs(args);
-        await processTaskCmd(ca.args, ca.options);
+        await processAgentCmd(ca.args, ca.options);
     });
-    inferenceOptions.forEach(o => taskCmd.addOption(o));
-    taskCmd.addOption(new Option("--reset", "reset the task config to the original"));
+    inferenceOptions.forEach(o => agentCmd.addOption(o));
+    agentCmd.addOption(new Option("--reset", "reset the task config to the original"));
     program.command("backend <name>")
         .description("set the default backend")
         .action(async (...args) => {
         const ca = parseCommandArgs(args);
-        await setBackend(ca.args[0]);
+        await state.setBackend(ca.args[0]);
     });
     program.command("backends")
         .description("list the available backends")
         .action(async (...args) => {
-        await listBackends();
+        await state.listBackends();
     });
     const updateCmd = program.command("update")
         .description("update the available features: run this after adding a new feature")
         .action(async (...args) => {
         const ca = parseCommandArgs(args);
-        await updateFeaturesCmd(ca.options);
+        await conf.updateFeaturesCmd(ca.options);
     });
     displayOptions.forEach(o => updateCmd.addOption(o));
     program.command("conf <path>")
         .description("process config file")
         .action(async (...args) => {
         const ca = parseCommandArgs(args);
-        await updateConfCmd(ca.args);
+        await conf.updateConfCmd(ca.args);
     });
     program.command("reset")
         .description("reset the config database")
         .action(async (...args) => {
         await resetDbCmd();
     });
+    program.command("regendb")
+        .description("regenerate the database from the current registered config file")
+        .action(async (...args) => {
+        await recreateDbCmd();
+    });
     return program;
 }
 export { initBaseCommands };

package/dist/cmd/build.d.ts

@@ -0,0 +1,9 @@
+import type { AgentInferenceOptions } from "@agent-smith/types";
+import { Command } from "commander";
+import { type McpClient } from "@agent-smith/core";
+import type { Agent } from "@agent-smith/agent";
+declare const program: Command;
+declare function chat(options: AgentInferenceOptions, agent: Agent, mcpServers: Array<McpClient>): Promise<void>;
+declare function buildCmds(): Promise<Command>;
+declare function parseCmd(program: Command): Promise<void>;
+export { buildCmds, chat, parseCmd, program };

package/dist/cmd/build.js

@@ -0,0 +1,59 @@
+import { input } from "@inquirer/prompts";
+import { Command } from "commander";
+import { query } from "../cli.js";
+import { db } from "@agent-smith/core";
+import { isChatMode, runMode, chatInferenceParams } from "../state.js";
+import { initBaseCommands } from "./base.js";
+import { initCommandsFromAliases } from "./aliases.js";
+import { initUserCmds } from "./cmds.js";
+const program = new Command();
+async function chat(options, agent, mcpServers) {
+    //console.log("CHAT AGENT", agent);
+    const data = { message: '>', default: "" };
+    const prompt = await input(data);
+    if (prompt == "/q") {
+        isChatMode.value = false;
+        if (runMode.value == "cmd") {
+            process.exit(0);
+        }
+        else {
+            mcpServers.forEach(async (s) => await s.stop());
+            await query(program);
+        }
+    }
+    //console.log("CHAT HIST", agent.history);
+    //options.history = undefined;
+    //console.log("RUN W PROMPT", prompt);
+    options.params = chatInferenceParams;
+    await agent.run(prompt, options);
+    console.log();
+    await chat(options, agent, mcpServers);
+}
+async function buildCmds() {
+    //program.allowUnknownOption(true);
+    //const perf = usePerfTimer();
+    initBaseCommands(program);
+    //perf.measure("initBaseCommands");
+    const aliases = db.readAliases();
+    //perf.measure("readAliases");
+    const feats = db.readFeatures();
+    //perf.measure("readFeatures");
+    initCommandsFromAliases(program, aliases, feats);
+    //perf.measure("initCommandsFromAliases");
+    await initUserCmds(feats.cmd, program);
+    //perf.measure("initUserCmds");
+    //perf.measure("cmds for each");
+    //perf.final("buildCmds");
+    return program;
+}
+async function parseCmd(program) {
+    program.name('Agent Smith terminal client');
+    program.description('Terminal agents toolkit');
+    await program.parseAsync();
+    //console.log("CMD END");
+    //exit(0)
+    /*if (isChatMode.value) {
+        await chat(program)
+    }*/
+}
+export { buildCmds, chat, parseCmd, program };

package/dist/cmd/callbacks.d.ts

@@ -0,0 +1,11 @@
+import type { AgentInferenceOptions, ToolCallSpec } from "@agent-smith/types";
+declare const useInferenceCallbacks: (agentName: string, options: AgentInferenceOptions) => {
+    onToken: (t: string, from: string) => void;
+    onStartThinking: (from: string) => void;
+    onEndThinking: (from: string) => void;
+    onThinkingToken: (t: string, from: string) => void;
+    onToolCallInProgress: (tc: Array<ToolCallSpec>, from: string) => void;
+    onToolCall: (tc: ToolCallSpec, type: string, from: string) => void;
+    onToolCallEnd: (tc: ToolCallSpec, tr: any, type: string, from: string) => void;
+};
+export { useInferenceCallbacks, };