acpkit 0.6.0__tar.gz → 0.7.0__tar.gz

{acpkit-0.6.0 → acpkit-0.7.0}/.agents/skills/acpkit-sdk/SKILL.md

@@ -417,6 +417,215 @@ Host-backed tools:
 - ACP Kit can expose client-backed filesystem and shell helpers
 - projection maps change how tools are rendered in ACP clients without changing the underlying tool contract
 
+### HostAccessPolicy
+
+`HostAccessPolicy` is ACP Kit's native typed guardrail surface for host-backed filesystem and terminal access.
+
+Reach for it first when an integration has started inventing ad hoc rules such as:
+
+- "warn for absolute paths but deny workspace escapes"
+- "show one caution in the client but enforce a different rule in the backend"
+- "treat command cwd and file paths as unrelated policy domains"
+
+Use it:
+
+- when host-backed file and terminal tools already exist
+- when approvals or projection warnings need to describe the same risk model that enforcement uses
+- when downstream code has started to accumulate one-off path checks
+
+Do not reach for it:
+
+- when the integration does not expose host-backed file or terminal tools at all
+- when the problem is product-specific approval wording rather than reusable access policy
+
+Use it when an integration needs one reusable place to decide:
+
+- whether absolute paths should only warn or hard fail
+- whether paths outside the active session cwd should warn or deny
+- whether workspace-root escapes should always deny
+- whether command cwd and command path arguments should follow the same policy language as file paths
+
+Important distinction:
+
+- `evaluate_path(...)` and `evaluate_command(...)` are for UI and approval surfaces
+- `enforce_path(...)` and `enforce_command(...)` are for actual blocking before ACP host requests are sent
+
+The evaluation objects are intentionally UI-friendly. They expose:
+
+- `disposition`
+- `headline`
+- `message`
+- `recommendation`
+- `risks`
+- `risk_codes`
+- `primary_risk`
+- `summary_lines()`
+
+That means downstream integrations do not need to invent their own warning strings just to show a clear caution card.
+
+Typical use:
+
+```python
+from pydantic_acp import ClientHostContext, HostAccessPolicy
+
+policy = HostAccessPolicy.strict()
+
+host = ClientHostContext.from_session(
+    client=client,
+    session=session,
+    access_policy=policy,
+    workspace_root=session.cwd,
+)
+```
+
+Small verified evaluation example:
+
+```python
+from pathlib import Path
+
+from pydantic_acp import HostAccessPolicy
+
+policy = HostAccessPolicy.strict()
+evaluation = policy.evaluate_path(
+    '../notes.txt',
+    session_cwd=Path('/workspace/app'),
+    workspace_root=Path('/workspace/app'),
+)
+
+assert evaluation.disposition == 'deny'
+assert evaluation.should_deny
+assert 'outside_cwd' in evaluation.risk_codes
+```
+
+Current presets:
+
+- `HostAccessPolicy()` is conservative default behavior
+- `HostAccessPolicy.strict()` denies more aggressively outside the active cwd
+- `HostAccessPolicy.permissive()` keeps more paths executable but still surfaces risk
+
+Current scope:
+
+- file path evaluation
+- command cwd evaluation
+- heuristic detection of obvious path-like command arguments
+- native backend-side deny enforcement
+
+Current limit:
+
+- it is not a full shell parser
+- it does not automatically wire itself through every integration seam yet
+
+Primary references:
+
+- [Host Backends and Projections](https://vcoderun.github.io/acpkit/host-backends/)
+- [Projection Cookbook](https://vcoderun.github.io/acpkit/projection-cookbook/)
+
+## Black-box Integration Harness
+
+`BlackBoxHarness` exists so downstream integrations can prove the ACP boundary without rebuilding test plumbing from scratch.
+
+Reach for it when the integration already "works" but still lacks proof for:
+
+- approval replay
+- host-backed side effects
+- session reload correctness
+- ACP-visible transcript truthfulness
+
+Use it:
+
+- after the integration already has a real adapter construction seam
+- when you need one reusable way to drive approvals, prompts, reloads, and visible updates
+- when a normal unit test would miss ACP-visible behavior
+
+Do not use it:
+
+- to inspect private helper ordering
+- as a substitute for product-level end-to-end testing
+- before the integration has a coherent ownership model for sessions, approvals, and host tools
+
+Use it when you want to verify:
+
+- session create/load behavior
+- visible ACP updates
+- approval roundtrips
+- host-backed file or terminal flows
+- replay after reload
+
+What it gives you:
+
+- adapter construction plus a recording ACP client in one object
+- `new_session(...)`
+- `load_session(...)`
+- `prompt_text(...)`
+- `set_mode(...)`
+- `set_model(...)`
+- permission response queueing helpers
+- update filtering
+- reconstructed agent messages
+
+Typical use:
+
+```python
+import asyncio
+
+from pydantic_acp import AdapterConfig, BlackBoxHarness, FileSessionStore
+
+harness = BlackBoxHarness.create(
+    agent_factory=build_agent,
+    config=AdapterConfig(session_store=FileSessionStore(tmp_path / 'sessions')),
+)
+
+session = asyncio.run(harness.new_session(cwd=str(tmp_path)))
+harness.queue_permission_selected('allow_once')
+response = asyncio.run(harness.prompt_text('Write the workspace note.'))
+
+assert response.stop_reason == 'end_turn'
+assert harness.tool_updates(session_id=session.session_id)
+assert harness.agent_messages(session_id=session.session_id)
+```
+
+Small verified example from the harness test shape:
+
+```python
+session = asyncio.run(harness.new_session(cwd=str(tmp_path)))
+harness.queue_permission_selected('allow_once')
+response = asyncio.run(harness.prompt_text('Write the workspace note.'))
+
+assert response.stop_reason == 'end_turn'
+assert harness.agent_messages(session_id=session.session_id) == ['done']
+```
+
+The harness is intentionally black-box.
+
+Prefer asserting on:
+
+- ACP return values
+- emitted `ToolCallStart` / `ToolCallProgress` updates
+- reconstructed visible messages
+- persisted replay behavior
+- real host-backed side effects
+
+Do not use it to:
+
+- inspect private helper choreography
+- lock internal runtime call order
+- replace product-level end-to-end tests
+
+Good default scenario ladder for a new integration:
+
+1. session create -> prompt -> reload
+2. approval required -> allow once
+3. approval required -> deny once
+4. host-backed file read/write
+5. host-backed terminal execution
+6. mode switch changes behavior
+7. model switch changes session-local state
+
+Primary references:
+
+- [Integration Testing](https://vcoderun.github.io/acpkit/integration-testing/)
+- [Examples Overview](https://vcoderun.github.io/acpkit/examples/)
+
 ## Projection Maps And Hook Rendering
 
 Projection maps make ACP clients see richer file or command behavior than a raw generic tool card.
@@ -430,6 +639,30 @@ Common maps:
 Use them when the client should see more structured output, but avoid pretending a tool is
 something it is not.
 
+### Projection Helper Primitives
+
+ACP Kit now also ships small reusable projection helpers for integrations that need consistent shaping but do not want to rebuild truncation and warning logic repeatedly.
+
+High-value helpers:
+
+- `truncate_text(...)`
+- `truncate_lines(...)`
+- `single_line_summary(...)`
+- `format_code_block(...)`
+- `format_diff_preview(...)`
+- `format_terminal_status(...)`
+- `caution_for_path(...)`
+- `caution_for_command(...)`
+
+Use these helpers when:
+
+- a chat client needs a plain-text diff preview
+- command titles should stay compact and consistent
+- long stdout/stderr content needs predictable truncation
+- caution text should come from the same `HostAccessPolicy` evaluation model as backend enforcement
+
+These helpers are intentionally small. They are building blocks, not a full rendering framework.
+
 ## Examples That Matter
 
 High-value maintained examples live under `examples/pydantic/`:
@@ -470,10 +703,101 @@ High-value docs pages:
 - [Providers](https://vcoderun.github.io/acpkit/providers/)
 - [Bridges](https://vcoderun.github.io/acpkit/bridges/)
 - [Host Backends and Projections](https://vcoderun.github.io/acpkit/host-backends/)
+- [Integration Testing](https://vcoderun.github.io/acpkit/integration-testing/)
+- [Projection Cookbook](https://vcoderun.github.io/acpkit/projection-cookbook/)
 - [Examples Overview](https://vcoderun.github.io/acpkit/examples/)
 - [Workspace Agent](https://vcoderun.github.io/acpkit/examples/workspace-agent/)
 - [pydantic_acp API](https://vcoderun.github.io/acpkit/api/pydantic_acp/)
 
+## Compatibility Manifest
+
+ACP Kit now also ships a typed root-level compatibility manifest schema through `acpkit`.
+
+Reach for it after the integration already has real seams and at least one black-box proof path.
+
+Do not use it as a speculative roadmap scratchpad. Use it as a reviewable declaration of what is actually wired today.
+
+Use it:
+
+- after at least one black-box proof path exists
+- when reviews need one typed declaration of supported ACP surfaces
+- when docs should be generated from validated code instead of prose drift
+
+Do not use it:
+
+- before the integration can already demonstrate the behavior it claims
+- as a replacement for proof tests
+- as a vague backlog matrix with no mapping seam
+
+Use it when a real integration needs one reviewable declaration of:
+
+- which ACP surfaces are implemented
+- which are partial
+- which are intentionally not used
+- which are only planned
+
+Core types:
+
+- `CompatibilityManifest`
+- `SurfaceSupport`
+- `SurfaceStatus`
+- `SurfaceOwner`
+
+Typical use:
+
+```python
+from acpkit import CompatibilityManifest, SurfaceSupport
+
+manifest = CompatibilityManifest(
+    integration_name='workspace-agent',
+    adapter='pydantic-acp',
+    surfaces={
+        'session.load': SurfaceSupport(
+            status='implemented',
+            owner='adapter',
+            mapping='FileSessionStore + load_session',
+        ),
+        'mode.switch': SurfaceSupport(
+            status='partial',
+            owner='bridge',
+            mapping='PrepareToolsBridge dynamic modes',
+            rationale='Only explicitly exposed runtime modes are surfaced.',
+        ),
+        'authenticate': SurfaceSupport(
+            status='planned',
+            rationale='No auth handshake has been added yet.',
+        ),
+    },
+)
+
+manifest.validate()
+```
+
+Minimal review rule:
+
+- every `implemented` surface should point to one concrete mapping seam
+- every `partial`, `intentionally_not_used`, and `planned` surface should explain why
+- `mixed` ownership is only acceptable when the split is named explicitly
+
+Important rule:
+
+- do not generate this from guesses
+- derive it from a real integration audit
+- then validate it in tests
+
+Recommended workflow:
+
+1. inventory real seams
+2. declare surfaces in code
+3. call `manifest.validate()` in tests or CI
+4. optionally publish `manifest.to_markdown()` into docs
+
+This is not a runtime feature. It is an integration review and documentation hygiene feature.
+
+Primary reference:
+
+- [Compatibility Manifest Guide](https://vcoderun.github.io/acpkit/compatibility-matrix-template/)
+
 ## Skill-Local Routing Aids
 
 These files exist to route you quickly into the right part of the codebase or docs set when the
@@ -499,6 +823,7 @@ Use the bundled scripts instead of guessing:
 - Keep examples runnable, explicit, and strongly typed.
 - Treat adapter-owned state and host-owned state as different design choices.
 - Prefer the narrowest seam that matches the user’s need.
+- Use the compatibility manifest when an integration needs one typed, reviewable ACP surface declaration instead of a loose prose matrix.
 - `FileSessionStore` uses `root=Path(...)`.
 - `FileSessionStore` is the hardened local durable store, not a distributed session backend.
 - Mode slash commands are dynamic, and mode ids must not collide with reserved names such as `model`, `thinking`, `tools`, `hooks`, or `mcp-servers`.

{acpkit-0.6.0 → acpkit-0.7.0}/.agents/skills/acpkit-sdk/resources/intro.md

@@ -67,6 +67,98 @@ Use these seams intentionally:
 - native ACP plan state and `PlanProvider` are separate ownership paths
 - `HookBridge(hide_all=True)` suppresses hook listing output, not the underlying hook capability itself
 - custom `run_event_stream` hooks and wrappers must return an async iterable, not a coroutine
+- `HostAccessPolicy` is the native typed guardrail surface for host-backed file and terminal access
+- `BlackBoxHarness` is the reusable black-box ACP boundary test helper for downstream integrations
+- projection helper primitives handle diff previews, truncation, command summaries, and guardrail-aware caution text without each integration rebuilding that shaping logic
+- the compatibility manifest schema gives integrations one typed, reviewable declaration of which ACP surfaces are implemented, partial, intentionally not used, or planned
+
+## New Native Surfaces
+
+### HostAccessPolicy
+
+Reach for `HostAccessPolicy` when an integration needs one reusable, typed place to evaluate file and command risk.
+
+It gives you:
+
+- `allow / warn / deny` policy decisions
+- file path evaluation against session cwd and workspace root
+- command cwd evaluation plus heuristic path-like argument inspection
+- UI-friendly evaluation outputs such as `headline`, `message`, and `recommendation`
+- backend-side `deny` enforcement before ACP host requests are sent
+
+Minimal example:
+
+```python
+from pathlib import Path
+
+from pydantic_acp import HostAccessPolicy
+
+policy = HostAccessPolicy.strict()
+evaluation = policy.evaluate_path(
+    '../notes.txt',
+    session_cwd=Path('/workspace/app'),
+    workspace_root=Path('/workspace/app'),
+)
+```
+
+Read next:
+
+- https://vcoderun.github.io/acpkit/host-backends/
+- https://vcoderun.github.io/acpkit/projection-cookbook/
+
+### BlackBoxHarness
+
+Reach for `BlackBoxHarness` when an integration needs proof, not just implementation.
+
+It gives you a reusable way to test:
+
+- session create/load
+- prompts at the ACP boundary
+- approval queueing
+- visible updates
+- replay after reload
+
+Use it to prove that an ACP integration is truthful without rebuilding a recording client and update parser for every project.
+
+Minimal example:
+
+```python
+session = asyncio.run(harness.new_session(cwd=str(tmp_path)))
+harness.queue_permission_selected('allow_once')
+response = asyncio.run(harness.prompt_text('Write the workspace note.'))
+```
+
+Read next:
+
+- https://vcoderun.github.io/acpkit/integration-testing/
+
+### CompatibilityManifest
+
+Reach for `CompatibilityManifest` after the integration already has real seams and at least one black-box proof path.
+
+It is for reviewability, not runtime behavior. Write it in Python, validate it in tests, and optionally render it into Markdown for humans.
+
+Minimal example:
+
+```python
+from acpkit import CompatibilityManifest, SurfaceSupport
+
+manifest = CompatibilityManifest(
+    integration_name='workspace-agent',
+    adapter='pydantic-acp',
+    surfaces={
+        'session.load': SurfaceSupport(
+            status='implemented',
+            owner='adapter',
+            mapping='FileSessionStore + load_session',
+        ),
+    },
+)
+```
+
+Read next:
+
+- https://vcoderun.github.io/acpkit/compatibility-matrix-template/
 
 ## Reference Files In This Skill
 

acpkit-0.7.0/.github/workflows/codecov.yml

@@ -0,0 +1,30 @@
+name: Run tests and upload coverage
+
+on: push
+
+jobs:
+  test:
+    name: Run tests and collect coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest --cov --cov-branch --cov-report=xml
+
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v6
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

{acpkit-0.6.0 → acpkit-0.7.0}/.gitignore

@@ -77,7 +77,12 @@ SPEC.md
 # Temporary
 tmp
 *.snapshot
-bump.sh
-local.sh
+*.sh
 coverage.json
-acpkit-implementation-plan.md
+/acprouter
+
+# Draft Plans
+*-integration.md
+*-improvement.md
+*-plan.md
+scripts/openrouter*.py

acpkit-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+ACP Kit uses `uv` for dependency management, tool execution, and workspace syncing.
+Use the repo commands below instead of ad hoc `pip`, `poetry`, or one-off local flows.
+
+## Prerequisites
+
+- Python `3.11+`
+- `uv`
+- `git`
+
+## Clone And Install
+
+```bash
+git clone https://github.com/vcoderun/acpkit
+cd acpkit
+uv sync --all-extras
+```
+
+`uv sync --all-extras` is the simplest contributor setup. It installs the root package,
+workspace packages, test tools, docs tools, and the `pydantic-acp` adapter surface used by
+most development work.
+
+If you want a narrower environment, the minimum useful setup for code contributions is:
+
+```bash
+uv sync --extra dev --extra pydantic
+```
+
+For docs work without the full extras set:
+
+```bash
+uv sync --extra dev --extra docs --extra pydantic --extra codex
+```
+
+You usually do not need to activate `.venv` manually because the commands below use `uv run`.
+
+## Pre-commit
+
+Install hooks with:
+
+```bash
+uv run pre-commit install
+```
+
+Run them manually with:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+Current hook behavior:
+
+- validates YAML and TOML files
+- runs `uv run --extra dev ruff check --fix`
+- checks that local package versions are ahead of the latest published PyPI versions
+- runs `make check-coverage` and `make prod` only for major staged changes
+
+If `ruff check --fix` rewrites files, re-stage them before committing.
+
+## Common Commands
+
+Formatting and validation:
+
+- `make format`: run `ruff format`
+- `make check-formatted`: verify formatting with `ruff format --check`
+- `make check`: run `ruff check`, `ty check`, and `basedpyright`
+- `make all`: run `make format` and `make check`
+
+Tests and coverage:
+
+- `make tests`: run the full test suite with `pytest`
+- `make check-coverage`: enforce line and branch coverage thresholds for `pydantic-acp`
+- `make save-coverage`: run the same coverage job and write the summary to [COVERAGE](https://github.com/vcoderun/acpkit/blob/main/COVERAGE)
+- `make check-matrix`: run lint and type checks across the supported Python version matrix
+
+Docs:
+
+- `make serve`: run the MkDocs dev server on `127.0.0.1:8080`
+- `uv run --extra docs --extra pydantic --extra codex mkdocs build --strict`: run the strict docs build used in CI
+
+Higher-cost validation:
+
+- `make prod`: run `tests`, `format`, and the multi-version `check-matrix` gate
+
+## Recommended Local Workflow
+
+For most changes:
+
+1. Sync dependencies with `uv sync --all-extras`.
+2. Make your change.
+3. Run `make format`.
+4. Run `make check`.
+5. Run `make tests`.
+6. Run `uv run pre-commit run --all-files` if you want the same hook surface before commit.
+
+Run the stricter commands when they matter:
+
+- If you touched `pydantic-acp` runtime, plan, approval, bridge, or projection code, run `make check-coverage`.
+- If you touched docs or README-linked docs surfaces, run `uv run --extra docs --extra pydantic --extra codex mkdocs build --strict`.
+- If you changed packaging, CI, or anything release-sensitive, run `make prod`.
+
+## Pull Requests
+
+Before opening a pull request:
+
+1. Make sure your branch is up to date with `main`.
+2. Ensure `make check` and `make tests` pass.
+3. Run the stricter coverage or docs gates when your changes affect those surfaces.
+4. Commit with a clean `pre-commit` result.
+5. Push your branch and verify GitHub Actions passes.
+
+## Notes
+
+- Prefer `uv run ...` over activating the environment and calling tools directly.
+- Do not add new contributor instructions that depend on `pip`, `poetry`, `pdm`, or `pip-tools`.
+- If you change the hook configuration, reinstall hooks with `uv run pre-commit install`.

acpkit-0.7.0/COVERAGE

@@ -0,0 +1,2 @@
+Line coverage: 97.26% (4526 / 4623)
+Branch coverage: 95.16% (1336 / 1404)

{acpkit-0.6.0 → acpkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acpkit
-Version: 0.6.0
+Version: 0.7.0
 Summary: ACP Kit provides a common adapter for Agent Frameworks.
 Project-URL: Homepage, https://github.com/vcoderun/acpkit
 Project-URL: Issues, https://github.com/vcoderun/acpkit/issues
@@ -65,6 +65,8 @@ Description-Content-Type: text/markdown
 
 # ACP Kit
 
+[![CI](https://github.com/vcoderun/acpkit/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/vcoderun/acpkit/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/vcoderun/acpkit/branch/main/graph/badge.svg?token=ZQL4NY4FK6)](https://codecov.io/gh/vcoderun/acpkit) [![PyPI version](https://img.shields.io/pypi/v/acpkit.svg)](https://pypi.org/project/acpkit/) [![Python versions](https://img.shields.io/pypi/pyversions/acpkit.svg)](https://pypi.org/project/acpkit/) [![GitHub release](https://img.shields.io/github/v/release/vcoderun/acpkit)](https://github.com/vcoderun/acpkit/releases) [![License](https://img.shields.io/github/license/vcoderun/acpkit)](https://github.com/vcoderun/acpkit/blob/main/LICENSE)
+
 ACP Kit is the adapter toolkit and monorepo for turning an existing agent surface into a truthful ACP server.
 
 - `acpkit` is the root CLI and target resolver
@@ -94,6 +96,26 @@ Operational notes:
 - dynamic mode slash commands come from configured mode ids; ids like `model`, `thinking`, `tools`, `hooks`, and `mcp-servers` are reserved
 - custom `run_event_stream` hooks must return an async iterable, not a coroutine or plain value
 
+Integration quality utilities:
+
+- `HostAccessPolicy` is the native typed guardrail surface for host-backed filesystem and terminal access
+- `BlackBoxHarness` is the reusable ACP boundary proof helper for approval, host-tool, and reload flows
+- `CompatibilityManifest` is the typed capability declaration for documenting which ACP surfaces an integration truly supports
+
+Prompt resource support:
+
+- `pydantic-acp` accepts ACP text, resource links, embedded text resources, image blocks, audio blocks, and embedded binary resources
+- editor clients can attach file refs, directory refs, selected ranges, and branch diffs as prompt context instead of forcing another tool round trip
+- Zed-style branch diff and selection attachments are preserved as explicit `context ref` prompt context
+- plain rule text such as `@rule ...` stays plain text unless your runtime gives it extra meaning
+
+Deeper guides:
+
+- [Integration testing guide](https://github.com/vcoderun/acpkit/blob/main/docs/integration-testing.md)
+- [Compatibility manifest guide](https://github.com/vcoderun/acpkit/blob/main/docs/compatibility-matrix-template.md)
+- [Host backends and guardrails](https://github.com/vcoderun/acpkit/blob/main/docs/host-backends.md)
+- [Prompt resources and context](https://github.com/vcoderun/acpkit/blob/main/docs/pydantic-acp/prompt-resources.md)
+
 ## Installation
 
 ```bash
@@ -107,6 +129,9 @@ uv pip install "acpkit[pydantic,launch]"
 uv pip install -e ".[dev,docs,pydantic]"
 ```
 
+Contributor setup and local validation commands are documented in
+[CONTRIBUTING.md](https://github.com/vcoderun/acpkit/blob/main/CONTRIBUTING.md).
+
 ## ACP Kit Skill
 
 This repo also ships an `acpkit-sdk` skill package for Codex.