acpkit 0.7.0__tar.gz → 0.8.0__tar.gz

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

@@ -36,6 +36,78 @@ The core contract across the repo is:
 That rule affects model selection, mode switching, slash commands, native plan state, approval
 flow, MCP metadata, hook rendering, cancellation, and host-backed tooling.
 
+## Capability Bridges And UI Projection
+
+Recent `pydantic-acp` bridge support covers both upstream capability wiring and ACP-visible transcript rendering, but those are different seams.
+
+Important distinction:
+
+- a capability bridge wires runtime behavior into the agent
+- a projection map decides whether matching tool calls render as rich ACP cards or generic tool output
+- provider-owned compaction visibility is now built into the runtime path and does not need a projection map
+
+Current high-value capability bridges:
+
+- `ThreadExecutorBridge`
+- `SetToolMetadataBridge`
+- `IncludeToolReturnSchemasBridge`
+- `WebSearchBridge`
+- `WebFetchBridge`
+- `ImageGenerationBridge`
+- `McpCapabilityBridge`
+- `ToolsetBridge`
+- `PrefixToolsBridge`
+- `OpenAICompactionBridge`
+- `AnthropicCompactionBridge`
+
+Current projection helpers for capability-owned builtin tools:
+
+- `WebToolProjectionMap()`
+- `BuiltinToolProjectionMap()`
+
+Use them like this:
+
+```python
+from pydantic_acp import (
+    AdapterConfig,
+    BuiltinToolProjectionMap,
+    WebFetchBridge,
+    WebSearchBridge,
+)
+
+config = AdapterConfig(
+    capability_bridges=[
+        WebSearchBridge(),
+        WebFetchBridge(),
+    ],
+    projection_maps=[BuiltinToolProjectionMap()],
+)
+```
+
+What this means in ACP clients:
+
+- `WebSearchBridge` + `WebToolProjectionMap` or `BuiltinToolProjectionMap`
+  - start card shows query/domain context
+  - completion card shows search results instead of opaque raw output
+- `WebFetchBridge` + `WebToolProjectionMap` or `BuiltinToolProjectionMap`
+  - start card shows URL
+  - completion card shows title, preview text, or binary fetch status
+- `ImageGenerationBridge` + `BuiltinToolProjectionMap`
+  - start card shows prompt and settings
+  - completion card shows revised prompt / image-generation summary
+- `McpCapabilityBridge` + `BuiltinToolProjectionMap`
+  - builtin `mcp_server:*` calls render as intentional MCP cards instead of generic execute noise
+
+Compaction is different:
+
+- `OpenAICompactionBridge` does not rely on a projection map for visibility
+- `AnthropicCompactionBridge` does not rely on a projection map for visibility
+- when compaction happens, ACP now emits a visible `Context Compaction` card
+- OpenAI compaction opens and closes a visible card around the preflight compaction request
+- Anthropic `CompactionPart` summaries are projected into the transcript as visible completion updates
+
+Use this when the product should avoid the "blank wait" failure mode during provider-owned history compaction.
+
 ## Use The Right Construction Seam
 
 Pick the narrowest seam that matches the job:

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

@@ -85,4 +85,7 @@ coverage.json
 *-integration.md
 *-improvement.md
 *-plan.md
+*PLAN.md
 scripts/openrouter*.py
+scripts/check_releases.py
+/.finance-agent

{acpkit-0.7.0 → acpkit-0.8.0}/.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
     hooks:
       - id: check-pypi-version-ordering
         name: ensure local package versions are ahead of PyPI
-        entry: python3.11 scripts/check_pypi_versions.py
+        entry: uv run --extra dev python3.11 scripts/check_pypi_versions.py
         language: system
         pass_filenames: false
         stages: [pre-commit]
@@ -25,8 +25,8 @@ repos:
         pass_filenames: false
         stages: [pre-commit]
       - id: check-coverage
-        name: check coverage thresholds for major changes
-        entry: python3.11 scripts/run_if_major_change.py --stage pre-commit -- make check-coverage
+        name: save and check coverage thresholds for major changes
+        entry: python3.11 scripts/run_if_major_change.py --stage pre-commit -- make save-coverage
         language: system
         pass_filenames: false
         stages: [pre-commit]

acpkit-0.8.0/CHANGELOG

@@ -0,0 +1,74 @@
+## Release Summary — 2026-04-17
+
+This release upgrades `pydantic-acp` to `pydantic-ai-slim==1.83.0`, expands the upstream
+capability bridge surface, improves ACP-native plan mode behavior, and tightens documentation,
+projection coverage, and runtime compatibility seams.
+
+### Highlights
+
+- Upgraded `pydantic-acp` to `pydantic-ai-slim==1.83.0`.
+- Hardened hook observation and introspection against upstream private API drift.
+- Added a generic bridge capability seam through `CapabilityBridge.build_agent_capabilities(...)`.
+- Expanded the built-in capability bridge surface to cover:
+  - `ThreadExecutorBridge`
+  - `SetToolMetadataBridge`
+  - `IncludeToolReturnSchemasBridge`
+  - `WebSearchBridge`
+  - `WebFetchBridge`
+  - `ImageGenerationBridge`
+  - `McpCapabilityBridge`
+  - `ToolsetBridge`
+  - `PrefixToolsBridge`
+  - `OpenAICompactionBridge`
+  - `AnthropicCompactionBridge`
+- Re-exported the new bridges from the public `pydantic_acp` package surface.
+
+### ACP Projection And UX
+
+- Added `WebToolProjectionMap` and `BuiltinToolProjectionMap`.
+- Added richer ACP tool-card projection for:
+  - web search starts and results
+  - web fetch starts, previews, and binary fetch fallbacks
+  - image generation starts and summaries
+  - upstream MCP capability calls and tool-list responses
+- Added visible transcript updates for provider-owned compaction, including OpenAI preflight
+  compaction visibility and Anthropic `CompactionPart` projection.
+- Fixed builtin tool result projection from `ModelResponse` history.
+- Expanded the default tool classifier to recognize common web, image, and `mcp_server:*` builtin
+  tool names.
+
+### Native Plan Mode
+
+- Added `TaskPlan` as the structured native-plan output surface for ACP plan mode.
+- Added a session-local `plan_generation_type` config option for `PrepareToolsBridge` with
+  `structured` and `tools` modes.
+- Made `structured` the default plan-mode behavior so native plan mode can require structured plan
+  generation without exposing `acp_set_plan`.
+- Restored tool-based native plan recording behind `plan_generation_type="tools"`.
+- Kept plan progress tools (`acp_update_plan_entry`, `acp_mark_plan_done`) tied to
+  `plan_tools=True` execution flows.
+
+### Runtime And Maintainability
+
+- Moved remaining private and semi-private hook access behind a dedicated compatibility layer.
+- Preserved hook ordering when wrapping `Hooks(...)` capabilities.
+- Split the large `runtime/adapter.py` delegation surface into dedicated runtime mixins.
+- Added focused inline docstrings on the public ACP-facing adapter methods and runtime mixins.
+
+### Docs And Examples
+
+- Extended the maintained bridges example to cover the new bridge and projection surfaces.
+- Updated API and bridge docs to reflect the generic capability seam and the current bridge set.
+- Clarified CLI ownership boundaries between `acpkit run ...`, `run_acp(...)`, and
+  `create_acp_agent(...)`.
+- Expanded the factory example docs with explicit session-derived input handling and fallback
+  guidance.
+- Documented native plan persistence wiring and clarified how ACP-native plan rendering already
+  works through `AgentPlanUpdate` plus `acp_get_plan`.
+- Clarified `FileSessionStore` recovery guarantees versus host-owned recovery metrics.
+
+### Verification
+
+- Added regression coverage for the new capability bridges, hook compatibility paths, projection
+  updates, native plan generation modes, and adapter runtime mixin delegation paths.
+- Added helper-path tests to keep coverage above the repository thresholds.

acpkit-0.8.0/COVERAGE

@@ -0,0 +1,2 @@
+Line coverage: 98.86% (5344 / 5386)
+Branch coverage: 97.70% (1614 / 1652)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acpkit
-Version: 0.7.0
+Version: 0.8.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
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.8
+Requires-Dist: mcp>=1.27.0
 Requires-Dist: typing-extensions>=4.12.0
 Provides-Extra: all
 Requires-Dist: agent-client-protocol>=0.9.0; extra == 'all'

acpkit-0.8.0/VERSION

@@ -0,0 +1 @@
+0.8.0

{acpkit-0.7.0 → acpkit-0.8.0}/docs/api/pydantic_acp.md

@@ -74,6 +74,28 @@ This page documents the public surface re-exported by `pydantic_acp`.
 
 ::: pydantic_acp.HistoryProcessorBridge
 
+::: pydantic_acp.ThreadExecutorBridge
+
+::: pydantic_acp.ImageGenerationBridge
+
+::: pydantic_acp.SetToolMetadataBridge
+
+::: pydantic_acp.IncludeToolReturnSchemasBridge
+
+::: pydantic_acp.ToolsetBridge
+
+::: pydantic_acp.PrefixToolsBridge
+
+::: pydantic_acp.WebSearchBridge
+
+::: pydantic_acp.WebFetchBridge
+
+::: pydantic_acp.McpCapabilityBridge
+
+::: pydantic_acp.OpenAICompactionBridge
+
+::: pydantic_acp.AnthropicCompactionBridge
+
 ::: pydantic_acp.McpBridge
 
 ::: pydantic_acp.McpServerDefinition
@@ -90,6 +112,10 @@ This page documents the public surface re-exported by `pydantic_acp`.
 
 ::: pydantic_acp.FileSystemProjectionMap
 
+::: pydantic_acp.WebToolProjectionMap
+
+::: pydantic_acp.BuiltinToolProjectionMap
+
 ::: pydantic_acp.CompositeProjectionMap
 
 ## Projection Helpers

{acpkit-0.7.0 → acpkit-0.8.0}/docs/bridges.md

@@ -37,6 +37,7 @@ Use `BufferedCapabilityBridge` when the bridge also needs to emit ACP transcript
 
 | Method | Override it when | Return value |
 |---|---|---|
+| `build_agent_capabilities(...)` | your bridge contributes Pydantic AI capabilities that should be attached to the active agent | `tuple[AbstractCapability, ...]` |
 | `get_session_metadata(...)` | you want a metadata section under your bridge `metadata_key` | `dict[str, JsonValue]` |
 | `get_tool_kind(...)` | you want custom ACP tool classification | `ToolKind` |
 | `get_mcp_capabilities(...)` | your bridge requires MCP transport capability flags | `McpCapabilities` |
@@ -47,11 +48,52 @@ Use `BufferedCapabilityBridge` when the bridge also needs to emit ACP transcript
 
 Practical rules:
 
+- use `build_agent_capabilities(...)` when the bridge needs to materialize upstream Pydantic AI capabilities
+- `AgentBridgeBuilder` is the adapter-local helper that turns those bridge contributions into agent constructor inputs
 - set `metadata_key` if you want your metadata to appear in session metadata
 - keep classification deterministic; the first bridge that returns a `ToolKind` wins
 - return `None` when your bridge is not authoritative for that surface
 - use bridge-local buffering only when you truly need ACP transcript updates, not just metadata
 
+## `AgentBridgeBuilder` Is The Capability Wiring Seam
+
+`AdapterConfig(capability_bridges=[...])` makes the adapter aware of bridge-owned ACP surfaces such as:
+
+- session metadata
+- tool classification
+- config options
+- mode state
+- model settings
+
+If a bridge also contributes upstream Pydantic AI capabilities, those still need to be attached to
+the active agent instance.
+
+Use `AgentBridgeBuilder(...)` inside your factory or source:
+
+```python
+builder = AgentBridgeBuilder(
+    session=session,
+    capability_bridges=bridges,
+)
+contributions = builder.build()
+
+agent = Agent(
+    model,
+    capabilities=contributions.capabilities,
+    history_processors=contributions.history_processors,
+)
+```
+
+That is the intended seam for:
+
+- `HookBridge`
+- `PrepareToolsBridge`
+- `ThreadExecutorBridge`
+- `SetToolMetadataBridge`
+- `IncludeToolReturnSchemasBridge`
+- `WebSearchBridge`
+- `WebFetchBridge`
+
 ## Compatibility Note: History Processor Types
 
 `HistoryProcessorBridge` depends on Pydantic AI history-processor callable types.
@@ -218,8 +260,172 @@ HookBridge(hide_all=True)
 
 Wraps history processors so their activity can be reflected into ACP updates.
 
+### `WebSearchBridge`
+
+Adds Pydantic AI's `WebSearch` capability into the active agent and classifies matching tools as ACP `search`.
+
+Use it when:
+
+- the runtime should expose builtin or local web search through one bridge-owned capability
+- ACP transcript cards should classify `web_search` or local fallback search tools as search operations
+- session metadata should show search configuration such as allowed domains or context size
+
+Default classified tool names:
+
+- `web_search`
+- `duckduckgo_search`
+- `exa_search`
+- `tavily_search`
+
+UI note:
+
+- add `WebToolProjectionMap()` or `BuiltinToolProjectionMap()` when you want ACP transcript cards to show query/domain context at start and search results at completion instead of generic tool output
+
+### `WebFetchBridge`
+
+Adds Pydantic AI's `WebFetch` capability into the active agent and classifies matching tools as ACP `fetch`.
+
+Use it when:
+
+- the runtime should expose builtin or local URL fetching through one bridge-owned capability
+- ACP transcript cards should classify `web_fetch` as a fetch operation instead of generic execute
+- session metadata should show fetch guardrails such as allowed domains, citations, or token limits
+
 This is useful when you want message-history trimming or contextual rewriting to remain observable.
 
+UI note:
+
+- add `WebToolProjectionMap()` or `BuiltinToolProjectionMap()` when you want ACP transcript cards to show fetched URLs, page titles, text previews, and binary-fetch status
+
+### `ImageGenerationBridge`
+
+Adds upstream `ImageGeneration` through the bridge-builder seam.
+
+Use it when:
+
+- the runtime should expose builtin image generation or a local fallback subagent through one ACP-owned seam
+- session metadata should reflect image-generation policy such as quality, size, or output format
+- projection maps should recognize `image_generation` or `generate_image` as intentional builtin work instead of generic tool noise
+
+UI note:
+
+- add `BuiltinToolProjectionMap()` when you want ACP transcript cards to show prompt, quality, size, and revised prompt summary for builtin image generation
+
+### `ThreadExecutorBridge`
+
+Adds Pydantic AI's `ThreadExecutor` capability through the bridge-builder seam.
+
+Use it when:
+
+- your ACP service is long-lived
+- sync tools or callbacks should run on a bounded executor
+- you want bridge-owned agent construction to keep executor policy explicit
+
+### `SetToolMetadataBridge`
+
+Adds upstream `SetToolMetadata` capability through the bridge-builder seam.
+
+Use it when:
+
+- tool metadata should be attached centrally instead of per-tool definition
+- downstream selectors, MCP logic, or provider behavior depend on consistent metadata
+
+### `IncludeToolReturnSchemasBridge`
+
+Adds upstream `IncludeToolReturnSchemas` capability through the bridge-builder seam.
+
+Use it when:
+
+- you want richer tool return contracts sent to models
+- downstream integrations should enable return-schema support consistently across selected tools
+
+### `ToolsetBridge`
+
+Adds upstream `Toolset` capability through the bridge-builder seam.
+
+Use it when:
+
+- a maintained `FunctionToolset` or other agent toolset should be injected through the same ACP-owned bridge path as other capabilities
+- integration code wants one explicit place to wire toolset-owned instructions or wrappers
+
+Compatibility notes:
+
+- toolset `get_instructions()` output passes through to the upstream model request as `instruction_parts`
+- ordering is explicit: `AgentBridgeBuilder.build(capabilities=...)` keeps user-supplied capabilities first, then appends bridge capabilities in configured bridge order
+
+### `PrefixToolsBridge`
+
+Adds upstream `PrefixTools` capability through the bridge-builder seam.
+
+Use it when:
+
+- a wrapped capability's tool names need a stable namespace prefix
+- downstream clients should see prefixed tool names without custom tool re-registration logic
+
+### `McpCapabilityBridge`
+
+Adds upstream `MCP` capability through the bridge-builder seam.
+
+Use it when:
+
+- the model should use builtin MCP server support when available and local HTTP fallback otherwise
+- ACP session metadata should expose the connected MCP URL, resolved server id, or allowlist shape
+- projection maps should summarize `mcp_server:*` builtin tool calls
+
+Compatibility note:
+
+- this bridge is separate from MCP toolsets such as `MCPServerStdio` or `MCPServerStreamableHTTP`
+- if those toolsets are attached directly to the agent with `include_instructions=True`, their server instructions still flow through the normal upstream toolset path into `instruction_parts`
+
+UI note:
+
+- add `BuiltinToolProjectionMap()` when you want ACP transcript cards to summarize builtin MCP calls such as `call_tool`, `list_tools`, and output previews instead of generic execute cards
+
+### `OpenAICompactionBridge`
+
+Adds provider-owned OpenAI Responses compaction through the bridge-builder seam.
+
+Use it when:
+
+- long-running ACP sessions should compact history without looking stalled in the client
+- the ACP transcript should show a visible `Context Compaction` card before and after OpenAI compaction runs
+- session metadata should still expose the configured trigger and instructions
+
+UI behavior:
+
+- no extra projection map is required
+- when compaction triggers, ACP emits a visible `Context Compaction` start/update pair
+- OpenAI shows provider status and round-trip payload preservation instead of a blank wait
+- OpenAI completion is emitted by the bridge-owned wrapper so the same card opens and closes around the compaction request
+
+### `AnthropicCompactionBridge`
+
+Adds provider-owned Anthropic context-management compaction through the bridge-builder seam.
+
+Use it when:
+
+- Anthropic context management should be configured through the bridge seam
+- Anthropic compaction summaries should be visible in ACP transcripts instead of disappearing into raw provider behavior
+
+UI behavior:
+
+- no extra projection map is required
+- when Anthropic returns a `CompactionPart`, ACP emits a visible `Context Compaction` card
+- readable Anthropic compaction summaries are shown in the completion update
+
+## Builtin Capability Projection
+
+Use `BuiltinToolProjectionMap()` when the agent exposes upstream builtin capability tools and you want ACP-visible cards instead of generic execute noise.
+
+Current builtin projection coverage:
+
+- web search
+- web fetch
+- image generation
+- builtin MCP server tools
+
+Compaction visibility is built into the runtime path and does not require a projection map.
+
 ### `McpBridge`
 
 Adds MCP-aware metadata and tool classification:

{acpkit-0.7.0 → acpkit-0.8.0}/docs/cli.md

@@ -13,7 +13,7 @@ The root `acpkit` package exposes two command families:
 ```bash
 acpkit run TARGET [-p PATH]...
 acpkit launch TARGET [-p PATH]...
-acpkit launch --command "python3.11 strong_agent.py"
+acpkit launch --command "python3.11 finance_agent.py"
 ```
 
 `TARGET` can be:
@@ -42,21 +42,63 @@ If the resolved value is not a supported agent type, `acpkit` raises `Unsupporte
 Use `run` when the target itself should be resolved and exposed through ACP:
 
 ```bash
-acpkit run strong_agent
-acpkit run strong_agent:agent
+acpkit run finance_agent
+acpkit run finance_agent:agent
 acpkit run app.agents.demo:agent -p ./examples
 acpkit run external_agent -p /absolute/path/to/agents
 ```
 
 This is the most direct path from Python code to a running ACP server.
 
+The expected Python module shape is:
+
+```python
+from pydantic_ai import Agent
+from pydantic_acp import run_acp
+
+agent = Agent("openai:gpt-5", name="demo-agent")
+
+run_acp(agent=agent)
+```
+
+That means:
+
+- `acpkit run my_agent_module`
+  - imports `my_agent_module`
+  - finds the last defined `pydantic_ai.Agent`
+  - exposes it through the matching ACP adapter
+- `acpkit run my_agent_module:agent`
+  - imports the explicit `agent` symbol and exposes that one
+
+If you need adapter configuration such as session persistence, plan bridges, approvals, or host
+projection maps, keep that wiring inside the target module and still run the module through
+`acpkit run`.
+
+## CLI Versus Runtime API
+
+Use the root CLI when:
+
+- you want target resolution from a module path
+- your editor or launcher shells out to a command
+- ACP transport lifecycle should be owned by the `acpkit` process
+
+Use `run_acp(...)` when:
+
+- you already have the Python agent object in-process
+- the module itself should start the ACP server directly
+
+Use `create_acp_agent(...)` when:
+
+- another runtime should own transport lifecycle
+- you want the ACP-compatible agent object without starting the server immediately
+
 ## `acpkit launch`
 
 Use `launch` when you want Toad ACP to launch the command for you:
 
 ```bash
-acpkit launch strong_agent
-acpkit launch strong_agent:agent -p ./examples
+acpkit launch finance_agent
+acpkit launch finance_agent:agent -p ./examples
 ```
 
 This mirrors the resolved target through:
@@ -68,13 +110,13 @@ toad acp "acpkit run TARGET [-p PATH]..."
 Raw command mode skips target resolution entirely:
 
 ```bash
-acpkit launch --command "python3.11 strong_agent.py"
+acpkit launch --command "python3.11 finance_agent.py"
 ```
 
 That becomes:
 
 ```bash
-toad acp "python3.11 strong_agent.py"
+toad acp "python3.11 finance_agent.py"
 ```
 
 ## Installation Hints And Failure Modes
@@ -90,6 +132,7 @@ Common failure cases:
 - the module imports but contains no detectable supported agent
 - `module:attribute` points at a non-agent object
 - the requested adapter package is not installed
+- the target module starts ACP with `run_acp(...)` but imports fail before the agent is created
 
 ## Runtime API
 

acpkit-0.8.0/docs/examples/finance.md

@@ -0,0 +1,38 @@
+# Finance Agent
+
+The maintained finance showcase is [`examples/pydantic/finance_agent.py`](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py).
+
+It is the main example for:
+
+- a direct module-level `Agent(...)` plus `AdapterConfig(...)` surface
+- `PrepareToolsBridge` mode shaping
+- structured native plan generation
+- approval-gated writes with `FileSystemProjectionMap`
+- file-backed ACP session persistence
+
+## Why This Example Exists
+
+Older examples in this repo split these ideas across separate files. That made the codebase noisy
+and kept coverage low in files that were too small to justify keeping around.
+
+`finance_agent.py` intentionally keeps those ACP surfaces together in one realistic workflow:
+
+- `ask` mode for read-only inspection
+- `plan` mode for ACP-native structured plans
+- `trade` mode for approval-gated note updates
+
+## Run It
+
+```bash
+uv run python -m examples.pydantic.finance_agent
+```
+
+By default the example uses `TestModel`. Set `ACP_FINANCE_MODEL` when you want a live model.
+
+## Key Patterns
+
+- the module exports plain `agent`, `config`, and `main` symbols without factory wrappers
+- `FinancePlanPersistenceProvider` writes ACP plans into `.acpkit/plans/`
+- `PrepareToolsBridge` keeps `ask`, `plan`, and `trade` behaviors explicit instead of scattering them across separate examples
+- `FileSystemProjectionMap` turns note reads and writes into rich ACP diffs
+- `NativeApprovalBridge` keeps mutating writes truthfully approval-gated

acpkit-0.8.0/docs/examples/index.md

@@ -0,0 +1,28 @@
+# Examples
+
+All maintained examples live under [`examples/pydantic/`](https://github.com/vcoderun/acpkit/tree/main/examples/pydantic).
+
+The repo intentionally keeps the maintained set small. Each example is broad enough to be useful on
+its own instead of only demonstrating one narrow helper.
+
+## Maintained Examples
+
+| Example | What it demonstrates |
+|---|---|
+| [`finance_agent.py`](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py) | session-aware finance workspace with ACP plans, approvals, mode-aware tool shaping, and projected note diffs |
+| [`travel_agent.py`](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/travel_agent.py) | travel planning runtime with hook projection, approval-gated trip files, and prompt-model override behavior for media prompts |
+
+## Recommended Reading Order
+
+1. [Finance Agent](finance.md)
+2. [Travel Agent](travel.md)
+
+## Running The Examples
+
+```bash
+uv run python -m examples.pydantic.finance_agent
+uv run python -m examples.pydantic.travel_agent
+```
+
+Both examples run without credentials by default. Set the example-specific environment variables
+only when you want live models.

acpkit-0.8.0/docs/examples/travel.md

@@ -0,0 +1,27 @@
+# Travel Agent
+
+The maintained travel showcase is [`examples/pydantic/travel_agent.py`](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/travel_agent.py).
+
+It is the main example for:
+
+- `Hooks` capability introspection rendered through `HookProjectionMap`
+- approval-gated read/write diff projection in a local workspace
+- prompt-model override behavior for image and audio prompts
+- a direct module-level `Agent(...)` plus `AdapterConfig(...)` surface without example-only factories
+
+## Run It
+
+```bash
+uv run python -m examples.pydantic.travel_agent
+```
+
+Without `MODEL_NAME`, the example uses `TestModel` so the demo remains credential-free. Set
+`MODEL_NAME` and optionally `ACP_TRAVEL_MEDIA_MODEL` when you want live-model behavior.
+
+## Key Patterns
+
+- the module exports plain `agent`, `config`, and `main` symbols without factory wrappers
+- `HookProjectionMap` relabels and hides selected hook lifecycle events
+- `TravelPromptModelProvider` shows how a host can supply an explicit media-model override
+- generated trip files keep the example self-contained instead of relying on tracked demo fixtures
+- `FileSystemProjectionMap` turns travel file reads and writes into ACP-visible diffs

{acpkit-0.7.0 → acpkit-0.8.0}/docs/getting-started/quickstart.md

@@ -200,4 +200,4 @@ acpkit run my_agent_module:agent -p ./examples
 - Want every `AdapterConfig` knob? Read [AdapterConfig](../pydantic-acp/adapter-config.md).
 - Want host-owned session state? Read [Providers](../providers.md).
 - Want ACP-visible capabilities? Read [Bridges](../bridges.md).
-- Want a full coding-agent setup? Read [Workspace Agent](../examples/workspace-agent.md).
+- Want maintained end-to-end examples? Read [Finance Agent](../examples/finance.md) and [Travel Agent](../examples/travel.md).