Migration
Parity matrix
Python versus TypeScript feature parity for @maniac-ai/agents, adapted from the internal parity matrix.
This page summarizes packages/agents/docs/parity-matrix.md for documentation readers. Serialized payloads use Python-compatible snake_case field names in both runtimes.
Legend: Alpha = ported with fixture/mock coverage; behavior should match Python for the listed surface.
| Area | TS status | Notes |
|---|
Public entry points (Maniac, runAgent, streams, resume) | Alpha | TS method names; Python-compatible payloads |
Agent schemas (AgentBudget, TraceEvent, checkpoints) | Alpha | Zod validation; tool_call_arguments_delta wire shape matches byte-for-byte |
Step hooks (prepare_step, stop_when, predicates) | Alpha | camelCase method names; same lifecycle firing points |
| Inference + adapters (OpenAI, OpenRouter, Vercel, Anthropic) | Alpha | Streaming, tool deltas, reasoning chunks |
| Tool loop (permissions, guardrails, middleware, budgets) | Alpha | TS requires explicit inputSchema on every tool |
| Partial-turn persistence on error | Alpha | persistPartialOnError opt-out on both sides |
| Area | TS status | Notes |
|---|
tool(), BaseToolset, delegated agents | Alpha | No Python signature introspection |
| Permissions + batched HITL | Alpha | ArgConstraint quantifiers, sub_actions / sub_decisions, checkpoint schema v2 |
Guardrail require_approval | Alpha | Routes through same HITL path as policy |
SessionPermissionCache | Alpha | TTL-aware caching + remember() for "always allow this turn" |
Builtin remember(note) | Alpha | Auto-injected when working-memory runner + enable_update_tool |
Builtin set_plan | Alpha | Plan primitive + ACP session/update emissions |
| Area | TS status | Notes |
|---|
Core Memory protocol + scopes | Alpha | In-memory, vector wrapper, Honcho adapter |
| Conversation / observation / checkpoint stores | Alpha | Same abstraction as agent memory |
WorkingMemoryStore + runner | Alpha | Mastra-style mutable doc tier |
SqliteMemory | TS only | Schema-compatible with Python Postgres reference |
PostgresMemory | Python only | Not ported to TypeScript |
| Memory relevance filter | Alpha | Maniac({ memoryRelevanceFilter }) flag-style config |
RuntimeMemoryAccess per chat turn | Alpha | "off" | "read" | "write" per observational/working tier |
| Area | TS status | Notes |
|---|
PythonSandboxClient + worker protocol | Alpha | Top-level await, namespace, stdout/stderr, injected RPC |
REPL loop (python_exec) | Alpha | Tool/namespace/memory injection conformance tests |
| Area | TS status | Notes |
|---|
BackgroundTaskDispatcher | Alpha | Whole-runAgent dispatch; concurrency caps; runStreamUntilIdle |
LM bg_* control tools | Alpha | Auto-inject when dispatcher + background-eligible tool present |
bg_wait multi-task | Alpha | task_ids: string[] + mode: "all" | "any"; legacy task_id fallback |
getActiveAbortSignal() | Alpha | Cooperative cancellation for tool authors |
| Area | TS status | Notes |
|---|
Tracer + correlation IDs | Alpha | turn_id, message_id, block_id, thread_id |
OTelTracer | Alpha | Optional @opentelemetry/* peers |
ACP server + TraceTranslator | Alpha | serveAcpStdio, plan primitive, capability-gated fs/terminal tools |
maniac-agents-acp CLI | Alpha | serve + client subcommands |
acp_agent_as_tool | Python only | No TS twin yet |
serve_acp_websocket | Python only | TS ships stdio server |
| Area | TS status | Notes |
|---|
serveChannels + ChatToolset | TS only | Slack/Discord/Telegram/Teams/WhatsApp via Chat SDK |
| Inbound multimodal | TS only | ContentPart[] through to model |
| Approval cards + checkpoint resume | TS only | requireApproval + resumeCheckpointStream |
| Webhook hardening | TS only | Signing verification, idempotency, body caps |
Python parity is tracked but blocked on a Python Chat SDK adapter ecosystem.
| Fixture | Purpose |
|---|
fixtures/schema_roundtrip.json | Messages, inference, agent result round-trips |
fixtures/trace_checkpoint.json | Trace sequences, HITL checkpoint, streaming tool-call chunks |
Replace or extend these with Python-generated golden traces as live integration coverage expands.
- Replace alpha fixtures with Python-generated golden traces from high-value integration tests
- Expand live provider integration coverage behind
OPENAI_API_KEY, OPENROUTER_API_KEY, etc.
- Package the Python worker as an optional peer artifact or separate process image
- Complete async background dispatch/re-entry orchestration on the durable task store