zk-data-agent/PARITY_CHECKLIST.md

Parity Checklist Against npm src

This document tracks what is already implemented in Python and what is still missing compared with the upstream npm runtime.

This is a functionality-oriented checklist, not a line-by-line source equivalence claim. Large parts of the mirrored Python workspace still act as inventory or scaffolding, while the working Python runtime currently lives mainly in src/agent_runtime.py, src/query_engine.py, src/agent_tools.py, src/agent_prompting.py, src/agent_context.py, src/agent_manager.py, src/plugin_runtime.py, src/agent_slash_commands.py, and src/openai_compat.py.

1. Core Agent Runtime

Done:

• One-shot agent loop with iterative tool calling
• OpenAI-compatible chat/completions client
• Streaming token-by-token assistant output
• Local-model execution against vLLM
• Local-model execution through Ollama
• Local-model execution through LiteLLM Proxy
• Transcript-aware session object for the Python runtime
• Session save and resume support
• Configurable max-turn execution
• Permission-aware tool execution
• Structured output / JSON schema request mode
• Cost tracking and usage budget enforcement
• Scratchpad directory integration
• File history journaling for write/edit/shell tool actions
• Incremental bash tool-result streaming events
• Incremental tool-result streaming for read-only text tools
• Incremental tool-result streaming across the current Python text tool surface
• Mutable tool transcript updates during tool execution
• Transcript mutation history for replaced/tombstoned messages
• Assistant streaming and tool-call transcript mutation history
• Session-wide mutation serial tracking across transcript updates
• Structured transcript block export for messages, tool calls, and tool results
• Resume-time file-history replay reminders
• Resume-time file-history snapshot previews for file edits
• File-history snapshot ids and replay summaries for file edits
• File-history result previews for shell and delegated-tool entries
• Truncated-response continuation flow for finish_reason=length
• Basic snipping of older tool/tool-call messages for context control
• Basic automatic compact-boundary insertion with preserved recent tail
• Reactive compaction retry after prompt-too-long backend failures
• Reasoning-token budget enforcement
• Tool-call and delegated-task budget enforcement
• Resume-aware cumulative model-call budgets
• Resume-aware cumulative session usage/cost persistence
• Basic nested-agent delegation tool
• Sequential multi-subtask delegation with parent-context carryover
• Dependency-aware delegated subtasks
• Topological dependency-batch delegation planning
• Basic agent-manager lineage tracking for nested agents
• Managed agent-group membership tracking with child indices
• Agent-manager strategy and batch summary tracking for delegated groups
• Delegated child-session resume by saved session id
• Agent-manager tracking for resumed child-session lineage
• Plugin-cache discovery and prompt-context injection
• Manifest-based plugin runtime discovery
• Manifest-defined plugin hooks for before-prompt and after-turn runtime injection
• Manifest-defined plugin lifecycle hooks for resume, persist, and delegate phases
• Manifest-defined plugin tool aliases over base runtime tools
• Manifest-defined executable virtual tools
• Manifest-defined plugin tool blocking
• Manifest-defined plugin beforeTool guidance
• Manifest-defined plugin tool-result guidance injected back into the transcript
• Plugin runtime session-state persistence and resume restoration
• Compaction metadata with compacted message ids
• Compaction metadata with preserved-tail ids and compaction depth
• Compaction metadata with compacted/preserved lineage ids and revision summaries
• Compaction metadata with source mutation serials and mutation totals
• Snipped-message metadata with source role/kind lineage
• Snipped-message metadata with source lineage id and revision
• Resume-time compaction / snipping replay reminder
• Resume-time compaction replay of source mutation summaries
• Query-engine facade that can drive the real Python runtime agent
• Query-engine runtime event counters and transcript-kind summaries
• Query-engine runtime mutation counters
• Query-engine stream-level runtime summary event
• Query-engine transcript-store compaction summaries
• Delegate-group and delegated-subtask runtime events
• Delegate-batch runtime events and summaries
• Query-engine runtime orchestration summaries for group status and child stop reasons
• Query-engine runtime context-reduction summaries
• Query-engine runtime lineage summaries
• Query-engine runtime resumed-child orchestration summaries

Missing:

• Full partial tool-result streaming parity across the complete upstream/npm tool surface
• Full rich transcript mutation behavior like the npm runtime beyond the current lineage, counters, block export, and mutation-serial tracking
• Full reasoning budgets and task budgets parity beyond the current cumulative model/tool/delegation/session-call enforcement
• Full multi-agent orchestration parity beyond dependency-aware batched delegation, resumed-child flows, and current agent-manager summaries
• Full file history snapshots and replay flows beyond the current preview/id-based implementation and delegated-batch replay metadata
• Full executable plugin lifecycle beyond manifest-driven prompt/tool/session hooks, blocking, aliases, virtual tools, and persisted runtime state
• Full session compaction / snipping parity beyond lineage-aware summaries, mutation-serial compaction metadata, and replay reminders
• Full QueryEngine.ts parity

2. CLI Entrypoints And Runtime Modes

Done:

• Python CLI entrypoint
• agent command
• agent-chat command
• agent-resume command
• agent-prompt command
• agent-context command
• agent-context-raw command
• Inventory/helper commands such as summary, manifest, commands, and tools

Missing:

• Daemon worker mode
• Background session mode
• Session process listing (ps)
• Background session logs
• Background attach flow
• Background kill flow
• Remote-control / bridge runtime mode
• Browser/native-host runtime mode
• Computer-use MCP mode
• Template job mode
• Environment runner mode
• Self-hosted runner mode
• tmux fast paths
• Worktree fast paths at the CLI entrypoint level
• Full entrypoints/cli.tsx and entrypoints/init.ts parity

3. Prompt Assembly

Done:

• Structured Python system prompt builder
• Intro/system/task/tool/tone/output sections
• Session-specific prompt guidance
• Environment-aware prompt sections
• User context reminder injection
• Custom system prompt override and append support

Missing:

• Full parity with constants/prompts.ts
• Hook instruction sections
• MCP instruction sections
• Model-family-specific prompt variations
• Output-style variants
• Language-control sections
• Scratchpad prompt instructions
• More exact autonomous/proactive behavior sections
• Growthbook / feature-gated prompt sections
• Cyber / risk sections used upstream

4. Context Building And Memory

Done:

• Current working directory snapshot
• Shell / platform / date capture
• Git status snapshot
• CLAUDE.md discovery
• Extra directory injection through --add-dir
• Session context usage report
• Raw context inspection command
• Plugin cache snapshot injection
• Manifest-based plugin runtime summary injection

Missing:

• Tokenizer-accurate context accounting
• Full parity with utils/queryContext.ts
• Rich memory prompt loading
• Internal permission-aware memory handling
• Resume-aware prompt cache shaping used upstream
• More exact context cache invalidation rules
• Session context analysis parity
• Full memory subsystem parity

5. Slash Commands

Done:

• /help
• /commands
• /context
• /usage
• /context-raw
• /env
• /prompt
• /system-prompt
• /permissions
• /model
• /tools
• /memory
• /status
• /session
• /clear

Missing:

• Full npm slash-command surface
• Slash commands backed by MCP integration
• Slash commands tied to task/plan systems
• Slash commands tied to remote/background sessions
• Slash commands with richer interactive behavior
• Slash commands tied to plugins and bundled skills
• Slash commands tied to settings, config, and account state

6. Built-in Tools

Done:

• list_dir
• read_file
• write_file
• edit_file
• glob_search
• grep_search
• bash

Missing:

• Agent spawning tool
• Skill tool
• Notebook edit tool
• Web fetch tool
• Web search tool
• Todo write tool
• Ask-user-question tool
• LSP tool
• MCP resource listing tool
• MCP resource read tool
• Tool search tool
• Config tool
• Task create/get/update/list tools
• Team create/delete tools
• Send-message tool
• Terminal capture tool
• Browser tool
• Workflow tool
• Remote trigger tool
• Sleep / cron tools
• PowerShell tool parity
• Worktree enter/exit tools
• Full tools.ts parity

7. Commands And Task Systems

Done:

• Basic local command dispatch for the Python runtime
• Inventory view of mirrored command names

Missing:

• Real implementation of the larger upstream command tree
• Task orchestration system
• Planner / task execution parity
• Team / collaboration command flows
• Background task management
• Command-specific session behaviors
• Full src/commands/* parity
• Full src/tasks/* parity

8. Permissions, Hooks, And Policy

Done:

• Read-only default mode
• Write-gated mode
• Shell-gated mode
• Unsafe mode for destructive shell actions

Missing:

• Hooks runtime
• Tool-permission workflow parity
• Policy limit loading
• Managed settings loading
• Trust-gated initialization
• Safe environment loading parity
• More exact denial tracking
• Hook-config management
• Full hooks and policy parity

9. MCP, Plugins, And Skills

Done:

• Placeholder mirrored package layout for plugins, skills, services, and remote subsystems

Missing:

• Real MCP client support
• MCP server integration
• MCP resource listing and reading
• MCP-backed tools
• Plugin discovery and loading
• Bundled plugin support
• Plugin lifecycle management
• Plugin update/cache behavior
• Skill discovery and execution parity
• Bundled skill support
• Full plugin and skill parity

10. Interactive UI / REPL / TUI

Done:

• Non-interactive CLI execution
• Basic interactive REPL-style agent chat loop
• Transcript printing for debugging

Missing:

• Interactive REPL parity beyond the current basic agent-chat loop
• Ink/TUI component parity
• Screen system parity
• Keyboard interaction parity
• Interactive status panes
• Approval UI flows
• Rich incremental rendering
• Full components, screens, and ink parity

11. Remote, Background, And Team Features

Done:

• Session save/resume on local disk

Missing:

• Remote execution modes
• Background agent processes
• Background attach/log/kill workflows
• Team runtime features
• Team messaging features
• Shared remote state
• Upstream proxy runtime integration
• Full remote, server, bridge, upstreamproxy, and team parity

12. Editor, Platform, And Native Integrations

Done:

• Standard shell-based local workflow

Missing:

• Voice mode parity
• VIM mode parity
• Keybinding parity
• Notification hooks
• Native TypeScript / platform helper parity
• JetBrains/editor integration parity
• Browser/native host integrations
• Platform-specific startup/shutdown logic

13. Services And Internal Subsystems

Done:

• Minimal internal service layer required by the current Python runtime

Missing:

• Real service implementations for the mirrored services package
• Config service parity
• Account/auth service parity
• Analytics/telemetry service parity
• Growthbook/feature-flag parity
• GitHub / git helper parity
• Sandbox/settings utility parity
• Todo/task utility parity
• Internal helpers used by the upstream runtime

14. Mirrored Workspace Versus Working Runtime

Working Python runtime today:

• src/main.py
• src/agent_runtime.py
• src/agent_tools.py
• src/agent_prompting.py
• src/agent_context.py
• src/agent_context_usage.py
• src/agent_session.py
• src/agent_slash_commands.py
• src/agent_types.py
• src/openai_compat.py
• src/session_store.py
• src/permissions.py

Mirrored inventory / scaffold areas that still need real implementation work:

• src/commands.py
• src/tools.py
• src/query_engine.py
• src/runtime.py
• src/services/*
• src/plugins/*
• src/remote/*
• src/voice/*
• src/vim/*
• Large parts of the rest of the mirrored package tree

15. High-Priority Next Steps

• Expand the real Python tool registry toward upstream tools.ts
• Replace more snapshot-backed mirrored modules with working runtime code
• Implement real MCP support
• Implement hooks and policy flows
• Build a real interactive REPL / TUI
• Add tokenizer-accurate context accounting
• Add background and remote session modes
• Port more of the command/task system
• Close the gap between the mirrored workspace and the working runtime