Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

kitaru-adapter-builder

Build a project-local Kitaru adapter for an unsupported Python or TypeScript agent framework. Use when a user wants to record or replay framework-native agent runs in Kitaru, needs a custom adapter, has no supported Kitaru integration for their framework, or needs to assess whether public framework hooks and the installed Kitaru SDK can support an adapter.

decodingai-magazine · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add decodingai-magazine/building-a-coding-agent-from-scratch-course --skill kitaru-adapter-builder

About this skill


name: kitaru-adapter-builder description: Build a project-local Kitaru adapter for an unsupported Python or TypeScript agent framework. Use when a user wants to record or replay framework-native agent runs in Kitaru, needs a custom adapter, has no supported Kitaru integration for their framework, or needs to assess whether public framework hooks and the installed Kitaru SDK can support an adapter.

Kitaru adapter builder

Build the smallest honest adapter inside the user's project. Preserve the framework's public entrypoint and report exactly what the adapter can observe, record, replay, and recover from.

Do not assume every framework can support the same fidelity. A useful result is either a locally tested adapter or a precise blocker tied to the installed versions and public hooks.

Core contract

  • Start with read-only inspection of the user's project and installed packages.
  • Prefer supported Kitaru adapters, importers, or OTLP export when they meet the requested recording and replay needs. Do not create a duplicate integration.
  • Treat the user's installed SDK and framework as authority. Use Kitaru reference adapters as patterns, not as source to copy or as proof of a published API.
  • Use only public framework hooks. Offer a coarser boundary or stop when complete coverage would require private internals.
  • Implement in the user's project first. Do not edit Kitaru core or prepare an upstream contribution unless the user separately approves that work.
  • Keep per-run session IDs, clients, node indexes, buffers, replay state, and framework context isolated. Never store invocation state on a shared wrapper.
  • Treat a partially recorded run as partial or failed evidence. Never call it a complete trace because the application returned successfully.
  • Treat replay as execution, not a transaction. Block unknown or write-capable side effects unless the selected policy and user approval make them safe.
  • Never install dependencies, call credentialed providers, create a remote Kitaru session, execute write-capable tools, or publish changes without the relevant approval.
  • Run every Kitaru CLI command and SDK script with KITARU_ACTIVE_SKILL=kitaru-adapter-builder set so the server attributes the resulting activity to this skill.
  • Start or restart a user-controlled worker with --concurrency 10. Use KITARU_WORKER_CONCURRENCY=10 only when the launch surface exposes worker settings through environment variables instead of CLI options.

Route from the project

Begin in the project that contains the real agent entrypoint.

  1. Read the repository instructions and inspect the working tree. Preserve all existing and concurrent changes.
  2. Identify the package manager, lockfile, runtime, language, framework and version, Kitaru package and version, public agent entrypoint, and invocation modes the application actually uses.
  3. Route by the entrypoint's runtime:
    • For Python, read the Python adapter reference.
    • For TypeScript, read the TypeScript adapter reference.
    • For another runtime, stop with an unsupported-language report.
  4. Read the adapter method, search the project, installed packages, and current Kitaru documentation for a compatible adapter, importer, or OTLP path, and create the adapter assessment before editing code.
  5. Read validation and reporting before finalizing the design or writing tests.

In a mixed repository, route from the process that executes the agent. Do not load both language references merely because both languages exist somewhere in the repository.

If the framework already exports traces in a format no built-in importer supports and that post-hoc evidence meets the user's goal, continue with kitaru-importer-builder instead of wrapping the live entrypoint. Carry forward the repository and revision, public entrypoint, framework and version, export source and shape, Kitaru package and version, target agent and version, and requested evidence. Choose this route once; do not bounce back merely because the importer mentions an adapter as an alternative.

Establish the requested fidelity

Separate these questions before choosing an implementation:

QuestionPossible answer
Recording boundaryWhole invocation, turn, model step, tool call, subagent call, or coarser span
Replay tierInput rerun, turn replay, framework-native boundary replay, finer checkpoint replay, or not claimed
Tool visibilityLocal tools, MCP tools, provider-native tools, hidden framework tools, or unknown
Invocation modesAsync, sync, streaming, manual iteration, batch, handoff, resume, interrupt, or durable execution
Failure policyKitaru failure fails the invocation, or recording is best effort with an explicit degraded result

Do not use “replay” without naming the tier. Running the same root input again is an input rerun, not deterministic replay.

For streaming, keep three claims separate:

  1. the application still yields tokens or events;
  2. the adapter observes the stream through completion, failure, cancellation, and abandonment;
  3. replay reproduces the original chunks or timing.

Supporting one does not prove the others.

Stop before writing code when necessary

Stop and give the exact reason when any of these apply:

  • a compatible existing adapter, importer, or OTLP route satisfies the request;
  • the project is not Python or TypeScript;
  • no usable public Kitaru SDK contract is installed or approved for installation;
  • the framework exposes no public hook at the required boundary;
  • the only Python entrypoint is synchronous and the available Kitaru contract is async, with no documented safe async framework hook;
  • the requested behavior depends on hidden provider or framework activity;
  • replay safety requires match c
Read the complete source ↗