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

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/.github/workflows/ci.yml

@@ -45,6 +45,7 @@ jobs:
           python examples/basic_cli.py
           python examples/billing_demo.py
           python examples/http_driver_demo.py
+          python examples/tutorial.py
 
   conformance_stub:
     name: "Weaver Spec Conformance Stub (v0.1.0)"

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-22
+
+### Added
+- "Secure your first MCP tool in 5 minutes" tutorial: new
+  [`docs/tutorial.md`](docs/tutorial.md) walks a new reader from install to a
+  working invocation, covering registration, principals, grants, the three
+  LLM-safe response modes (`summary` / `table` / `handle_only`), handle
+  expansion, policy denial with stable `reason_code`, and `explain()`
+  audit. The admin-only `raw` mode is described but not exercised by the
+  walkthrough. Companion runnable example
+  [`examples/tutorial.py`](examples/tutorial.py) uses `InMemoryDriver`
+  (offline, zero external deps) and is exercised by `make example` and CI;
+  it now `assert`s that no PII field leaks into the LLM-safe Frame so a
+  firewall regression fails the build. (#46)
+- README "How this relates to neighboring projects" section: a neutral
+  boundaries table covering `AgentFence` (external CLI/proxy gate),
+  `contextweaver` (context compilation library), `ChainWeaver`
+  (deterministic flow orchestrator), and `weaver-spec` (specification +
+  conformance suite), plus a "When *not* to use this" callout. (#71)
+- Grant-constraint enforcement on handle expansion (#76). `Handle` now carries
+  the `principal_id` and `constraints` from the original grant, persisted at
+  handle creation time by `HandleStore.store`. `HandleStore.expand` rechecks
+  these against the requested expand query:
+  - A request `limit` larger than the grant's `max_rows` is rejected with
+    `HandleConstraintViolation` (`reason_code = handle_constraint_violation`).
+  - A request `fields` entry outside `allowed_fields` is rejected; an
+    unscoped expand applies `allowed_fields` as the default projection.
+  - A request filter that disagrees with the grant's `scope` is rejected;
+    the scope filter is otherwise AND-merged so the caller cannot bypass it.
+  - A `principal_id` parameter that does not match the handle's stored
+    principal raises `HandleConstraintViolation`
+    (`reason_code = handle_principal_mismatch`).
+- `SensitivityTag.MEMORY` and memory-action policy rules in
+  `DefaultPolicyEngine` (#75). Project-scoped memory reads are allowed by
+  default; sensitive-scoped reads require the `memory_reader_sensitive` role
+  (or `admin`); writes always require `memory_writer` (or `admin`). The
+  `explain()` path lists the same conditions with stable `reason_code`s.
+- New stable `DenialReason` codes: `HANDLE_CONSTRAINT_VIOLATION`,
+  `HANDLE_PRINCIPAL_MISMATCH`, `MEMORY_WRITE_REQUIRES_WRITER`,
+  `MEMORY_SENSITIVE_READ_DENIED`.
+- `HandleConstraintViolation` error class (subclass of `AgentKernelError`,
+  exported from `agent_kernel`) — carries an optional `reason_code` matching
+  the `DenialReason` vocabulary so handle-side and grant-side denials share
+  one set of stable codes.
+- `Kernel.expand` accepts an optional `principal: Principal` argument that
+  is forwarded to `HandleStore.expand` for principal-mismatch checks.
+- Memory-action input redaction (#75): `ActionTrace.args` for any capability
+  whose ID starts with `memory.` has payload-like keys (`payload`, `content`,
+  `value`, `memory`, `text`, `body`) replaced with `"[REDACTED]"`. Keys are
+  preserved so audit can confirm the action took place without exposing the
+  durable content the agent wrote or read.
+- New `tests/test_firewall_boundary.py` (#74) — focused regression suite that
+  pushes synthetic secret/PII values through the raw → `Frame` boundary
+  end-to-end and asserts those values never appear in summary/table/raw
+  frames, are stripped by `allowed_fields`, never reach `ActionTrace.args`
+  for memory capabilities, and stay quarantined when raw mode is downgraded
+  for non-admin principals.
+
+### Security
+- Closes #76: handle expansion can no longer return data outside the original
+  grant's `max_rows` / `allowed_fields` / `scope`, and handle IDs are no
+  longer bearer credentials that work across principals.
+- Closes #75: memory reads and writes are governed actions with stable
+  denial codes and trace-side redaction of durable payloads.
+- Closes #74: redaction boundary is pinned by negative assertions against
+  fake-secret strings, catching future regressions that drop a redaction
+  step or route raw data through a new path.
+
 ## [0.7.0] - 2026-05-20
 
 ### Added

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/Makefile

@@ -16,5 +16,6 @@ example:
 	python examples/basic_cli.py
 	python examples/billing_demo.py
 	python examples/http_driver_demo.py
+	python examples/tutorial.py
 
 ci: fmt lint type test example

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weaver-kernel
-Version: 0.7.0
+Version: 0.8.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
@@ -289,6 +289,8 @@ pip install weaver-kernel
 
 > **Note:** The PyPI package is `weaver-kernel` (Weaver ecosystem), but the Python import remains `agent_kernel`.
 
+> **New here?** [docs/tutorial.md](docs/tutorial.md) walks through register → grant → invoke → expand → explain in five minutes.
+
 ```python
 import asyncio, os
 os.environ["AGENT_KERNEL_SECRET"] = "my-secret"
@@ -356,6 +358,45 @@ asyncio.run(main())
 
 `agent-kernel` sits **above** `contextweaver` (context compilation) and **above** raw tool execution. It provides the authorization, execution, and audit layer.
 
+## How this relates to neighboring projects
+
+`agent-kernel` is the embeddable runtime layer of the **Weaver ecosystem**. The
+projects below solve adjacent problems and are designed to compose, not to
+overlap.
+
+| Project | Role | Where it runs | Use it when… |
+|---|---|---|---|
+| **agent-kernel** *(this repo)* | Embeddable library/runtime: capability registry, policy, HMAC tokens, context firewall, audit trace. | In-process inside your agent host. | You need authorization, redaction, and audit between an LLM loop and a large tool ecosystem. |
+| [**AgentFence**](https://github.com/dgenio/AgentFence) | External CLI / local proxy that intercepts tool calls and applies a policy gate. | Out-of-process, alongside your agent. | You want a policy boundary without changing your agent code, or you need to gate a third-party agent host you can't modify. |
+| [**contextweaver**](https://github.com/dgenio/contextweaver) | Library that selects and compiles the context an LLM receives. | In-process, before the LLM call. | You need to assemble relevant context for a prompt. It sits *under* the LLM loop; agent-kernel sits *between* the LLM and tools. |
+| **ChainWeaver** | Orchestrator for deterministic tool chains. | In-process or as a separate service. | You need to run a multi-step deterministic flow rather than free-form LLM tool use. |
+| [**weaver-spec**](https://github.com/dgenio/weaver-spec) | Specification: invariants, capability/token/frame contracts, conformance suite. | Not a runtime — it's docs + a contract test suite. | You're building another Weaver-compatible implementation, or you want to verify an existing one. |
+
+A minimal architecture using `agent-kernel` as the central runtime:
+
+```
+LLM / agent loop
+       │
+       ▼
+contextweaver  ─►  agent-kernel  ─►  driver  ─►  MCP / HTTP / A2A / internal API
+                       │
+                       ▼
+                  ActionTrace
+```
+
+### When *not* to use this
+
+- You only need a process-level policy gate around an existing agent host —
+  reach for `AgentFence` instead.
+- You only need to compile context for a prompt — use `contextweaver`.
+- You want a deterministic, scripted workflow with no LLM in the inner loop —
+  use `ChainWeaver`.
+- You're writing a static analyzer or one-shot CLI scanner with no
+  per-invocation runtime — `agent-kernel` would be overkill.
+
+See [docs/tutorial.md](docs/tutorial.md) for an end-to-end "secure your first
+MCP tool in 5 minutes" walkthrough.
+
 ## Weaver Spec Compatibility: v0.1.0
 
 agent-kernel is a compliant implementation of [weaver-spec v0.1.0](https://github.com/dgenio/weaver-spec).

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/README.md

@@ -43,6 +43,8 @@ pip install weaver-kernel
 
 > **Note:** The PyPI package is `weaver-kernel` (Weaver ecosystem), but the Python import remains `agent_kernel`.
 
+> **New here?** [docs/tutorial.md](docs/tutorial.md) walks through register → grant → invoke → expand → explain in five minutes.
+
 ```python
 import asyncio, os
 os.environ["AGENT_KERNEL_SECRET"] = "my-secret"
@@ -110,6 +112,45 @@ asyncio.run(main())
 
 `agent-kernel` sits **above** `contextweaver` (context compilation) and **above** raw tool execution. It provides the authorization, execution, and audit layer.
 
+## How this relates to neighboring projects
+
+`agent-kernel` is the embeddable runtime layer of the **Weaver ecosystem**. The
+projects below solve adjacent problems and are designed to compose, not to
+overlap.
+
+| Project | Role | Where it runs | Use it when… |
+|---|---|---|---|
+| **agent-kernel** *(this repo)* | Embeddable library/runtime: capability registry, policy, HMAC tokens, context firewall, audit trace. | In-process inside your agent host. | You need authorization, redaction, and audit between an LLM loop and a large tool ecosystem. |
+| [**AgentFence**](https://github.com/dgenio/AgentFence) | External CLI / local proxy that intercepts tool calls and applies a policy gate. | Out-of-process, alongside your agent. | You want a policy boundary without changing your agent code, or you need to gate a third-party agent host you can't modify. |
+| [**contextweaver**](https://github.com/dgenio/contextweaver) | Library that selects and compiles the context an LLM receives. | In-process, before the LLM call. | You need to assemble relevant context for a prompt. It sits *under* the LLM loop; agent-kernel sits *between* the LLM and tools. |
+| **ChainWeaver** | Orchestrator for deterministic tool chains. | In-process or as a separate service. | You need to run a multi-step deterministic flow rather than free-form LLM tool use. |
+| [**weaver-spec**](https://github.com/dgenio/weaver-spec) | Specification: invariants, capability/token/frame contracts, conformance suite. | Not a runtime — it's docs + a contract test suite. | You're building another Weaver-compatible implementation, or you want to verify an existing one. |
+
+A minimal architecture using `agent-kernel` as the central runtime:
+
+```
+LLM / agent loop
+       │
+       ▼
+contextweaver  ─►  agent-kernel  ─►  driver  ─►  MCP / HTTP / A2A / internal API
+                       │
+                       ▼
+                  ActionTrace
+```
+
+### When *not* to use this
+
+- You only need a process-level policy gate around an existing agent host —
+  reach for `AgentFence` instead.
+- You only need to compile context for a prompt — use `contextweaver`.
+- You want a deterministic, scripted workflow with no LLM in the inner loop —
+  use `ChainWeaver`.
+- You're writing a static analyzer or one-shot CLI scanner with no
+  per-invocation runtime — `agent-kernel` would be overkill.
+
+See [docs/tutorial.md](docs/tutorial.md) for an end-to-end "secure your first
+MCP tool in 5 minutes" walkthrough.
+
 ## Weaver Spec Compatibility: v0.1.0
 
 agent-kernel is a compliant implementation of [weaver-spec v0.1.0](https://github.com/dgenio/weaver-spec).

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/docs/architecture.md

@@ -52,8 +52,9 @@ Both built-in engines satisfy `ExplainingPolicyEngine`:
   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×)
+  6. **MEMORY** — `memory.read` with `scope.memory_scope == "sensitive"` requires role `memory_reader_sensitive|admin`; `memory.write` / DESTRUCTIVE memory requires role `memory_writer|admin`. Project-scoped memory reads are allowed by default. The kernel also redacts `payload`/`content`/`value`/`memory`/`text`/`body` keys from `ActionTrace.args` for any capability whose ID starts with `memory.`
+  7. **max_rows** — 50 (user), 500 (service)
+  8. **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
@@ -96,6 +97,10 @@ Every `PolicyDecision`, `DenialExplanation`, `FailedCondition`, and `PolicyDenie
 | `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 |
+| `handle_constraint_violation` | `HandleStore.expand` request exceeded grant's `max_rows`, `allowed_fields`, or `scope` (#76) |
+| `handle_principal_mismatch` | Handle expansion attempted by a different principal than the one the original grant was issued to (#76) |
+| `memory_write_requires_writer` | `SensitivityTag.MEMORY` WRITE/DESTRUCTIVE without `memory_writer` or `admin` role (#75) |
+| `memory_sensitive_read_denied` | `SensitivityTag.MEMORY` read with `scope.memory_scope == "sensitive"` without `memory_reader_sensitive` or `admin` role (#75) |
 
 Allow-side codes (`AllowReason.*`): `default_policy_allow`, `rule_allow`, `default_fallthrough_allow`, `token_verified`.
 

weaver_kernel-0.8.0/docs/security.md

@@ -0,0 +1,95 @@
+# Security Model
+
+## Threat model
+
+| Threat | Mitigation |
+|--------|-----------|
+| Tool-space interference (agent calls wrong tool) | Capability registry + policy gate before any execution |
+| Confused deputy attack | Tokens are bound to `principal_id` — cannot be reused by another principal |
+| Token forgery / tampering | HMAC-SHA256 signature; any bit flip → `TokenInvalid` |
+| Token replay after expiry | Expiry checked on every `verify()` call |
+| Context injection via raw tool output | Firewall always transforms `RawResult → Frame`; raw data never reaches LLM by default |
+| PII / PCI leakage | Redaction + `allowed_fields` enforcement in the firewall |
+| Privilege escalation via WRITE/DESTRUCTIVE | Policy engine enforces role requirements |
+| Audit evasion | Every `invoke()` creates an immutable `ActionTrace` |
+| Handle scope escape (expand exceeds grant) | Handles persist grant constraints; `HandleStore.expand` rechecks `max_rows`, `allowed_fields`, `scope`, and principal binding (#76) |
+| Memory exfiltration via tool output | `SensitivityTag.MEMORY` capabilities gate sensitive reads and durable writes; `ActionTrace.args` redacts payload-like fields for `memory.*` capabilities (#75) |
+| Raw memory payload reaching audit log | Kernel strips `payload`/`content`/`value`/`memory`/`text`/`body` from `ActionTrace.args` for `memory.*` capabilities |
+
+## Token scopes
+
+A `CapabilityToken` binds:
+- `capability_id` — which capability is authorized
+- `principal_id` — who the token was issued to
+- `constraints` — max_rows, allowed_fields, etc. (signed into the token)
+- `expires_at` — validity window
+
+Any change to these fields invalidates the HMAC signature.
+
+## Confused deputy prevention
+
+Consider an agent that obtains a token for `billing.list_invoices` then passes it to a different agent. The second agent cannot use it because `verify()` checks that `token.principal_id == expected_principal_id`.
+
+The same principle extends to handles: every `Handle` carries the `principal_id`
+the original grant was issued to. When `handle.principal_id` is non-empty,
+`HandleStore.expand` rejects expansion unless the caller supplies a matching
+`principal_id`. **An omitted or empty `principal_id` is treated as a
+mismatch** (`HandleConstraintViolation`, `reason_code = HANDLE_PRINCIPAL_MISMATCH`),
+so a handle ID alone is not a bearer credential — proof of the original
+principal is always required. `Kernel.expand(..., principal=Principal(...))`
+forwards the principal automatically.
+
+## Handle expansion boundary
+
+Calling `kernel.expand(handle, query=...)` does not re-run the policy engine —
+the original grant already authorised the dataset, and handles are short-lived.
+But the grant's _constraints_ must still apply, otherwise an over-broad
+`expand` query would silently return data the original grant never covered.
+
+`HandleStore.expand` rechecks the constraints the kernel persists on the handle
+at creation time (`token.constraints`):
+
+| Constraint | Enforced behavior on expand |
+|------------|-----------------------------|
+| `max_rows` | A request `limit` larger than the cap raises `HandleConstraintViolation`. An unspecified or larger implicit limit is silently clamped. |
+| `allowed_fields` | A request `fields` entry that is not in `allowed_fields` raises `HandleConstraintViolation`. An unscoped expand applies `allowed_fields` as the default projection, so disallowed fields never leak. |
+| `scope` (e.g. `{"region": "eu"}`) | The scope filter is AND-merged into the request filter. A request filter that disagrees on a scoped dimension raises `HandleConstraintViolation`. |
+| `principal_id` | A mismatched `principal_id` parameter raises `HandleConstraintViolation` (`HANDLE_PRINCIPAL_MISMATCH`). |
+
+Errors carry stable `reason_code` values (`handle_constraint_violation`,
+`handle_principal_mismatch`) — assert on those, not on the message text.
+
+## Memory actions
+
+Capabilities tagged `SensitivityTag.MEMORY` represent durable agent memory
+(project notes, session handoff, learned context). Reads of project-scoped
+memory are allowed by default; reads of sensitive-scoped memory require an
+explicit role. Writes always require the `memory_writer` role (or `admin`)
+because they persist into future sessions.
+
+| Action | Required role | Denial reason code |
+|--------|---------------|--------------------|
+| `memory.read` with `scope["memory_scope"] == "project"` | none | — |
+| `memory.read` with `scope["memory_scope"] == "sensitive"` | `memory_reader_sensitive` or `admin` | `memory_sensitive_read_denied` |
+| `memory.write` (any scope) | `memory_writer` or `admin` | `memory_write_requires_writer` |
+| `memory.forget` (DESTRUCTIVE) | `admin` (then `memory_writer` or `admin`) | `missing_role`, then `memory_write_requires_writer` |
+
+To prevent durable memory content from leaking into the audit log, the kernel
+strips payload-like fields (`payload`, `content`, `value`, `memory`, `text`,
+`body`) from `ActionTrace.args` for any capability whose ID begins with
+`memory.`. Non-sensitive metadata keys (`key`, `id`, `scope`, ...) are
+preserved so audit can still confirm an action took place.
+
+## Security disclaimers
+
+> **v0.1 is not production-hardened for real authentication.**
+
+- HMAC tokens are tamper-evident but **not encrypted**. Do not put sensitive data in token fields.
+- The `AGENT_KERNEL_SECRET` must be kept secret. Rotate it if compromised.
+- The default `InMemoryDriver` has no persistence — suitable for testing only.
+- PII redaction is heuristic (regex-based). It is not a substitute for proper data governance.
+- Rate limiting is enforced per `(principal_id, capability_id)` pair using a sliding window.
+  Default limits: 60 READ / 10 WRITE / 2 DESTRUCTIVE invocations per 60-second window.
+  Principals with the `"service"` role receive 10× the default limits. Limits are
+  configurable via `DefaultPolicyEngine(rate_limits=...)`. There is no distributed or
+  persistent rate-limit state — limits reset on process restart.

weaver_kernel-0.8.0/docs/tutorial.md

@@ -0,0 +1,293 @@
+# Secure your first MCP tool in 5 minutes
+
+This walkthrough takes a brand-new reader from `pip install` to a working,
+authorized, audited tool invocation in roughly five minutes. Every code block
+is copy-pasteable; the runnable companion is
+[`examples/tutorial.py`](../examples/tutorial.py) (covered by CI).
+
+> The PyPI package is **`weaver-kernel`** but the Python import is
+> **`agent_kernel`**. We use both names in this document.
+
+## What you'll learn
+
+By the end of this page you will have seen, in this order:
+
+1. How to register a **capability** and how its `safety_class`,
+   `sensitivity`, and `allowed_fields` shape authorization.
+2. How a **principal** is created and why some attributes (like `tenant`)
+   are required for PII-tagged capabilities.
+3. How to issue a signed **token** with `kernel.get_token(...)`.
+4. How `kernel.invoke(...)` returns a bounded **Frame** in `summary`,
+   `table`, or `handle_only` modes — and why `email` never appears in any
+   of them.
+5. How to retrieve filtered raw rows by expanding a **Handle**.
+6. What a **policy denial** looks like and how to branch on its stable
+   `reason_code`.
+7. How `kernel.explain(action_id)` returns an audit **ActionTrace**.
+8. How to swap the in-process driver for a real **MCP** server.
+
+## 0. Install
+
+```bash
+pip install weaver-kernel
+```
+
+For the MCP section near the end, also install the optional extra:
+
+```bash
+pip install "weaver-kernel[mcp]"
+```
+
+Set a stable HMAC secret for the process. In production this should come
+from a real secret store; the example uses a fixed value so the output is
+reproducible:
+
+```python
+import os
+os.environ["AGENT_KERNEL_SECRET"] = "tutorial-secret-do-not-use-in-prod"
+```
+
+## 1. Register a capability
+
+A capability is the unit of authorization. The `safety_class` controls
+which roles may call it. The `sensitivity` tag tells the policy and
+firewall how to treat the data. `allowed_fields` is the projection the
+firewall applies before any row reaches the LLM.
+
+```python
+from agent_kernel import (
+    Capability,
+    CapabilityRegistry,
+    ImplementationRef,
+    SafetyClass,
+    SensitivityTag,
+)
+
+registry = CapabilityRegistry()
+registry.register(
+    Capability(
+        capability_id="billing.invoices.list",
+        name="List Invoices",
+        description="List recent invoices",
+        safety_class=SafetyClass.READ,
+        sensitivity=SensitivityTag.PII,
+        allowed_fields=["id", "customer_name", "amount", "status"],
+        tags=["billing", "invoices", "list"],
+        impl=ImplementationRef(driver_id="memory", operation="list_invoices"),
+    )
+)
+```
+
+> `email`, `phone`, and other non-listed columns will never reach the LLM
+> even if the driver returns them.
+
+## 2. Wire a driver and the kernel
+
+`InMemoryDriver` keeps the tutorial offline. The same pattern works with
+`HTTPDriver` or `MCPDriver` — see step 8.
+
+```python
+from agent_kernel import HMACTokenProvider, InMemoryDriver, Kernel, StaticRouter
+from agent_kernel.drivers.base import ExecutionContext
+
+INVOICES = [
+    {"id": "INV-001", "customer_name": "Alice", "email": "alice@example.com", "amount": 120.0, "status": "paid"},
+    {"id": "INV-002", "customer_name": "Bob",   "email": "bob@example.com",   "amount": 540.0, "status": "unpaid"},
+    {"id": "INV-003", "customer_name": "Carol", "email": "carol@example.com", "amount":  75.0, "status": "paid"},
+]
+
+driver = InMemoryDriver()
+driver.register_handler("list_invoices", lambda ctx: list(INVOICES))
+
+kernel = Kernel(
+    registry=registry,
+    token_provider=HMACTokenProvider(secret="tutorial-secret-do-not-use-in-prod"),
+    router=StaticRouter(routes={"billing.invoices.list": ["memory"]}),
+)
+kernel.register_driver(driver)
+```
+
+## 3. Create a principal
+
+The `DefaultPolicyEngine` requires a `tenant` attribute on the principal
+for any PII-tagged capability. Without it, the grant is denied with
+`reason_code="missing_tenant_attribute"`.
+
+```python
+from agent_kernel import Principal
+
+alice = Principal(principal_id="alice", roles=["reader"], attributes={"tenant": "acme"})
+```
+
+## 4. Grant a token
+
+`get_token` runs the policy engine and returns a signed
+`CapabilityToken`. No token, no invocation.
+
+```python
+from agent_kernel.models import CapabilityRequest
+
+request = CapabilityRequest(capability_id="billing.invoices.list", goal="list recent invoices")
+token = kernel.get_token(request, alice, justification="")
+print(token.token_id, token.expires_at)
+```
+
+## 5. Invoke and observe the Frame
+
+The default `response_mode` is `"summary"`. The Frame holds compact
+facts about the data plus a Handle the LLM can expand later.
+
+```python
+import asyncio
+
+frame = asyncio.run(kernel.invoke(token, principal=alice, args={"operation": "list_invoices"}))
+for fact in frame.facts:
+    print("•", fact)
+print("handle:", frame.handle and frame.handle.handle_id)
+```
+
+Try `response_mode="table"` to get a row preview that respects
+`allowed_fields`. Try `response_mode="handle_only"` to skip the preview
+entirely — the LLM gets only a reference. In every mode, **`email` is
+absent** from the Frame, because it is not in `allowed_fields`.
+
+```python
+table_frame = asyncio.run(
+    kernel.invoke(
+        kernel.get_token(request, alice, justification=""),
+        principal=alice,
+        args={"operation": "list_invoices"},
+        response_mode="table",
+    )
+)
+assert all("email" not in row for row in table_frame.table_preview)
+```
+
+## 6. Expand a Handle
+
+Handles let the LLM stay inside its context budget while still pulling
+specific rows or fields on demand. The expand query supports `offset`,
+`limit`, `fields`, and an equality `filter`.
+
+```python
+handle_frame = asyncio.run(
+    kernel.invoke(
+        kernel.get_token(request, alice, justification=""),
+        principal=alice,
+        args={"operation": "list_invoices"},
+        response_mode="handle_only",
+    )
+)
+expanded = kernel.expand(
+    handle_frame.handle,
+    query={"offset": 0, "limit": 2, "fields": ["id", "amount"]},
+    principal=alice,
+)
+print(expanded.table_preview)
+# [{'id': 'INV-001', 'amount': 120.0}, {'id': 'INV-002', 'amount': 540.0}]
+```
+
+> **Security boundary.** The `Firewall` enforces `allowed_fields` when it
+> builds the `summary` and `table` previews, so disallowed columns never
+> reach the LLM-safe Frame. `HandleStore.expand()` now also enforces the
+> grant's `allowed_fields` projection: requesting a field outside the
+> grant raises `HandleConstraintViolation`. The `principal` argument
+> ensures handles are not bearer credentials — a handle bound to one
+> principal cannot be expanded by another.
+
+Asking for a disallowed field is rejected with a stable `reason_code`:
+
+```python
+from agent_kernel.errors import HandleConstraintViolation
+
+try:
+    kernel.expand(handle_frame.handle, query={"fields": ["email"]}, principal=alice)
+except HandleConstraintViolation as exc:
+    print(exc.reason_code)   # 'handle_constraint_violation'
+```
+
+The same shape applies to `limit` over the grant's `max_rows`, a
+`filter` that disagrees with the grant's `scope`, and a `principal`
+mismatch (the last raises with
+`reason_code="handle_principal_mismatch"`).
+
+## 7. Watch policy enforcement
+
+Add a WRITE capability and try to call it as the reader principal. The
+denial carries both a human-readable `reason` and a stable
+`reason_code` your code can branch on.
+
+```python
+from agent_kernel.errors import PolicyDenied
+
+registry.register(
+    Capability(
+        capability_id="billing.invoices.create",
+        name="Create Invoice",
+        description="Create a new invoice",
+        safety_class=SafetyClass.WRITE,
+        tags=["billing", "invoices", "create"],
+        impl=ImplementationRef(driver_id="memory", operation="create_invoice"),
+    )
+)
+
+try:
+    kernel.get_token(
+        CapabilityRequest(capability_id="billing.invoices.create", goal="create an invoice"),
+        alice,
+        justification="reader trying a write — should fail",
+    )
+except PolicyDenied as exc:
+    print(exc.reason_code)   # 'missing_role'
+    print(str(exc))          # "WRITE capabilities require the 'writer' or 'admin' role..."
+```
+
+Stable reason codes come from `agent_kernel.policy_reasons.DenialReason`.
+Tests should assert on the code, not on the human-readable string.
+
+## 8. Audit with `explain()`
+
+Every successful invocation creates an `ActionTrace` keyed by
+`frame.action_id`. The trace records who, what, when, and which driver
+served the request — the auditable half of weaver-spec invariant I-02.
+
+```python
+trace = kernel.explain(frame.action_id)
+print(trace.action_id, trace.capability_id, trace.principal_id, trace.driver_id)
+```
+
+## 9. Swap the driver for an MCP server
+
+The kernel doesn't care whether the driver lives in-process, behind
+HTTP, or behind an MCP server — capabilities, policy, tokens, and
+firewall behave identically. To talk to a real MCP server, replace
+`InMemoryDriver` with `MCPDriver` (full transport details, including
+Streamable HTTP, live in [`docs/integrations.md`](integrations.md)):
+
+```python
+from agent_kernel.drivers.mcp import MCPDriver
+
+driver = MCPDriver.from_stdio(
+    command="python",
+    args=["-m", "my_mcp_server"],
+    server_name="local-tools",
+)
+kernel.register_driver(driver)
+
+# Discover the MCP server's tools and register each as an agent-kernel
+# capability under a namespace. Set safety_class/sensitivity/allowed_fields
+# on the resulting Capability objects to apply policy and the firewall.
+capabilities = asyncio.run(driver.discover(namespace="billing"))
+registry.register_many(capabilities)
+```
+
+That's the whole tutorial. From here:
+
+- [`docs/security.md`](security.md) — threat model, what HMAC tokens do
+  and do not protect against.
+- [`docs/context_firewall.md`](context_firewall.md) — redaction,
+  summarization, and budget details.
+- [`docs/capabilities.md`](capabilities.md) — designing capabilities
+  for large tool ecosystems.
+- [`docs/integrations.md`](integrations.md) — full MCP and HTTP driver
+  integration patterns.

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/examples/basic_cli.py

@@ -124,6 +124,7 @@ async def main() -> None:
         expanded = kernel.expand(
             frame.handle,
             query={"offset": 0, "limit": 3, "fields": ["id", "title"]},
+            principal=reader,
         )
         print("  First 3 rows (id + title only):")
         for row in expanded.table_preview:

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/examples/billing_demo.py

@@ -111,6 +111,7 @@ async def main() -> None:
         expanded = kernel.expand(
             frame.handle,
             query={"offset": 0, "limit": 3, "fields": ["id", "amount", "status"]},
+            principal=analyst,
         )
         for row in expanded.table_preview:
             print(f"  {row}")
@@ -121,6 +122,7 @@ async def main() -> None:
         overdue = kernel.expand(
             frame.handle,
             query={"filter": {"status": "overdue"}, "limit": 3, "fields": ["id", "amount"]},
+            principal=analyst,
         )
         print(f"  Overdue rows returned: {len(overdue.table_preview)}")
         for row in overdue.table_preview:

{weaver_kernel-0.7.0 → weaver_kernel-0.8.0}/examples/http_driver_demo.py

@@ -119,6 +119,7 @@ async def main() -> None:
             expanded = kernel.expand(
                 frame.handle,
                 query={"limit": 3, "fields": ["id", "name", "price"]},
+                principal=principal,
             )
             for row in expanded.table_preview:
                 print(f"  {row}")