matimo-core 0.1.3__tar.gz → 0.2.0__tar.gz

{matimo_core-0.1.3 → matimo_core-0.2.0}/.gitignore

@@ -58,7 +58,6 @@ temp/
 
 # Personal scratch notes / working docs — not part of the shipped repo
 .local-notes/
-typescript/examples/mcp/matimo-tools/.matimo-approvals.json
 typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
 typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
 typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
@@ -68,3 +67,6 @@ typescript/packages/cli/.matimo/certs/server.crt
 typescript/packages/cli/.matimo/certs/server.key
 typescript/examples/mcp/.matimo/certs/server.crt
 typescript/examples/mcp/.matimo/certs/server.key
+
+# HITL approval manifests are per-machine state (HMAC-signed approvals); never commit one
+**/.matimo-approvals.json

matimo_core-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROAIQ TECHNOLOGIES PRIVATE LIMITED
+
+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.

{matimo_core-0.1.3 → matimo_core-0.2.0}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.5
 Name: matimo-core
-Version: 0.1.3
+Version: 0.2.0
 Summary: Matimo core — framework-agnostic SDK: pre-built providers, skills layer, MCP, and a policy engine you control
 Project-URL: Homepage, https://matimo.dev
-Project-URL: Documentation, https://matimo.dev/docs
+Project-URL: Documentation, https://docs.matimo.dev/
 Project-URL: Repository, https://github.com/tallclub/matimo
 Project-URL: Issues, https://github.com/tallclub/matimo/issues
 License: MIT
-Keywords: agentic-ai,agents,ai,ai-governance,crewai,langchain,matimo,mcp,mcp-server,policy-engine,tools
+License-File: LICENSE
+Keywords: agentic-ai,agents,agno,ai,ai-governance,crewai,langchain,matimo,mcp,mcp-server,policy-engine,tools
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -31,7 +32,10 @@ Requires-Dist: readability-lxml>=0.8.4.1
 Requires-Dist: reportlab>=4.0
 Requires-Dist: simpleeval>=1.0
 Requires-Dist: typing-extensions>=4.9
+Provides-Extra: agno
+Requires-Dist: agno>=3.0; extra == 'agno'
 Provides-Extra: all
+Requires-Dist: agno>=3.0; extra == 'all'
 Requires-Dist: crewai>=0.80; extra == 'all'
 Requires-Dist: hvac>=2.0; extra == 'all'
 Requires-Dist: langchain-core>=0.3; extra == 'all'
@@ -42,6 +46,7 @@ Requires-Dist: boto3>=1.34; extra == 'aws'
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.80; extra == 'crewai'
 Provides-Extra: dev
+Requires-Dist: agno>=3.0; extra == 'dev'
 Requires-Dist: boto3>=1.34; extra == 'dev'
 Requires-Dist: crewai>=0.80; extra == 'dev'
 Requires-Dist: hvac>=2.0; extra == 'dev'
@@ -71,7 +76,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-core)](https://pypi.org/project/matimo-core/)
 [![Python](https://img.shields.io/pypi/pyversions/matimo-core)](https://pypi.org/project/matimo-core/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 [![Tests](https://img.shields.io/badge/tests-1134%20passing-brightgreen)](https://github.com/tallclub/matimo)
 [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)](https://github.com/tallclub/matimo)
 
@@ -188,7 +193,7 @@ await server.start()
 ### `Matimo.init()`
 
 ```python
-from matimo import Matimo, InitOptions
+from matimo import InitOptions, JsonlFileSink, Matimo
 
 matimo = await Matimo.init(
     tool_paths=['./tools', './agent-tools'],  # or a single string
@@ -199,6 +204,7 @@ matimo = await Matimo.init(
     log_level='info',          # silent | error | warn | info | debug
     log_format='json',         # json | simple
     on_event=my_event_handler,
+    audit_sink=JsonlFileSink('./logs/matimo-audit.jsonl'),  # hash-chained audit log
     on_hitl=my_approval_callback,
 )
 ```
@@ -242,14 +248,23 @@ execution:
 ## Policy Engine
 
 ```python
-from matimo import Matimo, InitOptions
+from matimo import ApprovalRequest, JsonlFileSink, Matimo
 
-matimo = await Matimo.init('./tools', InitOptions(
+
+async def ask_operator(request: ApprovalRequest) -> bool:
+    return input(f"Approve {request.tool_name} {request.params}? (y/n) ") == "y"
+
+
+matimo = await Matimo.init(
+    './tools',
     policy_file='./policy.yaml',
-    on_hitl=lambda req: {'approved': True, 'reason': 'auto'},
-))
+    on_approval=ask_operator,                       # calls that need approval ask here
+    audit_sink=JsonlFileSink('./matimo-audit.jsonl'),  # hash-chained audit log
+)
 ```
 
+Calls that need approval: tools with `requires_approval: true`, HTTP `DELETE` and command tools (the 0.2.0 secure default), and calls whose `sql`/`command` argument contains a destructive keyword. With no `on_approval` they are refused.
+
 `policy.yaml`:
 ```yaml
 allowedDomains:
@@ -309,25 +324,28 @@ Built-in tools that let agents manage other tools at runtime:
 | `matimo_list_skills` | List available skills | No |
 | `matimo_get_skill` | Read skill content | No |
 | `matimo_validate_skill` | Validate skill spec | No |
+| `matimo_search_skills` | Semantically rank skills by relevance (TF-IDF) | No |
+| `matimo_get_skill_sections` | Inventory a skill's sections and token costs | No |
+| `matimo_get_skill_content` | Load only specific sections of a skill | No |
 
 ---
 
 ## Documentation
 
-- [Getting Started](https://matimo.dev/docs/getting-started/QUICK_START)
-- [Full API Reference](https://matimo.dev/docs/api-reference/SDK)
-- [LangChain Integration](https://matimo.dev/docs/framework-integrations/LANGCHAIN)
-- [CrewAI Integration](https://matimo.dev/docs/framework-integrations/CREWAI)
-- [MCP Guide](https://matimo.dev/docs/MCP)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
-- [Meta-Tools Reference](https://matimo.dev/docs/api-reference/META_TOOLS)
+- [Getting Started](https://docs.matimo.dev/getting-started/QUICK_START)
+- [Full API Reference](https://docs.matimo.dev/api-reference/SDK)
+- [LangChain Integration](https://docs.matimo.dev/framework-integrations/LANGCHAIN)
+- [CrewAI Integration](https://docs.matimo.dev/framework-integrations/CREWAI)
+- [MCP Guide](https://docs.matimo.dev/MCP)
+- [Policy & Lifecycle](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE)
+- [Meta-Tools Reference](https://docs.matimo.dev/api-reference/META_TOOLS)
 
 ---
 
 ## Links
 
 - **PyPI:** https://pypi.org/project/matimo-core/
-- **Docs:** https://matimo.dev/docs
+- **Docs:** https://docs.matimo.dev/
 - **GitHub:** https://github.com/tallclub/matimo
 - **Changelog:** https://github.com/tallclub/matimo/blob/main/docs/RELEASES.md
 

{matimo_core-0.1.3 → matimo_core-0.2.0}/README.md

@@ -4,7 +4,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-core)](https://pypi.org/project/matimo-core/)
 [![Python](https://img.shields.io/pypi/pyversions/matimo-core)](https://pypi.org/project/matimo-core/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 [![Tests](https://img.shields.io/badge/tests-1134%20passing-brightgreen)](https://github.com/tallclub/matimo)
 [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)](https://github.com/tallclub/matimo)
 
@@ -121,7 +121,7 @@ await server.start()
 ### `Matimo.init()`
 
 ```python
-from matimo import Matimo, InitOptions
+from matimo import InitOptions, JsonlFileSink, Matimo
 
 matimo = await Matimo.init(
     tool_paths=['./tools', './agent-tools'],  # or a single string
@@ -132,6 +132,7 @@ matimo = await Matimo.init(
     log_level='info',          # silent | error | warn | info | debug
     log_format='json',         # json | simple
     on_event=my_event_handler,
+    audit_sink=JsonlFileSink('./logs/matimo-audit.jsonl'),  # hash-chained audit log
     on_hitl=my_approval_callback,
 )
 ```
@@ -175,14 +176,23 @@ execution:
 ## Policy Engine
 
 ```python
-from matimo import Matimo, InitOptions
+from matimo import ApprovalRequest, JsonlFileSink, Matimo
 
-matimo = await Matimo.init('./tools', InitOptions(
+
+async def ask_operator(request: ApprovalRequest) -> bool:
+    return input(f"Approve {request.tool_name} {request.params}? (y/n) ") == "y"
+
+
+matimo = await Matimo.init(
+    './tools',
     policy_file='./policy.yaml',
-    on_hitl=lambda req: {'approved': True, 'reason': 'auto'},
-))
+    on_approval=ask_operator,                       # calls that need approval ask here
+    audit_sink=JsonlFileSink('./matimo-audit.jsonl'),  # hash-chained audit log
+)
 ```
 
+Calls that need approval: tools with `requires_approval: true`, HTTP `DELETE` and command tools (the 0.2.0 secure default), and calls whose `sql`/`command` argument contains a destructive keyword. With no `on_approval` they are refused.
+
 `policy.yaml`:
 ```yaml
 allowedDomains:
@@ -242,25 +252,28 @@ Built-in tools that let agents manage other tools at runtime:
 | `matimo_list_skills` | List available skills | No |
 | `matimo_get_skill` | Read skill content | No |
 | `matimo_validate_skill` | Validate skill spec | No |
+| `matimo_search_skills` | Semantically rank skills by relevance (TF-IDF) | No |
+| `matimo_get_skill_sections` | Inventory a skill's sections and token costs | No |
+| `matimo_get_skill_content` | Load only specific sections of a skill | No |
 
 ---
 
 ## Documentation
 
-- [Getting Started](https://matimo.dev/docs/getting-started/QUICK_START)
-- [Full API Reference](https://matimo.dev/docs/api-reference/SDK)
-- [LangChain Integration](https://matimo.dev/docs/framework-integrations/LANGCHAIN)
-- [CrewAI Integration](https://matimo.dev/docs/framework-integrations/CREWAI)
-- [MCP Guide](https://matimo.dev/docs/MCP)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
-- [Meta-Tools Reference](https://matimo.dev/docs/api-reference/META_TOOLS)
+- [Getting Started](https://docs.matimo.dev/getting-started/QUICK_START)
+- [Full API Reference](https://docs.matimo.dev/api-reference/SDK)
+- [LangChain Integration](https://docs.matimo.dev/framework-integrations/LANGCHAIN)
+- [CrewAI Integration](https://docs.matimo.dev/framework-integrations/CREWAI)
+- [MCP Guide](https://docs.matimo.dev/MCP)
+- [Policy & Lifecycle](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE)
+- [Meta-Tools Reference](https://docs.matimo.dev/api-reference/META_TOOLS)
 
 ---
 
 ## Links
 
 - **PyPI:** https://pypi.org/project/matimo-core/
-- **Docs:** https://matimo.dev/docs
+- **Docs:** https://docs.matimo.dev/
 - **GitHub:** https://github.com/tallclub/matimo
 - **Changelog:** https://github.com/tallclub/matimo/blob/main/docs/RELEASES.md
 

{matimo_core-0.1.3 → matimo_core-0.2.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-core"
-version = "0.1.3"
+version = "0.2.0"
 description = "Matimo core — framework-agnostic SDK: pre-built providers, skills layer, MCP, and a policy engine you control"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.11"
-keywords = ["ai", "tools", "agents", "langchain", "crewai", "mcp", "matimo", "mcp-server", "agentic-ai", "ai-governance", "policy-engine"]
+keywords = ["ai", "tools", "agents", "langchain", "crewai", "agno", "mcp", "matimo", "mcp-server", "agentic-ai", "ai-governance", "policy-engine"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -40,6 +40,7 @@ dependencies = [
 [project.optional-dependencies]
 langchain = ["langchain-core>=0.3"]
 crewai = ["crewai>=0.80"]
+agno = ["agno>=3.0"]
 mcp = ["mcp>=1.28.1"]
 vault = ["hvac>=2.0"]
 aws = ["boto3>=1.34"]
@@ -47,6 +48,7 @@ dotenv = ["python-dotenv>=1.0"]
 all = [
     "langchain-core>=0.3",
     "crewai>=0.80",
+    "agno>=3.0",
     "mcp>=1.28.1",
     "hvac>=2.0",
     "python-dotenv>=1.0",
@@ -61,6 +63,7 @@ dev = [
     "types-pyyaml>=6.0",
     "langchain-core>=0.3",
     "crewai>=0.80",
+    "agno>=3.0",
     "mcp>=1.28.1",
     "hvac>=2.0",
     "boto3>=1.34",
@@ -69,7 +72,7 @@ dev = [
 
 [project.urls]
 Homepage = "https://matimo.dev"
-Documentation = "https://matimo.dev/docs"
+Documentation = "https://docs.matimo.dev/"
 Repository = "https://github.com/tallclub/matimo"
 Issues = "https://github.com/tallclub/matimo/issues"
 
@@ -80,7 +83,7 @@ core = "matimo:get_core_tools_path"
 packages = ["src/matimo"]
 
 [tool.hatch.build.targets.sdist]
-include = ["src/", "README.md", "../../../LICENSE"]
+include = ["src/", "README.md", "LICENSE"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{matimo_core-0.1.3 → matimo_core-0.2.0}/src/matimo/__init__.py

@@ -34,6 +34,7 @@ from matimo.approval.handler import (
     ApprovalCallback,
     ApprovalHandler,
     ApprovalRequest,
+    definition_requires_approval,
     get_global_approval_handler,
     set_global_approval_handler,
 )
@@ -122,7 +123,7 @@ from matimo.errors import (
 
 # Executors
 from matimo.executors.command_executor import CommandExecutor
-from matimo.executors.function_executor import FunctionExecutor
+from matimo.executors.function_executor import FunctionExecutor, FunctionToolContext
 from matimo.executors.http_executor import HttpExecutor
 
 # Main entry point + sync API
@@ -150,12 +151,26 @@ from matimo.mcp.tool_converter import convert_parameters_to_mcp_schema
 
 # Policy
 from matimo.policy.approval_manifest import ApprovalManifest, ApprovalRecord
+from matimo.policy.audit_sink import (
+    AUDIT_GENESIS_HASH,
+    AuditLogVerification,
+    AuditSink,
+    JsonlFileSink,
+    hash_audit_entry,
+    redact_secrets,
+    verify_audit_log,
+)
 from matimo.policy.content_validator import ContentViolation, validate_tool_content
 from matimo.policy.default_policy import DefaultPolicyEngine, PolicyEngine, get_tier_for_tool
 from matimo.policy.integrity_tracker import IntegrityAction, ToolIntegrityTracker
 from matimo.policy.policy_loader import load_policy_from_file
-from matimo.policy.risk_classifier import classify_risk
+from matimo.policy.risk_classifier import (
+    classify_execution_risk,
+    classify_risk,
+    meets_risk_threshold,
+)
 from matimo.policy.types import (
+    GovernanceMode,
     HITLCallback,
     HITLRequest,
     MatimoEvent,
@@ -170,7 +185,7 @@ from matimo.policy.types import (
 )
 from matimo.sync import MatimoSync
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 
 def get_core_tools_path() -> str:
@@ -231,6 +246,36 @@ def convert_tools_to_crewai(
     return _inner(tools, matimo_instance, credentials)
 
 
+def convert_tools_to_agno(
+    tools: list[Any],
+    matimo_instance: Matimo,
+    credentials: dict[str, str] | None = None,
+    **kwargs: Any,  # noqa: ANN401
+) -> list[Any]:
+    """Convert Matimo tools to Agno Function list. Requires agno.
+
+    Extra keyword arguments (context, confirm_risk_levels) are forwarded to
+    matimo.integrations.agno.convert_tools_to_agno.
+    """
+    from matimo.integrations.agno import convert_tools_to_agno as _inner
+    return _inner(tools, matimo_instance, credentials, **kwargs)
+
+
+def MatimoTools(  # noqa: N802
+    matimo_instance: Matimo,
+    tools: list[Any] | None = None,
+    **kwargs: Any,  # noqa: ANN401
+) -> Any:  # noqa: ANN401
+    """Build an Agno Toolkit exposing governed Matimo tools. Requires agno.
+
+    Named in CapWords to match Agno's <Name>Tools toolkit convention. Returns Any
+    because Toolkit comes from an optional dependency (agno). Extra keyword
+    arguments are forwarded to matimo.integrations.agno.MatimoTools.
+    """
+    from matimo.integrations.agno import MatimoTools as _inner
+    return _inner(matimo_instance, tools, **kwargs)
+
+
 # ---------------------------------------------------------------------------
 # Decorators
 # ---------------------------------------------------------------------------
@@ -272,7 +317,7 @@ __all__ = [
     "ParsedSkillContent", "SemanticSearchResult",
     "TfIdfEmbeddingProvider", "EmbeddingProvider", "cosine_similarity",
     # Executors
-    "HttpExecutor", "CommandExecutor", "FunctionExecutor",
+    "HttpExecutor", "CommandExecutor", "FunctionExecutor", "FunctionToolContext",
     # Auth
     "inject_auth_parameters", "extract_parameter_placeholders",
     "OAuth2Handler", "OAuth2ProviderLoader",
@@ -280,17 +325,20 @@ __all__ = [
     # Approval
     "ApprovalHandler", "ApprovalRequest", "ApprovalCallback",
     "get_global_approval_handler", "set_global_approval_handler",
+    "definition_requires_approval",
     # Encodings
     "apply_parameter_encodings",
     # Policy
     "PolicyEngine", "DefaultPolicyEngine", "PolicyConfig",
     "PolicyDecision", "PolicyAllowed", "PolicyDenied", "PolicyPendingApproval",
     "RiskLevel", "PolicyTier",
-    "MatimoEvent", "MatimoEventHandler", "HITLCallback", "HITLRequest",
+    "MatimoEvent", "MatimoEventHandler", "GovernanceMode", "HITLCallback", "HITLRequest",
     "ContentViolation", "validate_tool_content",
-    "classify_risk", "get_tier_for_tool",
+    "classify_risk", "classify_execution_risk", "meets_risk_threshold", "get_tier_for_tool",
     "ToolIntegrityTracker", "IntegrityAction",
     "ApprovalManifest", "ApprovalRecord",
+    "AuditSink", "JsonlFileSink", "AuditLogVerification", "verify_audit_log",
+    "redact_secrets", "hash_audit_entry", "AUDIT_GENESIS_HASH",
     "load_policy_from_file",
     # MCP
     "MCPServer", "MCPServerOptions", "create_mcp_server",
@@ -303,6 +351,8 @@ __all__ = [
     "get_skills_metadata",
     "build_relevant_skill_prompt",
     "convert_tools_to_crewai",
+    "convert_tools_to_agno",
+    "MatimoTools",
     # Decorators
     "tool", "set_global_matimo_instance", "get_global_matimo_instance",
     # Logging

{matimo_core-0.1.3 → matimo_core-0.2.0}/src/matimo/approval/handler.py

@@ -9,7 +9,11 @@ import logging
 import os
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from matimo.core.models import ToolDefinition
+    from matimo.policy.types import GovernanceMode
 
 logger = logging.getLogger("matimo")
 
@@ -22,6 +26,32 @@ DEFAULT_DESTRUCTIVE_KEYWORDS: list[str] = [
 ]
 
 
+# Tools whose approval prompt nothing may skip: neither MATIMO_AUTO_APPROVE nor
+# an approved pattern (not even "*"). Approving a tool is the step that lets
+# agent-written code run, so a human must always see it.
+# Mirrors NEVER_PRE_APPROVED_TOOLS in approval-handler.ts.
+NEVER_PRE_APPROVED_TOOLS: frozenset[str] = frozenset({"matimo_approve_tool"})
+
+
+def definition_requires_approval(tool: ToolDefinition, mode: GovernanceMode = "secure") -> bool:
+    """
+    Whether a tool's definition alone makes every call need approval.
+    Mirrors definitionRequiresApproval() in approval-handler.ts: an explicit
+    `requires_approval` in the YAML always wins, so a developer can opt a tool
+    out with `requires_approval: false`. When it is absent, in "secure" mode
+    HTTP DELETE and `type: command` (shell) tools need approval by default;
+    "legacy" mode has no such default.
+    """
+    if "requires_approval" in tool.model_fields_set:
+        return tool.requires_approval
+    if mode == "legacy":
+        return False
+    execution = tool.execution
+    if execution.type == "command":
+        return True
+    return execution.type == "http" and execution.method.upper() == "DELETE"
+
+
 @dataclass
 class ApprovalRequest:
     """Represents a pending approval for a tool execution."""
@@ -58,33 +88,59 @@ class ApprovalHandler:
     # Public API
     # ------------------------------------------------------------------
 
-    def set_approval_callback(self, callback: ApprovalCallback) -> None:
-        """Wire an async approval callback (e.g., Slack DM, CLI prompt)."""
+    def set_approval_callback(self, callback: ApprovalCallback | None) -> None:
+        """Wire an async approval callback (e.g., Slack DM, CLI prompt), or clear it."""
         self._callback = callback
 
-    async def request_approval(self, request: ApprovalRequest) -> bool:
+    def get_approval_callback(self) -> ApprovalCallback | None:
+        """Return the current approval callback (for save/restore patterns)."""
+        return self._callback
+
+    def requires_approval(
+        self, requires_approval_in_yaml: bool | None, content: str | None = None
+    ) -> bool:
         """
-        Gate execution on approval.
-        Returns True if approved, False if denied.
+        Whether a call needs per-call approval. Mirrors requiresApproval() in
+        approval-handler.ts: an explicit YAML `requires_approval: true` always
+        does; otherwise the supplied content (SQL, shell command, ...) is
+        scanned for destructive keywords.
         """
-        # 1. Hard auto-approve (CI / testing)
-        if self.auto_approve:
-            logger.debug(
-                "Auto-approving tool '%s' (MATIMO_AUTO_APPROVE=true)", request.tool_name
-            )
+        if requires_approval_in_yaml is True:
             return True
+        if content:
+            upper = content.upper()
+            return any(kw in upper for kw in self.destructive_keywords)
+        return False
+
+    def is_pre_approved(self, tool_name: str) -> bool:
+        """True when MATIMO_AUTO_APPROVE is on or the tool matches an approved pattern.
+        Never for NEVER_PRE_APPROVED_TOOLS."""
+        if tool_name in NEVER_PRE_APPROVED_TOOLS:
+            return False
+        return self.auto_approve or self._matches_approved_pattern(tool_name)
 
-        # 2. Pattern allowlist
-        if self._matches_approved_pattern(request.tool_name):
+    async def request_approval(
+        self, request: ApprovalRequest, callback: ApprovalCallback | None = None
+    ) -> bool:
+        """
+        Gate execution on approval.
+        Returns True if approved, False if denied.
+        `callback` overrides this handler's callback for this request (a Matimo
+        instance passes its own `on_approval` here).
+        """
+        callback = callback if callback is not None else self._callback
+        # 1-2. MATIMO_AUTO_APPROVE (CI / testing) or an approved pattern —
+        # never for NEVER_PRE_APPROVED_TOOLS
+        if self.is_pre_approved(request.tool_name):
             logger.debug(
-                "Tool '%s' matches approved pattern — skipping approval prompt",
+                "Tool '%s' is pre-approved (MATIMO_AUTO_APPROVE or approved pattern)",
                 request.tool_name,
             )
             return True
 
         # 3. HITL callback
-        if self._callback is not None:
-            approved = await self._callback(request)
+        if callback is not None:
+            approved = await callback(request)
             if not approved:
                 logger.info(
                     "Approval denied for tool '%s' by callback", request.tool_name
@@ -125,8 +181,9 @@ class ApprovalHandler:
         return {p.strip() for p in raw.split(",") if p.strip()}
 
     def _matches_approved_pattern(self, tool_name: str) -> bool:
+        # Case-insensitive on every OS, like matchesPattern() in approval-handler.ts
         return any(
-            fnmatch.fnmatch(tool_name, pattern)
+            fnmatch.fnmatchcase(tool_name.lower(), pattern.lower())
             for pattern in self.approved_patterns
         )
 

{matimo_core-0.1.3 → matimo_core-0.2.0}/src/matimo/auth/injection.py

@@ -31,8 +31,8 @@ def inject_auth_parameters(
     Scan all placeholders in the tool's execution config (URL, headers, body,
     query_params). For any placeholder that looks auth-related and has no value
     in params, attempt to resolve it from:
-      1. per-call credentials dict
-      2. process environment (MATIMO_{TOOL_NAME}_{KEY} or just {KEY})
+      1. per-call credentials dict ({KEY}, then MATIMO_{KEY})
+      2. process environment (MATIMO_{KEY}, MATIMO_{TOOL_NAME}_{KEY}, then {KEY})
 
     SECURITY: injected values are never logged.
 
@@ -71,21 +71,20 @@ def extract_parameter_placeholders(tool: ToolDefinition) -> set[str]:
     """
     placeholders: set[str] = set()
     exec_cfg = tool.execution
-    exec_type = exec_cfg.type
-
-    if exec_type == "http":
-        _scan_string(exec_cfg.url, placeholders)  # type: ignore[attr-defined]
-        _scan_object(exec_cfg.headers, placeholders)  # type: ignore[attr-defined]
-        _scan_object(exec_cfg.body, placeholders)  # type: ignore[attr-defined]
-        _scan_object(exec_cfg.query_params, placeholders)  # type: ignore[attr-defined]
-        _scan_object(exec_cfg.params, placeholders)  # type: ignore[attr-defined]
-
-    elif exec_type == "command":
-        _scan_string(exec_cfg.command, placeholders)  # type: ignore[attr-defined]
-        for arg in exec_cfg.args or []:  # type: ignore[attr-defined]
+
+    if exec_cfg.type == "http":
+        _scan_string(exec_cfg.url, placeholders)
+        _scan_object(exec_cfg.headers, placeholders)
+        _scan_object(exec_cfg.body, placeholders)
+        _scan_object(exec_cfg.query_params, placeholders)
+        _scan_object(exec_cfg.params, placeholders)
+
+    elif exec_cfg.type == "command":
+        _scan_string(exec_cfg.command, placeholders)
+        for arg in exec_cfg.args or []:
             _scan_string(arg, placeholders)
 
-    elif exec_type == "function":
+    elif exec_cfg.type == "function":
         # Function tools may have params passed directly — nothing to scan
         pass
 
@@ -103,19 +102,27 @@ def _resolve_auth_value(
     credentials: dict[str, str] | None,
 ) -> str | None:
     """
-    Try to resolve an auth placeholder in priority order:
-    1. per-call credentials
-    2. env MATIMO_{TOOL_NAME_UPPER}_{PLACEHOLDER_UPPER}
-    3. env {PLACEHOLDER} directly
+    Try to resolve an auth placeholder in priority order, matching
+    injectAuthParameters() in matimo-instance.ts:
+    1. per-call credentials: {PLACEHOLDER}, then MATIMO_{PLACEHOLDER}
+    2. env MATIMO_{PLACEHOLDER}
+    3. env MATIMO_{TOOL_NAME_UPPER}_{PLACEHOLDER_UPPER} (Python-only, kept for
+       existing deployments)
+    4. env {PLACEHOLDER}
     """
-    if credentials and placeholder in credentials:
-        return credentials[placeholder]
-
-    # e.g. MATIMO_SLACK_SLACK_BOT_TOKEN
-    env_key_prefixed = f"MATIMO_{tool_name.upper()}_{placeholder.upper()}"
-    val = os.environ.get(env_key_prefixed)
-    if val:
-        return val
+    if credentials:
+        for key in (placeholder, f"MATIMO_{placeholder}"):
+            if credentials.get(key):
+                return credentials[key]
+
+    for env_key in (
+        f"MATIMO_{placeholder}",
+        # e.g. MATIMO_SLACK_SEND_CHANNEL_MESSAGE_SLACK_BOT_TOKEN
+        f"MATIMO_{tool_name.upper()}_{placeholder.upper()}",
+    ):
+        val = os.environ.get(env_key)
+        if val:
+            return val
 
     # env directly (e.g. SLACK_BOT_TOKEN)
     return os.environ.get(placeholder)