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
• Manifest-based hook/policy runtime discovery
• Hook/policy before-prompt runtime injection
• Hook/policy after-turn runtime events
• Hook/policy tool preflight guidance
• Hook/policy tool blocking
• Hook/policy after-tool guidance
• Hook/policy budget override loading
• Hook/policy safe-environment overlay for shell tools
• Local manifest-backed MCP resource discovery
• Local MCP resource listing and reading
• MCP-backed runtime tools for local resource access
• Real stdio MCP client transport for initialize, resources/list, resources/read, tools/list, and tools/call
• Transport-backed MCP tool listing and execution
• Local manifest-backed remote runtime discovery
• Local remote profile listing and summary reporting
• Local remote connect/disconnect state persistence
• Local manifest/env-backed search runtime discovery
• Local search-provider activation persistence
• Provider-backed web search execution against configured search backends
• Local persistent task runtime discovery
• Local task create/get/list/update runtime flows
• Local todo-list replacement runtime flow
• Local persistent plan runtime discovery
• Local plan get/update/clear runtime flows
• Local plan-to-task sync flow
• Dependency-aware local task state with blocking and actionable-task selection
• Local task start/complete/block/cancel execution flows
• 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
• Local background session mode
• Local background session listing (agent-ps)
• Local background session logs (agent-logs)
• Local background attach snapshot (agent-attach)
• Local background kill flow (agent-kill)
• Local daemon-style background command family (daemon start/ps/logs/attach/kill)
• Local daemon worker command path (daemon worker)
• Local remote runtime CLI modes (remote-mode, ssh-mode, teleport-mode, direct-connect-mode, deep-link-mode)
• Local remote runtime inspection commands (remote-status, remote-profiles, remote-disconnect)
• Local account runtime inspection commands (account-status, account-profiles, account-login, account-logout)
• Local search runtime inspection commands (search-status, search-providers, search-activate, search)
• Local MCP runtime inspection commands (mcp-status, mcp-resources, mcp-resource, mcp-tools, mcp-call-tool)
• Inventory/helper commands such as summary, manifest, commands, and tools

Missing:

• Full daemon supervisor parity beyond the current local daemon wrapper and worker 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
• Local hook/policy guidance section in the Python system prompt
• Local MCP guidance section in the Python system prompt
• MCP transport/tool guidance section in the Python system prompt
• Local remote-runtime guidance section in the Python system prompt
• Local search-runtime guidance section in the Python system prompt
• Local account-runtime guidance section in the Python system prompt
• Local planning guidance section in the Python system prompt
• Local task guidance section in the Python system prompt

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
• Tokenizer-aware context accounting with cached model-specific backends and heuristic fallback
• Raw context inspection command
• Plugin cache snapshot injection
• Manifest-based plugin runtime summary injection
• Manifest-based hook/policy summary injection
• Trust-mode, managed-settings, and safe-env context injection
• Manifest-based MCP runtime summary injection
• Manifest-based MCP transport server summary injection
• Manifest-based remote runtime summary injection
• Manifest/env-based search runtime summary injection
• Manifest-based account runtime summary injection
• Manifest-based plan runtime summary injection
• Manifest-based task runtime summary injection

Missing:

• Full tokenizer/chat-message framing parity beyond the current model-aware text token counters
• 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
• /mcp
• /mcp tools
• /mcp tool <name>
• /search
• /remote
• /remotes
• /ssh
• /teleport
• /direct-connect
• /deep-link
• /disconnect
• /account
• /login
• /logout
• /resources
• /resource
• /plan
• /planner
• /tasks
• /todo
• /task
• /task-next
• /prompt
• /system-prompt
• /permissions
• /hooks
• /policy
• /trust
• /model
• /tools
• /memory
• /status
• /session
• /clear
• /config
• /settings

Missing:

• Full npm slash-command surface
• Slash commands backed by MCP integration
• Slash commands tied to task/plan systems beyond the current local /plan, /tasks, and /task flows
• Slash commands tied to remote/background sessions beyond the current local remote connect/disconnect and background inspection flows
• Slash commands with richer interactive behavior
• Slash commands tied to plugins and bundled skills
• Slash commands tied to account, settings, and auth flows beyond the current local /account, /login, /logout, /config, and /settings flows

6. Built-in Tools

Done:

• list_dir
• read_file
• write_file
• edit_file
• glob_search
• grep_search
• bash
• web_fetch
• search_status
• search_list_providers
• search_activate_provider
• web_search
• tool_search
• sleep
• ask_user_question
• account_status
• account_list_profiles
• account_login
• account_logout
• notebook_edit
• mcp_list_resources
• mcp_read_resource
• mcp_list_tools
• mcp_call_tool
• remote_status
• remote_list_profiles
• remote_connect
• remote_disconnect
• config_list
• config_get
• config_set
• plan_get
• update_plan
• plan_clear
• delegate_agent
• task_next
• task_list
• task_get
• task_create
• task_update
• task_start
• task_complete
• task_block
• task_cancel
• todo_write
• team_list
• team_get
• team_create
• team_delete
• send_message
• team_messages

Missing:

• Agent spawning tool parity beyond the current delegate_agent runtime tool
• Skill tool
• Web fetch parity beyond the current local text-fetch implementation
• Web search parity beyond the current provider-backed implementation
• LSP tool
• Tool search parity beyond the current local registry search
• Config tool
• Terminal capture tool
• Browser tool
• Workflow tool
• Remote trigger tool
• Sleep / cron tools beyond the current local sleep tool
• 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
• Local persistent task runtime with create/get/list/update flows
• Local todo-list replacement flow
• Local persistent plan runtime with get/update/clear flows
• Local plan-to-task sync flow
• Local dependency-aware task execution flow with next-task selection and blocked/unblocked state
• Local remote profile/runtime flow with persisted connect/disconnect state
• Local background task management for agent worker sessions
• Local ask-user runtime with queued answers, history, and slash/CLI inspection flows
• Local team runtime with persisted teams, messages, and slash/CLI inspection flows

Missing:

• Real implementation of the larger upstream command tree
• Task orchestration system beyond the current local dependency-aware task runtime
• Planner / task execution parity beyond the current local plan persistence, sync, and next-task flow
• Team / collaboration command flows beyond the current local team runtime and message recording flows
• 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
• Local hook/policy manifest discovery
• Hook before-prompt and after-turn runtime handling
• Hook/policy tool preflight, deny, and after-tool handling
• Policy budget override loading
• Managed settings loading and reporting
• Safe environment loading for shell tool context
• Trust reporting and hook/policy slash commands
• Permission-denial runtime events for policy/tool blocks

Missing:

• Tool-permission workflow parity
• Trust-gated initialization
• 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
• Local manifest-backed MCP discovery
• Local MCP resource listing and reading
• MCP-backed runtime tools for local resource access
• Real MCP client support over local stdio transport
• MCP server integration for stdio child-process servers
• MCP-backed tool listing and execution over transport

Missing:

• Full MCP-backed tool parity beyond the current stdio resource/tool list/read/call support
• 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
• Local manifest-backed remote profile/runtime state
• Local remote connect/disconnect session state
• Local background agent processes
• Local background attach/log/kill workflows
• Local daemon-style wrapper over background agent sessions

Missing:

• Real remote execution modes beyond the current local manifest-backed remote runtime and CLI/profile flows
• 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
• Local account/auth runtime for manifest-backed profile discovery and persisted login state

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/account_runtime.py
• src/config_runtime.py
• src/agent_types.py
• src/mcp_runtime.py
• src/plan_runtime.py
• src/plugin_runtime.py
• src/remote_runtime.py
• src/search_runtime.py
• src/hook_policy.py
• src/background_runtime.py
• src/task.py
• src/task_runtime.py
• src/tokenizer_runtime.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
• Remaining mirrored inventory surfaces still represented mainly by snapshot data under src/reference_data/*
• Command/task/plugin/skill/service/editor subsystems that exist upstream but do not yet have real Python modules after the tree cleanup

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
• Expand MCP parity beyond the current stdio resource/tool transport support
• Expand hooks and policy parity beyond the current manifest/runtime implementation
• Build a real interactive REPL / TUI
• Expand background session parity beyond the current local worker/log/attach model
• Add real remote session transport and shared remote state beyond the current local remote-profile runtime
• Port more of the command/task system
• Close the gap between the mirrored workspace and the working runtime