weaver-kernel 0.5.0__tar.gz → 0.7.0__tar.gz

{weaver_kernel-0.5.0 → weaver_kernel-0.7.0}/AGENTS.md

@@ -52,7 +52,7 @@ Use these terms consistently. Never substitute synonyms:
 - Error messages are part of the contract — tests must assert both exception type and message.
 - Keep modules ≤ 300 lines. Split if needed.
 - No randomness in matching, routing, or summarization. Deterministic outputs always.
-- No new dependencies without justification. The dep list is intentionally minimal (`httpx` only).
+- No new dependencies without justification. The dep list is intentionally minimal (`httpx`, `pydantic`).
 
 ## Security rules
 

weaver_kernel-0.7.0/CHANGELOG.md

@@ -0,0 +1,244 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.0] - 2026-05-20
+
+### Added
+- Structured intent and scope metadata on `CapabilityRequest`: new optional
+  `intent: str | None` and `scope: dict[str, Any]` fields let policy engines
+  authorize based on machine-readable intent and scope alongside the existing
+  free-text `goal`. `DeclarativePolicyEngine` rules can match on these via new
+  `intent: [...]` and `scope: {key: value}` clauses in YAML/TOML policy files.
+  Intent-aware allow rules fail closed for legacy callers that don't set an
+  intent. (#72)
+- Structured policy decision trace (`PolicyDecisionTrace` + `PolicyTraceStep`):
+  both built-in policy engines now attach a step-by-step trace to every
+  `PolicyDecision` (allow and deny paths). Each step records the rule
+  considered, the outcome (`matched`/`skipped`/`denied`/`allowed`/
+  `constraint_applied`), a human-readable detail, and — for terminal
+  steps — the stable reason code. Traces echo `intent` and `scope_keys`
+  (scope dimension names only — values redacted) from the request and contain
+  no raw argument values. `DryRunResult.policy_decision`
+  also carries a synthesized single-step trace. (#73)
+- Stable machine-readable denial reason codes: new `DenialReason` and
+  `AllowReason` enums in `agent_kernel.policy_reasons` (also exported as
+  `from agent_kernel import DenialReason, AllowReason`). Every built-in
+  denial path on `DefaultPolicyEngine` and `DeclarativePolicyEngine` populates
+  `PolicyDecision.reason_code`, `DenialExplanation.reason_code`,
+  `FailedCondition.reason_code`, and `PolicyDenied.reason_code`. Tests should
+  assert on these codes instead of matching the human-readable `reason` /
+  `narrative` strings, which remain part of the API but may evolve for
+  clarity. Codes: `missing_role`, `missing_tenant_attribute`,
+  `missing_attribute`, `insufficient_justification`, `invalid_constraint`,
+  `rate_limited`, `no_matching_rule`, `explicit_deny_rule`,
+  `intent_not_allowed`, `scope_not_allowed`; allow-side: `default_policy_allow`,
+  `rule_allow`, `default_fallthrough_allow`. (#77)
+- New public exports: `AllowReason`, `DenialReason`, `PolicyDecisionTrace`,
+  `PolicyTraceStep`.
+
+### Changed
+- `PolicyDecision` gained optional `reason_code: str | None` and
+  `trace: PolicyDecisionTrace | None` fields (both default `None` so
+  third-party engines that don't populate them keep working).
+- `DenialExplanation` and `FailedCondition` gained optional `reason_code`
+  fields populated by both built-in engines on every denial path.
+- `PolicyDenied(reason_code=...)` keyword argument: the exception now carries
+  a `reason_code` attribute so callers can branch on a stable code without
+  matching the human-readable message.
+
+## [0.6.0] - 2026-05-19
+
+### Added
+- Cross-invocation context budget manager (`BudgetManager`) tracks cumulative token usage across
+  multiple `Kernel.invoke()` calls within a session. When attached to a `Kernel` via the new
+  `budget_manager` keyword argument, the kernel reserves a budget slice before each invocation
+  and reconciles actual frame-payload usage afterwards. As the remaining budget shrinks the
+  requested `response_mode` is auto-escalated to a more aggressive tier (> 50% remaining keeps
+  the caller's mode; 20–50% downgrades `raw` to `table`; 5–20% floors at `summary`; < 5% forces
+  `handle_only`). `Kernel.invoke(..., dry_run=True)` now also reports `budget_remaining` and the
+  escalated `response_mode` when a manager is configured. The `BudgetManager` is optional and
+  off by default — existing kernels are unchanged. (#44)
+- `TokenCounter` protocol and `default_token_counter` (character-based `len(json.dumps(...))//4`
+  approximation) provide pluggable token counting without runtime dependencies. A new optional
+  `[tiktoken]` extra is reserved for callers that want to plug in `tiktoken`-based counting.
+- `BudgetExhausted(AgentKernelError)` raised by `BudgetManager.allocate()` (and by
+  `Kernel.invoke()` before driver execution) when the cumulative session budget is fully spent.
+- `BudgetConfigError(AgentKernelError)` raised by `BudgetManager` for invalid configuration or
+  validation failures (non-positive budgets, negative allocate/record/release amounts), replacing
+  bare `ValueError` so callers can catch budget mistakes via the `AgentKernelError` hierarchy
+  per `AGENTS.md` ("never raise bare ValueError to callers").
+- New public exports: `BudgetManager`, `BudgetExhausted`, `BudgetConfigError`, `TokenCounter`,
+  `default_token_counter`, and `Kernel.budget` accessor property.
+- LLM tool-format adapters and middleware (`agent_kernel.adapters`): `OpenAIMiddleware` (OpenAI
+  Responses API + Chat Completions, auto-detected on input) and `AnthropicMiddleware` (Anthropic
+  Messages with `cache_control` support). Both translate `Capability` objects to vendor tool
+  schemas, route tool calls through the full kernel pipeline (grant → invoke → firewall → trace),
+  and surface kernel errors (`PolicyDenied`, `CapabilityNotFound`, `DriverError`) as tool-result
+  errors so the LLM can react. Pre/post hooks (`intercept_tool_call`, `intercept_tool_result`,
+  sync or async) support logging, metrics, approval gates, and per-call justification injection.
+  Zero runtime dependency on the `openai` / `anthropic` SDK packages. (#55, #50, #40)
+- New `Capability` fields for LLM adapters: `parameters_model: type[pydantic.BaseModel] | None`
+  (input schema source + validation), `parameters_schema: dict | None` (raw JSON Schema escape
+  hatch), and `tool_hints: ToolHints | None` (vendor hints — Anthropic `cache_control`, OpenAI
+  `strict` mode). All default to ``None``; existing capabilities and tests are unaffected.
+- New `ToolHints` dataclass and `OpenAIMiddleware` / `AnthropicMiddleware` top-level exports.
+- New `AdapterParseError(AgentKernelError)` exception raised by adapter parse / validation
+  helpers (`tool_call_to_request`, `tool_use_to_request`, `make_namespace_safe_name`) instead
+  of bare `ValueError`. Satisfies `AGENTS.md`'s "no bare ValueError to callers" rule and
+  gives consumers a stable adapter-specific exception type. Also catches capability IDs that
+  contain the reserved OpenAI namespace separator `__` (which would otherwise produce
+  colliding tool names).
+- `Kernel.list_capabilities()` convenience accessor returning every registered capability in
+  registration order. Used by the new adapters but generally useful for tooling that needs to
+  enumerate the registry without keyword search.
+- Declarative policy engine (`DeclarativePolicyEngine`) that loads rules from YAML or TOML files.
+  Rules are evaluated top-down with first-match-wins semantics; supports `safety_class`, `sensitivity`,
+  `roles`, `attributes`, and `min_justification` match conditions. (#42)
+- Policy denial explanation: `ExplainingPolicyEngine` protocol plus `DefaultPolicyEngine.explain()` and
+  `DeclarativePolicyEngine.explain()` implementations return a structured `DenialExplanation` with a
+  `FailedCondition` list for every failing check (no short-circuit), a `remediation` list, and a
+  human-readable `narrative`. (#48)
+- Dry-run invocation mode: `kernel.invoke(..., dry_run=True)` verifies the token and resolves the
+  execution plan without calling the driver. Returns `DryRunResult` with the resolved `driver_id`,
+  `operation`, `response_mode`, and an `estimated_cost` tier (`low`/`medium`/`high`). (#43)
+- `Kernel.explain_denial()` convenience method that calls the policy engine's `explain()` for a given
+  `CapabilityRequest` and `Principal` without requiring a token. Raises `AgentKernelError` when the
+  configured engine does not implement `explain()`.
+- New public types exported from `agent_kernel`: `DeclarativePolicyEngine`, `ExplainingPolicyEngine`,
+  `PolicyEngine`, `PolicyMatch`, `PolicyRule`, `DenialExplanation`, `FailedCondition`, `DryRunResult`,
+  `PolicyConfigError`.
+- `policy` optional extra (`pip install weaver-kernel[policy]`) pulls in `pyyaml` and `tomli` (Python 3.10).
+- Example policy files in `examples/policies/` (YAML and TOML formats).
+
+### Changed
+- Runtime dependencies now include `pydantic>=2` in addition to `httpx`. Pydantic is used by the new
+  `agent_kernel.adapters` package for JSON-Schema generation and argument validation when a
+  `Capability` declares a `parameters_model`. Existing kernel behavior is unchanged; pydantic is not
+  imported at module load by anything outside the adapters.
+- `PolicyEngine` protocol no longer requires `explain()`. Engines that need to support
+  `Kernel.explain_denial()` should implement the new `ExplainingPolicyEngine` protocol. Built-in
+  engines satisfy both. This avoids a breaking typing change for downstream implementers.
+- `DeclarativePolicyEngine` now defers `yaml` and `tomllib`/`tomli` imports into the corresponding
+  loaders, so `import agent_kernel` works without the `policy` extra installed. Calling
+  `from_yaml`/`from_toml` without the parser surfaces a `PolicyConfigError` with an install hint.
+- `Kernel.invoke(dry_run=True)` resolves `operation` the same way drivers do
+  (`args.get("operation", capability_id)`) so `DryRunResult.operation` matches what a driver would
+  actually receive — instead of `capability.impl.operation`, which can diverge.
+- `Kernel.invoke(dry_run=True)` mirrors the Firewall's admin-only gate for `raw` mode: non-admin
+  principals see their requested `raw` mode downgraded to `summary` in `DryRunResult`, matching
+  what they would actually get at real-invoke time. Prevents probing for raw availability.
+
+### Documentation
+- `docs/architecture.md` now describes `PolicyEngine` / `ExplainingPolicyEngine` protocols,
+  `DefaultPolicyEngine` and `DeclarativePolicyEngine` (with policy-DSL semantics), and dry-run
+  mode (admin gate, operation resolution rule). Closes the canonical "Components & API
+  reference" gap flagged in audit.
+- `docs/capabilities.md` adds a "Dry-run mode" section (semantics, the three parity rules,
+  no-side-effects guarantee), a "Declarative policies" section (loaders, match conditions,
+  optional-extra behaviour), and a "Denial explanations" section. Closes the affected-files
+  gap from issue #43.
+
+### Fixed
+- `DeclarativePolicyEngine._parse_rule()` now validates the types of `roles`, `attributes`,
+  `min_justification`, and `constraints` in policy files and raises `PolicyConfigError` with a
+  precise message instead of silently producing misbehaving rules or raising at evaluation time.
+- `DeclarativePolicyEngine.explain()` now correctly reports explicit deny rules that fully match
+  (previously fell through to the misleading `no_matching_rule` fallback and dropped the rule's
+  reason). Partial-match deny rules are now skipped so the explanation focuses on actionable allow
+  rules instead of suggesting changes that would only trigger the deny.
+- Example policy files (`examples/policies/default.{yaml,toml}`) now use the correct `default` key
+  (was `default_action`, which the parser silently ignored), express PII-with-tenant as an allow
+  rule paired with default-deny (the previous deny rule was inverted under first-match-wins), and
+  order the `allow-secrets-service` rule before the deny rule (the deny was previously unreachable).
+- `Kernel.explain_denial()` docstring no longer contradicts itself ("never raises" vs.
+  `CapabilityNotFound`).
+- `DryRunResult.budget_remaining` docstring no longer references the unimplemented `BudgetManager`;
+  the field is documented as reserved for a future cross-invocation budget mechanism.
+- `drivers/mcp.py` adds an explicit `_McpError: type[BaseException] | None` annotation so mypy
+  `--strict` remains happy across the try/except import branches.
+
+### Tests
+- `tests/test_policy.py` adds `test_declarative_replicates_default_policy_decisions` — a
+  comparative test asserting that `DeclarativePolicyEngine` and `DefaultPolicyEngine` produce
+  the same allow/deny outcomes across a curated scenario matrix (READ × non-sensitive / PII /
+  PCI / SECRETS, WRITE/DESTRUCTIVE with and without required roles and justification). Closes
+  issue #42's "comparative test" acceptance criterion.
+
+## [0.5.0] - 2026-04-12
+
+### Added
+- Built-in `MCPDriver` with stdio and Streamable HTTP transports, tool auto-discovery, normalized MCP result handling, and optional dependency guardrails.
+- Declared weaver-spec v0.1.0 compatibility in README: invariants I-01 (firewall), I-02 (authorization + audit), and I-06 (scoped tokens) are satisfied.
+- Added placeholder `conformance_stub` CI job that will activate once the weaver-spec conformance suite ships (dgenio/weaver-spec#4).
+
+## [0.4.0] - 2026-03-14
+
+### Added
+- Sliding-window rate limiting in `DefaultPolicyEngine` per `(principal_id, capability_id)` pair (#39).
+  Default limits by safety class: 60 READ / 10 WRITE / 2 DESTRUCTIVE per 60s window.
+  Service-role principals get 10× limits. Configurable via constructor.
+- GitHub Release step in publish workflow — creates a release with auto-generated notes and artifacts before publishing to PyPI.
+
+### Fixed
+- `HTTPDriver`: DELETE requests now forward args as query params instead of silently dropping them.
+
+### Removed
+- Dead `_truncate_str` helper in `firewall/transform.py` (defined but never called).
+
+## [0.3.0] - 2026-03-09
+
+### Added
+- Structured logging at kernel decision points (invoke, grant, deny, revoke).
+- Agent-facing documentation system: `docs/agent-context/` (architecture, workflows, invariants, lessons-learned, review-checklist).
+- `.github/copilot-instructions.md` — review-critical projections for GitHub Copilot.
+- `.claude/CLAUDE.md` — Claude-specific operating instructions.
+- PyPI publish workflow (`.github/workflows/publish.yml`) with Trusted Publisher (OIDC) (#37).
+- `RELEASE.md` documenting the full release process.
+- `[project.urls]` in `pyproject.toml` (Homepage, Repository, Documentation, Changelog).
+- Optional dependency groups: `mcp` and `otel` in `pyproject.toml`.
+
+### Changed
+- Rewrote `AGENTS.md` with full domain vocabulary, security rules, code conventions, documentation map, and weaver-spec references.
+- Renamed PyPI package from `agent-kernel` to `weaver-kernel` to align with Weaver ecosystem.
+- Added `workflow_call` trigger to CI workflow so publish workflow can reuse it as a gate.
+
+### Refactored
+- Extracted `_log_verify_failure` helper in `tokens.py`.
+- Consolidated invoke logging with shared base dict in `kernel.py`.
+- Extracted `_deny` static method in policy engine.
+
+### Fixed
+- Pinned GitHub Actions to commit SHAs in publish workflow.
+- Added `contents:read` permission to publish job.
+- Clarified PyPI vs import name in README Quickstart.
+
+## [0.2.0] - 2026-03-06
+
+### Added
+- Token revocation support: `revoke_token()` and `revoke_all()` on `Kernel` (#33, #57).
+- `SECRETS` sensitivity tag enforcement in policy engine and redaction (#56).
+
+### Fixed
+- Policy engine now strips whitespace from justification before length check.
+- Policy engine reports both raw and stripped length in justification errors.
+- Policy engine checks role before justification in all safety/sensitivity blocks.
+- Redaction preserves field-name context in API key and connection string patterns.
+- `revoke_all()` drops `_principal_tokens` entry after revoking.
+
+## [0.1.0] - 2024-01-01
+
+### Added
+- Initial scaffold: `CapabilityRegistry`, `PolicyEngine`, `HMACTokenProvider`, `Kernel`.
+- `InMemoryDriver` and `HTTPDriver` (httpx-based).
+- Context `Firewall` with `Budgets`, redaction, and summarization.
+- `HandleStore` with TTL, pagination, field selection, and basic filtering.
+- `TraceStore` and `explain()` for full audit trail.
+- Examples: `basic_cli.py`, `billing_demo.py`, `http_driver_demo.py`.
+- Documentation: architecture, security model, integrations, capabilities, context firewall.
+- CI pipeline for Python 3.10, 3.11, 3.12 with ruff + mypy + pytest.

{weaver_kernel-0.5.0 → weaver_kernel-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weaver-kernel
-Version: 0.5.0
+Version: 0.7.0
 Summary: Capability-based security kernel for AI agents operating in large tool ecosystems
 Project-URL: Homepage, https://github.com/dgenio/agent-kernel
 Project-URL: Repository, https://github.com/dgenio/agent-kernel
@@ -221,6 +221,7 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mcp>=1.6; extra == 'dev'
@@ -228,11 +229,19 @@ Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.6; extra == 'mcp'
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Provides-Extra: policy
+Requires-Dist: pyyaml>=6.0; extra == 'policy'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'policy'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.6; extra == 'tiktoken'
 Description-Content-Type: text/markdown
 
 # agent-kernel

{weaver_kernel-0.5.0 → weaver_kernel-0.7.0}/docs/agent-context/invariants.md

@@ -64,6 +64,19 @@ tag is **silently ignored** — capabilities tagged with it pass policy without
 
 **Rule:** When adding a `SensitivityTag`, always add a matching policy rule and test.
 
+### Dry-run response-mode parity
+`Kernel.invoke(dry_run=True)` reports the response mode the caller would actually
+get at real-invoke time. The Firewall downgrades `raw` to `summary` for non-admin
+principals (`firewall/transform.py:108`), so dry-run must mirror that downgrade —
+otherwise a non-admin caller can probe/assume raw-mode availability they will never
+actually receive. The same applies to `operation`: dry-run resolves it the same way
+drivers do (`args.get("operation", capability_id)`), so what the caller sees in
+`DryRunResult` matches what a driver would receive.
+
+**Rule:** Any code path that reports a response mode or driver operation back to the
+caller must apply the same admin gate / resolution rule the real-invoke path uses,
+including dry-run, mock, and test paths.
+
 ## Safe vs. unsafe changes
 
 | Safe | Unsafe |

weaver_kernel-0.7.0/docs/architecture.md

@@ -0,0 +1,153 @@
+# Architecture
+
+## Overview
+
+`agent-kernel` is a capability-based security kernel that sits **above** raw tool execution (MCP, HTTP APIs, internal services) and **below** the LLM context window.
+
+```mermaid
+graph TD
+    LLM["LLM / Agent"] -->|goal text| K["Kernel"]
+    K -->|search| REG["CapabilityRegistry"]
+    REG -->|CapabilityRequest| K
+    K -->|evaluate| POL["PolicyEngine"]
+    POL -->|PolicyDecision| K
+    K -->|issue| TOK["TokenProvider (HMAC)"]
+    TOK -->|CapabilityToken| K
+    K -->|route| ROU["Router"]
+    ROU -->|RoutePlan| K
+    K -->|execute| DRV["Driver (Memory / HTTP / MCP)"]
+    DRV -->|RawResult| K
+    K -->|transform| FW["Firewall"]
+    FW -->|Frame| K
+    K -->|store| HS["HandleStore"]
+    K -->|record| TS["TraceStore"]
+    K -->|Frame| LLM
+```
+
+## Components
+
+### Kernel
+The central orchestrator. Wires all components together and exposes:
+- `request_capabilities(goal)` — discover relevant capabilities
+- `grant_capability(request, principal, justification)` — policy check + token issuance
+- `invoke(token, principal, args, response_mode, dry_run=False)` — execute + firewall + trace, or short-circuit before driver dispatch when `dry_run=True`
+- `expand(handle, query)` — paginate/filter stored results
+- `explain(action_id)` — retrieve audit trace
+- `explain_denial(request, principal, justification)` — return a structured `DenialExplanation` instead of raising `PolicyDenied`
+
+### CapabilityRegistry
+A flat dict of `Capability` objects indexed by `capability_id`. Provides keyword-based search (no LLM, no vector DB — purely token overlap scoring).
+
+### PolicyEngine
+Two protocols and two built-in engines:
+
+- **`PolicyEngine`** (protocol) — single required method: `evaluate(request, capability, principal, justification) -> PolicyDecision`.
+- **`ExplainingPolicyEngine`** (protocol, extends `PolicyEngine`) — adds `explain(...) -> DenialExplanation`. Only engines that implement this protocol can be used with `Kernel.explain_denial`; otherwise that call raises `AgentKernelError` with a clear message. Splitting the contract keeps existing downstream `PolicyEngine` implementers backward-compatible.
+
+Both built-in engines satisfy `ExplainingPolicyEngine`:
+
+- **`DefaultPolicyEngine`** — hardcoded role-based rules:
+  1. **READ** — always allowed
+  2. **WRITE** — requires `justification ≥ 15 chars` + role `writer|admin`
+  3. **DESTRUCTIVE** — requires role `admin` + `justification ≥ 15 chars`
+  4. **PII/PCI** — requires `tenant` attribute; enforces `allowed_fields` unless `pii_reader`
+  5. **SECRETS** — requires role `admin|secrets_reader` + `justification ≥ 15 chars`
+  6. **max_rows** — 50 (user), 500 (service)
+  7. **Rate limiting** — sliding-window per `(principal_id, capability_id)` (60 READ / 10 WRITE / 2 DESTRUCTIVE per 60s; service role gets 10×)
+- **`DeclarativePolicyEngine`** — loads rules from a YAML or TOML file (or a plain dict). Supports `safety_class`, `sensitivity`, `roles`, `attributes`, `min_justification`, `intent`, and `scope` match conditions; `allow`/`deny` actions; per-rule `constraints` merged into the resulting `PolicyDecision`; configurable `default` action. Rules are evaluated top-down with first-match-wins. `pyyaml` and `tomli` are optional dependencies — `import agent_kernel` works without them; calling `from_yaml`/`from_toml` without the parser raises `PolicyConfigError` with an install hint.
+
+#### Intent and scope on requests
+
+`CapabilityRequest` carries optional structured metadata alongside its free-text `goal`:
+
+- `intent: str | None` — a machine-readable label (e.g. `"customer_support_lookup"`).
+- `scope: dict[str, Any]` — a small structured map (e.g. `{"region": "eu-west", "customer_id": "C-42"}`).
+
+`DeclarativePolicyEngine` rules can match on these via top-level keys in `match`:
+
+```yaml
+- name: support_eu_lookup
+  match:
+    safety_class: [READ]
+    intent: [customer_support_lookup]
+    scope: { region: "eu-west" }
+  action: allow
+```
+
+Intent-aware rules fail closed: a request with `intent=None` never matches a rule that requires a specific intent. `scope: { key: "*" }` means "the key must be present with any value".
+
+#### Denial explanations
+
+`PolicyEngine.explain()` (when available) returns a structured `DenialExplanation` with `denied`, `rule_name`, a `failed_conditions: list[FailedCondition]` describing each missing condition with `required`/`actual`/`suggestion`/`reason_code`, a `remediation` list, a human-readable `narrative`, and a top-level `reason_code` (the code of the first failed condition). Engines collect all failing conditions (no short-circuit) so callers get the full picture. For `DeclarativePolicyEngine`, an explicit deny rule that fully matches is reported as the cause; partial-match deny rules are skipped during explanation so the surfaced advice is actionable rather than self-defeating.
+
+#### Reason codes
+
+Every `PolicyDecision`, `DenialExplanation`, `FailedCondition`, and `PolicyDenied` from the built-in engines carries a stable `reason_code`. Assert on these codes — not on the human-readable `reason` / `narrative` strings:
+
+| Code (`DenialReason.*`) | When |
+|---|---|
+| `missing_role` | Principal lacks a required role |
+| `missing_tenant_attribute` | PII/PCI capability needs `tenant` attribute |
+| `missing_attribute` | Declarative rule's required attribute absent or mismatched |
+| `insufficient_justification` | Justification shorter than the minimum |
+| `invalid_constraint` | Constraint value (e.g. `max_rows`) not parseable |
+| `rate_limited` | Sliding-window rate limit exceeded |
+| `no_matching_rule` | DSL: no rule matched + default `deny` |
+| `explicit_deny_rule` | DSL: a `deny` rule matched fully |
+| `intent_not_allowed` | DSL: `match.intent` rejected the request's intent |
+| `scope_not_allowed` | DSL: `match.scope` rejected the request's scope |
+
+Allow-side codes (`AllowReason.*`): `default_policy_allow`, `rule_allow`, `default_fallthrough_allow`, `token_verified`.
+
+#### Decision trace
+
+Every `PolicyDecision` from a built-in engine carries a `PolicyDecisionTrace` describing how the decision was reached: the engine name, the capability and principal IDs, the request's `intent` (echoed) and `scope_keys` (scope dimension names only — values are redacted), and an ordered list of `PolicyTraceStep` entries. Each step records the rule name, the outcome (`matched`/`skipped`/`denied`/`allowed`/`constraint_applied`), a human-readable detail, and — for terminal steps — the same stable `reason_code` carried on the decision. Traces are safe to log and serialize: they contain rule names, condition names, and codes only — never raw argument values.
+
+#### Dry-run mode
+
+`Kernel.invoke(dry_run=True)` verifies the token and resolves the route plan but **never calls the driver**. It returns a `DryRunResult` with the resolved `driver_id`, the same `operation` a driver would receive (`args.get("operation", capability_id)`), the request constraints, the effective `response_mode` (Firewall's admin-only gate is mirrored: non-admin `raw` is downgraded to `summary`), and a coarse `estimated_cost` tier based on `SafetyClass`. Token verification still raises `TokenExpired` / `TokenInvalid` / `TokenScopeError` in dry-run, so the mode is safe as a policy/route sanity check. See [`docs/capabilities.md`](capabilities.md#dry-run-mode) for usage and [`docs/agent-context/invariants.md`](agent-context/invariants.md) for the parity rule with the real-invoke path.
+
+### TokenProvider (HMAC)
+Issues HMAC-SHA256 signed tokens. Each token is bound to `principal_id + capability_id + constraints`. Verification checks: expiry → signature → principal → capability.
+
+### Router
+`StaticRouter` maps `capability_id → [driver_id, ...]`. First driver that succeeds wins; others are tried as fallbacks.
+
+### Drivers
+- **InMemoryDriver** — Python callables, used for tests and demos
+- **HTTPDriver** — `httpx`-based async HTTP client
+- (Future) **MCPDriver** — adapter for Model Context Protocol tool servers
+
+### Firewall
+Transforms `RawResult → Frame`. Never exposes raw output to the LLM.
+- Four response modes: `summary`, `table`, `handle_only`, `raw`
+- Enforces `Budgets` (max_rows, max_fields, max_chars, max_depth)
+- Redacts sensitive fields and inline PII patterns
+- Deterministic summarisation (no LLM)
+
+### HandleStore
+Stores full results by opaque handle ID with TTL. `expand()` supports pagination, field selection, and basic equality filtering.
+
+### TraceStore
+Records every `ActionTrace`. `explain(action_id)` returns the full audit record.
+
+### Adapters (`agent_kernel.adapters`)
+Vendor-specific tool-format adapters that translate between `Capability` objects
+and the tool shapes used by LLM provider APIs:
+
+- **`OpenAIMiddleware`** — emits OpenAI tool definitions (Responses API or Chat
+  Completions shape), parses `response.output` / `message.tool_calls`, and
+  returns `function_call_output` / tool-result messages. Dotted capability IDs
+  map to `namespace__function` (OpenAI tool names cannot contain `.`).
+- **`AnthropicMiddleware`** — emits Anthropic tool definitions with optional
+  `cache_control` blocks, parses `tool_use` content blocks, and returns
+  `tool_result` content blocks. Dotted capability IDs are preserved as-is.
+
+Both classes share `BaseToolMiddleware`, which owns hook registration
+(`intercept_tool_call`, `intercept_tool_result`), pre/post dispatch (sync or
+async), and conversion of kernel exceptions (`PolicyDenied`,
+`CapabilityNotFound`, `DriverError`) into tool-result errors the LLM can react
+to. Input arguments are validated against `Capability.parameters_model`
+(pydantic) when present. **Zero runtime dependency** on the `openai` /
+`anthropic` SDK packages. See [`docs/integrations.md`](integrations.md) for
+usage examples.

weaver_kernel-0.7.0/docs/capabilities.md

@@ -0,0 +1,169 @@
+# Designing Capabilities
+
+## Naming conventions
+
+- Use `domain.verb_noun` format: `billing.list_invoices`, `users.get_profile`.
+- Be specific: prefer `billing.cancel_invoice` over `billing.update`.
+- Avoid generic names like `billing.execute` or `api.call`.
+
+## Granularity
+
+Each capability should map to a single, auditable action with clear side-effects.
+
+**Good:**
+- `billing.list_invoices` (READ, no side-effects)
+- `billing.send_reminder` (WRITE, sends an email)
+- `billing.void_invoice` (DESTRUCTIVE, irreversible)
+
+**Avoid:**
+- `billing.do_stuff` (too broad)
+- `billing.list_or_update_invoices` (mixed safety classes)
+
+## Safety classes
+
+| Class | Examples | Policy |
+|-------|---------|--------|
+| READ | list, get, search, summarize | Always allowed |
+| WRITE | create, update, send, approve | Justification + writer role |
+| DESTRUCTIVE | delete, void, purge, terminate | Admin role only |
+
+## Sensitivity tags
+
+Use `SensitivityTag.PII` when results may contain: name, email, phone, SSN, address.
+Use `SensitivityTag.PCI` when results may contain: card numbers, CVV, bank details.
+Use `SensitivityTag.SECRETS` when results may contain: API keys, passwords, tokens.
+
+Always pair sensitivity tags with `allowed_fields` to restrict which fields are returned
+to non-privileged callers.
+
+## Tags
+
+Add descriptive tags to improve keyword matching:
+
+```python
+Capability(
+    capability_id="billing.list_invoices",
+    tags=["billing", "invoices", "list", "finance", "accounts receivable"],
+    ...
+)
+```
+
+## Dry-run mode
+
+`Kernel.invoke(..., dry_run=True)` verifies the token and resolves the route
+plan but **never calls the driver**. Use it to validate that a principal can
+invoke a capability, inspect what a driver *would* receive, or run policy
+checks in CI without live tool backends.
+
+```python
+result = await kernel.invoke(
+    token,
+    principal=principal,
+    args={"operation": "billing.list_invoices", "max_rows": 5},
+    response_mode="summary",
+    dry_run=True,
+)
+# result: DryRunResult(
+#   capability_id="billing.list_invoices",
+#   principal_id="user-001",
+#   policy_decision=PolicyDecision(allowed=True, ...),
+#   driver_id="billing",
+#   operation="billing.list_invoices",
+#   resolved_args={"operation": "billing.list_invoices", "max_rows": 5},
+#   response_mode="summary",
+#   budget_remaining=None,
+#   estimated_cost="low",
+# )
+```
+
+Three rules govern dry-run behaviour — keep them in sync with the real-invoke
+path if you change either:
+
+1. **Token verification still runs.** Expired, revoked, or scope-mismatched
+   tokens raise `TokenExpired` / `TokenRevoked` / `TokenInvalid` /
+   `TokenScopeError` exactly as they would at real-invoke. Policy is *not*
+   re-evaluated at invoke time — the granting policy decision is encoded in
+   the token at `grant_capability`.
+2. **Operation resolution mirrors drivers.** `DryRunResult.operation` is
+   computed the same way every driver computes it:
+   `str(args.get("operation", capability_id))`. Always use `args["operation"]`
+   when you need a fixed operation; otherwise the dry-run operation is the
+   capability ID, matching what the driver would see.
+3. **Raw-mode admin gate mirrors the Firewall.** Non-admin principals never
+   get `response_mode="raw"` at real-invoke (the Firewall downgrades it to
+   `"summary"` — see `firewall/transform.py`). Dry-run downgrades the same
+   way, so non-admin callers cannot probe for raw-mode availability via
+   `DryRunResult`.
+
+The driver's `execute()` is never called in dry-run, so the mode is free of
+side effects regardless of driver type (`InMemoryDriver`, `HTTPDriver`,
+`MCPDriver`). `DryRunResult.budget_remaining` is currently always `None`; the
+field is reserved for a future cross-invocation budget mechanism.
+
+## Declarative policies
+
+`DeclarativePolicyEngine` is an alternative to `DefaultPolicyEngine` that
+loads rules from a YAML or TOML file (or a plain dict). Rules are evaluated
+top-down, first-match-wins; if no rule matches, the policy's `default` action
+applies (`"deny"` unless overridden).
+
+```python
+from pathlib import Path
+from agent_kernel import DeclarativePolicyEngine, Kernel
+
+# YAML or TOML — both formats are interchangeable.
+policy = DeclarativePolicyEngine.from_yaml(Path("examples/policies/default.yaml"))
+
+# Or build entirely in-memory:
+policy = DeclarativePolicyEngine.from_dict({
+    "default": "deny",
+    "rules": [
+        {"name": "allow-read", "action": "allow",
+         "match": {"safety_class": ["READ"], "sensitivity": ["NONE"]}},
+        # ...
+    ],
+})
+
+kernel = Kernel(registry=registry, policy=policy)
+```
+
+A rule's `match` block supports `safety_class`, `sensitivity`, `roles`
+(ANY-of), `attributes` (ALL-of, with `"*"` meaning "attribute must be
+present"), and `min_justification` (minimum stripped length). On `allow`, the
+rule's `constraints` are merged into the resulting `PolicyDecision`. On
+`deny`, `reason` is embedded in the raised `PolicyDenied`.
+
+The DSL has no negation/missing-attribute operator today, so a policy that
+should deny "when an attribute is missing" should be expressed as an allow
+rule requiring the attribute paired with `default: deny`. See
+[`examples/policies/default.yaml`](../examples/policies/default.yaml) for a
+worked example.
+
+`pyyaml` and `tomli` are **optional** — they live behind the `[policy]`
+extra. `import agent_kernel` always works; calling `from_yaml` / `from_toml`
+without the parser installed raises `PolicyConfigError` with an install hint.
+
+## Denial explanations
+
+When a capability call is denied, `Kernel.explain_denial(request, principal,
+justification="")` returns a structured `DenialExplanation` describing
+**every** unmet condition (not just the first one), so the caller can see the
+full remediation path:
+
+```python
+explanation = kernel.explain_denial(
+    CapabilityRequest(capability_id="billing.update_invoice", goal="..."),
+    principal,
+    justification="too short",
+)
+# explanation.denied == True
+# explanation.rule_name == "write-min_justification"
+# explanation.failed_conditions == [FailedCondition(condition="roles", required=[...]), ...]
+# explanation.remediation == ["Add 'writer' or 'admin' role to ...", "Provide ..."]
+# explanation.narrative == "Request for 'billing.update_invoice' by '...' would be denied: ..."
+```
+
+Both built-in engines support `explain()`. If you bring a custom policy
+engine that implements only `PolicyEngine.evaluate`, `explain_denial` raises
+`AgentKernelError` with guidance — implement the `ExplainingPolicyEngine`
+protocol to enable structured explanations.