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

{weaver_kernel-0.5.0 → weaver_kernel-0.6.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.6.0/CHANGELOG.md

@@ -0,0 +1,199 @@
+# 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.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.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weaver-kernel
-Version: 0.5.0
+Version: 0.6.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.6.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.6.0/docs/architecture.md

@@ -0,0 +1,110 @@
+# 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`, and `min_justification` 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.
+
+#### 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`, a `remediation` list, and a human-readable `narrative`. 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.
+
+#### 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.6.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.

weaver_kernel-0.6.0/docs/context_firewall.md

@@ -0,0 +1,120 @@
+# Context Firewall
+
+## Why it exists
+
+Large tool ecosystems produce large, verbose outputs. Passing raw tool output to an LLM
+causes context blowup, leaks PII, and makes the agent unpredictable. The firewall
+transforms every `RawResult` into a bounded `Frame` before the LLM sees it.
+
+## Budgets
+
+```python
+from agent_kernel.firewall.budgets import Budgets
+
+Budgets(
+    max_rows=50,    # max rows in table_preview
+    max_fields=20,  # max fields per row
+    max_chars=4000, # total characters across all facts
+    max_depth=3,    # recursion depth for nested structures
+)
+```
+
+## Response modes
+
+| Mode | What you get | When to use |
+|------|-------------|-------------|
+| `summary` | ≤20 fact strings + handle | Default; best for LLM context |
+| `table` | ≤max_rows dicts + handle | When the LLM needs tabular data |
+| `handle_only` | handle + warnings | Defer all data to an expand() call |
+| `raw` | Full data (admin only) | Debugging; never for LLM context |
+
+## Handles
+
+A `Handle` is an opaque reference to the full dataset stored server-side.
+
+```python
+# Stored automatically on every invoke()
+handle = frame.handle
+
+# Expand with pagination
+expanded = kernel.expand(handle, query={"offset": 10, "limit": 5})
+
+# Field selection
+expanded = kernel.expand(handle, query={"fields": ["id", "name"]})
+
+# Basic filtering
+expanded = kernel.expand(handle, query={"filter": {"status": "unpaid"}})
+```
+
+## Redaction
+
+When a capability has `SensitivityTag.PII` or `SensitivityTag.PCI`:
+- Fields in `Capability.allowed_fields` are kept (others removed)
+- Sensitive field names (`email`, `phone`, `card_number`, `ssn`, etc.) are replaced with `[REDACTED]`
+- Inline patterns in string values (email addresses, phone numbers, SSNs, card numbers) are redacted
+
+Principals with the `pii_reader` role bypass `allowed_fields` enforcement.
+
+## Summarization
+
+Summaries are produced deterministically:
+- **list of dicts** → row count + top keys + numeric stats + categorical distributions
+- **dict** → key list + per-value type/value
+- **string** → truncated to 500 chars
+- **other** → repr() truncated to 200 chars
+
+## Cross-invocation budgets
+
+The per-invocation `Budgets` above cap a single Frame. A separate
+`BudgetManager` tracks cumulative token usage *across* invocations within a
+session. It is optional — if you don't attach one, kernel behavior is
+unchanged.
+
+```python
+from agent_kernel import BudgetManager, Kernel
+
+manager = BudgetManager(total_budget=100_000)
+kernel = Kernel(registry, budget_manager=manager)
+```
+
+Per `invoke()` the kernel:
+
+1. Reserves a slice of the remaining budget (default 4,000 tokens). If the
+   budget is empty, `BudgetExhausted` is raised before the driver runs.
+2. Consults `manager.suggested_mode(requested)` to escalate the requested
+   `response_mode` to a more aggressive tier as the remaining budget shrinks.
+3. After the firewall produces a Frame, counts the actual tokens in the
+   LLM-facing payload and reconciles them against the reservation.
+
+Escalation table:
+
+| Budget remaining | Suggested mode (effective `response_mode`)     |
+|-----------------:|------------------------------------------------|
+| > 50%            | Caller's requested mode (no change)            |
+| 20% – 50%        | `table` (when caller requested `raw`)          |
+| 5% – 20% (≥ 5%)  | `summary` (floor — never *relaxes* to `table`) |
+| < 5%             | `handle_only`                                  |
+
+Boundaries land in the more-conservative tier — exactly 50% remaining
+downgrades `raw` to `table`, exactly 20% floors at `summary`, and only when
+remaining drops *below* 5% does `handle_only` take over.
+
+`Kernel.invoke(..., dry_run=True)` mirrors the escalation and reports
+`budget_remaining` in the returned `DryRunResult`, so callers can preview
+what their next live invocation would actually return.
+
+Plug a different token counter (for example, a `tiktoken`-based one) via the
+`TokenCounter` protocol:
+
+```python
+import tiktoken                         # pip install weaver-kernel[tiktoken]
+enc = tiktoken.encoding_for_model("gpt-4o")
+
+def tiktoken_counter(value):
+    return len(enc.encode(str(value)))
+
+manager = BudgetManager(total_budget=128_000, token_counter=tiktoken_counter)
+```
+
+The default counter (`default_token_counter`) is a character-based
+`len(json.dumps(value)) // 4` approximation with no extra dependencies.