@matimo/core 0.1.0-alpha.8 → 0.1.0

package/dist/matimo-instance.js

@@ -1,28 +1,104 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _MatimoInstance_instances, _a, _MatimoInstance_policy, _MatimoInstance_integrityTracker, _MatimoInstance_approvalManifest, _MatimoInstance_onEvent, _MatimoInstance_hitlCallback, _MatimoInstance_hitlTimeoutMs, _MatimoInstance_trustedPaths, _MatimoInstance_untrustedPaths, _MatimoInstance_policyFile, _MatimoInstance_emitEvent, _MatimoInstance_resolveHITL;
+import fs from 'fs';
 import path from 'path';
 import { ToolLoader } from './core/tool-loader';
 import { ToolRegistry } from './core/tool-registry';
+import { SkillLoader } from './core/skill-loader';
+import { SkillRegistry } from './core/skill-registry';
 import { CommandExecutor } from './executors/command-executor';
 import { HttpExecutor } from './executors/http-executor';
 import { FunctionExecutor } from './executors/function-executor';
 import { MatimoError, ErrorCode } from './errors/matimo-error';
 import { getLoggerConfig, createLogger, setGlobalMatimoLogger, } from './logging';
 import { getGlobalApprovalHandler } from './approval/approval-handler';
+import { DefaultPolicyEngine } from './policy/default-policy';
+import { loadPolicyFromFile } from './policy/policy-loader';
+import { ToolIntegrityTracker } from './policy/integrity-tracker';
+import { ApprovalManifest } from './policy/approval-manifest';
+/**
+ * Find the core skills directory by walking up from process.cwd().
+ * Works in CJS (Jest), ESM (tsx), compiled dist, and on all platforms.
+ */
+function findCoreSkillsPath() {
+    let dir = process.cwd();
+    for (let i = 0; i < 20; i++) {
+        const candidate = path.join(dir, 'packages', 'core', 'skills');
+        if (fs.existsSync(candidate))
+            return candidate;
+        // Also check node_modules/@matimo/core/skills
+        const nmCandidate = path.join(dir, 'node_modules', '@matimo', 'core', 'skills');
+        if (fs.existsSync(nmCandidate))
+            return nmCandidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
 /**
  * Matimo Instance - Single initialization point for tool execution
  * Combines loader, registry, and executors into one interface
  */
 export class MatimoInstance {
-    constructor(toolPaths, logger) {
+    constructor(toolPaths, skillPaths, logger, policyOptions) {
+        _MatimoInstance_instances.add(this);
+        // Policy engine fields — runtime-enforced encapsulation via ES #private
+        _MatimoInstance_policy.set(this, void 0);
+        _MatimoInstance_integrityTracker.set(this, void 0);
+        _MatimoInstance_approvalManifest.set(this, void 0);
+        _MatimoInstance_onEvent.set(this, void 0);
+        _MatimoInstance_hitlCallback.set(this, void 0);
+        _MatimoInstance_hitlTimeoutMs.set(this, void 0);
+        _MatimoInstance_trustedPaths.set(this, void 0);
+        _MatimoInstance_untrustedPaths.set(this, void 0);
+        _MatimoInstance_policyFile.set(this, void 0);
         this.toolPaths = toolPaths;
+        this.skillPaths = skillPaths;
         this.logger = logger;
         this.loader = new ToolLoader();
         this.registry = new ToolRegistry();
+        this.skillLoader = new SkillLoader();
+        this.skillRegistry = new SkillRegistry();
         // Use the first path (primary) as working directory for command executor
         const workingDir = toolPaths.length > 0 ? path.dirname(toolPaths[0]) : process.cwd();
         this.commandExecutor = new CommandExecutor(workingDir);
         this.httpExecutor = new HttpExecutor();
         this.functionExecutor = new FunctionExecutor(toolPaths[0] || '');
         this.approvalHandler = getGlobalApprovalHandler();
+        // Policy engine setup
+        __classPrivateFieldSet(this, _MatimoInstance_policy, policyOptions?.policy ?? null, "f");
+        __classPrivateFieldSet(this, _MatimoInstance_trustedPaths, policyOptions?.trustedPaths ?? [], "f");
+        __classPrivateFieldSet(this, _MatimoInstance_untrustedPaths, policyOptions?.untrustedPaths ?? [], "f");
+        __classPrivateFieldSet(this, _MatimoInstance_integrityTracker, new ToolIntegrityTracker(), "f");
+        __classPrivateFieldSet(this, _MatimoInstance_onEvent, policyOptions?.onEvent ?? null, "f");
+        __classPrivateFieldSet(this, _MatimoInstance_hitlCallback, policyOptions?.onHITL ?? null, "f");
+        __classPrivateFieldSet(this, _MatimoInstance_hitlTimeoutMs, policyOptions?.hitlTimeoutMs ?? null, "f");
+        __classPrivateFieldSet(this, _MatimoInstance_policyFile, policyOptions?.policyFile ?? null, "f");
+        // Approval manifest
+        if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f")) {
+            const approvalDir = policyOptions?.approvalDir ?? process.cwd();
+            __classPrivateFieldSet(this, _MatimoInstance_approvalManifest, new ApprovalManifest(approvalDir, policyOptions?.approvalSecret, policyOptions?.approvalTtlSeconds), "f");
+        }
+        else {
+            __classPrivateFieldSet(this, _MatimoInstance_approvalManifest, null, "f");
+        }
+        // Freeze policy to prevent runtime mutation by agents.
+        // (The SDK's own reloadPolicy() bypasses the frozen reference by replacing #policy.)
+        if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f")) {
+            Object.freeze(__classPrivateFieldGet(this, _MatimoInstance_policy, "f"));
+        }
     }
     /**
      * Initialize Matimo with tools from directory or auto-discovery
@@ -82,27 +158,85 @@ export class MatimoInstance {
             autoDiscover: finalOptions.autoDiscover,
         });
         const toolPaths = [];
+        const skillPaths = [];
         // Include core tools (calculator, etc.) - currently not used in monorepo
         // Use explicit toolPaths or autoDiscover instead
         // if (finalOptions.includeCore) { ... }
-        // Add explicit paths
+        // Add explicit tool paths
         if (finalOptions.toolPaths) {
             toolPaths.push(...finalOptions.toolPaths);
             logger.debug(`Adding explicit tool paths`, { count: finalOptions.toolPaths.length });
         }
+        // Add explicit skill paths (include core skills by default)
+        if (finalOptions.skillPaths) {
+            skillPaths.push(...finalOptions.skillPaths);
+            logger.debug(`Adding explicit skill paths`, { count: finalOptions.skillPaths.length });
+        }
+        // Always include core skills bundled with Matimo
+        const coreSkillsPath = findCoreSkillsPath();
+        if (coreSkillsPath && !skillPaths.includes(coreSkillsPath)) {
+            skillPaths.push(coreSkillsPath);
+            logger.debug(`Including core skills`, { path: coreSkillsPath });
+        }
         // Auto-discover @matimo/* packages
         if (finalOptions.autoDiscover) {
             const discoveredPaths = new ToolLoader().autoDiscoverPackages();
             toolPaths.push(...discoveredPaths);
             logger.debug(`Auto-discovered tool paths`, { count: discoveredPaths.length });
+            // Also discover skill paths from the same @matimo/* packages
+            // Each discovered tool path is like @matimo/slack/tools/ — sibling skills/ may exist
+            for (const toolPath of discoveredPaths) {
+                const pkgDir = path.dirname(toolPath); // e.g. @matimo/slack/
+                const pkgSkillsPath = path.join(pkgDir, 'skills');
+                if (fs.existsSync(pkgSkillsPath) && !skillPaths.includes(pkgSkillsPath)) {
+                    skillPaths.push(pkgSkillsPath);
+                }
+            }
+            logger.debug(`Auto-discovered skill paths`, { count: skillPaths.length });
+        }
+        // Build policy engine
+        let policy = null;
+        if (finalOptions.policy) {
+            policy = finalOptions.policy;
+        }
+        else if (finalOptions.policyFile) {
+            policy = loadPolicyFromFile(finalOptions.policyFile);
         }
-        const instance = new MatimoInstance(toolPaths, logger);
+        else if (finalOptions.policyConfig) {
+            policy = new DefaultPolicyEngine(finalOptions.policyConfig);
+        }
+        const instance = new _a(toolPaths, skillPaths, logger, {
+            policy,
+            trustedPaths: finalOptions.trustedPaths,
+            untrustedPaths: finalOptions.untrustedPaths,
+            approvalSecret: finalOptions.approvalSecret,
+            approvalDir: finalOptions.approvalDir,
+            onEvent: finalOptions.onEvent,
+            onHITL: finalOptions.onHITL,
+            hitlTimeoutMs: finalOptions.hitlTimeoutMs,
+            approvalTtlSeconds: finalOptions.approvalTtlSeconds,
+            policyFile: finalOptions.policyFile,
+        });
         // Load tools from all paths
         const allTools = instance.loader.loadToolsFromMultiplePaths(toolPaths);
         instance.registry.registerAll(Array.from(allTools.values()));
+        // Load skills from all paths
+        for (const skillPath of skillPaths) {
+            try {
+                const skillsFromPath = instance.skillLoader.loadSkillsFromDirectory(skillPath, skillPath.includes('core') ? 'builtin' : 'user');
+                instance.skillRegistry.registerAll(skillsFromPath);
+            }
+            catch (err) {
+                logger.warn(`Failed to load skills from path: ${skillPath}`, {
+                    error: err.message,
+                });
+            }
+        }
         logger.info(`Matimo SDK initialized successfully`, {
             toolCount: allTools.size,
+            skillCount: instance.skillRegistry.count(),
             paths: toolPaths.length,
+            skillPaths: skillPaths.length,
         });
         return instance;
     }
@@ -121,12 +255,19 @@ export class MatimoInstance {
         return this.logger;
     }
     /**
-     * Execute a tool by name with parameters
+     * Execute a tool by name with parameters.
+     *
      * @param toolName - Name of the tool to execute
      * @param params - Tool parameters
+     * @param options - Optional execution options
+     * @param options.timeout - Execution timeout in milliseconds
+     * @param options.credentials - Per-call credential overrides (multi-tenant support).
+     *   Keys must match the env-var names the tool references (e.g. `SLACK_BOT_TOKEN`).
+     *   When provided, they take precedence over `process.env` for that single call.
+     *   Values are never logged and held in memory only for the duration of the call.
      * @returns Tool execution result
      */
-    async execute(toolName, params) {
+    async execute(toolName, params, options) {
         const tool = this.registry.get(toolName);
         if (!tool) {
             const availableTools = this.registry.getAll().map((t) => t.name);
@@ -144,6 +285,38 @@ export class MatimoInstance {
             paramCount: Object.keys(params).length,
         });
         try {
+            // Policy check: enforce RBAC and tool status before any execution
+            if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f")) {
+                const policyContext = options?.context ?? {};
+                const decision = __classPrivateFieldGet(this, _MatimoInstance_policy, "f").canExecute(policyContext, tool);
+                if (decision.allowed === false) {
+                    __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+                        type: 'tool:execution_denied',
+                        toolName,
+                        reason: decision.reason,
+                        agentId: policyContext.agentId,
+                        timestamp: new Date().toISOString(),
+                    });
+                    throw new MatimoError(`Policy denied execution of '${toolName}': ${decision.reason}`, ErrorCode.POLICY_DENIED, { toolName, reason: decision.reason, riskLevel: decision.riskLevel });
+                }
+                // Handle quarantined tools — check approval manifest or invoke HITL callback
+                if (decision.allowed === 'pending_approval') {
+                    const approved = await __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_resolveHITL).call(this, tool, decision, policyContext);
+                    if (!approved) {
+                        __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+                            type: 'tool:quarantine_rejected',
+                            toolName,
+                            timestamp: new Date().toISOString(),
+                        });
+                        throw new MatimoError(`Tool '${toolName}' is quarantined and was not approved: ${decision.reason}`, ErrorCode.POLICY_DENIED, { toolName, reason: decision.reason, riskLevel: decision.riskLevel });
+                    }
+                    __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+                        type: 'tool:quarantine_approved',
+                        toolName,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+            }
             // Simple approval flow:
             // 1. Check if tool requires approval (from YAML or keyword detection)
             // 2. Check if pre-approved via env vars
@@ -171,7 +344,12 @@ export class MatimoInstance {
                     scanContent = parts.join(' ');
             }
             const requiresApproval = this.approvalHandler.requiresApproval(tool.requires_approval, scanContent);
-            if (requiresApproval && !this.approvalHandler.isPreApproved(toolName)) {
+            // Skip approval prompt if options.approved=true (e.g., MCP pre-confirmed approval).
+            // This avoids mutating global state in concurrent scenarios.
+            const skipApprovalPrompt = options?.approved === true;
+            if (requiresApproval &&
+                !this.approvalHandler.isPreApproved(toolName) &&
+                !skipApprovalPrompt) {
                 this.logger.debug(`Approval required for: ${toolName}`, { toolName });
                 await this.approvalHandler.requestApproval({
                     toolName,
@@ -180,10 +358,42 @@ export class MatimoInstance {
                 });
                 this.logger.info(`Destructive operation approved: ${toolName}`, { toolName });
             }
-            // Auto-inject authentication parameters from environment variables
-            const finalParams = this.injectAuthParameters(tool, params);
-            const executor = this.getExecutor(tool);
-            const result = await executor.execute(tool, finalParams);
+            const credentials = options?.credentials;
+            const timeoutOverride = options?.timeout;
+            // Auto-inject authentication parameters. When per-call credentials are
+            // supplied they take precedence over process.env (multi-tenant support).
+            const finalParams = this.injectAuthParameters(tool, params, credentials);
+            // After injection, detect any auth-looking placeholders that are still unfilled.
+            // This gives a clear actionable error instead of silently sending a bad header to the API.
+            this.assertAuthParamsFilled(tool, finalParams, credentials);
+            // Apply per-call timeout override if provided. Create a shallow copy so the
+            // registered tool definition is never mutated between calls.
+            // Built-in interception: matimo_reload_tools must run on the instance
+            // itself because reloadTools() clears/rebuilds the in-memory registry.
+            // The function executor has no reference to the MatimoInstance, so we
+            // handle it directly here. This works identically for SDK, LangChain,
+            // and MCP callers.
+            if (toolName === 'matimo_reload_tools') {
+                const reloadResult = await this.reloadTools();
+                this.logger.info('matimo_reload_tools: reload completed', {
+                    loaded: reloadResult.loaded,
+                    removed: reloadResult.removed,
+                    rejected: reloadResult.rejected.length,
+                });
+                return {
+                    success: true,
+                    loaded: reloadResult.loaded,
+                    removed: reloadResult.removed,
+                    revalidated: reloadResult.revalidated,
+                    rejected: reloadResult.rejected,
+                    message: `Reload complete. ${reloadResult.loaded} tools loaded, ${reloadResult.removed} removed, ${reloadResult.rejected.length} rejected.`,
+                };
+            }
+            const effectiveTool = timeoutOverride !== undefined
+                ? { ...tool, execution: { ...tool.execution, timeout: timeoutOverride } }
+                : tool;
+            const executor = this.getExecutor(effectiveTool);
+            const result = await executor.execute(effectiveTool, finalParams, credentials);
             this.logger.debug(`Tool executed successfully: ${toolName}`, {
                 toolName,
                 hasResult: !!result,
@@ -207,34 +417,201 @@ export class MatimoInstance {
         return this.registry.get(toolName);
     }
     /**
-     * List all available tools
+     * List all available tools, optionally filtered by policy.
+     * @param context - PolicyContext for filtering. If omitted and policy is active, returns all tools (backward compatible).
      * @returns Array of tool definitions
      */
-    listTools() {
-        return this.registry.getAll();
+    listTools(context) {
+        const tools = this.registry.getAll();
+        if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f") && context) {
+            return __classPrivateFieldGet(this, _MatimoInstance_policy, "f").filterForAgent(context, tools);
+        }
+        return tools;
     }
     /**
      * Get all available tools (alias for listTools)
      * @returns Array of tool definitions
      */
-    getAllTools() {
-        return this.registry.getAll();
+    getAllTools(context) {
+        return this.listTools(context);
+    }
+    /**
+     * Return only the tools this agent context is permitted to use.
+     * Mirrors: Matimo.get_tools_for_agent() in Python SDK.
+     *
+     * @param context - PolicyContext (agentId, roles, environment)
+     * @returns Tools permitted for this context, filtered through the policy engine
+     */
+    getToolsForAgent(context) {
+        const tools = this.registry.getAll();
+        if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f")) {
+            return __classPrivateFieldGet(this, _MatimoInstance_policy, "f").filterForAgent(context, tools);
+        }
+        return tools;
     }
     /**
      * Search tools by name or description
      * @param query - Search query
      * @returns Matching tools
      */
-    searchTools(query) {
-        return this.registry.search(query);
+    searchTools(query, context) {
+        const results = this.registry.search(query);
+        if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f") && context) {
+            return __classPrivateFieldGet(this, _MatimoInstance_policy, "f").filterForAgent(context, results);
+        }
+        return results;
     }
     /**
      * Get tools by tag
      * @param tag - Tag to search for
      * @returns Tools with the given tag
      */
-    getToolsByTag(tag) {
-        return this.registry.getByTag(tag);
+    getToolsByTag(tag, context) {
+        const results = this.registry.getByTag(tag);
+        if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f") && context) {
+            return __classPrivateFieldGet(this, _MatimoInstance_policy, "f").filterForAgent(context, results);
+        }
+        return results;
+    }
+    /**
+     * Return the credential key names that a tool expects.
+     *
+     * This lets multi-tenant callers know exactly what to put in `options.credentials`
+     * without having to read the tool's YAML definition.
+     *
+     * The returned strings are the keys you pass to `execute()`:
+     * ```typescript
+     * const keys = matimo.getRequiredCredentials('slack-send-message');
+     * // → ['SLACK_BOT_TOKEN']
+     *
+     * // Then collect from your secrets store:
+     * const credentials = Object.fromEntries(
+     *   keys.map(k => [k, tenant.secrets[k]])
+     * );
+     * await matimo.execute('slack-send-message', params, { credentials });
+     * ```
+     *
+     * @param toolName - Exact tool name
+     * @returns Array of credential key names (may be empty if the tool needs no auth)
+     * @throws `MatimoError(TOOL_NOT_FOUND)` if the tool doesn't exist
+     */
+    getRequiredCredentials(toolName) {
+        const tool = this.registry.get(toolName);
+        if (!tool) {
+            throw new MatimoError(`Tool '${toolName}' not found in registry`, ErrorCode.TOOL_NOT_FOUND, {
+                toolName,
+                availableTools: this.registry.getAll().map((t) => t.name),
+            });
+        }
+        const authPatterns = [
+            'token',
+            'key',
+            'secret',
+            'password',
+            'credential',
+            'auth',
+            'bearer',
+            'api_key',
+        ];
+        const referencedParams = this.extractParameterPlaceholders(tool);
+        const credentialKeys = [];
+        for (const paramName of referencedParams) {
+            const lowerName = paramName.toLowerCase();
+            if (authPatterns.some((pattern) => lowerName.includes(pattern))) {
+                credentialKeys.push(paramName);
+            }
+        }
+        // Also include basic-auth env var names declared in authentication config
+        const auth = tool.authentication;
+        if (auth?.type === 'basic') {
+            if (auth.username_env && !credentialKeys.includes(auth.username_env)) {
+                credentialKeys.push(auth.username_env);
+            }
+            if (auth.password_env && !credentialKeys.includes(auth.password_env)) {
+                credentialKeys.push(auth.password_env);
+            }
+        }
+        return credentialKeys;
+    }
+    // ─── Skills API ──────────────────────────────────────────────────────────
+    /**
+     * List all available skills (Level 1 discovery - minimal context)
+     * @returns Array of skill summaries
+     */
+    listSkills() {
+        return this.skillRegistry.list();
+    }
+    /**
+     * Get a single skill by name (Level 2 activation - full content)
+     * @param name - Skill name
+     * @returns Skill definition or null
+     */
+    getSkill(name) {
+        return this.skillRegistry.get(name) || null;
+    }
+    /**
+     * Get selective skill content — only the sections an agent needs.
+     * Prevents dumping entire SKILL.md files into the LLM context window.
+     *
+     * @example
+     * // Get only error handling, max 500 tokens
+     * matimo.getSkillContent('postgres-query-operations', {
+     *   sections: ['Error Handling'],
+     *   maxTokens: 500,
+     * })
+     */
+    getSkillContent(name, options) {
+        return this.skillRegistry.getSkillContent(name, options);
+    }
+    /**
+     * List all sections of a skill with their token costs.
+     * Agents use this to decide which sections to load before activating.
+     */
+    getSkillSections(name) {
+        return this.skillRegistry.getSkillSections(name);
+    }
+    /**
+     * Search skills by keyword, category, difficulty, etc.
+     * Set `options.semantic = true` for embedding-based similarity ranking.
+     * @param options - Search options
+     * @returns Matching skills
+     */
+    searchSkills(options = {}) {
+        return this.skillRegistry.search(options);
+    }
+    /**
+     * Semantic search with relevance scores.
+     * Uses embeddings to find skills by meaning, not just keywords.
+     *
+     * @example
+     * const results = await matimo.semanticSearchSkills('How do I handle Postgres locking?');
+     * // → [{ skill: { name: 'postgres-query-operations' }, score: 0.82 }]
+     */
+    async semanticSearchSkills(query, options) {
+        return this.skillRegistry.semanticSearch(query, options);
+    }
+    /**
+     * Set a custom embedding provider for semantic skill search.
+     * If not set, a built-in TF-IDF provider is used.
+     */
+    setSkillEmbeddingProvider(provider) {
+        this.skillRegistry.setEmbeddingProvider(provider);
+    }
+    /**
+     * Get a bundled resource from a skill (Level 3 resources)
+     * @param skillName - Skill name
+     * @param resourcePath - Relative path to resource (e.g., "scripts/extract.py")
+     * @returns Resource content
+     */
+    getSkillResource(skillName, resourcePath) {
+        return this.skillLoader.loadSkillResource(skillName, this.skillPaths[0], resourcePath);
+    }
+    /**
+     * Get all skill paths
+     * @returns Array of skill paths
+     */
+    getSkillPaths() {
+        return [...this.skillPaths];
     }
     /**
      * Automatically inject parameters from environment variables
@@ -242,19 +619,15 @@ export class MatimoInstance {
      *
      * 1. Scans the execution config for all parameter placeholders
      * 2. For each parameter not provided by user, checks if it looks like auth (TOKEN, KEY, SECRET, etc.)
-     * 3. If yes, attempts to load from environment: MATIMO_<PARAM_NAME> or <PARAM_NAME>
-     *
-     * This works for ANY tool with ANY auth parameter name - no hardcoding needed.
-     * Scales to unlimited tools - contributors just submit YAML.
+     * 3. If yes, attempts to load from (in order of priority):
+     *    a. `credentials[paramName]`          — per-call override (multi-tenant)
+     *    b. `credentials[MATIMO_${paramName}]` — prefixed per-call override
+     *    c. `process.env[MATIMO_${paramName}]` — prefixed env var
+     *    d. `process.env[paramName]`           — direct env var
      *
-     * Examples:
-     * - GMAIL_ACCESS_TOKEN → looks in env vars
-     * - GITHUB_TOKEN → looks in env vars
-     * - SLACK_BOT_TOKEN → looks in env vars
-     * - MY_CUSTOM_API_KEY → looks in env vars
-     * - ANY_SECRET → looks in env vars
-     */
-    injectAuthParameters(tool, params) {
+     * Credential values are never logged.
+     */
+    injectAuthParameters(tool, params, credentials) {
         const result = { ...params };
         // Collect all parameter names referenced in the execution config
         const referencedParams = this.extractParameterPlaceholders(tool);
@@ -279,21 +652,79 @@ export class MatimoInstance {
             const lowerName = paramName.toLowerCase();
             const isAuthParam = authPatterns.some((pattern) => lowerName.includes(pattern));
             if (isAuthParam) {
-                // Try to load from environment
-                // First try MATIMO_ prefixed version for organization
-                let envValue = process.env[`MATIMO_${paramName}`];
-                // If not found, try the parameter name directly
-                if (!envValue) {
-                    envValue = process.env[paramName];
+                // Lookup order:
+                // 1. Per-call credentials (multi-tenant override — never touches process.env)
+                // 2. Per-call credentials with MATIMO_ prefix
+                // 3. Environment variable with MATIMO_ prefix
+                // 4. Environment variable with the exact param name
+                let resolvedValue;
+                if (credentials) {
+                    resolvedValue = credentials[paramName] ?? credentials[`MATIMO_${paramName}`];
+                }
+                if (!resolvedValue) {
+                    resolvedValue = process.env[`MATIMO_${paramName}`] ?? process.env[paramName];
                 }
-                // If found, inject it
-                if (envValue) {
-                    result[paramName] = envValue;
+                if (resolvedValue) {
+                    result[paramName] = resolvedValue;
                 }
             }
         }
         return result;
     }
+    /**
+     * After injectAuthParameters(), verify no auth-looking placeholders remain unfilled.
+     * Only checks HTTP headers (where auth credentials are injected) — not query params or body.
+     * Throws AUTH_FAILED with actionable guidance naming the missing env var(s).
+     */
+    assertAuthParamsFilled(tool, finalParams, credentials) {
+        const execution = tool.execution;
+        if (!('headers' in execution) || !execution.headers)
+            return;
+        const authPatterns = [
+            'token',
+            'key',
+            'secret',
+            'password',
+            'credential',
+            'auth',
+            'bearer',
+            'api_key',
+        ];
+        const placeholderRegex = /\{([^}]+)\}/g;
+        const missing = [];
+        // Only inspect headers — auth credentials belong there, not in query_params or body
+        for (const [headerName, headerValue] of Object.entries(execution.headers)) {
+            if (typeof headerValue !== 'string')
+                continue;
+            // Only check headers that look auth-related (Authorization, X-API-Key, etc.)
+            const lowerHeader = headerName.toLowerCase();
+            const isAuthHeader = lowerHeader === 'authorization' ||
+                lowerHeader.includes('auth') ||
+                lowerHeader.includes('token') ||
+                lowerHeader.includes('key') ||
+                lowerHeader.includes('secret');
+            if (!isAuthHeader)
+                continue;
+            let match;
+            placeholderRegex.lastIndex = 0;
+            while ((match = placeholderRegex.exec(headerValue)) !== null) {
+                const paramName = match[1];
+                if (paramName in finalParams)
+                    continue;
+                const lowerName = paramName.toLowerCase();
+                if (authPatterns.some((p) => lowerName.includes(p))) {
+                    missing.push(paramName);
+                }
+            }
+        }
+        if (missing.length === 0)
+            return;
+        const hints = missing
+            .map((n) => `  • ${n}  →  MATIMO_${n} (or pass via credentials option)`)
+            .join('\n');
+        const credentialsHint = credentials ? '' : '  (No per-call credentials were supplied.)';
+        throw new MatimoError(`Authentication credentials are missing for tool "${tool.name}".\n${hints}\n${credentialsHint}`.trim(), ErrorCode.AUTH_FAILED, { toolName: tool.name, missingCredentials: missing });
+    }
     /**
      * Extract all parameter placeholders from execution config
      * Scans headers, body, URL, and query_params for {paramName} patterns
@@ -395,7 +826,275 @@ export class MatimoInstance {
                 throw new MatimoError(`Unsupported execution type: ${executionType}`, ErrorCode.EXECUTION_FAILED, { executionType });
         }
     }
+    /**
+     * Hot-reload tools from all configured paths.
+     * Re-validates untrusted tools via content validator and integrity tracker.
+     * Tools that fail validation are rejected and not loaded.
+     *
+     * Atomic: if loading fails mid-way (e.g. I/O error), the registry is restored
+     * to its previous state and `rolledBack: true` is included in the result.
+     */
+    async reloadTools() {
+        const previousNames = new Set(this.registry.getAll().map((t) => t.name));
+        // Snapshot the previous registry state for rollback on partial failure
+        const snapshot = this.registry.getAll();
+        this.registry.clear();
+        const result = {
+            loaded: 0,
+            removed: 0,
+            revalidated: 0,
+            rejected: [],
+            rolledBack: false,
+        };
+        let allTools;
+        try {
+            allTools = this.loader.loadToolsFromMultiplePaths(this.toolPaths);
+        }
+        catch (err) {
+            // I/O failure during load — restore snapshot and signal rollback
+            this.registry.registerAll(snapshot);
+            result.rolledBack = true;
+            this.logger.error('reloadTools: failed to load tools, rolled back to previous state', {
+                error: err.message,
+            });
+            return result;
+        }
+        const untrustedSet = new Set(__classPrivateFieldGet(this, _MatimoInstance_untrustedPaths, "f"));
+        for (const [, tool] of allTools) {
+            const defPath = tool._definitionPath ?? '';
+            const isUntrusted = untrustedSet.size > 0 && __classPrivateFieldGet(this, _MatimoInstance_untrustedPaths, "f").some((up) => defPath.startsWith(up));
+            if (isUntrusted && __classPrivateFieldGet(this, _MatimoInstance_policy, "f")) {
+                // Run policy validation on untrusted tools
+                const policyDecision = __classPrivateFieldGet(this, _MatimoInstance_policy, "f").canCreate({}, tool);
+                if (policyDecision.allowed === false) {
+                    result.rejected.push(tool.name);
+                    __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+                        type: 'tool:rejected',
+                        toolName: tool.name,
+                        violations: [
+                            { rule: 'policy-denied', severity: 'high', message: policyDecision.reason },
+                        ],
+                        timestamp: new Date().toISOString(),
+                    });
+                    this.logger.warn(`Tool rejected during reload: ${tool.name}`, {
+                        reason: policyDecision.reason,
+                    });
+                    continue;
+                }
+                if (policyDecision.allowed === 'pending_approval') {
+                    // Quarantine: mark as pending in the approval manifest
+                    if (__classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f")) {
+                        __classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f").markPending(tool.name);
+                    }
+                    __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+                        type: 'tool:quarantined',
+                        toolName: tool.name,
+                        riskLevel: policyDecision.riskLevel,
+                        reason: policyDecision.reason,
+                        timestamp: new Date().toISOString(),
+                    });
+                    this.logger.info(`Tool quarantined during reload: ${tool.name}`, {
+                        riskLevel: policyDecision.riskLevel,
+                        reason: policyDecision.reason,
+                    });
+                    // Still register the tool so it exists, but it will be blocked
+                    // at execution time until approved via the approval manifest
+                    result.revalidated++;
+                }
+                else {
+                    result.revalidated++;
+                }
+            }
+            this.registry.register(tool);
+            const source = isUntrusted ? 'untrusted' : 'trusted';
+            __classPrivateFieldGet(this, _MatimoInstance_integrityTracker, "f").record(tool.name, JSON.stringify(tool), source);
+            result.loaded++;
+        }
+        // Calculate removed tools
+        const currentNames = new Set(this.registry.getAll().map((t) => t.name));
+        for (const name of previousNames) {
+            if (!currentNames.has(name)) {
+                result.removed++;
+                __classPrivateFieldGet(this, _MatimoInstance_integrityTracker, "f").removeEntry(name);
+            }
+        }
+        __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+            type: 'tools:reloaded',
+            loaded: result.loaded,
+            removed: result.removed,
+            rejected: result.rejected,
+            timestamp: new Date().toISOString(),
+        });
+        this.logger.info('Tools reloaded', {
+            loaded: result.loaded,
+            removed: result.removed,
+            revalidated: result.revalidated,
+            rejected: result.rejected.length,
+        });
+        return result;
+    }
+    /**
+     * Check if a policy engine is active.
+     */
+    hasPolicy() {
+        return __classPrivateFieldGet(this, _MatimoInstance_policy, "f") !== null;
+    }
+    /**
+     * Get the approval manifest (if policy engine is active).
+     */
+    getApprovalManifest() {
+        return __classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f");
+    }
+    /**
+     * Get the integrity tracker.
+     */
+    getIntegrityTracker() {
+        return __classPrivateFieldGet(this, _MatimoInstance_integrityTracker, "f");
+    }
+    /**
+     * Get the tool registry (for advanced use cases).
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Set a Human-in-the-Loop callback for quarantined tools.
+     * The callback is invoked when a tool with `pending_approval` status is executed.
+     * Return `true` to approve, `false` to reject.
+     */
+    setHITLCallback(callback) {
+        __classPrivateFieldSet(this, _MatimoInstance_hitlCallback, callback, "f");
+    }
+    /**
+     * Hot-reload the policy engine at runtime.
+     *
+     * - If `configOrFile` is a `PolicyConfig` object, creates a new `DefaultPolicyEngine`.
+     * - If `configOrFile` is a string, re-reads and parses the YAML file.
+     * - If omitted and the instance was initialized with `policyFile`, re-reads that file.
+     *
+     * The new policy is validated before swap — if validation fails, the old policy remains active.
+     * After swap, all tools are re-validated against the new policy via `reloadTools()`.
+     *
+     * @returns The ReloadResult from the subsequent tool re-validation.
+     */
+    async reloadPolicy(configOrFile) {
+        let newPolicy;
+        if (typeof configOrFile === 'string') {
+            // Re-read from file path
+            newPolicy = loadPolicyFromFile(configOrFile);
+            __classPrivateFieldSet(this, _MatimoInstance_policyFile, configOrFile, "f");
+        }
+        else if (configOrFile) {
+            // Build from inline config
+            newPolicy = new DefaultPolicyEngine(configOrFile);
+        }
+        else if (__classPrivateFieldGet(this, _MatimoInstance_policyFile, "f")) {
+            // Re-read the original policy file
+            newPolicy = loadPolicyFromFile(__classPrivateFieldGet(this, _MatimoInstance_policyFile, "f"));
+        }
+        else if (__classPrivateFieldGet(this, _MatimoInstance_policy, "f") && 'updateConfig' in __classPrivateFieldGet(this, _MatimoInstance_policy, "f")) {
+            // No config provided and no file — nothing to reload
+            this.logger.warn('reloadPolicy: no config or file provided, nothing to reload');
+            return {
+                loaded: 0,
+                removed: 0,
+                revalidated: 0,
+                rejected: [],
+            };
+        }
+        else {
+            this.logger.warn('reloadPolicy: no policy engine to reload');
+            return {
+                loaded: 0,
+                removed: 0,
+                revalidated: 0,
+                rejected: [],
+            };
+        }
+        // Atomic swap: replace the policy engine reference
+        __classPrivateFieldSet(this, _MatimoInstance_policy, newPolicy, "f");
+        Object.freeze(__classPrivateFieldGet(this, _MatimoInstance_policy, "f"));
+        __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+            type: 'policy:reloaded',
+            timestamp: new Date().toISOString(),
+        });
+        this.logger.info('Policy engine reloaded');
+        // Re-validate all tools against the new policy
+        return this.reloadTools();
+    }
 }
+_a = MatimoInstance, _MatimoInstance_policy = new WeakMap(), _MatimoInstance_integrityTracker = new WeakMap(), _MatimoInstance_approvalManifest = new WeakMap(), _MatimoInstance_onEvent = new WeakMap(), _MatimoInstance_hitlCallback = new WeakMap(), _MatimoInstance_hitlTimeoutMs = new WeakMap(), _MatimoInstance_trustedPaths = new WeakMap(), _MatimoInstance_untrustedPaths = new WeakMap(), _MatimoInstance_policyFile = new WeakMap(), _MatimoInstance_instances = new WeakSet(), _MatimoInstance_emitEvent = function _MatimoInstance_emitEvent(event) {
+    if (__classPrivateFieldGet(this, _MatimoInstance_onEvent, "f")) {
+        try {
+            __classPrivateFieldGet(this, _MatimoInstance_onEvent, "f").call(this, event);
+        }
+        catch {
+            // Never let event handler errors break SDK execution
+        }
+    }
+}, _MatimoInstance_resolveHITL = 
+/**
+ * Resolve a quarantined tool via HITL callback or approval manifest.
+ *
+ * Resolution order:
+ * 1. Check approval manifest — if already approved, allow.
+ * 2. Invoke HITL callback — if set, ask the human.
+ * 3. If no callback, reject by default (safe fail-closed).
+ */
+async function _MatimoInstance_resolveHITL(tool, decision, context) {
+    // 1. Check approval manifest — previously approved tools pass through
+    if (__classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f")) {
+        const yamlHash = __classPrivateFieldGet(this, _MatimoInstance_integrityTracker, "f").getHash(tool.name);
+        if (yamlHash && __classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f").isApproved(tool.name, yamlHash)) {
+            return true;
+        }
+    }
+    // 2. Invoke HITL callback
+    if (__classPrivateFieldGet(this, _MatimoInstance_hitlCallback, "f")) {
+        __classPrivateFieldGet(this, _MatimoInstance_instances, "m", _MatimoInstance_emitEvent).call(this, {
+            type: 'tool:quarantined',
+            toolName: tool.name,
+            riskLevel: decision.riskLevel,
+            reason: decision.reason,
+            environment: context.environment,
+            timestamp: new Date().toISOString(),
+        });
+        const callbackPromise = __classPrivateFieldGet(this, _MatimoInstance_hitlCallback, "f").call(this, {
+            toolName: tool.name,
+            riskLevel: decision.riskLevel,
+            reason: decision.reason,
+            environment: context.environment,
+            agentId: context.agentId,
+            toolDefinition: tool,
+        });
+        let approved;
+        if (__classPrivateFieldGet(this, _MatimoInstance_hitlTimeoutMs, "f") !== null) {
+            const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(_a.HITL_TIMEOUT_SENTINEL), __classPrivateFieldGet(this, _MatimoInstance_hitlTimeoutMs, "f")));
+            const result = await Promise.race([callbackPromise, timeoutPromise]);
+            if (result === _a.HITL_TIMEOUT_SENTINEL) {
+                this.logger.warn(`HITL callback timed out after ${__classPrivateFieldGet(this, _MatimoInstance_hitlTimeoutMs, "f")}ms for tool '${tool.name}' — auto-rejecting`);
+                approved = false;
+            }
+            else {
+                approved = result;
+            }
+        }
+        else {
+            approved = await callbackPromise;
+        }
+        // If approved, record in manifest for future calls
+        if (approved && __classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f")) {
+            const yamlHash = __classPrivateFieldGet(this, _MatimoInstance_integrityTracker, "f").getHash(tool.name) ??
+                __classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f").computeHash(JSON.stringify(tool));
+            __classPrivateFieldGet(this, _MatimoInstance_approvalManifest, "f").approve(tool.name, yamlHash);
+        }
+        return approved;
+    }
+    // 3. No callback — fail closed
+    return false;
+};
+// Sentinel value used to distinguish HITL timeout from explicit rejection
+MatimoInstance.HITL_TIMEOUT_SENTINEL = Symbol('HITL_TIMEOUT');
 /**
  * Matimo namespace - Entry point for the SDK
  */