@agent-smith/core 0.0.1

package/dist/features/skills/document-package/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: document-package
+description: use when asked to create or update package documentation in the docsite
+---
+
+This skill describes the workflow to document a package for the Agent Smith CLI.
+
+## Workflow
+
+Execute this one step after the other:
+
+1. **Locate the package** — Read `.agents/documentation/codebase-summary.md` to find the package path
+
+2. **Read codebase summary** — Read `[package-path].agents/documentation/codebase-summary.md` (e.g., `agent-smith-plugins/system/shell/.agents/documentation/codebase-summary.md`). This provides a quick overview of tools, agents, dependencies, and architecture.
+
+3. **Read source code** — Inspect `src/actions/`, `dist/agents/*.yml`, `dist/tasks/*.yml` to identify tools, agents, and capabilities.
+
+4. **Find next number** — List existing docs in `agent-smith/docsite/public/doc/plugins/`. Use the next available number (e.g., if 1-8 exist, use 9).
+
+5. **Write the doc** at `agent-smith/docsite/public/doc/plugins/<N>.<name>.md` using this exact structure:
+
+```markdown
+# <PackageName>
+
+![pub package](https://img.shields.io/npm/v/@agent-smith/feat-<name>)
+
+One-line description of what the package does.
+
+## Install
+
+```bash
+npm i -g @agent-smith/feat-<name>
+```
+
+Add the package to your `config.yml` file and run the `conf` command:
+
+```yml
+plugins:
+  - "@agent-smith/feat-<name>"
+```
+
+```bash
+lm conf
+```
+
+## Actions and tools
+
+### <category>
+
+Available tools:
+
+- <kbd>tool-name</kbd> one-line description of what it does (include container image if applicable)
+
+## Agents
+
+Available agents:
+
+- <kbd>agent-name</kbd> one-line description. Lists tools used:
+    - `tool-a` — purpose
+    - `tool-b` — purpose
+
+## Example agent
+
+```yaml
+description: A brief description
+model: qwen4b
+toolsList:
+  - agent-name # this tool is a subagent
+```
+
+## Links
+
+Add a next page link. All internal links must be of this form:
+
+<a href="javascript:openLink('/plugins/overview')">Back: Overview</a>
+```
+
+## Rules
+
+- Keep it short and information-dense — match the style of `6.filesystem.md` and `8.search.md`
+- Use `<kbd>tool-name</kbd>` for all tools/agents
+- Use backticks `for tool names in prose
+- End with navigation link to overview (or next package if known)

package/dist/features/skills/t/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: t
+description: describes how agent tasks work
+---
+
+# Tasks
+
+The tasks are located in an `.agents/tasks` directory, or `[project-name].agents/tasks` for projects
+
+## Read a task
+
+Read `.agents/tasks/[task-name]` to list the task files. If a `state.md` file is there read it: it details the task progression.
+
+## Write to a task
+
+Check if an `.agents/tasks/[task-name]` directory exists, if not create it. You can write markdown files in it.
+
+## Execute or continue a task
+
+Check what is remaining to do. Avoid verifying previous phases and execute the next phase directly. Always execute the phases one by one. Update the sate after each phase to mark it done.
+
+## After a task is executed or created: manage the state
+
+If the task is completed ask the user to confirm if everything is all right. If yes delete the task directory.
+
+If the task is not completed create or update`.agents/tasks/[task-name]/state.md` to indicate briefly what was done and what remains to do to complete the quickstart task. This file should contains step by step instructions and their state.

package/dist/features/skills/update-codebase-summary/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: update-codebase-summary
+description: use when asked to create or update the codebase summary documentation
+---
+
+This skill describes the workflow to create or update a codebase documentation file (`[project-path].agents/documentation/codebase-summary.md`).
+
+## Workflow
+
+1. **Explore the project** — Walk the directory tree, identify package/module boundaries, read manifest files (e.g., `package.json`), locate entry points, and understand inter-module dependencies.
+
+2. **Check for existing file** — Look for `[project-path].agents/documentation/codebase-summary.md` in the project directory. If it exists, update it. If not, create it.
+
+3. **Write the file** using exactly these 7 sections in this order:
+
+### Section Format
+
+```markdown
+# <module-name>
+
+## Summary
+One sentence: what the module does and why it exists.
+
+## Dependencies
+- `<dep-module>` — key types, functions, or services used
+- External: `<library>` (<purpose>)
+
+## Used By
+- `<consumer-module>` — why it uses this module
+
+## Entry Point
+- `<path>` — one-line description of what it exports or provides
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `<src/path>` | One-line: what the file does conceptually |
+
+## Architecture
+- 2–4 bullet points on main design patterns and data flow.
+
+## Related
+- See `<related-module>` — how they work together
+
+Keep the file as short and condensed as possible

package/dist/features/skills/update-doc-map/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: update-doc-map
+description: read this only when instructed to update the documentation map
+---
+
+Run the `agent-smith/packages/core/src/features/skills/update-doc-map/scripts/generate-doc-map.mjs` Nodejs script.
+
+Report only the end result: if the script has run ok or not.

package/dist/features/skills/update-doc-map/scripts/generate-doc-map.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+/**
+ * generate-doc-map.mjs
+ * 
+ * Scans the project for all documentation files and generates a doc-map.md
+ * file that helps AI agents navigate the codebase documentation.
+ */
+
+import { readdir, stat, writeFile } from 'node:fs/promises';
+import { join, relative, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// The script is in .agents/, so the project root is one level up
+const PROJECT_ROOT = join(__dirname, '../../../../../../../');
+
+// Packages that have their own .agents/documentation
+const PACKAGES = [
+  'core', 'agent', 'cli', 'wscli', 'types', 'smem', 'tmem', 'server'
+];
+
+/**
+ * Recursively find all markdown files in a directory
+ */
+async function findMarkdownFiles(dir, baseDir) {
+  const files = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip node_modules and other non-doc directories
+        if (!['node_modules', '.git', 'dist', 'build', '__pycache__'].includes(entry.name)) {
+          files.push(...await findMarkdownFiles(fullPath, baseDir));
+        }
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const relPath = relative(baseDir, fullPath);
+        files.push({ path: fullPath, relative: relPath });
+      }
+    }
+  } catch (err) {
+    // Skip directories we can't read
+  }
+  return files;
+}
+
+/**
+ * Extract a human-readable title from the filename
+ */
+function extractTitle(fileRelative) {
+  const parts = fileRelative.split('/');
+  const filename = basename(fileRelative, '.md');
+
+  // Try to get a better name from the path segments
+  if (parts.length > 1) {
+    return parts.slice(0, -1).join('/') + '/' + filename;
+  }
+  return filename;
+}
+
+/**
+ * Format a file path for display and linking using full workspace-relative path
+ */
+function formatLink(fileRelative, basePath) {
+  // Return full path from workspace root with .md extension preserved
+  return `${basePath}/${fileRelative}`;
+}
+
+/**
+ * Generate the documentation map markdown content
+ */
+async function generateDocMap() {
+  const docSections = [];
+
+  // Scan public documentation (docsite/public/doc)
+  const publicDocPath = join(PROJECT_ROOT, 'docsite/public/doc');
+  try {
+    await stat(publicDocPath);
+    const files = await findMarkdownFiles(publicDocPath, publicDocPath);
+
+    if (files.length > 0) {
+      // Group by top-level category
+      const grouped = {};
+      for (const file of files) {
+        const parts = file.relative.split('/');
+        const category = parts[0] || 'root';
+        if (!grouped[category]) grouped[category] = [];
+        grouped[category].push(file);
+      }
+
+      docSections.push({
+        title: '📚 Public Documentation',
+        description: 'Main project documentation hosted in the docsite.',
+        files: grouped,
+        basePath: 'docsite/public/doc'
+      });
+    }
+  } catch (err) {
+    // Skip if directory doesn't exist
+  }
+
+  // Scan root .agents/documentation
+  const rootAgentsPath = join(PROJECT_ROOT, '.agents/documentation');
+  try {
+    await stat(rootAgentsPath);
+    const files = await findMarkdownFiles(rootAgentsPath, rootAgentsPath);
+
+    if (files.length > 0) {
+      docSections.push({
+        title: '🤖 Root Agent Documentation',
+        description: 'Documentation for the agent system itself.',
+        files: { '': files },
+        basePath: '.agents'
+      });
+    }
+  } catch (err) {
+    // Skip if directory doesn't exist
+  }
+
+  // Scan each package's .agents/documentation
+  for (const pkg of PACKAGES) {
+    const pkgAgentsPath = join(PROJECT_ROOT, `packages/${pkg}/.agents/documentation`);
+    try {
+      await stat(pkgAgentsPath);
+      const files = await findMarkdownFiles(pkgAgentsPath, pkgAgentsPath);
+
+      if (files.length > 0) {
+        docSections.push({
+          title: `📦 Package: @agent-smith/${pkg}`,
+          description: `Documentation for the ${pkg} package.`,
+          files: { '': files },
+          basePath: `packages/${pkg}/.agents`
+        });
+      }
+    } catch (err) {
+      // Skip if directory doesn't exist or has no docs
+    }
+  }
+
+  // Generate the markdown content - compact format for AI agents
+  const lines = [
+    '# 🗺️ Documentation Map',
+    '',
+  ];
+
+  // Detailed sections only (no summary table, no horizontal rules)
+  for (const section of docSections) {
+    lines.push(`## ${section.title}`);
+    lines.push('');
+
+    for (const [category, files] of Object.entries(section.files)) {
+      if (files.length === 0) continue;
+
+      if (category) {
+        lines.push(`### ${category}`);
+        lines.push('');
+      }
+
+      // Sort files: files starting with numbers come first, then alphabetical
+      const sortedFiles = [...files].sort((a, b) => {
+        const aName = basename(a.relative, '.md');
+        const bName = basename(b.relative, '.md');
+        return aName.localeCompare(bName, undefined, { numeric: true });
+      });
+
+      for (const file of sortedFiles) {
+        const fullPath = formatLink(file.relative, section.basePath);
+        const workspacePath = `agent-smith/${fullPath}`;
+        lines.push(`- [\`${workspacePath}\`](${workspacePath})`);
+      }
+
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Main execution
+async function main() {
+  console.log('🔍 Scanning for documentation files...');
+
+  const content = await generateDocMap();
+  const outputPath = join(PROJECT_ROOT, '.agents/documentation/documentation-map.md');
+
+  // Write the file
+  await writeFile(outputPath, content, 'utf-8');
+
+  console.log(`✅ Documentation map generated: ${outputPath}`);
+}
+
+main().catch(err => {
+  console.error('❌ Error generating doc-map:', err);
+  process.exit(1);
+});

package/dist/features/workflows/agent-smith-db.yml

@@ -0,0 +1,9 @@
+tool:
+  description: and sql agent to retrieve data in the Agent Smith database by asking a question in natural language and get the data back
+  arguments:
+    prompt:
+        description: the question to ask about the data
+steps:
+  - adaptater: agent-smith-db-getschema
+  - agent: agent-smith-sql
+  - action: db-execute-read-query

package/dist/features/workflows/q.yml

@@ -0,0 +1,3 @@
+steps:
+  - adaptater: prequery
+  - agent: infer

package/dist/features/workflows/vision.yml

@@ -0,0 +1,3 @@
+steps:
+  - action: imgs2base64
+  - task: infer

package/dist/main.d.ts

@@ -0,0 +1,127 @@
+import { executeAction } from "./actions/cmd.js";
+import { McpClient } from "./mcp.js";
+import { extractToolDoc } from "./tools.js";
+import { executeWorkflow } from "./workflows/cmd.js";
+import { readWorkflow } from "./workflows/read.js";
+import { writeToClipboard } from "./utils/sys/clipboard.js";
+import { execute, runShellCmd } from "./utils/sys/execute.js";
+import { readConf } from "./utils/sys/read_conf.js";
+import { createConfigFileIfNotExists, getConfigPath, processConfPath, updateConfigFile } from "./conf.js";
+import { initDb } from "./db/db.js";
+import { deleteFileIfExists } from "./utils/sys/delete_file.js";
+import { getAgentPrompt, getInputFromOptions, openAgentSpec } from "./utils/io.js";
+import { getFeatureSpec } from "./state/features.js";
+import * as dbw from "./db/write.js";
+import * as dbr from "./db/read.js";
+import { init, initFilepaths, initState, pluginDataDir } from "./state/state.js";
+import { initBackends, listBackends, setBackend } from "./state/backends.js";
+import { initAgentSettings, getAgentSettings } from "./state/tasks.js";
+import { readAgent, readAgentsDir } from "./utils/sys/read_agent.js";
+import { extractBetweenTags } from "./utils/text.js";
+import { recreateDbFromConf, updateConfCmd, updateFeaturesCmd } from "./updateconf.js";
+import { useAgentExecutor } from "./agents/useagent.js";
+import { executeAgent } from "./agents/cmd.js";
+declare const db: {
+    db: any;
+    readAgentSettings: typeof dbr.readAgentSettings;
+    readAliases: typeof dbr.readAliases;
+    readBackends: typeof dbr.readBackends;
+    readFeature: typeof dbr.readFeature;
+    readFeaturePaths: typeof dbr.readFeaturePaths;
+    readFeatures: typeof dbr.readFeatures;
+    readFeaturesType: typeof dbr.readFeaturesType;
+    readFilePath: typeof dbr.readFilePath;
+    readFilePaths: typeof dbr.readFilePaths;
+    readPlugins: typeof dbr.readPlugins;
+    readSetting: typeof dbr.readSetting;
+    readSettings: typeof dbr.readSettings;
+    readSkillsFromList: typeof dbr.readSkillsFromList;
+    readAgentSetting: typeof dbr.readAgentSetting;
+    readTool: typeof dbr.readTool;
+    readWorkspaces: typeof dbr.readWorkspaces;
+    readSamplingPreset: typeof dbr.readSamplingPreset;
+    readSamplingPresets: typeof dbr.readSamplingPresets;
+    readAllSkills: typeof dbr.readAllSkills;
+    updatePromptfilePath: typeof dbw.updatePromptfilePath;
+    updateWorkspacePath: typeof dbw.updateWorkspacePath;
+    updateDataDirPath: typeof dbw.updateDataDirPath;
+    upsertBackends: typeof dbw.upsertBackends;
+    upsertSetting: typeof dbw.upsertSetting;
+    upsertWorkspace: typeof dbw.upsertWorkspace;
+    upsertAndCleanWorkspaces: typeof dbw.upsertAndCleanWorkspaces;
+    setDefaultBackend: typeof dbw.setDefaultBackend;
+    insertFeaturesPathIfNotExists: typeof dbw.insertFeaturesPathIfNotExists;
+    insertPluginIfNotExists: typeof dbw.insertPluginIfNotExists;
+    updateFeatures: typeof dbw.updateFeatures;
+    updateAliases: typeof dbw.updateAliases;
+    cleanupFeaturePaths: typeof dbw.cleanupFeaturePaths;
+    upsertFilePath: typeof dbw.upsertFilePath;
+    upsertAgentSettings: typeof dbw.upsertAgentSettings;
+    deleteAgentSettings: typeof dbw.deleteAgentSettings;
+    deleteAgentSetting: typeof dbw.deleteAgentSetting;
+    deleteWorkspace: typeof dbw.deleteWorkspace;
+    upsertSamplingPresets: typeof dbw.upsertSamplingPresets;
+    upsertSamplingPreset: typeof dbw.upsertSamplingPreset;
+    deleteSamplingPreset: typeof dbw.deleteSamplingPreset;
+    init: typeof initDb;
+};
+declare const fs: {
+    openAgentSpec: typeof openAgentSpec;
+    readWorkflow: typeof readWorkflow;
+};
+declare const conf: {
+    getConfigPath: typeof getConfigPath;
+    processConfPath: typeof processConfPath;
+    readConf: typeof readConf;
+    updateConfigFile: typeof updateConfigFile;
+    createConfigFileIfNotExists: typeof createConfigFileIfNotExists;
+    updateConfCmd: typeof updateConfCmd;
+    updateFeaturesCmd: typeof updateFeaturesCmd;
+    recreateDbFromConf: typeof recreateDbFromConf;
+    confDir: string;
+    dbPath: string;
+};
+declare const utils: {
+    execute: typeof execute;
+    runShellCmd: typeof runShellCmd;
+    deleteFileIfExists: typeof deleteFileIfExists;
+    readAgent: typeof readAgent;
+    readAgentsDir: typeof readAgentsDir;
+    extractBetweenTags: typeof extractBetweenTags;
+    writeToClipboard: typeof writeToClipboard;
+    usePerfTimer: (startTimer?: boolean) => {
+        start: () => void;
+        time: () => string;
+        timeRaw: () => string | number;
+        printTime: () => void;
+        measure: (name: string) => void;
+        final: (name?: string) => void;
+    };
+};
+declare const state: {
+    dataDirPath: import("@vue/reactivity").Ref<string, string>;
+    formatMode: import("@vue/reactivity").Ref<import("@agent-smith/types/dist/core.js").FormatMode, import("@agent-smith/types/dist/core.js").FormatMode>;
+    init: typeof init;
+    initFilepaths: typeof initFilepaths;
+    initState: typeof initState;
+    inputMode: import("@vue/reactivity").Ref<import("@agent-smith/types/dist/core.js").InputMode, import("@agent-smith/types/dist/core.js").InputMode>;
+    isStateReady: import("@vue/reactivity").Ref<boolean, boolean>;
+    lastCmd: {
+        name: string;
+        args: Array<string>;
+    };
+    outputMode: import("@vue/reactivity").Ref<import("@agent-smith/types/dist/core.js").OutputMode, import("@agent-smith/types/dist/core.js").OutputMode>;
+    pluginDataDir: typeof pluginDataDir;
+    promptfilePath: import("@vue/reactivity").Ref<string, string>;
+    pyShell: import("python-shell/index.js").PythonShell;
+    agentSettings: Record<string, import("@agent-smith/types/dist/agent.js").AgentSettings>;
+    isAgentSettingsInitialized: import("@vue/reactivity").Ref<boolean, boolean>;
+    initAgentSettings: typeof initAgentSettings;
+    getAgentSettings: typeof getAgentSettings;
+    backend: import("@vue/reactivity").Ref<import("@agent-smith/agent/dist/client.js").Lm | undefined, import("@agent-smith/agent/dist/client.js").Lm | undefined>;
+    backends: Record<string, import("@agent-smith/agent/dist/client.js").Lm>;
+    initBackends: typeof initBackends;
+    listBackends: typeof listBackends;
+    setBackend: typeof setBackend;
+};
+export { db, fs, conf, utils, state, executeAction, executeWorkflow, getAgentPrompt, getInputFromOptions, getFeatureSpec, extractToolDoc, McpClient, openAgentSpec, useAgentExecutor, executeAgent, };

package/dist/main.js

@@ -0,0 +1,80 @@
+import { executeAction } from "./actions/cmd.js";
+import { McpClient } from "./mcp.js";
+import { extractToolDoc } from "./tools.js";
+import { executeWorkflow } from "./workflows/cmd.js";
+import { readWorkflow } from "./workflows/read.js";
+import { writeToClipboard } from "./utils/sys/clipboard.js";
+import { execute, runShellCmd } from "./utils/sys/execute.js";
+import { readConf } from "./utils/sys/read_conf.js";
+import { confDir, createConfigFileIfNotExists, dbPath, getConfigPath, processConfPath, updateConfigFile } from "./conf.js";
+import { initDb, db as cdb } from "./db/db.js";
+import { usePerfTimer } from "./utils/perf.js";
+import { deleteFileIfExists } from "./utils/sys/delete_file.js";
+import { getAgentPrompt, getInputFromOptions, openAgentSpec } from "./utils/io.js";
+import { getFeatureSpec } from "./state/features.js";
+import * as dbw from "./db/write.js";
+import * as dbr from "./db/read.js";
+import { dataDirPath, formatMode, init, initFilepaths, initState, inputMode, isStateReady, lastCmd, outputMode, pluginDataDir, promptfilePath, pyShell, } from "./state/state.js";
+import { backend, backends, initBackends, listBackends, setBackend, } from "./state/backends.js";
+import { agentSettings, isAgentSettingsInitialized, initAgentSettings, getAgentSettings } from "./state/tasks.js";
+import { readAgent, readAgentsDir, } from "./utils/sys/read_agent.js";
+import { extractBetweenTags } from "./utils/text.js";
+import { recreateDbFromConf, updateConfCmd, updateFeaturesCmd, } from "./updateconf.js";
+import { useAgentExecutor } from "./agents/useagent.js";
+import { executeAgent } from "./agents/cmd.js";
+const db = {
+    init: initDb,
+    ...dbw,
+    ...dbr,
+    db: cdb,
+};
+const fs = {
+    openAgentSpec,
+    readWorkflow,
+};
+const conf = {
+    getConfigPath,
+    processConfPath,
+    readConf,
+    updateConfigFile,
+    createConfigFileIfNotExists,
+    updateConfCmd,
+    updateFeaturesCmd,
+    recreateDbFromConf,
+    confDir,
+    dbPath,
+};
+const utils = {
+    execute,
+    runShellCmd,
+    deleteFileIfExists,
+    readAgent,
+    readAgentsDir,
+    extractBetweenTags,
+    writeToClipboard,
+    usePerfTimer,
+};
+const state = {
+    dataDirPath,
+    formatMode,
+    init,
+    initFilepaths,
+    initState,
+    inputMode,
+    isStateReady,
+    lastCmd,
+    outputMode,
+    pluginDataDir,
+    promptfilePath,
+    pyShell,
+    agentSettings,
+    isAgentSettingsInitialized,
+    initAgentSettings,
+    getAgentSettings,
+    backend,
+    backends,
+    initBackends,
+    listBackends,
+    setBackend,
+};
+export { db, fs, conf, utils, state, executeAction, executeWorkflow, getAgentPrompt, getInputFromOptions, getFeatureSpec, extractToolDoc, McpClient, openAgentSpec, useAgentExecutor, executeAgent, };

package/dist/mcp.d.ts

@@ -0,0 +1,16 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { ToolSpec } from "@agent-smith/types";
+declare class McpClient {
+    name: string;
+    transport: StdioClientTransport;
+    client: Client;
+    authorizedTools: Array<string> | null;
+    askUserTools: Array<string> | null;
+    tools: Record<string, ToolSpec>;
+    constructor(servername: string, command: string, args: Array<string>, authorizedTools?: Array<string> | null, askUserTools?: Array<string> | null);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    extractTools(options: Record<string, any>): Promise<Array<ToolSpec>>;
+}
+export { McpClient, };