@matimo/core 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/matimo-instance.d.ts

@@ -1,21 +1,68 @@
-import { ToolDefinition } from './core/schema';
+import { ToolRegistry } from './core/tool-registry';
+import type { SemanticSearchResult } from './core/skill-registry';
+import { ToolDefinition, SkillDefinition, SkillSummary, SearchSkillsOptions, SkillContentOptions, EmbeddingProvider } from './core/types';
 import { MatimoLogger, LoggerConfig } from './logging';
+import type { ExecuteOptions } from './core/types';
+import type { PolicyEngine, PolicyContext, PolicyConfig, HITLCallback } from './policy/types';
+import { ToolIntegrityTracker } from './policy/integrity-tracker';
+import { ApprovalManifest } from './policy/approval-manifest';
+import type { MatimoEventHandler } from './policy/events';
+/**
+ * Result of a hot-reload operation
+ */
+export interface ReloadResult {
+    loaded: number;
+    removed: number;
+    revalidated: number;
+    rejected: string[];
+    /** True if a mid-load failure caused the registry to be restored to its previous state. */
+    rolledBack?: boolean;
+}
 /**
  * Options for MatimoInstance initialization
  */
 export interface InitOptions extends LoggerConfig {
     toolPaths?: string[];
+    /** Skill paths for discovering SKILL.md files (Level 1 discovery) */
+    skillPaths?: string[];
     autoDiscover?: boolean;
     includeCore?: boolean;
+    /** Custom PolicyEngine implementation. Mutually exclusive with policyConfig and policyFile. */
+    policy?: PolicyEngine;
+    /** Shorthand to create a DefaultPolicyEngine. Ignored if `policy` is provided. */
+    policyConfig?: PolicyConfig;
+    /** Path to a policy.yaml file. Loaded into a DefaultPolicyEngine. Ignored if `policy` is provided. */
+    policyFile?: string;
+    /** Paths containing trusted (developer-authored) tools. Defaults to auto-discovered @matimo/* paths. */
+    trustedPaths?: string[];
+    /** Paths containing untrusted (agent-created) tools. These tools undergo content validation. */
+    untrustedPaths?: string[];
+    /** HMAC secret for approval manifest. Overrides MATIMO_APPROVAL_SECRET env. */
+    approvalSecret?: string;
+    /** Directory for .matimo-approvals.json. Defaults to process.cwd(). */
+    approvalDir?: string;
+    /** Event handler for audit events (tool creation, approval, execution, etc.) */
+    onEvent?: MatimoEventHandler;
+    /**
+     * Human-in-the-loop callback for quarantined tools.
+     * Called when a tool enters `pending_approval` state (medium-risk in prod with enableHITL).
+     * Return `true` to approve, `false` to reject.
+     * If not set, quarantined tools are rejected by default.
+     */
+    onHITL?: HITLCallback;
 }
 /**
  * Matimo Instance - Single initialization point for tool execution
  * Combines loader, registry, and executors into one interface
  */
 export declare class MatimoInstance {
+    #private;
     private toolPaths;
+    private skillPaths;
     private loader;
     private registry;
+    private skillLoader;
+    private skillRegistry;
     private commandExecutor;
     private httpExecutor;
     private functionExecutor;
@@ -59,12 +106,19 @@ export declare class MatimoInstance {
      */
     getLogger(): MatimoLogger;
     /**
-     * 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
      */
-    execute(toolName: string, params: Record<string, unknown>): Promise<unknown>;
+    execute(toolName: string, params: Record<string, unknown>, options?: ExecuteOptions): Promise<unknown>;
     /**
      * Get a tool definition by name
      * @param toolName - Name of the tool
@@ -72,46 +126,140 @@ export declare class MatimoInstance {
      */
     getTool(toolName: string): ToolDefinition | undefined;
     /**
-     * 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(): ToolDefinition[];
+    listTools(context?: PolicyContext): ToolDefinition[];
     /**
      * Get all available tools (alias for listTools)
      * @returns Array of tool definitions
      */
-    getAllTools(): ToolDefinition[];
+    getAllTools(context?: PolicyContext): ToolDefinition[];
     /**
      * Search tools by name or description
      * @param query - Search query
      * @returns Matching tools
      */
-    searchTools(query: string): ToolDefinition[];
+    searchTools(query: string, context?: PolicyContext): ToolDefinition[];
     /**
      * Get tools by tag
      * @param tag - Tag to search for
      * @returns Tools with the given tag
      */
-    getToolsByTag(tag: string): ToolDefinition[];
+    getToolsByTag(tag: string, context?: PolicyContext): ToolDefinition[];
+    /**
+     * 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: string): string[];
+    /**
+     * List all available skills (Level 1 discovery - minimal context)
+     * @returns Array of skill summaries
+     */
+    listSkills(): SkillSummary[];
+    /**
+     * Get a single skill by name (Level 2 activation - full content)
+     * @param name - Skill name
+     * @returns Skill definition or null
+     */
+    getSkill(name: string): SkillDefinition | 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: string, options?: SkillContentOptions): string | null;
+    /**
+     * List all sections of a skill with their token costs.
+     * Agents use this to decide which sections to load before activating.
+     */
+    getSkillSections(name: string): Array<{
+        path: string;
+        level: number;
+        tokenEstimate: number;
+    }> | null;
+    /**
+     * 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?: SearchSkillsOptions): SkillSummary[];
+    /**
+     * 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 }]
+     */
+    semanticSearchSkills(query: string, options?: {
+        limit?: number;
+        minScore?: number;
+    }): Promise<SemanticSearchResult[]>;
+    /**
+     * Set a custom embedding provider for semantic skill search.
+     * If not set, a built-in TF-IDF provider is used.
+     */
+    setSkillEmbeddingProvider(provider: EmbeddingProvider): void;
+    /**
+     * 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: string, resourcePath: string): string;
+    /**
+     * Get all skill paths
+     * @returns Array of skill paths
+     */
+    getSkillPaths(): string[];
     /**
      * Automatically inject parameters from environment variables
      * Uses a YAML-native, scale-friendly approach:
      *
      * 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
+     * Credential values are never logged.
      */
     private injectAuthParameters;
+    /**
+     * 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).
+     */
+    private assertAuthParamsFilled;
     /**
      * Extract all parameter placeholders from execution config
      * Scans headers, body, URL, and query_params for {paramName} patterns
@@ -125,6 +273,50 @@ export declare class MatimoInstance {
      * Get the appropriate executor for a tool
      */
     private getExecutor;
+    /**
+     * 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.
+     */
+    reloadTools(): Promise<ReloadResult>;
+    /**
+     * Check if a policy engine is active.
+     */
+    hasPolicy(): boolean;
+    /**
+     * Get the approval manifest (if policy engine is active).
+     */
+    getApprovalManifest(): ApprovalManifest | null;
+    /**
+     * Get the integrity tracker.
+     */
+    getIntegrityTracker(): ToolIntegrityTracker;
+    /**
+     * Get the tool registry (for advanced use cases).
+     */
+    getRegistry(): ToolRegistry;
+    /**
+     * 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: HITLCallback | null): void;
+    /**
+     * 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.
+     */
+    reloadPolicy(configOrFile?: PolicyConfig | string): Promise<ReloadResult>;
 }
 /**
  * Matimo namespace - Entry point for the SDK

package/dist/matimo-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matimo-instance.d.ts","sourceRoot":"","sources":["../src/matimo-instance.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EACL,YAAY,EACZ,YAAY,EAIb,MAAM,WAAW,CAAC;AAGnB;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,eAAe,CAAkB;IAEzC,OAAO;IAaP;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACU,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAqE1E;;;OAGG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;;OAGG;IACH,SAAS,IAAI,YAAY;IAIzB;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAiFlF;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIrD;;;OAGG;IACH,SAAS,IAAI,cAAc,EAAE;IAI7B;;;OAGG;IACH,WAAW,IAAI,cAAc,EAAE;IAI/B;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAI5C;;;;OAIG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE;IAI5C;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,oBAAoB;IAmD5B;;;OAGG;IACH,OAAO,CAAC,4BAA4B;IAkDpC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0C3B;;OAEG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED;;GAEG;AACH,eAAO,MAAM,MAAM;IACjB;;;;OAIG;oBACmB,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAGvD,CAAC"}
+{"version":3,"file":"matimo-instance.d.ts","sourceRoot":"","sources":["../src/matimo-instance.ts"],"names":[],"mappings":"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"}