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

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

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

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/AGENTS.md

@@ -46,7 +46,7 @@ Use these terms consistently. Never substitute synonyms:
 
 ## Quality bar
 
-- `make ci` must pass before every push. It runs: `fmt → lint → type → test → example`.
+- `make ci` must pass before every push. It runs: `fmt-check → lint → type → test → example`. Use `make fmt` to auto-fix formatting before re-running `make ci`.
 - All public interfaces need type hints and docstrings.
 - Never raise bare `ValueError` or `KeyError` to callers. Use custom exceptions from `errors.py`. Catching stdlib exceptions internally to remap them is fine.
 - Error messages are part of the contract — tests must assert both exception type and message.

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

@@ -7,6 +7,135 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-29
+
+### Added
+- Capability namespaces and hierarchical discovery in `CapabilityRegistry`:
+  dot-notation `capability_id`s now expose `list_namespaces()` /
+  `list_namespace(prefix)` operations; `register_namespace(prefix, loader=...)`
+  enables deferred registration for large tool ecosystems (the loader runs
+  at most once on first access). `search()` gained an `offset` kwarg for
+  pagination, strips a small stop-word set, and now scores with a
+  BM25-flavoured ranker that weights `capability_id`/`tags` matches above
+  `description`. Flat (un-namespaced) capability IDs continue to work
+  unchanged. (#45)
+- Capability marketplace, part 1 — manifest format & local registry: new
+  `CapabilityDescriptor` and `CapabilityManifest` dataclasses (both
+  JSON-round-trippable via `to_dict`/`from_dict`), new
+  `agent_kernel.federation` module with `build_manifest()`,
+  `import_manifest()`, and `merge_sensitivity()`, and new `Kernel.advertise()`
+  / `Kernel.import_remote()` methods. `Kernel` gained a `kernel_id`
+  argument used as the manifest publisher identity. Three trust policies
+  are honoured at import time (`most_restrictive` (default), `local_only`,
+  `remote_deferred`); imported capabilities are routed through a
+  caller-supplied driver and flow through the full local policy → token →
+  firewall pipeline. HMAC tokens remain kernel-scoped — a token issued by
+  one kernel cannot be verified by another with a different secret. New
+  errors `NamespaceNotFound`, `FederationError`, `ManifestError`,
+  `TrustPolicyError`. (#52)
+- New docs: [`docs/federation.md`](docs/federation.md) for the marketplace
+  protocol and a namespace section in
+  [`docs/capabilities.md`](docs/capabilities.md).
+- Capability marketplace, part 2 — federated discovery: new
+  `agent_kernel.federation_discovery` module with `discover_peers()`,
+  `sign_manifest()`, `verify_manifest()`, `serve_manifest_payload()`, and
+  `DiscoveryRateLimiter`. `Kernel.discover_peers()` fetches one or more
+  manifests over HTTP from peer URLs or a registry URL. Signed envelopes
+  (HMAC-SHA256) detect tampering and let importers refuse unsigned
+  manifests when a verification secret is in play (and vice versa). New
+  errors `ManifestSignatureError` and `DiscoveryError`. (#51, closes #49)
+- OpenTelemetry integration: new `agent_kernel.otel` module with
+  `instrument_kernel(kernel)` that wraps `Kernel.invoke` and
+  `Kernel.grant_capability` with OTel spans + metrics (invocation count,
+  latency histogram, denial counter). No-op when the optional `[otel]`
+  extra is not installed (`OTEL_AVAILABLE` reports the runtime status).
+  Idempotent — repeat calls on the same kernel are no-ops. (#38)
+- Streaming firewall: new `Firewall.apply_stream()` async-iterator method
+  that processes driver chunks one-at-a-time, applying PII redaction
+  per-chunk. New `StreamingDriver` Protocol in `drivers/base.py` extends
+  `Driver` with an optional `execute_stream()`. New `Kernel.invoke_stream()`
+  yields `Frame` chunks; the last chunk carries `is_final=True`. Drivers
+  without `execute_stream` automatically fall back to a single-chunk stream
+  via `execute()`. `Frame` gained an `is_final: bool` field. (#47)
+- `examples/readme_quickstart.py` — a runnable mirror of the README quickstart,
+  wired into `make example` and the CI "Examples" step. Together with
+  `tests/test_readme_quickstart.py` (which extracts and runs the inline README
+  snippet itself), CI fails if the documented quickstart stops producing the
+  expected output. (#83)
+
+### Changed
+- Tech debt: `policy_dsl.py` decomposed (was 661 lines). Parsing and
+  schema dataclasses now live in `policy_dsl_parser.py`
+  (`PolicyMatch`, `PolicyRule`, `parse_engine_data`, `parse_rule`,
+  YAML/TOML loaders), and the denial-explanation traversal in
+  `policy_dsl_explain.py`. The public import surface
+  (`DeclarativePolicyEngine`, `PolicyMatch`, `PolicyRule`) is unchanged.
+  `RateLimiter` and rate-limit constants extracted from `policy.py` into
+  a new `rate_limit.py` module; `policy.py` continues to re-export them
+  under their original names. (#68)
+- Tech debt: `kernel.py` split into the `agent_kernel.kernel` sub-package
+  to honour AGENTS.md's ≤ 300-line module bar. The `Kernel` class lives
+  in `kernel/__init__.py`; heavy methods (invoke pipeline, dry-run,
+  federation, streaming) delegate to sibling modules. Existing
+  `from agent_kernel import Kernel` / `from agent_kernel.kernel import Kernel`
+  imports are unchanged. (#68)
+
+### Documentation
+- Fixed handle-expansion examples that omitted the now-required `principal`
+  argument and therefore raised `HandleConstraintViolation` when copy-pasted:
+  the README quickstart (#83) and `docs/context_firewall.md` +
+  `docs/architecture.md` (#84) now pass `principal=` and link to
+  `docs/security.md#handle-expansion-boundary`. The README quickstart also
+  drops two unused imports (`ExecutionContext`, `HMACTokenProvider`).
+- `docs/capabilities.md` "Sensitivity tags" now lists `SensitivityTag.MEMORY`
+  and links to `docs/security.md#memory-actions`. (#89)
+- Corrected the base-dependency list in `docs/agent-context/invariants.md` and
+  `docs/agent-context/architecture.md` from "`httpx` only" to
+  "`httpx` + `pydantic`", pointing to `AGENTS.md` as the canonical dependency
+  policy. (#90)
+- The `agent_kernel` module docstring's `Errors::` block now lists every
+  exported error class — added `TokenRevoked`, `AdapterParseError`,
+  `CapabilityAlreadyRegistered`, `HandleConstraintViolation`,
+  `ManifestSignatureError`, and `DiscoveryError`. (#91)
+
+### Tests
+- Added explicit dry-run regression tests for `HTTPDriver` and `MCPDriver`,
+  pinning the kernel's driver-agnostic dry-run short-circuit. (#68)
+- `tests/test_public_api.py` — asserts every error class exported via `__all__`
+  appears in the `agent_kernel` module docstring, preventing public-API
+  docstring drift. (#91)
+- `tests/test_readme_quickstart.py` — extracts the README quickstart code block
+  and executes it, asserting the documented output so the inline snippet cannot
+  silently drift from the working API. (#83)
+
+### Fixed
+- `merge_sensitivity()` (and `most_restrictive` imports) now ranks the `MEMORY`
+  sensitivity tag instead of silently treating it as `NONE`. (#52)
+- `import_manifest()` is now atomic: a manifest whose capability ID is already
+  registered locally — or that lists the same ID more than once — raises
+  `ManifestError` and registers nothing, instead of leaving a partial,
+  unrouted import behind. (#52)
+- `CapabilityRegistry.search()` now triggers every pending deferred namespace
+  loader before ranking, so matches are no longer missed when the query shares
+  no token with a namespace prefix. (#45)
+- A deferred namespace loader that fails (by raising or returning an
+  out-of-namespace capability) no longer permanently disables the namespace —
+  the load is retried on a later access. (#45)
+- `Makefile` now invokes every tool via `python -m <tool>` (matching the
+  existing `test` target) so `make ci` uses the active interpreter's
+  site-packages instead of whatever `ruff` / `mypy` resolves first on
+  `PATH`. Fixes spurious `import-not-found` / `no-redef` errors on machines
+  where `mypy` or `ruff` is provided by an isolated installer such as
+  `uv tool` or `pipx`. (#86)
+- `make ci` now runs the non-mutating `fmt-check` target (`ruff format
+  --check`) instead of the file-mutating `fmt` target. Local `make ci`
+  now fails on unformatted code exactly like `.github/workflows/ci.yml`
+  does, instead of silently auto-fixing the working tree and letting an
+  unfixed commit be pushed. `make fmt` remains available for manual
+  auto-formatting. `AGENTS.md`, `docs/agent-context/workflows.md`,
+  `docs/agent-context/review-checklist.md`, `CONTRIBUTING.md`, and the
+  `README.md` development section are updated to describe the new chain. (#88)
+
 ## [0.8.0] - 2026-05-22
 
 ### Added

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/CONTRIBUTING.md

@@ -15,11 +15,12 @@ pip install -e ".[dev]"
 ## Running checks
 
 ```bash
-make fmt    # auto-format with ruff
-make lint   # lint with ruff
-make type   # type-check with mypy
-make test   # run pytest with coverage
-make ci     # all of the above + examples
+make fmt        # auto-format with ruff (not run by `make ci`)
+make fmt-check  # verify formatting with `ruff format --check` (no mutation)
+make lint       # lint with ruff
+make type       # type-check with mypy
+make test       # run pytest with coverage
+make ci         # fmt-check + lint + type + test + example
 ```
 
 ## Pull request guidelines

weaver_kernel-0.9.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: fmt fmt-check lint type test example ci
+
+fmt:
+	python -m ruff format src/ tests/ examples/
+
+fmt-check:
+	python -m ruff format --check src/ tests/ examples/
+
+lint:
+	python -m ruff check src/ tests/ examples/
+
+type:
+	python -m mypy src/
+
+test:
+	python -m pytest -q --cov=agent_kernel
+
+example:
+	python examples/basic_cli.py
+	python examples/billing_demo.py
+	python examples/http_driver_demo.py
+	python examples/tutorial.py
+	python examples/readme_quickstart.py
+
+ci: fmt-check lint type test example

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weaver-kernel
-Version: 0.8.0
+Version: 0.9.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
@@ -296,10 +296,9 @@ import asyncio, os
 os.environ["AGENT_KERNEL_SECRET"] = "my-secret"
 
 from agent_kernel import (
-    Capability, CapabilityRegistry, HMACTokenProvider,
+    Capability, CapabilityRegistry,
     InMemoryDriver, Kernel, Principal, SafetyClass, StaticRouter,
 )
-from agent_kernel.drivers.base import ExecutionContext
 from agent_kernel.models import CapabilityRequest
 
 # 1. Register a capability
@@ -332,7 +331,11 @@ async def main():
     print(frame.facts)           # ['Total rows: 1', 'Top keys: id, title', ...]
     print(frame.handle)          # Handle(handle_id='...', ...)
 
-    expanded = kernel.expand(frame.handle, query={"limit": 1, "fields": ["title"]})
+    # `principal` is required: the handle is bound to the granting principal,
+    # so an omitted principal raises HandleConstraintViolation.
+    expanded = kernel.expand(
+        frame.handle, query={"limit": 1, "fields": ["title"]}, principal=principal
+    )
     print(expanded.table_preview)  # [{'title': 'Buy milk'}]
 
     trace = kernel.explain(frame.action_id)
@@ -341,6 +344,12 @@ async def main():
 asyncio.run(main())
 ```
 
+> This snippet is extracted and executed by CI (`tests/test_readme_quickstart.py`), and
+> a standalone runnable mirror lives at
+> [`examples/readme_quickstart.py`](examples/readme_quickstart.py) (run by `make example`).
+> CI fails if either stops producing the documented output, so this quickstart cannot
+> silently drift from the working API.
+
 ## Where it fits
 
 ```
@@ -433,7 +442,7 @@ See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the
 git clone https://github.com/dgenio/agent-kernel
 cd agent-kernel
 pip install -e ".[dev]"
-make ci      # fmt + lint + type + test + examples
+make ci      # fmt-check + lint + type + test + examples
 ```
 
 ## License

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

@@ -50,10 +50,9 @@ import asyncio, os
 os.environ["AGENT_KERNEL_SECRET"] = "my-secret"
 
 from agent_kernel import (
-    Capability, CapabilityRegistry, HMACTokenProvider,
+    Capability, CapabilityRegistry,
     InMemoryDriver, Kernel, Principal, SafetyClass, StaticRouter,
 )
-from agent_kernel.drivers.base import ExecutionContext
 from agent_kernel.models import CapabilityRequest
 
 # 1. Register a capability
@@ -86,7 +85,11 @@ async def main():
     print(frame.facts)           # ['Total rows: 1', 'Top keys: id, title', ...]
     print(frame.handle)          # Handle(handle_id='...', ...)
 
-    expanded = kernel.expand(frame.handle, query={"limit": 1, "fields": ["title"]})
+    # `principal` is required: the handle is bound to the granting principal,
+    # so an omitted principal raises HandleConstraintViolation.
+    expanded = kernel.expand(
+        frame.handle, query={"limit": 1, "fields": ["title"]}, principal=principal
+    )
     print(expanded.table_preview)  # [{'title': 'Buy milk'}]
 
     trace = kernel.explain(frame.action_id)
@@ -95,6 +98,12 @@ async def main():
 asyncio.run(main())
 ```
 
+> This snippet is extracted and executed by CI (`tests/test_readme_quickstart.py`), and
+> a standalone runnable mirror lives at
+> [`examples/readme_quickstart.py`](examples/readme_quickstart.py) (run by `make example`).
+> CI fails if either stops producing the documented output, so this quickstart cannot
+> silently drift from the working API.
+
 ## Where it fits
 
 ```
@@ -187,7 +196,7 @@ See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the
 git clone https://github.com/dgenio/agent-kernel
 cd agent-kernel
 pip install -e ".[dev]"
-make ci      # fmt + lint + type + test + examples
+make ci      # fmt-check + lint + type + test + examples
 ```
 
 ## License

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/docs/agent-context/architecture.md

@@ -39,7 +39,7 @@ The architecture optimizes for:
 | Tokens signed, not encrypted | Simplicity; avoids key management complexity | Payloads are readable — never store secrets in them |
 | Keyword-based capability search | Deterministic; no external service dependency | Less flexible than semantic search; relies on good tagging |
 | Firewall is mandatory | Prevents accidental context blowup and data leakage | All output is bounded; debugging requires admin `raw` mode |
-| Single dep (`httpx` only) | Minimal attack surface for a security kernel | Adding a dependency requires justification |
+| Minimal deps (`httpx` + `pydantic`) | Small attack surface for a security kernel | Adding a dependency requires justification (see `AGENTS.md`) |
 
 ## Things not to simplify
 

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/docs/agent-context/invariants.md

@@ -40,7 +40,8 @@ These constraints are non-negotiable. Violating any one silently degrades securi
    derived keys must stay out of logs, error messages, and traces.
 
 6. **Never add dependencies without justification.** The dependency list is intentionally
-   minimal (`httpx` only). Every new dependency expands the attack surface.
+   minimal (`httpx` + `pydantic` — see [`AGENTS.md`](../../AGENTS.md) for the canonical
+   dependency policy). Every new dependency expands the attack surface.
 
 7. **Never register duplicate capability IDs.** The registry raises
    `CapabilityAlreadyRegistered`. Duplicates cause ambiguous routing and policy

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/docs/agent-context/review-checklist.md

@@ -10,7 +10,7 @@
 Run before every PR submission.
 
 ### CI gate
-- [ ] `make ci` passes (fmt → lint → type → test → example).
+- [ ] `make ci` passes (fmt-check → lint → type → test → example).
 
 ### Correctness
 - [ ] Every changed docstring matches the actual implementation.

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/docs/agent-context/workflows.md

@@ -7,18 +7,24 @@
 
 | Command | Purpose | When to run |
 |---------|---------|-------------|
-| `make ci` | Full pre-push gate: fmt → lint → type → test → example | Before every push |
-| `make fmt` | Auto-format with ruff | During development |
+| `make ci` | Full pre-push gate: fmt-check → lint → type → test → example | Before every push |
+| `make fmt` | Auto-format with ruff (mutates files) | During development |
+| `make fmt-check` | Verify formatting with `ruff format --check` (no mutation) | Used by `make ci`; matches what CI runs |
 | `make lint` | Lint check with ruff | Isolated lint verification |
 | `make type` | mypy type check | After changing type annotations |
 | `make test` | pytest with coverage | After changing code |
 | `make example` | Run all example scripts | After changing examples or core APIs |
 
 `make ci` is the **single authoritative pre-push command**. It runs all five targets
-in sequence. If `make ci` passes, the PR is ready for review.
-
-**Note:** `make fmt` auto-formats locally, but CI runs `ruff format --check` and fails
-on unformatted code. Always run `make ci` to catch this asymmetry.
+in sequence and mirrors the checks in the `test` job of `.github/workflows/ci.yml`: the
+format step is the non-mutating `fmt-check` (equivalent to CI's `ruff format --check`),
+and lint/type/test/example run the same tools CI does. (CI's separate `conformance_stub`
+job is a no-op placeholder and is not part of the local gate.) The Makefile
+additionally invokes every tool via `python -m <tool>` — a local hardening over CI
+that uses the active interpreter's site-packages, preventing spurious failures when
+`ruff` or `mypy` are provided by isolated installers such as `uv tool` or `pipx`. If
+`make ci` passes locally, the same checks will pass in CI. Use `make fmt` (the
+mutating target) when you want to auto-fix formatting before re-running `make ci`.
 
 ## PR conventions
 

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

@@ -31,7 +31,7 @@ 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
+- `expand(handle, *, query, principal=None)` — paginate/filter stored results; `principal` is required for principal-bound handles (see [`docs/security.md`](security.md#handle-expansion-boundary))
 - `explain(action_id)` — retrieve audit trace
 - `explain_denial(request, principal, justification)` — return a structured `DenialExplanation` instead of raising `PolicyDenied`
 

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/docs/capabilities.md

@@ -3,9 +3,60 @@
 ## Naming conventions
 
 - Use `domain.verb_noun` format: `billing.list_invoices`, `users.get_profile`.
+- Prefer fully namespaced IDs (`billing.invoices.list`) over flat ones —
+  the registry will infer namespace operations from the dot-segments and
+  large ecosystems benefit from being able to list/search per namespace.
 - Be specific: prefer `billing.cancel_invoice` over `billing.update`.
 - Avoid generic names like `billing.execute` or `api.call`.
 
+## Namespaces and discovery
+
+`CapabilityRegistry` recognises dot-notation namespaces automatically. No
+extra registration step is required — `register(Capability(capability_id=
+"billing.invoices.list", ...))` is enough to populate the `billing` and
+`billing.invoices` namespaces.
+
+```python
+registry.list_namespaces()
+# ['billing', 'crm']
+
+registry.list_namespace("billing")
+# [Capability('billing.invoices.list'), Capability('billing.payments.refund'), …]
+```
+
+For large tool ecosystems where eagerly registering hundreds of
+capabilities is wasteful, declare a deferred loader. The loader runs at
+most once, the first time the namespace is searched, listed, or any
+capability under it is fetched via `get()`:
+
+```python
+def load_billing() -> list[Capability]:
+    return [
+        Capability(capability_id="billing.invoices.list", …),
+        Capability(capability_id="billing.invoices.create", …),
+        Capability(capability_id="billing.payments.refund", …),
+    ]
+
+registry.register_namespace(
+    "billing",
+    description="Billing and invoicing tools",
+    loader=load_billing,
+)
+```
+
+Search ranks matches with a BM25-flavoured scorer that weights
+`capability_id` and `tags` higher than `description`, strips a small
+stop-word set (`a`, `the`, `please`, …), and offers `offset` for
+pagination:
+
+```python
+results = registry.search("list invoices", max_results=10, offset=0)
+```
+
+Search is deterministic — equal-scoring capabilities are returned in
+`capability_id` order — and trips any deferred namespace loader whose
+prefix shares a token with the query.
+
 ## Granularity
 
 Each capability should map to a single, auditable action with clear side-effects.
@@ -32,6 +83,10 @@ Each capability should map to a single, auditable action with clear side-effects
 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.
+Use `SensitivityTag.MEMORY` when results are durable agent memory (project notes,
+session handoff, learned context). Pair it with the `memory.read` / `memory.write` /
+`memory.forget` capability IDs to activate the policy rules and audit-trace redaction
+described in [`docs/security.md#memory-actions`](security.md#memory-actions).
 
 Always pair sensitivity tags with `allowed_fields` to restrict which fields are returned
 to non-privileged callers.

{weaver_kernel-0.8.0 → weaver_kernel-0.9.0}/docs/context_firewall.md

@@ -32,18 +32,23 @@ Budgets(
 
 A `Handle` is an opaque reference to the full dataset stored server-side.
 
+A handle is bound to the principal it was granted to, so `expand()` requires that
+same `principal` — an omitted or mismatched principal raises
+`HandleConstraintViolation` (handle IDs are not bearer credentials). See
+[`docs/security.md#handle-expansion-boundary`](security.md#handle-expansion-boundary).
+
 ```python
 # Stored automatically on every invoke()
 handle = frame.handle
 
 # Expand with pagination
-expanded = kernel.expand(handle, query={"offset": 10, "limit": 5})
+expanded = kernel.expand(handle, query={"offset": 10, "limit": 5}, principal=principal)
 
 # Field selection
-expanded = kernel.expand(handle, query={"fields": ["id", "name"]})
+expanded = kernel.expand(handle, query={"fields": ["id", "name"]}, principal=principal)
 
 # Basic filtering
-expanded = kernel.expand(handle, query={"filter": {"status": "unpaid"}})
+expanded = kernel.expand(handle, query={"filter": {"status": "unpaid"}}, principal=principal)
 ```
 
 ## Redaction
@@ -118,3 +123,59 @@ 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.
+
+## Streaming
+
+For large results that arrive incrementally (e.g. SSE-style HTTP responses,
+chunked database cursors, line-by-line tool output), `Firewall.apply_stream()`
+lets you process chunks one at a time. PII redaction and per-chunk budget
+caps apply on every yielded Frame — secrets cannot leak just because they
+arrived in chunk N rather than the final aggregate.
+
+```python
+from agent_kernel.drivers.base import ExecutionContext, StreamingDriver
+
+class MyStreamingDriver:
+    driver_id = "stream"
+
+    async def execute(self, ctx: ExecutionContext):
+        # one-shot fallback, called when StreamingDriver isn't used.
+        ...
+
+    async def execute_stream(self, ctx: ExecutionContext):
+        async for row in some_async_cursor(ctx):
+            yield {"row": row}
+        yield {"__is_final__": True}  # explicit sentinel (optional)
+
+
+# isinstance(driver, StreamingDriver) is runtime-checkable.
+assert isinstance(MyStreamingDriver(), StreamingDriver)
+
+async for frame in kernel.invoke_stream(token, principal=p, args={}):
+    handle_chunk(frame)
+    if frame.is_final:
+        break
+```
+
+When the resolved driver does **not** implement `StreamingDriver`,
+`Kernel.invoke_stream` falls back to a single `Driver.execute()` call and
+yields exactly one `Frame` with `is_final=True`. Each invocation produces
+one `ActionTrace` covering the whole stream.
+
+## Observability
+
+`agent_kernel.instrument_kernel(kernel)` installs OpenTelemetry spans and
+metric emission on `Kernel.invoke` and `Kernel.grant_capability`:
+
+```python
+from agent_kernel import Kernel, instrument_kernel, OTEL_AVAILABLE
+
+kernel = Kernel(registry=...)
+if OTEL_AVAILABLE:
+    instrument_kernel(kernel)  # no-op when [otel] extra not installed
+```
+
+Spans: `agent_kernel.invoke`, `agent_kernel.grant`. Metrics:
+`agent_kernel.invocations` (counter), `agent_kernel.invocation_duration`
+(histogram, ms), `agent_kernel.policy_denials` (counter). The call is
+idempotent — repeat invocations on the same kernel are no-ops.