weaver-kernel 0.3.0__tar.gz

weaver_kernel-0.3.0/.claude/CLAUDE.md

@@ -0,0 +1,56 @@
+# Claude Instructions — agent-kernel
+
+Read `AGENTS.md` before making any changes. It is the canonical source of truth
+for all shared rules, conventions, and documentation pointers.
+
+## Explore before acting
+
+- Read `AGENTS.md` and the relevant `docs/agent-context/` file for the topic
+  before proposing changes.
+- Check existing code patterns in the target area. Do not infer repo-wide
+  conventions from a single file.
+- When path-specific conventions exist (see Code conventions in `AGENTS.md`),
+  follow them exactly.
+
+## Implement safely
+
+- Preserve invariants. Consult `docs/agent-context/invariants.md` before any
+  change that touches security, tokens, policy, or the firewall.
+- Use only the conventions documented in `AGENTS.md`. Do not invent new ones.
+- Use `make ci` as the single validation command. Do not guess alternatives.
+- Do not "clean up" or "simplify" code unless the change was requested. Hidden
+  constraints may exist.
+
+## Validate before completing
+
+- Run `make ci` and confirm it passes.
+- If a public API, workflow, invariant, or convention changed, update the
+  relevant canonical doc in the same changeset.
+- Verify that every changed docstring matches the final implementation.
+- Check for dead code: unused parameters, fixtures, or helpers.
+
+## Handle contradictions
+
+When docs contradict code or each other:
+1. Code is authoritative over docs.
+2. Canonical shared docs (`AGENTS.md`, `docs/agent-context/`) are authoritative
+   over tool-specific files.
+3. Surface the contradiction explicitly. Do not silently pick one side.
+4. Fix stale docs in the same changeset when possible.
+
+## Capture lessons
+
+When a mistake or unexpected pattern is discovered during work:
+1. Determine if it generalizes — would it recur in a similar task?
+2. If yes, identify the canonical home using the workflow in
+   `docs/agent-context/lessons-learned.md`.
+3. Treat candidate lessons as provisional. Do not promote a fresh observation
+   into durable guidance from a single incident.
+
+## Update order
+
+1. Update canonical shared docs (`AGENTS.md`, `docs/agent-context/`) first.
+2. Update tool-specific files (this file, `.github/copilot-instructions.md`)
+   second.
+3. If a Claude-specific rule becomes shared and durable, promote it into
+   canonical docs and remove it from `.claude/`.

weaver_kernel-0.3.0/.github/copilot-instructions.md

@@ -0,0 +1,53 @@
+# Copilot Instructions — agent-kernel
+
+> Canonical rules: `AGENTS.md`. This file projects review-critical rules that
+> must be visible during GitHub PR review.
+
+## Review checklist
+
+Flag these in every PR — CI does not catch them:
+
+- Docstrings and descriptions must match actual implementation.
+- No security bypass vectors: whitespace-only justification, truncated JSON, bare `int()` on untrusted input.
+- No dead code: unused parameters, fixtures, or helpers.
+- No backward-compat breaks: adding required methods to an existing Protocol breaks downstream.
+- Naming consistent: use capability, principal, grant, Frame — never synonyms.
+
+Canonical checklist: `docs/agent-context/review-checklist.md`
+
+## Code and docs reviewed together
+
+- PRs that change public APIs, workflows, invariants, review rules, or path conventions must include doc updates.
+- If a docstring changed, verify it matches the final code.
+- Code is authoritative over docs. Fix stale docs in the same PR.
+- Surface contradictions explicitly. Do not silently work around them.
+
+## Invariants
+
+Non-negotiable. Violations silently degrade security:
+
+- Firewall always mediates: `RawResult → Frame`. Never bypass.
+- Token verification before every invocation. Never skip.
+- Non-admin principals never get `raw` response mode.
+- Policy rule ordering is security-critical — a rule placed before sensitivity checks creates a silent bypass.
+- New `SensitivityTag` values need a matching policy rule, or the tag is silently ignored.
+
+Full list: `docs/agent-context/invariants.md`
+
+## Convention discipline
+
+- Follow conventions in `AGENTS.md`. Do not invent new ones.
+- `make ci` is the single pre-push command. Do not guess alternatives.
+- Custom exceptions from `errors.py` only. Never raise bare `ValueError`/`KeyError` to callers (catching stdlib internally to remap is fine).
+- No new dependencies without justification.
+
+## Canonical sources
+
+| Topic | File |
+|-------|------|
+| All shared rules | `AGENTS.md` |
+| Hard invariants | `docs/agent-context/invariants.md` |
+| Full review checklist | `docs/agent-context/review-checklist.md` |
+| Workflows & commands | `docs/agent-context/workflows.md` |
+| Recurring mistakes | `docs/agent-context/lessons-learned.md` |
+| Architecture intent | `docs/agent-context/architecture.md` |

weaver_kernel-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "copilot/**"]
+  pull_request:
+    branches: ["main"]
+  workflow_call:
+
+jobs:
+  test:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff check)
+        run: ruff check src/ tests/ examples/
+
+      - name: Format check (ruff format)
+        run: ruff format --check src/ tests/ examples/
+
+      - name: Type check (mypy)
+        run: mypy src/
+
+      - name: Test (pytest)
+        run: python -m pytest -q --cov=agent_kernel --cov-report=term-missing
+
+      - name: Examples
+        run: |
+          python examples/basic_cli.py
+          python examples/billing_demo.py
+          python examples/http_driver_demo.py

weaver_kernel-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  ci:
+    name: "CI gate"
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: "Build & publish"
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read   # required for actions/checkout
+      id-token: write  # required for Trusted Publisher (OIDC)
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1.13.0

weaver_kernel-0.3.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

weaver_kernel-0.3.0/AGENTS.md

@@ -0,0 +1,143 @@
+# AGENTS.md — AI Agent Instructions
+
+This is the canonical source of truth for AI coding agents working in this repository.
+Tool-specific instruction files (`.github/copilot-instructions.md`, `.claude/CLAUDE.md`)
+reference this file and add only tool-specific guidance.
+
+## Repo layout
+
+```
+src/agent_kernel/        — library source (one module per concern, ≤300 lines each)
+  drivers/               — capability drivers (one file per driver)
+  firewall/              — context firewall (redaction, summarization, budgets)
+tests/                   — pytest suite (one test file per module)
+examples/                — runnable demos (prefer offline; network OK with fallback)
+docs/                    — reference documentation
+docs/agent-context/      — deeper agent guidance (architecture, workflows, invariants)
+```
+
+## Weaver ecosystem
+
+agent-kernel is part of the **Weaver ecosystem**:
+- [weaver-spec](https://github.com/dgenio/weaver-spec) — formal specification with invariants
+- [contextweaver](https://github.com/dgenio/contextweaver) — context compilation library
+- ChainWeaver — orchestration layer
+
+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-06**: Tokens must bind principal + capability + constraints; no reuse across principals.
+
+Full spec: [dgenio/weaver-spec](https://github.com/dgenio/weaver-spec)
+
+## Domain vocabulary
+
+Use these terms consistently. Never substitute synonyms:
+
+| Term | Means | Not |
+|------|-------|-----|
+| capability | a registered, auditable action | tool, function, API |
+| principal | the identity invoking a capability | agent, user, caller |
+| grant | a policy-approved token issuance | permission, access |
+| Frame | the bounded, redacted result returned to the LLM | response, output |
+
+## Quality bar
+
+- `make ci` must pass before every push. It runs: `fmt → lint → type → test → example`.
+- 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.
+- 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).
+
+## Security rules
+
+- Never log or print secret key material.
+- HMAC secrets come from `AGENT_KERNEL_SECRET` env var; fallback to a random dev secret with a logged warning.
+- Tokens are HMAC-signed but **not encrypted**. Never store secrets in token payloads.
+- Confused-deputy prevention: tokens bind `principal_id + capability_id + constraints`.
+- Never bypass token verification before capability invocation.
+- Firewall always transforms `RawResult → Frame`. Raw driver output never reaches the LLM.
+- Non-admin principals never get `raw` response mode. The Firewall downgrades to `summary`.
+- No duplicate capability IDs in the registry.
+
+See [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the full "never do" list and security traps.
+
+## Code conventions
+
+**All modules (`src/agent_kernel/`):**
+Relative imports. Dataclasses with `slots=True`. Protocols for interfaces.
+`__all__` in every `__init__.py`. Google-style docstrings.
+`CamelCase` for classes, `snake_case` for functions. Error classes end with `Error`.
+
+**Drivers (`drivers/`):**
+One file per driver. `Driver` Protocol in `base.py`. Async `execute()` method.
+Driver classes end with `Driver`. Use `DriverError` for exceptions.
+
+**Firewall (`firewall/`):**
+Pure functions for redaction and summarization. `Firewall` class in `transform.py` orchestrates.
+Use `FirewallError` for exceptions.
+
+**Tests (`tests/`):**
+Every module has a corresponding test file (`kernel.py` → `test_kernel.py`).
+Conftest fixtures only for cross-test reuse (≥2 test files). Local helpers otherwise.
+
+**Examples (`examples/`):**
+Prefer offline. Network examples OK only with a clear fallback.
+
+## Workflow
+
+- One logical change per PR. Squash-merge. Conventional commit titles (`feat:`, `fix:`, `test:`, `docs:`).
+- `make ci` is the single authoritative pre-push command.
+- Update `CHANGELOG.md` in the same PR when adding features or fixes.
+- Code is authoritative over docs. Fix stale docs when you spot discrepancies.
+
+See [docs/agent-context/workflows.md](docs/agent-context/workflows.md) for full details.
+
+## Adding a capability driver
+
+1. Implement the `Driver` protocol in `src/agent_kernel/drivers/`.
+2. Register it with `StaticRouter` or implement a custom `Router`.
+3. Add integration tests in `tests/test_drivers.py`.
+
+See [docs/integrations.md](docs/integrations.md) for MCP and HTTP examples.
+
+## Adding a policy rule
+
+1. Add the rule to `DefaultPolicyEngine.evaluate()` in `policy.py`.
+2. **Placement matters:** rules are evaluated in order. A new rule placed before sensitivity checks silently bypasses them.
+3. If adding a new `SensitivityTag`, you must also add a corresponding policy rule — otherwise the tag is silently ignored.
+4. Cover it with a test in `tests/test_policy.py`.
+
+## Review checklist (beyond `make ci`)
+
+Before submitting a PR, verify:
+- [ ] Docstrings and descriptions match the actual implementation.
+- [ ] Security edge cases handled (whitespace-only justification, truncated JSON, bare `int()` on untrusted input).
+- [ ] No dead or unused code (parameters, fixtures, helpers).
+- [ ] No backward compatibility breaks (e.g., adding required methods to a Protocol).
+- [ ] Naming consistent across docs and code (use capability, principal, grant, Frame — never synonyms).
+
+See [docs/agent-context/review-checklist.md](docs/agent-context/review-checklist.md) for the full checklist.
+
+## Documentation map
+
+| Topic | Canonical source |
+|-------|-----------------|
+| Architecture & design intent | [docs/agent-context/architecture.md](docs/agent-context/architecture.md) |
+| Components & API reference | [docs/architecture.md](docs/architecture.md) |
+| Security model & threats | [docs/security.md](docs/security.md) |
+| Hard invariants & forbidden shortcuts | [docs/agent-context/invariants.md](docs/agent-context/invariants.md) |
+| Workflow rules & commands | [docs/agent-context/workflows.md](docs/agent-context/workflows.md) |
+| Recurring mistakes | [docs/agent-context/lessons-learned.md](docs/agent-context/lessons-learned.md) |
+| Review & self-check | [docs/agent-context/review-checklist.md](docs/agent-context/review-checklist.md) |
+| Driver integration patterns | [docs/integrations.md](docs/integrations.md) |
+| Capability design conventions | [docs/capabilities.md](docs/capabilities.md) |
+| Context firewall details | [docs/context_firewall.md](docs/context_firewall.md) |
+
+## Update policy
+
+Code is authoritative. When docs contradict code, fix the docs.
+Each topic has one canonical source (see table above). Update the canonical source;
+do not create parallel guidance elsewhere.

weaver_kernel-0.3.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# 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.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.3.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to agent-kernel
+
+Thank you for your interest in contributing!
+
+## Development setup
+
+```bash
+git clone https://github.com/dgenio/agent-kernel.git
+cd agent-kernel
+python -m venv .venv
+source .venv/bin/activate
+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
+```
+
+## Pull request guidelines
+
+1. Keep PRs focused — one logical change per PR.
+2. Add or update tests for every behaviour change.
+3. All checks in `make ci` must pass.
+4. Follow the existing code style (ruff-enforced).
+5. Write docstrings on all public interfaces.
+
+## Security
+
+Please report security vulnerabilities privately via GitHub Security Advisories.
+Do **not** open a public issue for a security bug.