matimo 0.1.0-alpha.9 → 0.1.2

package/packages/core/dist/policy/policy-loader.js

@@ -0,0 +1,156 @@
+/**
+ * Policy-as-YAML loader for Matimo.
+ *
+ * Allows the developer to configure the policy engine through a YAML file
+ * instead of inline TypeScript, making it easy to adjust policy across
+ * environments without rebuilding.
+ *
+ * Schema for policy.yaml:
+ *
+ * ```yaml
+ * allowedDomains:
+ *   - api.slack.com
+ *   - slack.com
+ *
+ * allowedCredentials:
+ *   - SLACK_BOT_TOKEN
+ *   - OPENAI_API_KEY
+ *
+ * allowedHttpMethods:
+ *   - GET
+ *   - POST
+ *
+ * allowCommandTools: false
+ * allowFunctionTools: false
+ *
+ * protectedNamespaces:
+ *   - matimo_
+ * ```
+ *
+ * Usage:
+ *   const matimo = await MatimoInstance.init({ policyFile: './policy.yaml' });
+ */
+import fs from 'fs';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { DefaultPolicyEngine } from './default-policy.js';
+import { MatimoError, ErrorCode } from '../errors/matimo-error.js';
+// ──────────────────────────────────────────────────────────────────────────────
+// Zod schema — validates the YAML before constructing PolicyConfig
+// ──────────────────────────────────────────────────────────────────────────────
+// Valid HTTP methods supported by the policy engine
+const VALID_HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+const ValidHttpMethodEnum = z.enum(VALID_HTTP_METHODS);
+const PolicyFileSchema = z.object({
+    allowedDomains: z.array(z.string()).optional(),
+    allowedCredentials: z.array(z.string()).optional(),
+    allowedHttpMethods: z
+        .array(z
+        .string()
+        .transform((val) => val.toUpperCase())
+        .pipe(ValidHttpMethodEnum))
+        .optional(),
+    allowCommandTools: z.boolean().optional(),
+    allowFunctionTools: z.boolean().optional(),
+    protectedNamespaces: z.array(z.string()).optional(),
+    enableHITL: z.boolean().optional(),
+    quarantineRiskLevels: z.array(z.enum(['low', 'medium', 'high', 'critical'])).optional(),
+    approvalTtlSeconds: z.number().int().positive().optional(),
+});
+// ──────────────────────────────────────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Parse a YAML policy file and return a PolicyEngine configured from it.
+ *
+ * Throws `MatimoError(INVALID_SCHEMA)` if the file cannot be read or fails validation.
+ *
+ * @param filePath - Absolute or cwd-relative path to the policy YAML file
+ * @returns A frozen `DefaultPolicyEngine` built from the parsed config
+ *
+ * @example
+ * ```ts
+ * // Direct usage
+ * const engine = loadPolicyFromFile('./policy.yaml');
+ * const matimo = await MatimoInstance.init({ policy: engine });
+ *
+ * // Or use the shorthand InitOption (preferred)
+ * const matimo = await MatimoInstance.init({ policyFile: './policy.yaml' });
+ * ```
+ */
+export function loadPolicyFromFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new MatimoError(`Cannot read policy file "${filePath}": ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (err) {
+        throw new MatimoError(`Policy file "${filePath}" contains invalid YAML: ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    const result = PolicyFileSchema.safeParse(parsed ?? {});
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  • ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new MatimoError(`Policy file "${filePath}" is invalid:\n${issues}`, ErrorCode.INVALID_SCHEMA, { filePath, issues: result.error.issues });
+    }
+    const policyConfig = buildPolicyConfig(result.data);
+    return new DefaultPolicyEngine(policyConfig);
+}
+/**
+ * Parse a YAML policy file into a PolicyConfig (without creating an engine).
+ * Useful for hot-reload: parse the new file, then call engine.updateConfig().
+ */
+export function parsePolicyFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new MatimoError(`Cannot read policy file "${filePath}": ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (err) {
+        throw new MatimoError(`Policy file "${filePath}" contains invalid YAML: ${err.message}`, ErrorCode.INVALID_SCHEMA, { filePath });
+    }
+    const result = PolicyFileSchema.safeParse(parsed ?? {});
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  \u2022 ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new MatimoError(`Policy file "${filePath}" is invalid:\n${issues}`, ErrorCode.INVALID_SCHEMA, { filePath, issues: result.error.issues });
+    }
+    return buildPolicyConfig(result.data);
+}
+function buildPolicyConfig(data) {
+    const config = {};
+    if (data.allowedDomains !== undefined)
+        config.allowedDomains = data.allowedDomains;
+    if (data.allowedCredentials !== undefined)
+        config.allowedCredentials = data.allowedCredentials;
+    if (data.allowedHttpMethods !== undefined)
+        config.allowedHttpMethods = data.allowedHttpMethods;
+    if (data.allowCommandTools !== undefined)
+        config.allowCommandTools = data.allowCommandTools;
+    if (data.allowFunctionTools !== undefined)
+        config.allowFunctionTools = data.allowFunctionTools;
+    if (data.protectedNamespaces !== undefined)
+        config.protectedNamespaces = data.protectedNamespaces;
+    if (data.enableHITL !== undefined)
+        config.enableHITL = data.enableHITL;
+    if (data.quarantineRiskLevels !== undefined)
+        config.quarantineRiskLevels = data.quarantineRiskLevels;
+    if (data.approvalTtlSeconds !== undefined)
+        config.approvalTtlSeconds = data.approvalTtlSeconds;
+    return config;
+}
+//# sourceMappingURL=policy-loader.js.map

package/packages/core/dist/policy/policy-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-loader.js","sourceRoot":"","sources":["../../src/policy/policy-loader.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/policy/risk-classifier.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Risk Classifier for Matimo tools.
+ *
+ * Pure function that classifies a tool's risk level based on its execution
+ * type, HTTP method, and approval requirements. No schema changes needed.
+ */
+import type { ToolDefinition } from '../core/schema.js';
+import type { RiskLevel } from './types.js';
+/**
+ * Classify the risk level of a tool based on its definition.
+ *
+ * - critical: arbitrary code execution (type: function)
+ * - high: shell execution (type: command), HTTP DELETE, or explicit requires_approval
+ * - medium: HTTP POST/PUT/PATCH (write operations)
+ * - low: HTTP GET, read-only tools
+ */
+export declare function classifyRisk(tool: ToolDefinition): RiskLevel;
+//# sourceMappingURL=risk-classifier.d.ts.map

package/packages/core/dist/policy/risk-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-classifier.d.ts","sourceRoot":"","sources":["../../src/policy/risk-classifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAoC5D"}

package/packages/core/dist/policy/risk-classifier.js

@@ -0,0 +1,47 @@
+/**
+ * Risk Classifier for Matimo tools.
+ *
+ * Pure function that classifies a tool's risk level based on its execution
+ * type, HTTP method, and approval requirements. No schema changes needed.
+ */
+/**
+ * Classify the risk level of a tool based on its definition.
+ *
+ * - critical: arbitrary code execution (type: function)
+ * - high: shell execution (type: command), HTTP DELETE, or explicit requires_approval
+ * - medium: HTTP POST/PUT/PATCH (write operations)
+ * - low: HTTP GET, read-only tools
+ */
+export function classifyRisk(tool) {
+    // Explicit override declared in the tool YAML takes precedence
+    if (tool.risk) {
+        return tool.risk;
+    }
+    const exec = tool.execution;
+    // Arbitrary code execution is always critical risk
+    if (exec.type === 'function') {
+        return 'critical';
+    }
+    // Shell commands are high risk (injection vectors)
+    if (exec.type === 'command') {
+        return 'high';
+    }
+    // HTTP tools: risk depends on method
+    if (exec.type === 'http') {
+        if (tool.requires_approval === true) {
+            return 'high';
+        }
+        const method = exec.method.toUpperCase();
+        if (method === 'DELETE') {
+            return 'high';
+        }
+        if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+            return 'medium';
+        }
+        // GET is low risk
+        return 'low';
+    }
+    // Unknown execution type — treat as high
+    return 'high';
+}
+//# sourceMappingURL=risk-classifier.js.map

package/packages/core/dist/policy/risk-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-classifier.js","sourceRoot":"","sources":["../../src/policy/risk-classifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,+DAA+D;IAC/D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,IAAiB,CAAC;IAChC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;IAE5B,mDAAmD;IACnD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,mDAAmD;IACnD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qCAAqC;IACrC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;YACpC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YAChE,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,kBAAkB;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yCAAyC;IACzC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/packages/core/dist/policy/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Policy Engine types for Matimo Agent-Native SDK.
+ *
+ * The policy engine governs what tools agents can create, execute, and discover.
+ * Agents cannot mutate policy at runtime; the host configures it and may hot-reload via `updateConfig()`.
+ */
+import type { ToolDefinition } from '../core/schema.js';
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Three-tier classification for agent-created tool proposals.
+ *
+ * - `auto`: Can be created and used immediately (low-risk GET tools, no auth).
+ * - `approval-required`: Allowed but must be approved before execution
+ *   (tools with auth, POST/PUT/DELETE, external data writes).
+ * - `blocked`: Can never be created regardless of policy config
+ *   (reserved namespaces, function/command execution, SSRF targets,
+ *   tools referencing policy internals).
+ */
+export type PolicyTier = 'auto' | 'approval-required' | 'blocked';
+/**
+ * Identity and environment context passed by the host application.
+ * Matimo does not authenticate — this is whatever the caller provides.
+ */
+export interface PolicyContext {
+    /** Identifier for the calling agent (optional — SDK doesn't mandate identity) */
+    agentId?: string;
+    /** Deployment environment (e.g. 'dev', 'staging', 'prod') */
+    environment?: string;
+    /** Roles assigned to the caller (e.g. ['reader', 'writer', 'admin']) */
+    roles?: string[];
+    /** Extensible metadata for custom policy rules */
+    metadata?: Record<string, unknown>;
+}
+export type PolicyDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    riskLevel?: RiskLevel;
+} | {
+    allowed: 'pending_approval';
+    reason: string;
+    riskLevel: RiskLevel;
+    /** Tool name for the approval flow to reference */
+    toolName?: string;
+};
+/**
+ * Async callback invoked when a tool enters the quarantine/HITL state.
+ * Returns `true` if the admin approves, `false` if rejected.
+ * Integrators wire this to a UI, Slack message, or approval queue.
+ */
+export type HITLCallback = (request: HITLRequest) => Promise<boolean>;
+export interface HITLRequest {
+    toolName: string;
+    riskLevel: RiskLevel;
+    reason: string;
+    environment?: string;
+    agentId?: string;
+    /** Full tool definition for admin review */
+    toolDefinition?: unknown;
+}
+export interface Violation {
+    /** Machine-readable rule identifier (e.g. 'no-ssrf', 'reserved-namespace') */
+    rule: string;
+    /** Severity of the violation */
+    severity: RiskLevel;
+    /** Human-readable explanation */
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    violations: Violation[];
+}
+export interface ValidationContext {
+    /** Whether the tool comes from a trusted or untrusted path */
+    source: 'trusted' | 'untrusted';
+    /** Active policy configuration (defaults to empty/permissive) */
+    policy?: PolicyConfig;
+}
+/**
+ * Developer-configurable policy rules. All fields optional with conservative defaults.
+ */
+export interface PolicyConfig {
+    /** HTTP tool URL domain allowlist. If set, only these domains are permitted. */
+    allowedDomains?: string[];
+    /** Env var names that agent-created tools may reference for auth. */
+    allowedCredentials?: string[];
+    /** HTTP methods allowed for agent-created tools (default: ['GET', 'POST']). */
+    allowedHttpMethods?: string[];
+    /** Allow agent-created tools with execution type 'command' (default: false). */
+    allowCommandTools?: boolean;
+    /** Allow agent-created tools with execution type 'function' (default: false — always false for untrusted). */
+    allowFunctionTools?: boolean;
+    /** Tool name prefixes reserved for built-in tools (default: ['matimo_']). */
+    protectedNamespaces?: string[];
+    /**
+     * Enable quarantine/HITL for medium-risk tools in production.
+     * When true, `canCreate()` returns `pending_approval` instead of `allowed: false`
+     * for medium-risk tools, allowing a human reviewer to approve or reject.
+     * Default: false (original binary behavior preserved).
+     */
+    enableHITL?: boolean;
+    /**
+     * Risk levels eligible for HITL quarantine instead of outright rejection.
+     * Default: ['medium'] — critical/high are always blocked, low is always auto.
+     */
+    quarantineRiskLevels?: RiskLevel[];
+    /**
+     * Number of seconds after which an approval expires and the tool must be re-approved.
+     * If not set, approvals never expire.
+     */
+    approvalTtlSeconds?: number;
+}
+/**
+ * The PolicyEngine interface. Implementations are frozen at boot time and
+ * cannot be mutated by agents at runtime.
+ */
+export interface PolicyEngine {
+    /** Check whether this agent is allowed to execute a given tool. */
+    canExecute(context: PolicyContext, tool: ToolDefinition): PolicyDecision;
+    /** Check whether this agent is allowed to create/propose a tool definition. */
+    canCreate(context: PolicyContext, toolDef: ToolDefinition): PolicyDecision;
+    /**
+     * Update the policy configuration at runtime (hot-reload).
+     * Implementations should validate the new config before applying.
+     */
+    updateConfig?(config: PolicyConfig): void;
+    /** Filter a list of tools to only those this agent is allowed to see/use. */
+    filterForAgent(context: PolicyContext, tools: ToolDefinition[]): ToolDefinition[];
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/core/dist/policy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/policy/types.js

@@ -0,0 +1,8 @@
+/**
+ * Policy Engine types for Matimo Agent-Native SDK.
+ *
+ * The policy engine governs what tools agents can create, execute, and discover.
+ * Agents cannot mutate policy at runtime; the host configures it and may hot-reload via `updateConfig()`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/core/dist/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/policy/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 tallclub
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,243 +0,0 @@
-# Matimo — Toolbox For AI Agents
-
-<p align="center">
-  <img src="./docs/assets/logo.png" alt="Matimo Logo" width="300" />
-</p>
-<p align="center">
-    <strong>Matimo - "to be powerful"</strong>
-</p>
-
-<p align="center">
-  <a href="https://github.com/tallclub/matimo/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/tallclub/matimo/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
-  <a href="https://www.npmjs.com/package/matimo"><img src="https://img.shields.io/npm/v/matimo.svg?style=for-the-badge" alt="npm version"></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="MIT License"></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9+-blue?style=for-the-badge" alt="TypeScript"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18+-green?style=for-the-badge" alt="Node.js"></a>
-</p>
-
-<p align="center">
-  <a href="https://discord.gg/3JPt4mxWDV"><img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
-</p>
-
-**Matimo** is a universal, configuration‑driven AI tools ecosystem. Define tools **once in YAML** and reuse them across the SDK, LangChain, custom agents, and a single MCP server, without re‑implementing schemas or fragmenting integration logic.
-
-**Define once → Plug into any agent ecosystem.**
-
-[📖 Documentation](./docs) · [🚀 Quick Start](./docs/getting-started/QUICK_START.md) · [📚 API Reference](./docs/api-reference/SDK.md) · [🛠️ Add Tools](./docs/tool-development/ADDING_TOOLS.md) · [🤖 Examples](./examples)
-
----
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install matimo
-# OR auto-discover tools from node_modules/@matimo/*
-npm install matimo @matimo/slack @matimo/gmail
-```
-
-### Minimal Example (TypeScript)
-
-```typescript
-import { MatimoInstance } from '@matimo/core';
-
-const matimo = await MatimoInstance.init({
-  autoDiscover: true,
-});
-
-const result = await matimo.execute('slack-send-message', {
-  channel: '#general',
-  text: 'Hello from Matimo!',
-});
-```
-
-See [Three Integration Patterns](#three-integration-patterns) and [examples/](./examples) for more.
-
-## What's Included
-
-Matimo ships with built-in support for:
-
-- **Core Tools**: File I/O, Web fetch, Command execution, Code search
-- **Slack Integration**: Send messages, manage channels, read threads
-- **Gmail Integration**: Send/read email, manage threads
-- **GitHub Integration**: Issues, pull requests, releases
-- **Postgres Tools**: Query/modify data with safety checks
-- **HubSpot Tools**: Read/Write data to Hubspot CRM
-- **Auto-Discovery**: Automatic detection of @matimo/\* providers from npm
-- **Matimo CLI**: Tool discovery, installation, and management
-- **OAuth2 Support**: Provider-agnostic authorization for Slack, Gmail, GitHub, etc.
-- **Framework Support**: Factory pattern, Decorator pattern, LangChain, CrewAI
-- **TypeScript SDK**: Full type safety and IDE support
-
-## Why Matimo?
-
-**The Problem:** Every AI framework (LangChain, CrewAI, custom agents, etc.) defines tools differently. You duplicate tool logic across frameworks.
-
-**The Solution:** Define tools **once** in clean YAML, use them **everywhere** — with built-in:
-
-- TypeScript SDK (factory & decorator patterns)
-- LangChain integration (with examples)
-- Matimo CLI (tool discovery & management)
-- Auto-discovery from npm packages
-- OAuth2 support + parameter validation
-
-See [Contributing](./CONTRIBUTING.md) for details.
-
----
-
-## Three Integration Patterns
-
-### 1️⃣ Factory Pattern (Simplest)
-
-```typescript
-const matimo = await MatimoInstance.init({ autoDiscover: true });
-const result = await matimo.execute('calculator', { operation: 'add', a: 5, b: 3 });
-```
-
-### 2️⃣ Decorator Pattern (Class-Based)
-
-```typescript
-@tool('slack-send-message')
-async sendMessage(channel: string, text: string) { /* Auto-executed */ }
-```
-
-### 3️⃣ LangChain Integration
-
-```typescript
-const tools = matimo.listTools().map(tool => ({
-  type: 'function',
-  function: { name: tool.name, description: tool.description, ... }
-}));
-```
-
-See [SDK Usage Patterns](./docs/user-guide/SDK_PATTERNS.md) and [LangChain Integration](./docs/framework-integrations/LANGCHAIN.md) for details.
-
----
-
-## Installation
-
-### From npm (Recommended)
-
-```bash
-npm install matimo
-
-# Install tool providers
-npm install @matimo/slack @matimo/gmail
-```
-
-Then use with auto-discovery:
-
-```typescript
-const matimo = await MatimoInstance.init({ autoDiscover: true });
-```
-
-### Matimo CLI (Tool Management)
-
-```bash
-npm install -g @matimo/cli
-
-matimo list      # Show installed packages
-matimo search email  # Find tools
-matimo install slack # Install tools
-```
-
-See [CLI Docs](./packages/cli/README.md) for full reference.
-
-### From Source (Contributors)
-
-```bash
-git clone https://github.com/tallclub/matimo
-cd matimo && pnpm install && pnpm build
-pnpm test
-cd examples/tools && pnpm install && pnpm agent:factory
-```
-
----
-
-## Features **Coming Soon:**
-
-- More tool providers (Stripe, Twilio, Notion, etc.)
-- Python SDK
-- Custom Tool Marketplace
-- MCP Server support
-
----
-
-## Adding Tools to Matimo
-
-If you build @matimo/<provider> following this pattern, we’ll list it in the official docs and README with you as maintainer.
-
-Create tool providers as independent npm packages:
-
-```bash
-mkdir packages/github
-cd packages/github && cat > package.json << 'EOF'
-{ "name": "@matimo/github", "type": "module", ... }
-EOF
-
-mkdir tools/github-create-issue
-cat > tools/github-create-issue/definition.yaml << 'EOF'
-name: github-create-issue
-parameters:
-  owner: { type: string, required: true }
-  repo: { type: string, required: true }
-  title: { type: string, required: true }
-execution:
-  type: http
-  method: POST
-  url: https://api.github.com/repos/{owner}/{repo}/issues
-  headers:
-    Authorization: "Bearer {GITHUB_TOKEN}"
-EOF
-```
-
-Then publish to npm as `@matimo/github`. Users install and auto-discover:
-
-```bash
-npm install @matimo/github
-# New tools automatically available!
-const matimo = await MatimoInstance.init({ autoDiscover: true });
-```
-
-See [Adding Tools to Matimo](./docs/tool-development/ADDING_TOOLS.md) for the complete 6-step guide.
-
----
-
-## Documentation
-
-- [Getting Started](./docs/getting-started/)
-- [API Reference](./docs/api-reference/SDK.md)
-- [Tool Development](./docs/tool-development/ADDING_TOOLS.md)
-- [Architecture Overview](./docs/architecture/OVERVIEW.md)
-- [Contributing](./CONTRIBUTING.md)
-
----
-
-## License
-
-MIT © 2026 Matimo Contributors
-
----
-
-## Support the Project
-
-- ⭐ Star the repo
-- 🐛 Open issues for bugs or features
-- 🔀 Submit PRs (see [Contributing](./CONTRIBUTING.md))
-  Best way to help: add a new provider (Notion, Jira, Stripe, Twilio…) or expand existing toolsets.
-- 📢 Share on Twitter, Reddit, Discord
-
----
-
-## Contributors
-
-<a href="https://github.com/tallclub/matimo/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=tallclub/matimo" />
-</a>
-
----
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=tallclub/matimo&type=Date)](https://star-history.com/#tallclub/matimo&Date)