Merge remote-tracking branch 'origin/main' into feat/mcp-driver

Author: dgenio

.github/workflows/ci.yml

@@ -45,3 +45,32 @@ jobs:
           python examples/basic_cli.py
           python examples/billing_demo.py
           python examples/http_driver_demo.py
+
+  conformance_stub:
+    name: "Weaver Spec Conformance Stub (v0.1.0)"
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      # Placeholder: activate once dgenio/weaver-spec#4 ships the conformance runner.
+      # weaver-spec and weaver-contracts are published on PyPI.
+      # weaver_contracts.conformance does not yet exist (dgenio/weaver-spec#4).
+      # Replace this step with:
+      #   pip install weaver-contracts          # PyPI dist name uses a hyphen
+      #   python -m weaver_contracts.conformance --target agent_kernel
+      - name: weaver-spec conformance suite (stub)
+        run: |
+          echo "weaver-contracts 0.2.0 is on PyPI; weaver_contracts.conformance runner not yet available (dgenio/weaver-spec#4)."
+          echo "Stub passes. Activate when dgenio/weaver-spec#4 ships."

AGENTS.md

@@ -25,9 +25,12 @@ agent-kernel is part of the **Weaver ecosystem**:
 
 This repo must conform to weaver-spec invariants. Key invariants (all equally critical):
 - **I-01**: Every tool output must pass through a context boundary before reaching the LLM.
-- **I-02**: Context boundaries must enforce budgets (size, depth, field count).
+- **I-02**: Every execution must be authorized and auditable (preceded by a policy decision, followed by a trace event).
 - **I-06**: Tokens must bind principal + capability + constraints; no reuse across principals.
 
+Note: Budget enforcement (size, depth, field count) is an agent-kernel implementation
+constraint that satisfies I-01 — it is not a separate weaver-spec invariant number.
+
 Full spec: [dgenio/weaver-spec](https://github.com/dgenio/weaver-spec)
 
 ## Domain vocabulary

CHANGELOG.md

@@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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

README.md

@@ -110,6 +110,19 @@ asyncio.run(main())
 
 `agent-kernel` sits **above** `contextweaver` (context compilation) and **above** raw tool execution. It provides the authorization, execution, and audit layer.
 
+## Weaver Spec Compatibility: v0.1.0
+
+agent-kernel is a compliant implementation of [weaver-spec v0.1.0](https://github.com/dgenio/weaver-spec).
+The following invariants are satisfied:
+
+| Invariant | Description | How agent-kernel satisfies it |
+|-----------|-------------|-------------------------------|
+| **I-01** | LLM never sees raw tool output by default | `Context Firewall` always transforms `RawResult → Frame`; raw driver output is not returned by default, and non-admin principals cannot obtain `raw` response mode |
+| **I-02** | Every execution is authorized and auditable | `PolicyEngine` authorizes at grant time; a valid `CapabilityToken` (HMAC-verified on every `invoke()`) carries the authorization decision; `TraceStore` records every `ActionTrace` |
+| **I-06** | CapabilityTokens are scoped | Tokens bind `principal_id + capability_id + constraints` with an explicit TTL; `revoke(token_id)` / `revoke_all(principal_id)` are supported |
+
+See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the full internal invariant list and [weaver-spec INVARIANTS.md](https://github.com/dgenio/weaver-spec/blob/main/docs/INVARIANTS.md) for the specification.
+
 ## Security disclaimers
 
 > **v0.1 is not production-hardened for real authentication.**

docs/agent-context/invariants.md

@@ -11,9 +11,12 @@ All three are equally critical — there is no priority ordering.
 | Invariant | Requirement | Where enforced |
 |-----------|-------------|----------------|
 | **I-01** | Every tool output must pass through a context boundary before reaching the LLM | `Firewall.transform()` in `firewall/transform.py` |
-| **I-02** | Context boundaries must enforce budgets (size, depth, field count) | `Budgets` in `firewall/budgets.py` |
+| **I-02** | Every execution must be authorized and auditable (CapabilityToken validated before execution; TraceEvent recorded after) | `HMACTokenProvider.verify()` + `TraceStore.record()` in `kernel.py`; `PolicyEngine.evaluate()` at grant time in `grant_capability()` |
 | **I-06** | Tokens must bind principal + capability + constraints; no reuse across principals | `HMACTokenProvider.verify()` in `tokens.py` |
 
+> **Budget enforcement** (size, depth, field count via `Budgets` in `firewall/budgets.py`) is an
+> implementation constraint that strengthens I-01. It has no separate invariant number in weaver-spec.
+
 ## Forbidden shortcuts — "never do" list
 
 These constraints are non-negotiable. Violating any one silently degrades security.