@tyvm/knowhow 0.0.109 → 0.0.111

package/autodoc/modules-guide.md

@@ -1,352 +1,379 @@
-# Knowhow Custom Modules Guide
+# Custom Modules Guide (Knowhow CLI)
 
-Knowhow **modules** are the primary extension mechanism for adding new capabilities to the Knowhow CLI/runtime. A module is a dynamically loaded package (an npm package or a local file) that can register **tools**, **agents**, **plugins**, **AI clients**, and **chat commands**.
+Knowhow **modules** are the primary extension mechanism for adding new capabilities—tools, agents, plugins, AI clients, and even chat commands—without modifying the Knowhow core.
+
+This guide explains how modules are loaded and how to write your own.
 
 ---
 
 ## 1) What modules are
 
-When Knowhow starts, it reads configuration and **dynamically loads** each configured module. A module can extend Knowhow by contributing any of the following:
+A **module** is a dynamically loaded JavaScript/TypeScript export (usually an **npm package**, sometimes a **local file**) that can extend Knowhow at runtime by providing:
+
+- **Tools**: callable functions the LLM/agent can invoke
+- **Agents**: additional agent definitions that can use tools
+- **Plugins**: plugin instances registered into Knowhow’s plugin system
+- **Clients**: AI clients (providers + model lists) registered into Knowhow
+- **Commands**: chat commands the module can define
 
-- **Tools**: functions that Knowhow/agents can call (tool calling)
-- **Agents**: preconfigured agent definitions (prompts, tool access, etc.)
-- **Plugins**: plugin objects registered under a module-provided name
-- **AI clients**: provider/client/model registrations for model routing
-- **Commands**: additional chat commands supported by the module
-- **Initialization hook (`init`)**: async setup work before registration
+Knowhow loads modules listed in your config and then registers their contributions into the relevant services (Tools, Agents, Plugins, Clients).
 
 ---
 
-## 2) Configuring modules (`knowhow.json`)
+## 2) Configuring modules (`modules` array in `knowhow.json`)
+
+Add module package names and/or local paths to the `modules` array in `knowhow.json`.
 
-In your project’s `knowhow.json`, add a `modules` array.
+### Local `knowhow.json` example
 
 ```jsonc
 {
   "modules": [
-    "@acme/knowhow-module-internal-api",
-    "./modules/local-module.js"
+    "@tyvm/knowhow-module-script",
+    "./modules/my-company-module",
+    "../../packages/knowhow-module-load-webpage"
   ]
 }
 ```
 
-### Supported module entries
-Each entry supports both:
+### Supported module specifiers
 
-- **npm package names** (e.g. `@acme/knowhow-module-internal-api`)
-- **local file paths** (e.g. `./modules/local-module.js`)
+From the loader behavior, `modules` entries can be:
 
-> Tip: Use the correct extension/format for your runtime (often compiled `.js`). If you author in TypeScript, compile to a Node-loadable format first.
+- **npm package names** (e.g. `@scope/name`, `name`)
+- **local file paths** that start with `"."` (relative to `process.cwd()`), e.g. `./modules/x`
+
+**Resolution behavior highlights**
+- Relative entries starting with `"."` are resolved with `path.resolve(process.cwd(), modulePath)`.
+- Package names are resolved using `require.resolve()` with special search paths (see “Global vs local modules” below).
 
 ---
 
-## 3) Global vs local modules
+## 3) Global vs local modules (load order)
 
-Knowhow supports both a global and local configuration:
+Knowhow supports:
 
-1. **Global config**: `~/.knowhow/knowhow.json`
-2. **Local config**: your project’s `knowhow.json`
+- **Global modules**: `~/.knowhow/knowhow.json`
+- **Local modules**: `./.knowhow/knowhow.json`
 
 ### Load order
-Modules load in this order:
 
-1. **Global modules** from `~/.knowhow/knowhow.json` load **first**
-2. **Local modules** from `./knowhow.json` load **after**
+Modules are loaded in this order:
+
+1. **Global** `modules` array
+2. **Local** `modules` array
+
+This is done by concatenating:
+- `...(globalConfig.modules || [])`
+- `...(localConfig.modules || [])`
 
-This means local modules can add additional capabilities or change behavior depending on how Knowhow merges/handles registrations (for example, tool name conflicts).
+and then de-duplicating via `toUniqueArray(...)` (preserving order).
+
+### Where module packages are resolved from
+
+When loading module specifiers, Knowhow searches these locations (in order):
+
+1. `./.knowhow/node_modules` (so `knowhow modules install` “just works”)
+2. `~/.knowhow/node_modules` (global install)
+3. `./node_modules` (project install)
 
 ---
 
-## 4) The `KnowhowModule` interface
+## 4) The `KnowhowModule` interface (what a module must export)
 
-A module must export an object compatible with the `KnowhowModule` interface. At minimum, a module must provide:
+A module must export an object that matches this interface:
 
-### `init(params)` (async initialization)
 ```ts
-async init(params): Promise<void>
+export interface KnowhowModule {
+  init: (params: InitParams) => Promise<void>;
+  commands: ModuleChatCommand[];
+  tools: ModuleTool[];
+  agents: ModuleAgent[];
+  plugins: ModulePlugin[];
+  clients: ModuleClient[];
+}
 ```
 
-Knowhow calls `init` during module loading so you can perform setup such as:
+### Required exports / properties
 
-- validate config
-- read environment variables/secrets
-- initialize API clients
-- precompute schemas or caches
+#### `init(params)` (async)
 
-### `tools`
 ```ts
-tools: Array<{
-  name: string;
-  handler: (...args: any[]) => any;
-  definition: any;
-}>
+init: (params: {
+  config: Config;
+  cwd: string;
+  context?: ModuleContext;
+}) => Promise<void>;
 ```
 
-Your module provides tools as entries with:
-- **`name`**: the tool name
-- **`handler`**: the implementation function
-- **`definition`**: tool metadata/schema
+Knowhow calls `init()` before registering tools/agents/plugins/clients.
+
+- `params.config` is your config (local + merged with globals by the caller)
+- `params.cwd` is `process.cwd()`
+- `params.context` may include services like `Tools`, `Agents`, `Plugins`, etc.
+  - The loader checks `context.Agents`, `context.Tools`, etc. before registering.
 
-#### Important: tool definition shape
-In Knowhow’s tool registration flow, tool metadata is used to register the tool, and the tool handler is bound using the tool definition’s function name. That implies your `definition` must include a function name (commonly via something like `definition.function.name`).
+#### `tools`
 
-A typical definition looks like:
+An array of:
 
 ```ts
-{
-  type: "function",
-  function: {
-    name: "my_tool",
-    description: "...",
-    parameters: { /* JSON-schema-like */ }
-  }
-}
+type ModuleTool = {
+  name: string;
+  handler: (...args: any[]) => any;
+  definition: Tool;
+};
 ```
 
-### `agents`
+Knowhow registers each tool by:
+- `context.Tools.addTool(tool.definition)`
+- `context.Tools.setFunction(tool.definition.function.name, tool.handler)`
+
+So your `definition` **must include** `definition.function.name`.
+
+#### `agents`
+
 ```ts
-agents: any[] // array of agent configs (shape depends on Knowhow)
+export type ModuleAgent = IAgent;
 ```
 
-Agents are module-provided configurations. The exact schema depends on your Knowhow version, but typically includes:
+So `agents` must be an array of `IAgent` objects (not just plain JSON configs), matching Knowhow’s agent interface.
 
-- agent name
-- instructions/system prompt
-- allowed tools (by tool name)
-- model/provider selection (or references to registered clients/models)
+#### `plugins`
 
-### `plugins`
 ```ts
-plugins: Array<{
-  name: string;
-  plugin: any; // plugin instance/object
-}>
+type ModulePlugin = { name: string; plugin: PluginConstructor };
 ```
 
-### `clients`
+Knowhow registers each plugin with:
+
+- `context.Plugins.registerPlugin(plugin.name, new plugin.plugin(context))`
+
+So your module should provide a plugin constructor (`class ...`) that takes `PluginContext`.
+
+#### `clients`
+
 ```ts
-clients: Array<{
+type ModuleClient = {
+  client: GenericClient;
   provider: string;
-  client: any;     // AI client instance/constructor
-  models: string[]; // supported model IDs
-}>
+  models: string[];
+};
 ```
 
-### `commands`
+Knowhow registers each client with:
+
+- `context.Clients.registerClient(client.provider, client.client)`
+- `context.Clients.registerModels(client.provider, client.models)`
+
+#### `commands`
+
 ```ts
-commands: any[] // chat commands
+type ModuleChatCommand = {
+  name: string;
+  description: string;
+  handler: (ctx: any) => void;
+};
 ```
 
-Commands are additional chat-loop commands exposed by your module (exact handler signature depends on Knowhow’s command system).
+Your module can define chat commands. (Registration happens elsewhere in the CLI; the interface is provided for modules to declare them.)
 
 ---
 
 ## 5) Writing a custom module (step-by-step)
 
-Below is a practical workflow with a concrete example at the end.
+Below is a realistic workflow you can follow.
+
+### Step 1: Create the module file
 
-### Step 1 — Create the module file
-Example layout:
+Example local structure:
 
 ```
 your-project/
-  knowhow.json
+  .knowhow/
   modules/
-    hello-module.js   (or hello-module.ts compiled to js)
+    my-company-module.ts
+  .knowhow/knowhow.json
+```
+
+In `knowhow.json`, you’ll later point to:
+
+```jsonc
+{
+  "modules": ["./modules/my-company-module"]
+}
+```
+
+---
+
+### Step 2: Implement `init(params)`
+
+Typically used to:
+- read config
+- set up clients or API keys
+- do any async initialization (discover endpoints, validate auth, etc.)
+
+```ts
+export async function init(params: InitParams) {
+  // do async setup
+}
 ```
 
-### Step 2 — Implement `init(params)`
-Create an async function that performs any setup once at startup.
+In practice, you export the whole module object with `init`.
 
-### Step 3 — Add a custom tool (with a definition)
-Add a tool entry:
-- choose a unique tool `name`
-- implement `handler`
-- provide `definition` with a callable-function name (commonly `definition.function.name`)
+---
+
+### Step 3: Add a custom tool
+
+A tool is the most common extension. Provide:
 
-### Step 4 — Add a custom agent
-Add an agent config referencing your tools and setting prompt/model behavior.
+- a unique tool `name`
+- a `handler` function
+- a `definition` object with `definition.function.name`
 
-### Step 5 — Register the module in `knowhow.json`
-Add your module path or npm package to the `modules` array.
+Knowhow will connect `definition.function.name` → `handler`.
 
 ---
 
-## 6) Plugin packages (`pluginPackages`)
+### Step 4: Add a custom agent
+
+Your module must provide `IAgent` objects. The exact shape depends on `IAgent` implementation in your Knowhow version.
+
+**Pattern:** create an agent class/instance using Knowhow’s agent interfaces and add it to `agents`.
 
-In addition to full **modules**, Knowhow can load **plugin-only** npm packages via a configuration map called `pluginPackages`.
+> Note: Since `IAgent` isn’t shown in the provided code, the exact constructor/signature may differ. Use Knowhow’s built-in agent implementations as reference and then export them as module `agents`.
 
-Conceptually, Knowhow will iterate `pluginPackages` entries and load/instantiate them, typically expecting a default export that represents a plugin constructor/class.
+---
 
-Example (conceptual):
+### Step 5: Register the module in `knowhow.json`
 
 ```jsonc
 {
-  "pluginPackages": {
-    "acme-lint": "@acme/knowhow-plugin-eslint",
-    "kb": "./plugins/my-kb-plugin.js"
-  }
+  "modules": [
+    "./modules/my-company-module"
+  ]
 }
 ```
 
-**Use `pluginPackages` when** your package is intended to register plugins only and doesn’t need to define tools/agents/clients.
+Then run:
+
+```bash
+knowhow
+```
+
+(or restart the CLI) so the module gets loaded.
+
+---
+
+## 6) Plugin packages (plugin-only npm registrations)
+
+Knowhow also supports **plugin-only packages** via a `pluginPackages`-style map (a simpler way to load/register plugins without a full “module” object).
+
+Conceptually:
+
+- `modules` are full modules (tools + agents + plugins + clients + commands)
+- `pluginPackages` is for registering **plugins only** from npm packages
+
+> The exact config schema can vary by Knowhow version. If you use `pluginPackages`, ensure the referenced package exports a plugin constructor compatible with Knowhow’s plugin system.
 
 ---
 
 ## 7) Use cases
 
-Modules are ideal for connecting Knowhow to your organization’s environment, for example:
+Common reasons teams create custom modules:
 
 1. **Connect to internal APIs**
-   - Build tools like `internal_ticket_create`, `internal_user_lookup`, `internal_doc_search`
-   - Use `init` to authenticate and construct API clients
+   - Add tools that call `https://internal.company/api/...`
+   - Add clients for proprietary model providers
+   - Add agents that follow company workflows
 
-2. **Custom tools**
-   - Wrap internal services as LLM-callable tools
-   - Provide JSON-schema-like definitions so agents can call them safely
+2. **Company-specific tools**
+   - e.g., “Create Jira ticket”, “Search internal docs”, “Trigger deployment”
+   - Provide tool definitions with strict JSON schemas and safe handlers
 
 3. **Company-specific agents**
-   - Ship agents tuned for your workflows (support triage, engineering review, compliance checks)
-   - Restrict agents to only the tools you want them to use
+   - Add agents with tailored instructions and model/provider selection
+   - Reuse built-in tools and add new company-only tools
 
-4. **Custom AI clients**
-   - Register model providers that point to internal gateways or custom hosting
-   - Limit allowed models to those approved by your org
+4. **Environment-specific behavior**
+   - In `init`, detect environment variables, feature flags, or endpoint availability
+   - Register only the tools/clients that are valid for this deployment
 
 ---
 
-## Complete working TypeScript example (minimal module)
+# Complete working TypeScript example (minimal module)
 
-> This is a minimal module that:
-> - implements `init`
-> - registers one tool with a `definition.function.name`
-> - registers one agent
-> - leaves plugins/clients empty
-> - registers one chat command
->
-> **Save as:** `modules/minimal-module.ts`  
-> **Compile to JS** (CommonJS or runtime-compatible output), then reference the compiled `.js` in `knowhow.json`.
+This minimal module registers **one tool**: `getGreeting({ name })`.
 
-### `modules/minimal-module.ts`
-```ts
-// modules/minimal-module.ts
+It includes:
+- `init()`
+- `tools` with a proper `definition.function.name`
+- everything else left empty
 
-// If you have the exact Knowhow types in your repo, replace `any` with real imports.
-// This example is intentionally robust against type mismatches.
+> Save this file as: `./modules/minimal-greeting-module.ts` and reference it in `./.knowhow/knowhow.json`.
 
-type ToolDefinition = {
-  type: "function";
-  function: {
-    name: string;
-    description?: string;
-    parameters?: any;
-  };
-};
+## `modules/minimal-greeting-module.ts`
 
-type KnowhowModule = {
-  init: (params: { config: any; cwd: string }) => Promise<void> | void;
-  tools: Array<{
-    name: string;
-    handler: (args: any) => Promise<any> | any;
-    definition: ToolDefinition;
-  }>;
-  agents: any[];
-  plugins: Array<{ name: string; plugin: any }>;
-  clients: Array<{ provider: string; client: any; models: string[] }>;
-  commands: any[];
-};
-
-const toolDefinition: ToolDefinition = {
+```ts
+import type { KnowhowModule, InitParams, ModuleTool } from "../src/services/modules/types";
+import type { Tool } from "../src/clients/types";
+
+/**
+ * Minimal, working module:
+ * - provides 1 tool
+ * - no agents/plugins/clients/commands
+ */
+const toolDefinition: Tool = {
   type: "function",
   function: {
-    name: "demo_echo",
-    description: "Echoes input back to the caller.",
+    name: "getGreeting",
+    description: "Return a friendly greeting for a given name.",
     parameters: {
       type: "object",
       properties: {
-        text: { type: "string", description: "Text to echo" }
+        name: { type: "string", description: "Name to greet" }
       },
-      required: ["text"],
-      additionalProperties: false
+      required: ["name"]
     }
   }
 };
 
+const greetingTool: ModuleTool = {
+  name: "getGreeting",
+  definition: toolDefinition,
+  handler: ({ name }: { name: string }) => {
+    return `Hello, ${name}! 👋`;
+  }
+};
+
 const module: KnowhowModule = {
-  // 1) Required async initialization hook
-  async init({ config, cwd }) {
-    // Example: validate config or prepare resources once at startup
-    // console.log("[minimal-module] init", { cwd, hasConfig: !!config });
-    void config;
-    void cwd;
+  async init(_params: InitParams) {
+    // Optional initialization.
+    // You could validate env vars or configure SDK clients here.
   },
 
-  // 2) Tool registrations
-  tools: [
-    {
-      name: "demo_echo",
-      definition: toolDefinition,
-
-      // Important: handler is bound to definition.function.name by Knowhow’s loader
-      handler: async (args: any) => {
-        const text = typeof args?.text === "string" ? args.text : "";
-        return { echoed: text };
-      }
-    }
-  ],
-
-  // 3) Agent registrations (shape depends on Knowhow’s IAgent schema)
-  agents: [
-    {
-      name: "demo-echo-agent",
-      description: "A demo agent that can call demo_echo.",
-      // Common pattern: restrict the agent to specific tools by name
-      tools: ["demo_echo"],
-      // Provide instructions/prompt. (Field names vary by Knowhow version.)
-      systemPrompt: "You are a demo agent. When asked to echo, call demo_echo."
-    }
-  ],
+  commands: [],
 
-  // 4) Plugin registrations (optional)
-  plugins: [],
+  tools: [greetingTool],
 
-  // 5) AI client registrations (optional)
-  clients: [],
-
-  // 6) Chat commands (optional; exact handler signature depends on Knowhow)
-  commands: [
-    {
-      name: "/echo",
-      description: "Echo text using the demo_echo tool.",
-      handler: (ctx: any) => {
-        // This is a minimal placeholder. Depending on Knowhow’s command system,
-        // you may need to call a tool runner from ctx.
-        const raw = typeof ctx?.args === "string" ? ctx.args : ctx?.args?.text;
-        const text = typeof raw === "string" ? raw : "hello";
-        ctx?.reply?.({ text: `Echo: ${text}` });
-      }
-    }
-  ]
+  agents: [],
+  plugins: [],
+  clients: []
 };
 
-// Export strategy:
-// - If your Knowhow loader uses require(), CommonJS export can be safest.
-// - This `export =` pattern works with CommonJS outputs.
-export = module;
+export default module;
 ```
 
-### Register it in `knowhow.json`
-
-After compiling, point to the compiled JS file, for example:
+## Register it in `./.knowhow/knowhow.json`
 
 ```jsonc
 {
-  "modules": [
-    "./modules/dist/minimal-module.js"
-  ]
+  "modules": ["./modules/minimal-greeting-module"]
 }
 ```
 
+Then restart Knowhow.
+
 ---
 
-If you paste (or link) the exact `KnowhowModule`, `Tool` definition, and `IAgent` type shapes from your source tree, I can tailor the example to be **fully type-checked** (no `any`) and ensure your command handler matches the exact runtime signature.
+If you share your Knowhow version and (optionally) the `IAgent` / `Tool` type definitions from your repo, I can provide a fully compiling example that also includes a custom agent and a plugin/client.