zenml-io Kitaru Adapter Development
Read AGENTS.md. For Python adapters, also read plugins/AGENTS.md and plugins/DEVELOPMENT.md. For TypeScript adapters, read release/typescript.md before changing package or release metadata. Load the same-name kitaru-dev repo skill for the current host for the general command and PR workflow.
Start from the closest current adapter and the target framework's public API. Do not port a historical adapter wholesale.
Choose the extension point
Recording adapters are independent Python distributions under plugins/packages/<slug>/, with focused tests under plugins/tests/adapters/<slug>/. Importer-backed adapters are different: they live inside the provider's importer package as an ImporterBackedAdapter subclass, never intercept model or tool calls, and follow the kitaru-importer-development skill instead of this section's package rules. Agent versions running them declare runtime_capabilities with overrides: false and tool_policies: false on the run spec. TypeScript framework adapters are packages such as packages/mastra/ and packages/vercel-ai/; shared adapter primitives live under packages/core/src/adapter/.
Before editing, state:
- which public framework call, hook, callback, or wrapper is intercepted
- which model, tool, handoff, child-agent, and failure events are observable there
- when sessions and nodes are written, including what the caller observes if recording fails
- which replay overrides can be applied at a real framework boundary
- which streaming, tool, approval, resume, stateful, or dynamic cases remain unsupported
Preserve the framework's ordinary behavior, configured hooks and state, public entrypoint, and native result type. Reject unsupported replay configurations before model or tool execution. Treat passthrough tools as real side effects, not as a reversible transaction. If the framework has no public per-run model replacement point, do not emulate one by mutating shared agent state or reading private fields; stop and report that replay boundary.
Package and documentation work
Python feature PRs follow the version and dependency ownership rules in plugins/AGENTS.md. Leave existing package versions unchanged. Use the exact development dependency from plugins/DEVELOPMENT.md only when the adapter needs unreleased core; release prep selects the published compatibility floor.
For a new Python adapter, inspect the current package inventory and update only the required integration points:
plugins/packages/<slug>/pyproject.toml, README, changelog, source package, public exports, and focused teststool.kitaru.artifact.import-modulefor standalone artifact-smoke coverageplugins/pyproject.tomlonly when the adapter must be a workspace development dependency or sourcerelease/release-units.tomlfor an independently released distribution
Python adapters are installed directly by agent projects. Keep default-catalog = false in release/release-units.toml and do not add them to DEFAULT_PLUGIN_DEFINITIONS.
For a new TypeScript adapter, add a separate package instead of framework-specific code in packages/core/. Inspect the root workspace scripts, lockstep version rules, packaging smoke, and .github/workflows/release-typescript.yml; do not assume a newly added package is automatically built or published.
Document shipped adapters under docs/book/adapters/, update docs/book/adapters/README.md and docs/book/toc.md, and add a runnable example only when it exercises a supported path.
Core boundary
An adapter request does not authorize a new core abstraction, server resource, or replay protocol. Stop and surface the missing extension point before changing any of these areas merely to finish the adapter:
openapi/src/kitaru/api_models/src/kitaru/client/src/kitaru/server/src/kitaru/worker/- CLI or MCP code
packages/core/src/adapter/when the proposed primitive is useful only to one framework package
Explain what the adapter cannot observe or override, why the current public boundary is insufficient, and the smallest separate core decision that would unblock it. Continue only after a maintainer approves that bounded core change; a request to change core "if needed" is not approval to broaden the adapter patch opportunistically.
Validation
Test the public wrapper, captured node semantics, native result preservation, supported replay, unsupported replay preflight, concurrency, and recording-finalization failures as applicable.
For Python adapters, run the focused adapter tests, then the plugin workspace format, lint, typecheck, and test commands from plugins/AGENTS.md. Run just plugin-artifact-smoke after package metadata or artifact-loading changes.
For TypeScript adapters, run the affected package's test, typecheck, lint, and build scripts. Run the root pnpm test, pnpm typecheck, pnpm lint, and pnpm pack:check when shared primitives, workspace metadata, or packaging changes.
Use live provider or framework tests only when their credentials and external side effects are explicitly in scope.