@agent-smith/core 0.0.1

package/dist/features/actions/read-feature.js

@@ -0,0 +1,25 @@
+/*
+# tool
+name: read-feature
+description: read a feature and get it's content
+arguments:
+    name:
+        description: the feature name
+        required: true
+    type:
+        description: 'the feature type: agent, workflow, action, adaptater or skill'
+        required: true
+*/
+import { getFeatureSpec } from "../../main.js";
+import { readFile } from "../../utils/sys/read.js";
+async function action(args, options) {
+    //console.log("NA", args);
+    //console.log("NO", options);
+    const { found, path } = getFeatureSpec(args.name, args.type);
+    if (!found) {
+        return `feature ${args.name} of type ${args.type} not found`;
+    }
+    const content = readFile(path);
+    return JSON.stringify(content);
+}
+export { action, };

package/dist/features/actions/run-agent.d.ts

@@ -0,0 +1,2 @@
+declare function action(args: Record<string, any>, options: Record<string, any>): Promise<string>;
+export { action, };

package/dist/features/actions/run-agent.js

@@ -0,0 +1,34 @@
+/*
+# tool
+name: run-agent
+description: use an agent in an independant context to accomplish a task
+arguments:
+    name:
+        description: the name of the agent to use
+        required: true
+    prompt:
+        description: the prompt for the agent
+        required: true
+*/
+import { useAgentExecutor } from "../../agents/useagent.js";
+async function action(args, options) {
+    //console.log("RA ARGS", args);
+    console.log("RA OPTS", options);
+    const errb = new Array();
+    if (!args?.name) {
+        errb.push(`loading agent: provide an agent name`);
+    }
+    if (!args?.prompt) {
+        errb.push(`loading agent: provide an prompt for the agent`);
+    }
+    if (errb.length > 0) {
+        throw new Error(errb.join(" "));
+    }
+    const aOpts = { ...options };
+    aOpts.history = [];
+    const ax = await useAgentExecutor(args.name, { prompt: args.prompt }, aOpts);
+    const res = await ax.execute();
+    //console.log("AH", ax.agent.history);
+    return res.text;
+}
+export { action, };

package/dist/features/actions/run-collaborator.d.ts

@@ -0,0 +1 @@
+export function action(args: any, options: any): Promise<string>;

package/dist/features/actions/run-collaborator.js

@@ -0,0 +1,42 @@
+/*
+# tool
+name: run-collaborator
+description: use an collaborator in context to accomplish a task
+agentType: worker
+parallelCalls: false
+arguments:
+    role:
+        description: the role of the collaborator to use
+        required: true
+    prompt:
+        description: the prompt for the collaborator
+        required: true
+*/
+import { useAgentExecutor } from "../../agents/useagent.js";
+async function action(args, options) {
+    //console.log("RC OPTS IN", options);
+    const errb = new Array();
+    if (!args?.prompt) {
+        errb.push(`loading collaborator: provide an collaborator prompt`);
+    }
+    if (!args?.role) {
+        errb.push(`loading collaborator: provide an role for the collaborator`);
+    }
+    if (errb.length > 0) {
+        throw new Error(errb.join(" "));
+    }
+    const aOpts = { ...options };
+    if (!aOpts?.system) {
+        console.warn(`loading collaborator ${args.name}: no system in opts`);
+    }
+    if (aOpts.caller == "collaborator") {
+        return "you can not run collaborators while beeing in collaborator mode already. Answer directly.";
+    }
+    //console.log("Run collab **********************", aOpts.caller, args.role);
+    //console.log("RC OPTS OUT", aOpts.caller, aOpts);
+    const ax = await useAgentExecutor("collaborator", args, aOpts);
+    const res = await ax.execute();
+    //console.log("AH", ax.agent.history);
+    return res.text;
+}
+export { action, };

package/dist/features/actions/run-worker.d.ts

@@ -0,0 +1,2 @@
+declare function action(args: Record<string, any>, options: Record<string, any>): Promise<string>;
+export { action, };

package/dist/features/actions/run-worker.js

@@ -0,0 +1,34 @@
+/*
+# tool
+name: run-worker
+description: use an worker in context to accomplish a task
+type: worker
+arguments:
+    name:
+        description: the name of the worker to use
+        required: true
+    prompt:
+        description: the prompt for the worker
+        required: true
+*/
+import { useAgentExecutor } from "../../agents/useagent.js";
+async function action(args, options) {
+    //console.log("RW ARGS", args);
+    console.log("RW OPTS", options);
+    const errb = new Array();
+    if (!args?.name) {
+        errb.push(`loading worker: provide an worker name`);
+    }
+    if (!args?.prompt) {
+        errb.push(`loading worker: provide an prompt for the worker`);
+    }
+    if (errb.length > 0) {
+        throw new Error(errb.join(" "));
+    }
+    const aOpts = { ...options };
+    const ax = await useAgentExecutor(args.name, { prompt: args.prompt }, aOpts);
+    const res = await ax.execute();
+    //console.log("AH", ax.agent.history);
+    return res.text;
+}
+export { action, };

package/dist/features/adaptaters/agent-smith-db-getschema.d.ts

@@ -0,0 +1,4 @@
+declare function action(args: Record<string, any>, options: Record<string, any>): Promise<{
+    prompt: any;
+}>;
+export { action, };

package/dist/features/adaptaters/agent-smith-db-getschema.js

@@ -0,0 +1,62 @@
+import { dbPath } from "../../conf.js";
+// @ts-ignore
+import DatabaseConstructor from "better-sqlite3";
+async function action(args, options) {
+    //console.log("SCH ARGS", args);
+    //console.log("SCH OPTS", options);
+    if (args.length < 1) {
+        throw new Error("agent-smith-db-getschema: provide a prompt argument");
+    }
+    const db = new DatabaseConstructor(dbPath, { fileMustExist: true, readonly: true });
+    const prompt = args.prompt;
+    // Get the schema information as SQL CREATE TABLE statements
+    const schema = [];
+    // Get all table names
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all();
+    for (const table of tables) {
+        const tableName = table.name;
+        const tableInfo = db.prepare(`PRAGMA table_info(${tableName})`).all();
+        const indexes = db.prepare(`SELECT name, sql FROM sqlite_master WHERE type='index' AND tbl_name='${tableName}'`).all();
+        // Generate CREATE TABLE statement
+        let createTableSQL = `CREATE TABLE ${tableName} (\n`;
+        // @ts-ignore
+        const columns = tableInfo.map(col => {
+            let columnDef = `  ${col.name} ${col.type}`;
+            if (col.notnull) {
+                columnDef += " NOT NULL";
+            }
+            if (col.dflt_value !== null) {
+                columnDef += ` DEFAULT ${col.dflt_value}`;
+            }
+            if (col.pk) {
+                columnDef += " PRIMARY KEY";
+            }
+            return columnDef;
+        });
+        createTableSQL += columns.join(",\n");
+        createTableSQL += "\n);";
+        // Add indexes
+        //@ts-ignore
+        const indexSQL = indexes.map(index => index.sql).join("\n");
+        if (tableName != "sqlite_sequence") {
+            schema.push({
+                tableName,
+                createTableSQL,
+                indexes: indexSQL
+            });
+        }
+    }
+    db.close();
+    // Return only the SQL schema string
+    let sqlSchema = "";
+    for (const table of schema) {
+        sqlSchema += table.createTableSQL + "\n\n";
+        if (table.indexes) {
+            sqlSchema += table.indexes + ";\n\n";
+        }
+    }
+    options.variables.schema = sqlSchema.trim();
+    options.variables.dbpath = dbPath;
+    return { prompt: prompt };
+}
+export { action, };

package/dist/features/adaptaters/imgs2base64.d.ts

@@ -0,0 +1 @@
+export function action(args: any, options: any): Promise<any>;

package/dist/features/adaptaters/imgs2base64.js

@@ -0,0 +1,13 @@
+import { imgs2base64 } from "../utils.js";
+async function action(args, options) {
+    const isVerbose = options?.debug || options?.verbose;
+    if (args.length < 2) {
+        throw new Error("Provide an image path and a prompt");
+    }
+    const pr = args.pop();
+    const { params, prompt } = await imgs2base64(args, pr, isVerbose);
+    options.params = { ...options.params, ...params };
+    const res = prompt;
+    return res;
+}
+export { action };

package/dist/features/adaptaters/prequery.d.ts

@@ -0,0 +1,4 @@
+declare function action(params: Array<any>, options: Record<string, any>): Promise<{
+    prompt: string;
+}>;
+export { action };

package/dist/features/adaptaters/prequery.js

@@ -0,0 +1,5 @@
+async function action(params, options) {
+    const res = { prompt: params.join(" ") };
+    return res;
+}
+export { action };

package/dist/features/agents/agent-smith-colab.yml

@@ -0,0 +1,37 @@
+description: An agent to manage Agent Smith's documentation
+category: internal
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized collaborators. Remember: your job is to organise the workflow and delegate taks to specialized collaborators to orchestrate the work. 
+
+      A collaborator is like a fork of yourself that can work independently and have access to your memory and context history, just like you. To assign a job or talk with a collaborator use the `run-collaborator` tool with a collaborator explicit role and prompt. Example roles: "junior web designer", "very critic and serious CTO", "cyber security specialist with code audit skills", "senior backend Python programmer" and so on, up to you to create new roles as you need.
+      Important: you can only run collaborators when you are not already in collaborator mode. Run them one at the time.
+
+      {file:../fragments/workspace.txt}
+
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation
+
+      Evaluate the user request and organise the work of collaborators to get an answer.
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - run-collaborator

package/dist/features/agents/agent-smith-doc.yml

@@ -0,0 +1,50 @@
+tool:
+  name: agent-smith-doc
+  description: An agent to manage Agent Smith project's documentation
+  arguments:
+      prompt:
+          description: The query about the documentation, the task to perform
+          required: true
+description: An agent to manage Agent Smith's documentation
+category: internal
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are a documentation agent for the Agent Smith project, a toolkit to run AI agents.
+
+      In addition to your tools you are provided with some skills: these are instructions to accomplish specific tasks. Here are the available skills and instructions about when to use them:
+
+      {skills}
+
+      You can choose to use a skill using the `load-skill` tool when it matches the task. Loading the skill will provide you with instructions to follow about how to accomplish the specific task it was made for.
+
+      {file:../fragments/workspace.txt}
+
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation. Always start by reading this before searching.
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - notify-user
+skills:
+  - update-doc-map
+  - update-codebase-summary
+  - document-package
+  - create-package-readme

package/dist/features/agents/agent-smith-help.yml

@@ -0,0 +1,35 @@
+description: An agent to manage Agent Smith's documentation
+category: doc
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith help agent for the Agent Smith project, a toolkit to run AI agents. It uses different classes of internal features:
+      - `agent`: an ai agent defined in yaml
+      - `workflow`: a workflow defined in yaml
+      - `actions`: code actions defined in yaml or javascript or python
+      - `adaptaters`: adaptater code defined in javascript
+      - `skills`: process instructions defined in markdown
+
+      {file:../fragments/workspace.txt}
+      {file:../fragments/ctx-helper-files.md}
+      
+      Information about the database: agent-smith/docsite/public/doc/architecture/3.database.md. 
+      Important: to read any agents, actions and other builtin features always use the "read-feature" tool if you need to read one. For other files use the "shell" tool.
+
+      Read AGENTS.md, the project nav file and the database info file before all to get a good idea of the context
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - agent-smith-db
+  - read-feature

package/dist/features/agents/agent-smith-search.yml

@@ -0,0 +1,41 @@
+tool:
+  name: agent-smith-search
+  description: An agent to run web search
+  arguments:
+      prompt:
+          description: the web search to perform or question about a web page
+          required: true
+description: An agent to run web search
+category: internal
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are a web search agent for the Agent Smith project, a toolkit to run AI agents.
+
+      {file:../fragments/workspace.txt}
+
+      Project's context helper files:
+
+      - `AGENTS.md`: general high level context map of the project to navigate
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - ddsearch
+  - open_page

package/dist/features/agents/agent-smith-sql.yml

@@ -0,0 +1,31 @@
+tool:
+    description: Create a database query for Agent Smith database
+    arguments:
+        prompt: 
+            description: The user question to create a query from
+description: Create an sql query
+category: internal
+prompt: |-
+    Schema:
+    {schema}
+    
+    Question: {prompt}
+
+    Important: output ONLY raw SQL code. Example: SELECT * FROM tablename
+model: text2sql
+template:
+    system: |-
+        You are given a database schema and a natural language question. Generate the SQL query that answers the question.
+
+        - Use only tables and columns from the provided schema
+        - Use uppercase SQL keywords (SELECT, FROM, WHERE, etc.)
+        - Use SQLite-compatible syntax
+    assistant: "```sql\n"
+    stop: 
+        - "```"
+inferParams:
+    temperature: 0
+variables:
+    required:
+        schema:
+            description: the database sql schema

package/dist/features/agents/agent-smith.yml

@@ -0,0 +1,37 @@
+description: An agent to manage Agent Smith's documentation
+category: internal
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized agents. Available subagents:
+
+        - `agent-smith-doc`: a documentation manager agent. Use it for all documentation related tasks, like verify, create or update documentation. It has specific skills to create codebase summaries and manage documentation.
+        - `agent-smith-search`: a web search and web page reader agent. Use to search information or ask questions about some web pages.
+
+      Agents call mode info: you can call an agent in worker mode using `run-worker`, it will have all the context you have in the conversation history. Or you can call an agent in isolation mode using `run-agent`: the agent will be completly independant and have no context. Use the isolation mode for independant tasks that are heavy and do not require context, otherwise use the worker mode to share context and dialog with workers.
+
+      {file:../fragments/workspace.txt}
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: read this to find documentation
+model: qwen35b
+backend: llamaccp
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - run-worker
+  - run-agent

package/dist/features/agents/collaborator.yml

@@ -0,0 +1,15 @@
+description: A collaborator agent
+type: builtin
+prompt: |-
+    You are on collaborator mode. Your role is: {role}. Main agent request:
+
+    {prompt}
+model: qwen35b
+variables:
+    required:
+        workspace:
+            description: The local directory path where to operate
+        role:
+            description: The role of the collaborator
+
+

package/dist/features/agents/infer.yml

@@ -0,0 +1,12 @@
+name: infer
+description: Run a raw inference query
+type: builtin
+prompt: |-
+    {prompt}
+model: qwen4b
+inferParams:
+  top_p: 0.8
+  top_k: 20
+  min_p: 0
+  temperature: 0.6
+  repeat_penalty: 1

package/dist/features/fragments/ctx-helper-files.md

@@ -0,0 +1,4 @@
+Project's context helper files:
+
+- `AGENTS.md`: general high level context map of the project
+- `.agents/documentation/project-nav.md`: a map of the project repositories and overview of the project

package/dist/features/fragments/workspace.txt

@@ -0,0 +1,6 @@
+You are operating on a Linux filesystem in a workspace located at /workspace. The current directory is /. If a user refers to a path prepend /workspace to it for shell commands: example: ls /workspace/src if user refers to a `src` directory.
+
+Directories for AI agents:
+
+- `.agents/documentation`: where the documentation to navigate the codebase is
+- `.agents/tasks`: where we store tasks for AI agents. If the user refers to a task check this directory

package/dist/features/skills/create-package-readme/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: create-package-readme
+description: use this to create comprehensive README file for a given package
+---
+
+## Workflow: Package README Creation
+
+### Phase 1: Discovery
+1. Read `/workspace/AGENTS.md` and `/workspace/.agents/documentation/project-nav.md` to understand project structure
+2. Read `/workspace/agent-smith/.agents/documentation/codebase-summary.md` and `/workspace/agent-smith/.agents/documentation/dpcumentation-map.md`
+3. Locate target package in the codebase summary (note its position, dependencies, and purpose)
+
+### Phase 2: Deep Dive
+3. Navigate to package directory: `/workspace/agent-smith/packages/{package-name}/`
+4. Read `.agents/documentation/codebase-summary.md` for package-specific architecture, key files, and usage patterns
+5. Read documentation from `/workspace/agent-smith/docsite/public/doc/libraries/{package-name}/*.md` (get_started, usage, api)
+
+### Phase 3: Synthesis & Writing
+6. Create `/workspace/agent-smith/packages/{package-name}/README.md` with this structure:
+   - **Npm badge**: example:
+      ```
+      [![pub package](https://img.shields.io/npm/v/this-package-name)](https://www.npmjs.com/package/this-package-name)
+      ```
+   - **Title & Tagline**: Package name + one-sentence description. Mention that this package is part of the Agent Smith toolkit (repository: https://github.com/lynxai-team/agent-smith)
+   - **Features**: Bullet list of key capabilities (use emojis for visual hierarchy)
+   - **Documentation**: 2 sections: documentation for AI agents (must include a link to the codebase navigation map at .agents/documentation/codebase-summary.md and the relevant doc from documentation), and documentation for humans, with the relevant doc http links. Correct links formats:
+      - For humans use the site link: https://lynxai-team.github.io/agent-smith/: replace the `docsite/public/doc` paths by this link. Example:
+         ```md
+         - [Complete doc](https://lynxai-team.github.io/agent-smith/libraries/agent/)
+         ```
+      - For AI agents provide detailled links map and use the raw file paths links. Example:
+         ```md
+         - [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the agent package
+         - [Get Started](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/1.get_started.md) — Installation and basic usage
+         - [Tools](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/2.tools.md) — Defining and configuring tools for agents
+         - [Templates](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/3.templates.md) — System prompts, YAML specs, and few-shot examples
+         - [Supervision](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/libraries/agent/4.supervision.md) — Human-in-the-loop tool authorization
+         ```
+   - **Installation**: npm/yarn command in code block
+   - **Quick Start**: Minimal working example showing creation, init, and basic operations
+   - **Usage**: Detailed patterns with code examples (creation, initialization, verbose mode, reading/writing, error handling)
+   - **Complete Example**: Full working async function demonstrating all operations
+   - **API Reference**: Factory function signature + parameters table + interface + method summary table
+   - **Important Notes**: Browser-only warnings, limitations, related packages
+   - **Documentation Links**: References to full docsite
+   - **License**: MIT/appropriate license
+
+### Key Principles
+- **Information Density**: Every section must convey unique value; avoid repetition between Quick Start and Usage
+- **Code Examples**: All examples must be complete, runnable TypeScript with proper async/await
+- **Type Safety**: Show generic type parameters explicitly (e.g., `get<string>()`)
+- **Error Handling**: Document error cases explicitly with try/catch examples
+- **Browser vs Node**: Clearly state environment constraints early in the README
+- **Visual Hierarchy**: Use emojis for feature bullets, clear section headers, and tables for API reference
+
+### Output Validation
+Before finalizing, verify:
+- [ ] All code blocks are syntactically valid TypeScript
+- [ ] API signatures match actual implementation (check source files if needed)
+- [ ] Installation command uses correct package name (`@agent-smith/{package-name}`)
+- [ ] Documentation links follow consistent pattern
+- [ ] No internal paths or implementation details leak into public documentation
+
+Documentation links base url: https://lynxai-team.github.io/agent-smith/
+
+Notify the user when the task is completed