@agent-smith/server 0.0.8 → 0.0.9

package/README.md

@@ -0,0 +1,349 @@
+# @agent-smith/server
+
+A Koa v3 backend server that exposes the Agent Smith runtime via REST API (`/api/*`) and WebSocket (`/ws`), enabling remote AI agent execution with real-time token streaming. Part of the [Agent Smith toolkit](https://github.com/lynxai-team/agent-smith).
+
+## Features
+
+- 🌐 **REST API** — Full CRUD for agents, workflows, backends, models, settings, and configurations
+- 🔌 **WebSocket Execution** — Real-time bidirectional communication for agent inference with streaming tokens
+- ⚒️ **Tool Call Confirmation** — Async confirmation pattern for user-approved tool executions
+- 📡 **Streaming Events** — Token, thinking, tool call, and turn events streamed over WebSocket
+- 🔧 **Plugin Support** — Install npm plugins and add feature search folders via API
+- 🏗️ **Programmatic API** — Use `runServer()` to embed the server in your own applications
+- 🌍 **CORS Enabled** — Cross-origin requests supported with credentials
+
+## Documentation
+
+### For AI Agents
+
+- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the server package
+- [API Reference](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/server/2.api.md) — Complete REST endpoints and WebSocket protocol
+- [Client Usage](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/server/3.client-usage.md) — Integration patterns with wscli and HTTP clients
+- [Deployment](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/server/4.deployment.md) — Production deployment considerations
+
+### For Humans
+
+- [Get Started](https://lynxai-team.github.io/agent-smith/server/get-started) — Installation and basic usage
+- [API Reference](https://lynxai-team.github.io/agent-smith/server/api) — Complete REST endpoints and WebSocket protocol
+- [Client Usage](https://lynxai-team.github.io/agent-smith/server/client-usage) — Integration patterns with wscli and HTTP clients
+- [Deployment](https://lynxai-team.github.io/agent-smith/server/deployment) — Production deployment considerations
+
+## Installation
+
+```bash
+npm install @agent-smith/server
+```
+
+Or build from source:
+
+```bash
+cd agent-smith/server
+npm install
+npm run build
+```
+
+## Quick Start
+
+### Running the Server
+
+```bash
+# Development mode with hot-reload
+npm run devserver
+
+# Production mode
+npm run server
+```
+
+The server listens on port **5184** by default. Verify it's running:
+
+```bash
+curl http://localhost:5184/ping
+# Response: { "ok": true }
+```
+
+### Executing an Agent via WebSocket
+
+```typescript
+import { useWsServer } from "@agent-smith/wscli";
+
+const ws = useWsServer({
+    url: "ws://localhost:5184/ws",
+    onToken: (token) => process.stdout.write(token),
+});
+
+ws.executeAgent("my-agent", { prompt: "Hello, world!" });
+```
+
+## Usage
+
+### Programmatic Server Startup
+
+Use `runServer()` to embed the server in your application:
+
+```typescript
+import { runServer } from "@agent-smith/server";
+
+// Start with default routes and no static directory
+runServer();
+
+// Or with custom routes and static file serving
+runServer(
+    undefined,           // Custom route functions (optional)
+    "/path/to/static"   // Static file directory (optional)
+);
+```
+
+### REST API Examples
+
+```typescript
+// List all agents
+const agentsRes = await fetch("http://localhost:5184/api/agents");
+const agents = await agentsRes.json();
+
+// Get a specific agent
+const agentRes = await fetch("http://localhost:5184/api/agent/my-agent");
+const agent = await agentRes.json();
+
+// List inference backends
+const backendsRes = await fetch("http://localhost:5184/api/backends");
+const backends = await backendsRes.json();
+
+// Get available models for a backend
+const modelsRes = await fetch("http://localhost:5184/api/models/openai");
+const models = await modelsRes.json();
+
+// Update agent settings
+const settingsRes = await fetch("http://localhost:5184/api/agentSettings", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "my-agent", settings: { temperature: 0.5 } }),
+});
+```
+
+### WebSocket Agent Execution
+
+Connect directly to the WebSocket endpoint for real-time streaming:
+
+```typescript
+const ws = new WebSocket('ws://localhost:5184/ws');
+
+ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data);
+    switch (msg.type) {
+        case 'token':
+            process.stdout.write(msg.msg);
+            break;
+        case 'thinkingtoken':
+            console.log(`\x1b[2m${msg.msg}\x1b[0m`);
+            break;
+        case 'toolcall':
+            const payload = JSON.parse(msg.msg);
+            console.log(`Tool call: ${payload.tc.name}`);
+            break;
+        case 'endemit':
+            const result = JSON.parse(msg.msg);
+            console.log('\nDone:', result);
+            ws.close();
+            break;
+        case 'error':
+            console.error('Error:', msg.msg);
+            ws.close();
+            break;
+    }
+};
+
+ws.onopen = () => {
+    ws.send(JSON.stringify({
+        type: "command",
+        command: "my-agent",
+        feature: "agent",
+        payload: { prompt: "Write a poem" },
+        options: {}
+    }));
+};
+```
+
+### System Commands (Stop & Confirm)
+
+```typescript
+// Stop current execution
+ws.send(JSON.stringify({
+    type: "system",
+    command: "stop"
+}));
+
+// Confirm or reject a tool call
+ws.send(JSON.stringify({
+    type: "system",
+    command: "confirmtool",
+    payload: { confirm: true, id: "tool-call-uuid" }
+}));
+```
+
+### Full Callback Example with wscli
+
+```typescript
+import { useWsServer } from "@agent-smith/wscli";
+import type { ToolCallSpec } from "@agent-smith/types";
+
+const ws = useWsServer({
+    url: "ws://localhost:5184/ws",
+    onToken: (token, from) => process.stdout.write(token),
+    onThinkingToken: (token, from) => console.log(`\x1b[2m${token}\x1b[0m`),
+    onToolCall: (tc, type, from) => {
+        console.log(`\n⚒️ Tool: ${tc.name}`);
+    },
+    onToolCallEnd: (tc, content, type, from) => {
+        console.log(`  Result: ${content?.slice(0, 100)}`);
+    },
+    onConfirmToolUsage: async (tool: ToolCallSpec) => {
+        return true; // Return false to deny
+    },
+    onEndEmit: (result, from) => {
+        console.log(`\nInference complete. Tokens: ${result.stats?.totalTokens}`);
+    },
+    onError: (msg, from) => {
+        console.error(`[${from}] ${msg}`);
+    },
+});
+
+ws.executeAgent("code-review", { prompt: "Review this function" });
+```
+
+## Complete Example
+
+```typescript
+import { useWsServer } from "@agent-smith/wscli";
+
+async function runAgent() {
+    const tokenStream: string[] = [];
+
+    const ws = useWsServer({
+        url: "ws://localhost:5184/ws",
+        onToken: (token) => tokenStream.push(token),
+        onThinkingToken: (token) => console.log(`[thinking] ${token}`),
+        onError: (msg) => console.error(`Error: ${msg}`),
+    });
+
+    try {
+        await ws.executeAgent("summarize", {
+            prompt: "Summarize the key points of quantum computing"
+        });
+
+        const fullText = tokenStream.join("");
+        console.log("\nFull response:", fullText);
+    } catch (err) {
+        console.error("Execution failed:", err);
+    } finally {
+        ws.close();
+    }
+}
+
+runAgent();
+```
+
+## API Reference
+
+### Factory Function: `runServer()`
+
+```typescript
+function runServer(
+    routes?: ((r: Router) => void)[],
+    staticDir?: string
+): void;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `routes` | `(r: Router) => void[]` | Optional custom route functions to compose with base routes |
+| `staticDir` | `string` | Optional directory path for static file serving |
+
+### REST Endpoints
+
+All REST routes are prefixed with `/api`.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/ping` | Health check — returns `{ ok: true }` |
+| `GET` | `/api/agents` | List all agents |
+| `GET` | `/api/agent/:id` | Get agent spec by ID |
+| `GET` | `/api/workflows` | List all workflows |
+| `GET` | `/api/workflow/:id` | Get workflow spec by ID |
+| `GET` | `/api/backends` | List inference backends |
+| `GET` | `/api/backend/:name` | Set default backend |
+| `POST` | `/api/tools` | Get tool definitions for tool names |
+| `GET` | `/api/models/:backend` | List models for a backend |
+| `GET` | `/api/models/presets/read` | List model sampling presets |
+| `POST` | `/api/models/preset/update` | Create or update a preset |
+| `DELETE` | `/api/models/preset/delete/:name` | Delete a preset |
+| `GET` | `/api/agentsettings` | Get per-agent inference config |
+| `POST` | `/api/agentsettings/update` | Update agent settings |
+| `GET` | `/api/state` | Get server state |
+| `GET` | `/api/conf` | Get current configuration |
+| `GET` | `/api/conf/create` | Create config file if missing |
+| `POST` | `/api/plugins/install` | Install npm plugins |
+| `POST` | `/api/folders/add` | Add feature search folders |
+| `GET` | `/api/app/:name/conf` | Get app config |
+| `POST` | `/api/app/:name/update` | Update app config |
+| `GET` | `/api/workspace` | Get workspace info |
+| `POST` | `/api/workspace` | Create or update workspace |
+| `POST` | `/api/workspace/update` | Set default workspace |
+| `GET` | `/api/settings` | Get application settings |
+
+### WebSocket Protocol
+
+**Endpoint:** `ws://localhost:5184/ws`
+
+#### Client Messages (`WsClientMsg`)
+
+```typescript
+interface WsClientMsg {
+    command: string;           // Agent or workflow name
+    type: 'command' | 'system';
+    feature?: 'agent' | 'workflow';
+    payload?: any;             // Prompt and execution context
+    options?: Record<string, any>;  // Abort controller, variables, etc.
+}
+```
+
+#### Server Messages (`WsRawServerMsg`)
+
+```typescript
+interface WsRawServerMsg {
+    type: string;
+    from: string;
+    msg: string;
+}
+```
+
+| Type | Description |
+|------|-------------|
+| `error` | Error message |
+| `startemit` | Inference started |
+| `token` | Generated token |
+| `thinkingtoken` | Thinking/reasoning token |
+| `turnstart` | New conversation turn |
+| `turnend` | Turn completed |
+| `assistant` | Assistant text output |
+| `think` | Model thinking content |
+| `toolcall` | Tool call initiated |
+| `toolcallend` | Tool call completed |
+| `toolcallconfirm` | Awaiting tool confirmation |
+| `finalresult` | Final inference result |
+| `endemit` | Inference complete |
+
+## Important Notes
+
+- **Port**: The server listens on port **5184** by default. Change it in `src/server/server.ts` or use a reverse proxy.
+- **Authentication**: No built-in authentication — intended for local use. Deploy behind a reverse proxy for production.
+- **CORS**: Enabled with credentials by default. Restrict origins in production deployments.
+- **Static Files**: Served from project root when `NODE_ENV` is not `"development"`.
+- **Dependencies**: Requires `@agent-smith/core` and `@agent-smith/types` packages.
+- **Related Packages**:
+  - [`@agent-smith/wscli`](https://www.npmjs.com/package/@agent-smith/wscli) — WebSocket client for the server
+  - [`@agent-smith/core`](https://www.npmjs.com/package/@agent-smith/core) — Runtime engine (DB, features, execution)
+  - [`@agent-smith/types`](https://www.npmjs.com/package/@agent-smith/types) — Shared interfaces
+
+## License
+
+MIT

package/dist/callbacks.d.ts

@@ -0,0 +1,4 @@
+import type { WsClientMsg } from "@agent-smith/types";
+import type { Context } from "koa";
+declare function buildCallbacks(msg: WsClientMsg, ctx: Context, confirmToolCalls: Record<string, (value: boolean) => void>): void;
+export { buildCallbacks, };

package/dist/callbacks.js

@@ -0,0 +1,182 @@
+import { default as color } from "ansi-colors";
+import { createAwaiter } from "./utils.js";
+function buildCallbacks(msg, ctx, confirmToolCalls) {
+    if (!msg?.options) {
+        msg.options = {};
+    }
+    msg.options.onStartEmit = (p, from) => {
+        const rsm = {
+            type: "startemit",
+            from: from,
+            msg: JSON.stringify(p),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onThinkingToken = (t, from) => {
+        const rsm = {
+            type: "thinkingtoken",
+            from: from,
+            msg: t,
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+        process.stdout.write(`\x1b[2m${t}\x1b[0m`);
+    };
+    msg.options.onToken = (t, from) => {
+        const rsm2 = {
+            type: "token",
+            from: from,
+            msg: t,
+        };
+        ctx.websocket.send(JSON.stringify(rsm2));
+        process.stdout.write(t);
+    };
+    msg.options.onStartThinking = (from) => {
+        const rsm = {
+            type: "thinkingstart",
+            from: from,
+            msg: "",
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onEndThinking = (from) => {
+        const rsm = {
+            type: "thinkingend",
+            from: from,
+            msg: "",
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onTurnStart = (from) => {
+        const rsm = {
+            type: "turnstart",
+            from: from,
+            msg: "",
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onTurnEnd = (ht, from) => {
+        const rsm = {
+            type: "turnend",
+            from: from,
+            msg: JSON.stringify(ht),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onAssistant = (txt, from) => {
+        const rsm = {
+            type: "assistant",
+            from: from,
+            msg: txt,
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onThink = (txt, from) => {
+        const rsm = {
+            type: "think",
+            from: from,
+            msg: txt,
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onEndEmit = (res, from) => {
+        const rsm = {
+            type: "endemit",
+            from: from,
+            msg: JSON.stringify(res),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onToolCallToken = (t, from) => {
+        const rsm = {
+            type: "toolcalltoken",
+            from: from,
+            msg: JSON.stringify(t),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onToolCallInProgress = (tcs, from) => {
+        const rsm = {
+            type: "toolcallinprogress",
+            from: from,
+            msg: JSON.stringify(tcs),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onPromptProcessingProgress = (progress, from) => {
+        const rsm = {
+            type: "promptprocessingprogress",
+            from: from,
+            msg: JSON.stringify(progress),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onToolsTurnStart = (tcs, from) => {
+        const rsm = {
+            type: "toolsturnstart",
+            from: from,
+            msg: JSON.stringify(tcs),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onToolsTurnEnd = (tr, from) => {
+        const rsm = {
+            type: "toolsturnend",
+            from: from,
+            msg: JSON.stringify(tr),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.onToolCall = (tc, type, from) => {
+        if (!tc?.id) {
+            tc.id = crypto.randomUUID();
+        }
+        const payload = { tc: tc, type: type, from: from };
+        const rsm = {
+            type: "toolcall",
+            from: from,
+            msg: JSON.stringify(payload),
+        };
+        ctx.websocket.send(JSON.stringify(rsm));
+        console.log("\n⚒️ ", color.bold(msg.command), "=>", `${color.yellowBright(tc.name)}`, tc.arguments);
+    };
+    msg.options.onToolCallEnd = (tc, tr, type, from) => {
+        let toolResData;
+        if (typeof tr == 'object') {
+            tr.type = type;
+            if (tr?.text) {
+                // comes from an inference task
+                toolResData = tr.text;
+            }
+            else {
+                toolResData = JSON.stringify(tr);
+            }
+        }
+        else {
+            toolResData = tr.toString();
+        }
+        const payload = { tc: tc, type: type, from: from };
+        const rsm = {
+            type: "toolcallend",
+            from: from,
+            msg: `${JSON.stringify(payload)}<|xtool_call_id|>` + toolResData,
+        };
+        //console.log("TOOL CALL END", toolResData);
+        ctx.websocket.send(JSON.stringify(rsm));
+    };
+    msg.options.confirmToolUsage = async (tc, from) => {
+        if (!tc?.id) {
+            tc.id = crypto.randomUUID();
+        }
+        const rsm = {
+            type: "toolcallconfirm",
+            from: from,
+            msg: JSON.stringify(tc),
+        };
+        const { promise, resolve } = createAwaiter();
+        confirmToolCalls[tc.id] = resolve;
+        ctx.websocket.send(JSON.stringify(rsm));
+        const res = await promise;
+        return res;
+    };
+}
+export { buildCallbacks, };

package/dist/routes/agent_settings.d.ts

@@ -0,0 +1,4 @@
+import type Router from '@koa/router';
+declare function getAgentSettingsCmd(r: Router): void;
+declare function updateAgentSettingsCmd(r: Router): void;
+export { getAgentSettingsCmd, updateAgentSettingsCmd, };

package/dist/routes/agent_settings.js

@@ -0,0 +1,20 @@
+import { db, state } from '@agent-smith/core';
+function getAgentSettingsCmd(r) {
+    r.get('/agentsettings', async (ctx, next) => {
+        const ts = state.getAgentSettings(true);
+        ctx.body = ts;
+        ctx.status = 200;
+    });
+}
+function updateAgentSettingsCmd(r) {
+    r.post('/agentsettings/update', async (ctx, next) => {
+        const data = ctx.request.body;
+        //console.log("DATA", data);
+        const name = data.name;
+        const settings = data.settings;
+        const ts = db.upsertAgentSettings(name, settings);
+        ctx.body = ts;
+        ctx.status = 200;
+    });
+}
+export { getAgentSettingsCmd, updateAgentSettingsCmd, };

package/dist/routes/agents.js

@@ -1,8 +1,20 @@
-import { db, fs } from '@agent-smith/cli';
+import { db, fs } from '@agent-smith/core';
+import { excludedTaskTypes } from '../utils.js';
 function getAgentsRoute(r) {
     r.get('/agents', async (ctx, next) => {
         const agents = db.readFeaturesType("agent");
-        ctx.body = agents;
+        let ag = {};
+        for (const [name, feat] of Object.entries(agents)) {
+            if (feat?.type) {
+                if (!excludedTaskTypes.includes(feat.type)) {
+                    ag[name] = feat;
+                }
+            }
+            else {
+                ag[name] = feat;
+            }
+        }
+        ctx.body = ag;
         ctx.status = 200;
         //console.log("AGENTS", ctx.status);
         //await next()
@@ -11,8 +23,16 @@ function getAgentsRoute(r) {
 function getAgentRoute(r) {
     r.get('/agent/:id', async (ctx, next) => {
         //console.log(ctx.params.id)
-        const taskSpec = fs.openTaskSpec(ctx.params.id, true);
-        ctx.body = taskSpec.taskFileSpec;
+        let spec;
+        try {
+            spec = fs.openAgentSpec(ctx.params.id);
+        }
+        catch (e) {
+            ctx.body = `error reading the agent spec file ${ctx.params.id}`;
+            ctx.status = 500;
+            return;
+        }
+        ctx.body = spec.agentSpec;
         ctx.status = 200;
         //await next()
     });

package/dist/routes/apps.js

@@ -1,9 +1,9 @@
-import { getConfigPath } from "@agent-smith/cli";
+import { conf } from "@agent-smith/core";
 import fs, { existsSync } from "node:fs";
 import path from "node:path";
 import yaml from "yaml";
 function getOrCreateAppConfigFile(appName) {
-    const { confDir } = getConfigPath("agent-smith/" + appName, "config.db");
+    const { confDir } = conf.getConfigPath("agent-smith/" + appName, "config.db");
     if (!fs.existsSync(confDir)) {
         fs.mkdirSync(confDir);
     }
@@ -19,7 +19,7 @@ function getOrCreateAppConfigFile(appName) {
     }
 }
 function updateAppConfigFile(appName, content) {
-    const { confDir } = getConfigPath("agent-smith/" + appName, "config.db");
+    const { confDir } = conf.getConfigPath("agent-smith/" + appName, "config.db");
     const fp = path.join(confDir, "config.yml");
     const txt = yaml.stringify(content);
     fs.writeFileSync(fp, txt, { encoding: "utf-8" });

package/dist/routes/backends.js

@@ -1,4 +1,4 @@
-import { db, setBackend } from '@agent-smith/cli';
+import { db, state } from '@agent-smith/core';
 function getBackendsRoute(r) {
     r.get('/backends', async (ctx, next) => {
         const backends = db.readBackends();
@@ -10,7 +10,7 @@ function setBackendRoute(r) {
     r.get('/backend/:name', async (ctx, next) => {
         const name = ctx.params.name;
         console.log("Loading backend", name);
-        const ok = await setBackend(name, true);
+        const ok = await state.setBackend(name, true);
         if (!ok) {
             ctx.status = 400;
             ctx.body = "backend not found";

package/dist/routes/conf.js

@@ -1,4 +1,4 @@
-import { createConfigFile, updateConfCmd } from '@agent-smith/cli';
+import { conf } from '@agent-smith/core';
 import { getConfig } from '../utils.js';
 function getConfRoute(r) {
     r.get('/conf', async (ctx, next) => {
@@ -17,7 +17,7 @@ function createConfRoute(r) {
     r.get('/conf/create', async (ctx, next) => {
         let cfp = null;
         try {
-            cfp = createConfigFile(undefined, ["llamacpp"]);
+            cfp = conf.createConfigFileIfNotExists();
         }
         catch (e) {
             console.error("500", e);
@@ -27,7 +27,7 @@ function createConfRoute(r) {
         if (cfp) {
             ctx.body = cfp;
             ctx.status = 201;
-            await updateConfCmd([cfp]);
+            await conf.updateConfCmd([cfp]);
         }
     });
 }

package/dist/routes/folders.js

@@ -1,9 +1,8 @@
-import { updateConfCmd, updateConfigFile, init } from '@agent-smith/cli';
+import { conf as c } from '@agent-smith/core';
 import { getConfig } from '../utils.js';
 function addFolderRoute(r) {
     r.post('/folders/add', async (ctx, next) => {
         const payload = ctx.request.body;
-        await init();
         const { found, conf, path } = getConfig();
         if (!found) {
             throw new Error("no config file found");
@@ -18,9 +17,9 @@ function addFolderRoute(r) {
         ;
         console.log("Updating config file at", path);
         console.dir(conf, { depth: 3 });
-        updateConfigFile(conf, path);
+        c.updateConfigFile(conf, path);
         console.log("Updating db features from config file");
-        await updateConfCmd([path]);
+        await c.updateConfCmd([path]);
         ctx.status = 202;
     });
 }