Pydantic AI-first assistant framework: generalization and adoption

Assistant Runtime should provide the application layer around Pydantic AI: configurable assistant definitions and evolving artifacts, general host context and actions, persistent conversations, operational policies, and a smooth integration experience.

The architectural analogy is Next.js over React: compose the underlying primitives and contribute coherent application conventions. It is not a claim of comparable maturity.

Accepted direction:
- Prefer supported Pydantic AI functionality to equivalent custom implementations.
- Keep Python/Pydantic AI integration central; reuse native tools, capabilities, execution, and protocol adapters.
- Make identity/persona/artifact content configurable with neutral defaults.
- Preserve self-editing artifacts, including explicitly permitted autonomous updates, with application-configured policies.
- Define host-independent context, images, tools, result, and event structures.
- Keep current integrations optional and preserve configured installations.
- Prove the experience with a lightweight frontend, another host, and outside adoption.

Audit baseline: runtime 4dd78d2; installed/locked Pydantic AI 2.38.0. Public streaming, enqueue/cancellation, history processing, and capabilities already exist in that version. Host deferred tools, multimodal content, and UsageLimits are already composed. Harness features are separate evaluation candidates.

Competitive correction: Vercel now advertises a Python AI SDK beta (https://ai-sdk.dev/getting-started), so language alone is not the differentiator.

Historical readiness tracker #55 and dashboard-specific settings UI issue #40 were retired as outdated on 2026-09-05. Their closure does not claim their original scopes were implemented. Current host access and independent adoption work is tracked in #91 and #95. This epic coordinates implementation in small issues, not a simultaneous rewrite.

Completion:
- Native primitives replace documented duplication without losing required behavior.
- Applications define their own assistants and artifact evolution.
- Multiple hosts integrate through supported contracts without core edits.
- Persistence, access, usage, and recovery behavior are explicit and demonstrated.
- Independent adoption results establish the framework's value beyond direct Pydantic AI use.

The detailed review and source audit are saved locally and intentionally excluded from commits. This epic and its child issues are self-contained; they must not require access to those local files.

Recommended order (prerequisites are also listed in each issue):

- [x] #84 — Establish the Pydantic AI compatibility baseline and migration cases
- [x] #85 — Expose public assistant composition with native Pydantic AI capabilities
- [x] #86 — Use public Pydantic AI streaming, enqueue, and cancellation APIs
- [x] #87 — Consolidate history processing and evaluate upstream compaction
- [x] #88 — Make assistant definitions and prompt artifact schemas configurable
- [x] #89 — Preserve evolving artifacts with configurable mutation policies
- [x] #90 — Define general host context, attachment, and action contracts
- [x] #91 — Integrate host identity and scoped access across runtime interfaces
- [x] #92 — Define persistence and recovery for sessions and deferred actions (PR #104, merged 2026-09-06)
- [x] #93 — Integrate an upstream UI protocol adapter with the runtime (PR #105, merged 2026-09-06)
- [x] #94 — Expose native usage budgets and account for auxiliary model work
- [ ] #95 — Ship a lightweight reference application and validate independent adoption

Next: #87 — consolidate history processing and evaluate upstream compaction; the initial source review is recorded on that issue. Complete and verify each change before moving to its dependents. The detailed local planning files are intentionally excluded from Git.

## Progress — 2026-09-05

[PR #96](https://github.com/eandualem/assistant-runtime/pull/96) merged into develop (`692d91f`), completing #84 and #85 after surveyor review, CodeRabbit feedback, a clean follow-up review, and all four CI jobs passing. The implementation passes 1,992 tests on Pydantic AI 2.38.0 and 2.40.0. Public event streaming and enqueue were brought forward from #86 to preserve native capability semantics. At that point, #86 remained open for cancellation/disconnect policy and snapshot persistence; PR #97 subsequently completed that work. Local planning files remain excluded from commits.

[PR #97](https://github.com/eandualem/assistant-runtime/pull/97) merged into develop (`c740dba2da1586f741cc17fc045ac0ca60dce011`) and closes #86. The issue is verified closed as completed. Native cancellation now saves partial/completed work and accepted host results, with explicit disconnect/shutdown/replacement policies and steering retries. Surveyor review was completed before the PR; CodeRabbit reported no actionable comments; all four CI jobs passed. The local full gate passed 2,032 tests, including 75 real-agent compatibility cases verified on both selected Pydantic AI versions.

Three of the twelve implementation issues are complete: #84 and #85 via PR #96, and #86 via PR #97. Nine implementation issues remain (#87–#95), plus this umbrella issue. Outdated #40 and #55 were retired with explicit reasons rather than claimed as implemented. The shared AGENTS.md now requires exact closing references, precise merged PR links, and verified issue closure for future implementation work.

Start with the completed child issues #84–#94 and the next issue, #87, which contains the source-review direction for history processing and upstream compaction. Read the Pydantic AI 2.38.0 compatibility baseline and existing runtime contracts before selecting a small child issue. Done for this epic requires validated native integrations, host-independent contracts, explicit persistence and recovery behavior, and independent adoption evidence.

Written by the indexing model from the issue text.