c64bridge 1.0.6 → 1.1.0

package/doc/plans/meta-tools/catalog.md

@@ -1,435 +0,0 @@
-## Meta Tools Catalog for c64bridge (Research Draft)
-
-Purpose: Reduce round-trips and keep richer agent-side state by bundling multiple REST calls into single, stateful meta tools. Each entry lists its intent, agent-managed state, and the underlying Ultimate 64 REST endpoints it composes.
-
-Conventions:
-
-- Endpoint notation: METHOD /v1/<route>[:<command>] (see `doc/c64u/c64-rest-api.md`).
-- When a meta tool composes MCP tools, these map onto the same REST calls via the `C64Client` facade.
-- Agent-managed state includes timers, queues, background tasks, rolling buffers, snapshots, and derived artifacts written to the agent filesystem.
-
-### Memory inspection, capture, and disassembly
-
-- "memory_dump_to_file"
-  - Capture a large RAM range in chunks and write to a local file (hex or binary), with optional pause/resume for stability.
-  - Agent state: chunking progress, retries, output file path, checksum.
-  - REST: GET /v1/machine:readmem, PUT /v1/machine:pause, PUT /v1/machine:resume
-
-- "memory_snapshot_and_diff"
-  - Take two or more snapshots of one or multiple address ranges and produce a diff report (hex and structured JSON with offsets and values).
-  - Agent state: named snapshots, diff histories.
-  - REST: GET /v1/machine:readmem, PUT /v1/machine:pause, PUT /v1/machine:resume
-
-- "verify_and_write_memory"
-  - Pause, read current bytes, verify expected pattern, write bytes, read back to confirm, then resume. Fails fast on mismatch.
-  - Agent state: expected vs actual buffers, verification report.
-  - REST: PUT /v1/machine:pause, GET /v1/machine:readmem, PUT|POST /v1/machine:writemem, PUT /v1/machine:resume
-
-- "watch_memory_until_condition"
-  - Poll a region until a predicate matches (e.g., value equals, non-zero, bitmask set), with timeout and sampling period; optional callback tool.
-  - Agent state: poll scheduler, condition function, elapsed time.
-  - REST: GET /v1/machine:readmem
-
-- "disassemble_ram_region"
-  - Pause, read region, disassemble 6502 bytes (agent-side disassembler), write labeled listing to disk with optional symbol hints; resume.
-  - Agent state: symbol map, disassembly options, output files.
-  - REST: PUT /v1/machine:pause, GET /v1/machine:readmem, PUT /v1/machine:resume
-
-- "trace_code_flow_by_checksums"
-  - Periodically hash code ranges, detect self-modifying changes, and log a time series; optional dump on change.
-  - Agent state: rolling hashes, change log, thresholds.
-  - REST: GET /v1/machine:readmem
-
-### Graphics, sprites, and screen workflows
-
-- "extract_sprites_from_ram"
-  - Scan RAM (configured ranges and stride) for likely 63-byte sprite patterns; decode and save each as `.spr`/hex/base64 with coordinates if discoverable.
-  - Agent state: candidate heuristics, sprite index mapping, output folder.
-  - REST: GET /v1/machine:readmem, optional PUT /v1/machine:pause|resume
-
-- "rip_charset_from_ram"
-  - Locate 2 KB character sets (8x8 tiles × 256) by entropy/structure checks; export as binary and preview PNG.
-  - Agent state: range scan plan, preview images, output paths.
-  - REST: GET /v1/machine:readmem, optional PUT /v1/machine:pause|resume
-
-- "screen_capture_timeline"
-  - Capture PETSCII text screen at fixed intervals, producing a time-stamped log and optional GIF assembled from frames (agent-side).
-  - Agent state: timer, frame store, export settings.
-  - REST: GET /v1/machine:readmem (via screen helper), or use MCP read_screen; optional PUT /v1/machine:pause|resume
-
-- "sprite_preview_prg_batch"
-  - For many sprite binaries, generate and run preview PRGs back-to-back; snapshot screen between runs.
-  - Agent state: job queue, per-item results, failures.
-  - REST: POST /v1/runners:run_prg, GET /v1/machine:readmem (screen), PUT /v1/machine:reset
-
-### Program execution and orchestration
-
-- "program_shuffle"
-  - Discover PRG/CRT under a root path, run each for a configurable duration, capture screen, then soft reset and continue.
-  - Agent state: iterator cursor, per-program artifacts, time budgets, failure handling.
-  - REST: PUT /v1/runners:run_prg, PUT /v1/runners:run_crt, PUT /v1/machine:reset, GET /v1/machine:readmem, GET /v1/files/{path}:info
-
-- "batch_run_with_assertions"
-  - Run a list of programs with post-conditions (screen contains text, memory byte equals value, SID silent); abort on first failure or continue-on-error.
-  - Agent state: assertions, pass/fail log, junit-like report.
-  - REST: PUT /v1/runners:run_prg or :run_crt, GET /v1/machine:readmem, GET /v1/machine:debugreg, optional PUT /v1/machine:pause|resume|reset
-
-- "compile_run_verify_cycle"
-  - Assemble/compile source (BASIC/ASM/SIDWAVE), run, then verify via screen and/or audio analysis; archive artifacts.
-  - Agent state: build outputs, verification records.
-  - REST: POST /v1/runners:run_prg (uploaded PRG), GET /v1/machine:readmem; SID path uses POST /v1/runners:sidplay
-
-- "cold_boot_and_run"
-  - Firmware reboot, then run target; used to validate cold-start behavior.
-  - Agent state: boot timing, outcomes.
-  - REST: PUT /v1/machine:reboot, PUT /v1/runners:run_prg or :run_crt
-
-### Background scheduling and automation
-
-- "start_background_task"
-  - Start a named background task that invokes a tool (e.g., `c64_memory` `read`, `read_screen`, `sid_note_on`) at a fixed interval for N iterations or indefinitely.
-  - Agent state: task registry (id, name, schedule, next-run, last error), persistent across session.
-  - REST: Depends on scheduled tool; common: GET /v1/machine:readmem, PUT|POST /v1/machine:writemem, PUT /v1/runners:run_prg, etc.
-
-- "stop_background_task"
-  - Stop a task by name/id; supports graceful drain.
-  - Agent state: registry update.
-  - REST: none (meta only)
-
-- "list_background_tasks"
-  - List active and recent tasks with status and next fire time.
-  - Agent state: registry enumeration.
-  - REST: none (meta only)
-
-- "stop_all_background_tasks"
-  - Cancel all active tasks.
-  - Agent state: registry update.
-  - REST: none (meta only)
-
-### Storage, drives, and filesystem recipes
-
-- "drive_mount_and_verify"
-  - Mount an image, power-on if needed, reset drive, and verify state via drive list.
-  - Agent state: retries, final mode, verification snapshot.
-  - REST: PUT /v1/drives/{drive}:on, PUT /v1/drives/{drive}:mount, PUT /v1/drives/{drive}:reset, GET /v1/drives
-
-- "create_and_mount_blank_d64"
-  - Create a blank D64 at path, mount it, and optionally run a BASIC program to write a directory header.
-  - Agent state: created image metadata.
-  - REST: PUT /v1/files/{path}:create_d64, PUT /v1/drives/{drive}:mount
-
-- "batch_on_assets_apply_tools"
-  - For all PRG/CRT/D64 under a root path (wildcards), apply a named sequence of tools with templated args.
-  - Agent state: recipe registry, per-asset logs, concurrency window.
-  - REST: GET /v1/files/{path}:info (wildcards), PUT /v1/runners:run_prg|:run_crt, PUT /v1/drives/{drive}:mount
-
-- "drive_mode_profile_switch"
-  - Set drive to 1541/1571/1581, reset, and verify; optional ROM load before switching.
-  - Agent state: selected profile, last mode.
-  - REST: PUT /v1/drives/{drive}:load_rom, PUT /v1/drives/{drive}:set_mode, PUT /v1/drives/{drive}:reset
-
-- "eject_and_poweroff_drive"
-  - Remove image and power off selected drive slot.
-  - Agent state: last known image, slot state.
-  - REST: PUT /v1/drives/{drive}:remove, PUT /v1/drives/{drive}:off
-
-### Filesystem discovery and deduplication
-
-Container-aware traversal: All tools in this group recurse into disk/tape containers (`.d64/.d71/.d81/.dnp/.t64`) and operate on their internal directory entries, not just the host filesystem. When container introspection is not available via REST, tools fall back to mounting the image and scraping the CBM directory via BASIC.
-
-- "find_and_run_program_by_name"
-  - Search under a root (including inside `.d64/.d71/.d81/.t64`) for the first program whose filename contains a substring; run it. Supports PRG and CRT, case sensitivity toggle, and optional sort (path order vs. alphabetical).
-  - Agent state: recent searches (root, pattern, extensions), last run path.
-  - REST: Container-aware GET /v1/files/{root}/**/*:info (wildcards) to discover; if target is inside a container, mount via PUT /v1/drives/{drive}:mount and run via a tiny BASIC loader (`c64_program`, op `upload_run_basic`) or menu automation; direct PUT /v1/runners:run_prg|:run_crt when file is on the host filesystem.
-
-- "filesystem_stats_by_extension"
-  - Walk all files beneath a root—including files inside disk/tape images—and compute counts and size statistics (total, min, max, mean) per extension, with convenience rollups for PRG vs non‑PRG and per‑folder (and per‑container) summaries.
-  - Agent state: cached directory index, prior stats snapshots for trend comparisons.
-  - REST: Container-aware GET /v1/files/{root}/**/*:info (wildcards); fallback: mount images and scrape directory via BASIC.
-
-- "find_paths_by_name"
-  - Return fully qualified device paths for files whose names contain a substring; optional extension filter and max results. Returns host paths and logical paths inside containers (`<container>#<cbm-path>`).
-  - Agent state: result caches with TTL and last search parameters.
-  - REST: Container-aware GET /v1/files/{root}/**/*{substring}*{.{ext}}:info (wildcards)
-
-- "run_copy_move_delete_by_path"
-  - Execute a batch of file operations addressed by fully qualified paths. Operations: run (PRG/CRT), copy, move, delete. Supports dry‑run planning and per‑op guards.
-  - Agent state: audit log of planned/applied ops, allowlist/denylist of roots, optional quarantine path for deletes.
-  - REST: Run → PUT /v1/runners:run_prg|:run_crt; Copy/Move/Delete → not exposed in current API (host‑side or future firmware endpoints). When unavailable, tool returns a plan and no‑ops unless host mapping is configured.
-
-- "container_aware_walk_and_classify"
-  - Recursively walk host paths and container contents; classify each entry as `BASIC`, `PRG-MC`, `SEQ`, `USR`, `REL`, or `UNKNOWN`.
-  - Agent state: classification cache keyed by content hash and CBM directory entry, per-container manifests.
-  - REST: Container-aware GET /v1/files/{root}/**/*:info; for BASIC vs PRG‑MC, either (a) read PRG header bytes if `/files:read` is available, or (b) use PUT /v1/runners:load_prg followed by GET /v1/machine:readmem at the file’s load address to inspect tokens; cleanup via PUT /v1/machine:reset.
-
-- "classify_prg_basic_or_mc"
-  - For a given PRG path (host or inside a container), determine if it is tokenized BASIC or machine code/data using load address and token checks.
-  - Agent state: last probe result, token scanner configuration (PAL/NTSC irrelevant here).
-  - REST: PUT /v1/runners:load_prg (does not run), GET /v1/machine:readmem (few hundred bytes from load address), optional PUT /v1/machine:reset.
-
-File-Type Determination (CBM directory and PRG content):
-
-- Step 1: Fetch metadata/listing for host files; detect container types (`.d64/.d71/.d81/.t64`).
-- Step 2: For containers, parse directory entries: CBM file type byte at offset $02 (0x02 = SEQ, 0x82 = PRG, etc.) to classify `SEQ/PRG/USR/REL/UNKNOWN`.
-- Step 3: If type is `PRG`, inspect first bytes of file data: load address, plausible next-line pointer, and presence of BASIC tokens (≥ $80) before `00 00` (end-of-program marker) → classify as `BASIC`; else `PRG-MC` (machine code).
-- Practical note: When byte reads are not supported by firmware for host files, use `load_prg` (non-running) + `readmem` to examine the loaded header without executing.
-
-- "dedup_scan"
-  - Discover duplicate files under a root using a tiered strategy: (1) group by size and extension; (2) optional filename normalization; (3) optional content fingerprint when available. Produces groups of candidate duplicates.
-  - Agent state: size→paths index, optional fingerprint cache, serialized scan manifests.
-  - REST: GET /v1/files/{root}/**/*:info (wildcards). Note: content hashing requires a future `/files:read` capability; when absent, tool limits to size/name heuristics.
-
-- "dedup_plan_and_apply"
-  - From a dedup scan, create a reversible plan that keeps one canonical file per group and quarantines the rest. Apply step moves duplicates into a timestamped quarantine directory; final deletion is an explicit, separate step.
-  - Agent state: quarantine root, manifest of moved paths, rollback map, retention policy.
-  - REST: No direct delete/move endpoints today; this tool defaults to dry‑run and plan output. Apply is disabled unless host‑side filesystem integration or future endpoints are configured.
-  - Safety guards: dry‑run by default; explicit `apply=true` and `confirm_phrase` required; path allowlist; maximum deletions threshold; quarantine with rollback window; never touches outside allowed roots.
-
-### SID, music, and audio analysis
-
-- "sid_param_sweep"
-  - Sweep ADSR/waveform/pulse width across ranges; schedule notes, capture audio, and score results by analysis.
-  - Agent state: sweep matrix, top-N results, audio artifacts.
-  - REST: PUT|POST /v1/machine:writemem (via SID registers), POST /v1/runners:sidplay (for sid attachments), optional streams
-
-- "music_compile_play_analyze"
-  - Compile SIDWAVE→PRG or SID, play, then record-and-analyze; export analysis JSON and summary.
-  - Agent state: compilation cache, expected score, analysis logs.
-  - REST: POST /v1/runners:run_prg or POST /v1/runners:sidplay
-
-- "silence_and_verify"
-  - Silence all voices, then verify via short audio capture that output drops below a threshold.
-  - Agent state: threshold, capture window.
-  - REST: PUT|POST /v1/machine:writemem (SID reset), optional streams
-
-### Streaming and monitoring
-
-- "stream_video_for_duration"
-  - Start video stream to host:port for a fixed duration; stop and record timing.
-  - Agent state: timer, destination, failure logs.
-  - REST: PUT /v1/streams/video:start, PUT /v1/streams/video:stop
-
-- "stream_audio_and_record"
-  - Start audio stream, run program, keep stream for N seconds, then stop; optionally run analysis afterward.
-  - Agent state: chained schedule (start→run→stop), record path.
-  - REST: PUT /v1/streams/audio:start, PUT /v1/streams/audio:stop, PUT /v1/runners:run_prg|:sidplay
-
-- "debug_stream_watch"
-  - Start debug stream, collect diagnostic packets, and summarize rates; auto-stop on idle.
-  - Agent state: packet counters, idle detection.
-  - REST: PUT /v1/streams/debug:start, PUT /v1/streams/debug:stop
-
-#### Debug stream–based feedback loops
-
-- "debug_loop_run_and_capture"
-  - Pause → start debug stream → resume → perform action (tool callback) → wait window or until condition → pause → stop stream → parse and summarize packets.
-  - Agent state: host:port, selected mode (6510/VIC/1541), rolling buffer, filters (address ranges, R/W, device), last summary.
-  - REST: PUT /v1/machine:pause, PUT /v1/streams/debug:start, PUT /v1/machine:resume, [action tool], PUT /v1/machine:pause, PUT /v1/streams/debug:stop
-  - Safety: refuse when video stream is active; enforce max duration; auto-stop on packet loss; configurable throttling.
-
-- "debug_trace_until_cpu_write"
-  - Run until a CPU write to an address (or set) is observed; then immediately pause and return a short trace window around the event.
-  - Agent state: address watch set, pre/post window sizes, event metadata.
-  - REST: PUT /v1/machine:pause, PUT /v1/streams/debug:start, PUT /v1/machine:resume, PUT /v1/machine:pause, PUT /v1/streams/debug:stop
-
-- "verify_irq_jitter"
-  - Measure IRQ handler periodicity by detecting writes to $D019 (IRQ ack) or reads/writes around vector/$0314; compute intervals and jitter vs. threshold.
-  - Agent state: target addresses, acceptable jitter, histogram of deltas.
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop
-
-- "verify_raster_irq_line"
-  - Verify raster IRQ is programmed to a specific line by correlating writes to $D012/$D011 and ensuing IRQ acks; report mismatches.
-  - Agent state: expected lines, tolerance for off-by-one conditions.
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop
-
-- "iec_bus_handshake_probe"
-  - Use 1541 debug mode to capture ATN/CLOCK/DATA activity during a load/save; verify protocol phases and timings.
-  - Agent state: phase detector, timing thresholds, pass/fail report.
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop (1541 mode), optional PUT /v1/runners:load_prg|:run_prg
-
-- "sid_register_write_profile"
-  - Capture and summarize writes to $D400–$D418 (SID) to verify gates, ADSR and waveform updates; report per-voice rates and anomalies.
-  - Agent state: address filters, per-register counters, time-bucketed stats.
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop
-
-- "action_latency_measure"
-  - Measure cycles between issuing an action (e.g., menu_button, `c64_memory` `write`) and the first observed matching bus event; return cycle/µs estimate.
-  - Agent state: action timestamp, first-match timestamp, CPU clock assumption (PAL/NTSC option).
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop, PUT /v1/machine:menu_button|:writemem|runners
-
-- "time_bounded_trace_around_event"
-  - Maintain a circular buffer of debug entries and freeze it when a predicate matches (address, R/W, data mask); export the pre/post window.
-  - Agent state: predicate, buffer size, captured window.
-  - REST: PUT /v1/machine:pause|resume, PUT /v1/streams/debug:start|stop
-
-Notes:
-
-- Debug stream consumes significant bandwidth and cannot run concurrently with video; tools enforce mutual exclusion and strict time limits.
-- Modes supported: 6510, VIC, 6510&VIC, 1541, 6510&1541. Tools select minimal necessary mode for the predicate to reduce load.
-
-### Configuration and diagnostics bundles
-
-- "config_snapshot_and_restore"
-  - Read all categories, persist a JSON snapshot; restore later via batch update.
-  - Agent state: snapshot store (versioned), diff reports.
-  - REST: GET /v1/configs, GET /v1/configs/{category}, POST /v1/configs (batch), PUT /v1/configs:save_to_flash|:load_from_flash
-
-- "firmware_info_and_healthcheck"
-  - Fetch version and info, run zero-page read probe, and produce a readiness report.
-  - Agent state: probe outcomes, latency metrics.
-  - REST: GET /v1/version, GET /v1/info, GET /v1/machine:readmem
-
-- "safe_reset_sequence"
-  - Pause, snapshot select RAM ranges, soft reset, verify ranges known to persist (or not), and resume.
-  - Agent state: before/after snapshots, persistence metrics.
-  - REST: PUT /v1/machine:pause, GET /v1/machine:readmem, PUT /v1/machine:reset, PUT /v1/machine:resume
-
-### High-level screen and UI assertions
-
-- "wait_for_screen_text"
-  - Poll screen until a regex/text appears or timeout; return matched region and timestamp.
-  - Agent state: screen sampling schedule, regex cache.
-  - REST: GET /v1/machine:readmem (screen RAM)
-
-- "menu_navigation_script"
-  - Send menu button toggles with delays, capturing screens between steps; export a chronicle.
-  - Agent state: scripted steps, captures.
-  - REST: PUT /v1/machine:menu_button, GET /v1/machine:readmem
-
-### Developer loops and QA harnesses
-
-- "red_green_refactor_loop"
-  - Run program → capture screen → apply `c64_memory` `write` fixups → rerun and compare; stop when assertion passes.
-  - Agent state: assertion, iteration counter, diffs.
-  - REST: PUT /v1/runners:run_prg, GET /v1/machine:readmem, PUT|POST /v1/machine:writemem, PUT /v1/machine:reset
-
-- "multi_range_guardrails"
-  - Enforce invariant constraints across several memory regions (e.g., IRQ vector unchanged); if violated, auto-restore from snapshot.
-  - Agent state: invariant set, restore buffers.
-  - REST: GET /v1/machine:readmem, PUT|POST /v1/machine:writemem
-
-- "drive_recovery_sequence"
-  - Detect drive error, then reset, power cycle, remount last image, and verify.
-  - Agent state: last-known drive config, retries, backoff.
-  - REST: PUT /v1/drives/{drive}:reset, PUT /v1/drives/{drive}:off, PUT /v1/drives/{drive}:on, PUT /v1/drives/{drive}:mount, GET /v1/drives
-
-### RAG-coupled meta tools (knowledge + action)
-
-- "ask_and_apply_memory_fix"
-  - Retrieve assembly guidance (RAG), compute targeted writes, then apply verify_and_write_memory.
-  - Agent state: retrieved refs, decision trace, applied edits.
-  - REST: GET /v1/machine:readmem, PUT|POST /v1/machine:writemem
-
-- "sprite_program_from_prompt"
-  - Generate PETSCII/sprite from text prompt, upload preview PRG, and capture screen for report.
-  - Agent state: prompt, generated assets, screen capture.
-  - REST: POST /v1/runners:run_prg, GET /v1/machine:readmem
-
-### Artifact pipelines (exports and reports)
-
-- "export_directory_listing_via_basic"
-  - Run a tiny BASIC that prints disk directory; scrape screen pages into a single directory listing, write to disk.
-  - Agent state: pagination state, parsed entries.
-  - REST: PUT /v1/runners:run_prg, GET /v1/machine:readmem
-
-- "bundle_run_artifacts"
-  - For any run, collect screen capture, memory snapshot, debugreg, and tool logs into a single folder/tarball.
-  - Agent state: run session id, paths.
-  - REST: GET /v1/machine:readmem, GET /v1/machine:debugreg
-
----
-
-## Additional ideas (brief)
-
-- "memory_heatmap_over_time": periodical reads of ranges, visualize write frequency (GET /v1/machine:readmem).
-- "irq_latency_probe": run tiny PRG that toggles debug/colour and sample with debug stream; compute jitter (streams + run_prg).
-- "sid_voice_stuck_guard": watchdog that issues sid_note_off for lingering gates (writemem to SID regs).
-- "auto_benchmark_suite": run set of PRGs with timing reads from zero-page timers (run_prg + readmem).
-- "firmware_compat_matrix": try features and record which endpoints function on current hardware (GET/PUT variety).
-- "ultimate_config_migrate": snapshot on device A and batch apply to device B (GET /v1/configs, POST /v1/configs).
-
----
-
-## Notes on composition with existing MCP tools
-
-These meta tools build atop existing MCP tools which already wrap the REST surface:
-
-- Memory: `c64_memory` (operations: `read`, `write`, `read_screen`, `wait_for_text`)
-- Programs: `c64_program` (operations: `upload_run_basic`, `upload_run_asm`, `run_prg`, `load_prg`, `run_crt`, `batch_run`, `bundle_run`)
-- Machine control: `c64_system` (operations: `pause`, `resume`, `reset`, `reboot`, `poweroff`, `menu`, `start_task`, `stop_task`, `stop_all_tasks`, `list_tasks`)
-- Storage: `c64_disk` (operations: `list_drives`, `mount`, `unmount`, `file_info`, `create_image`, `find_and_run`) and `c64_drive` (operations: `reset`, `power_on`, `power_off`, `set_mode`, `load_rom`)
-- Audio/SID: `c64_sound` (ops `set_volume`, `reset`, `note_on`, `note_off`, `silence_all`, `play_sid_file`, `play_mod_file`, `generate`, `compile_play`, `pipeline`, `record_analyze`, `analyze`)
-- Streaming: `c64_stream` (ops `start`, `stop`)
-- Developer/Config: `c64_config` (ops `list`, `get`, `set`, `batch_update`, `load_flash`, `save_flash`, `reset_defaults`, `read_debugreg`, `write_debugreg`, `info`, `version`, `snapshot`, `restore`, `diff`, `shuffle`)
-
-By bundling these into single, parameterized meta tools with agent-side scheduling and state, the agent can execute complex workflows with one invocation, reducing latency and improving determinism.
-
----
-
-### Effort/Benefit/Dependencies Matrix
-
-| Tool | Effort (min) | Benefit | Dependencies |
-|---|---:|---|---|
-| memory_dump_to_file | 45 | medium | none |
-| memory_snapshot_and_diff | 50 | high | memory_dump_to_file |
-| verify_and_write_memory | 35 | high | none |
-| watch_memory_until_condition | 40 | medium | none |
-| disassemble_ram_region | 60 | medium | none |
-| trace_code_flow_by_checksums | 75 | medium | memory_snapshot_and_diff |
-| extract_sprites_from_ram | 80 | medium | memory_dump_to_file |
-| rip_charset_from_ram | 75 | medium | memory_dump_to_file |
-| screen_capture_timeline | 50 | medium | wait_for_screen_text |
-| sprite_preview_prg_batch | 60 | medium | program_shuffle |
-| program_shuffle | 45 | medium | wait_for_screen_text |
-| batch_run_with_assertions | 60 | high | wait_for_screen_text |
-| compile_run_verify_cycle | 90 | high | batch_run_with_assertions, bundle_run_artifacts |
-| cold_boot_and_run | 40 | medium | firmware_info_and_healthcheck |
-| start_background_task | 50 | high | none |
-| stop_background_task | 15 | high | start_background_task |
-| list_background_tasks | 20 | medium | start_background_task |
-| stop_all_background_tasks | 15 | medium | start_background_task |
-| drive_mount_and_verify | 45 | medium | firmware_info_and_healthcheck |
-| create_and_mount_blank_d64 | 35 | medium | drive_mount_and_verify |
-| batch_on_assets_apply_tools | 70 | medium | find_paths_by_name |
-| drive_mode_profile_switch | 40 | low | drive_mount_and_verify |
-| eject_and_poweroff_drive | 25 | low | drive_mount_and_verify |
-| find_and_run_program_by_name | 45 | high | find_paths_by_name |
-| filesystem_stats_by_extension | 35 | medium | none |
-| find_paths_by_name | 40 | high | none |
-| run_copy_move_delete_by_path | 50 | medium | find_paths_by_name |
-| container_aware_walk_and_classify | 60 | medium | find_paths_by_name |
-| classify_prg_basic_or_mc | 45 | medium | container_aware_walk_and_classify |
-| dedup_scan | 60 | medium | filesystem_stats_by_extension |
-| dedup_plan_and_apply | 75 | medium | dedup_scan |
-| sid_param_sweep | 90 | medium | silence_and_verify |
-| music_compile_play_analyze | 90 | high | silence_and_verify |
-| silence_and_verify | 35 | high | none |
-| stream_video_for_duration | 40 | medium | none |
-| stream_audio_and_record | 50 | medium | none |
-| debug_stream_watch | 55 | medium | none |
-| debug_loop_run_and_capture | 80 | high | debug_stream_watch |
-| debug_trace_until_cpu_write | 70 | high | debug_loop_run_and_capture |
-| verify_irq_jitter | 70 | medium | debug_loop_run_and_capture |
-| verify_raster_irq_line | 70 | high | debug_loop_run_and_capture |
-| iec_bus_handshake_probe | 85 | medium | debug_loop_run_and_capture |
-| sid_register_write_profile | 70 | medium | debug_loop_run_and_capture |
-| action_latency_measure | 75 | medium | debug_loop_run_and_capture |
-| time_bounded_trace_around_event | 70 | medium | debug_loop_run_and_capture |
-| config_snapshot_and_restore | 60 | medium | none |
-| firmware_info_and_healthcheck | 30 | high | none |
-| safe_reset_sequence | 45 | medium | firmware_info_and_healthcheck |
-| wait_for_screen_text | 35 | high | none |
-| menu_navigation_script | 45 | medium | wait_for_screen_text |
-| red_green_refactor_loop | 70 | high | verify_and_write_memory, wait_for_screen_text |
-| multi_range_guardrails | 80 | medium | verify_and_write_memory, memory_snapshot_and_diff |
-| drive_recovery_sequence | 60 | medium | drive_mount_and_verify |
-| ask_and_apply_memory_fix | 65 | high | verify_and_write_memory |
-| sprite_program_from_prompt | 75 | medium | sprite_preview_prg_batch |
-| export_directory_listing_via_basic | 45 | medium | wait_for_screen_text |
-| bundle_run_artifacts | 50 | high | memory_snapshot_and_diff, wait_for_screen_text |
-| memory_heatmap_over_time | 60 | medium | watch_memory_until_condition |
-| irq_latency_probe | 70 | medium | debug_stream_watch |
-| sid_voice_stuck_guard | 45 | medium | silence_and_verify |
-| auto_benchmark_suite | 80 | medium | program_shuffle, batch_run_with_assertions |
-| firmware_compat_matrix | 60 | medium | firmware_info_and_healthcheck |
-| ultimate_config_migrate | 75 | medium | config_snapshot_and_restore |

package/doc/plans/meta-tools/notes.md

@@ -1,192 +0,0 @@
-# Meta Tools Implementation Notes
-
-This document tracks observations, decisions, and learnings from the meta tools rollout.
-
-## Overview
-
-Meta tools are high-level orchestration tools that compose multiple MCP operations into single, stateful workflows. They reduce round-trips between client and server and enable complex agent behaviors.
-
-## Current State (as of 2025-10-30)
-
-### Implemented Tools (12)
-
-- Phase 0 foundations: firmware_info_and_healthcheck, wait_for_screen_text, verify_and_write_memory, background task suite, find_paths_by_name, memory_dump_to_file, config_snapshot_and_restore
-- Phase 1 orchestration: program_shuffle, batch_run_with_assertions, bundle_run_artifacts, compile_run_verify_cycle
-- Phase 2 quick wins: find_and_run_program_by_name, silence_and_verify, filesystem_stats_by_extension
-
-### File Organization
-
-- Source: `src/tools/meta/` with submodules by domain (diagnostics, screen, memory, background, filesystem, config, program, artifacts, compilation)
-- Tests: Integrated into existing test suites, no dedicated meta/ test folder yet
-- Docs: **Reorganized into `doc/meta-tools/`** (matching improve-knowledge pattern)
-
-## Documentation Structure
-
-Following the improve-knowledge precedent:
-
-```text
-doc/meta-tools/
-  ├── catalog.md        (formerly meta-tools.md — comprehensive tool definitions)
-  ├── rollout.md        (formerly meta-tools-rollout.md — implementation checklist)
-  ├── analysis.md       (NEW — impact analysis and prioritization)
-  └── notes.md          (this file — observations and decisions)
-```
-
-Benefits:
-
-- Cleaner doc/ root folder
-- Related documents grouped together
-- Easier to find meta tools documentation
-- Consistent with improve-knowledge structure
-
-## Prioritization Rationale
-
-### Why Reprioritize?
-
-Original rollout followed dependency order and implementation phases. However, based on actual agent usage patterns, some unimplemented tools would provide much higher value:
-
-1. **Filesystem discovery** — Agents frequently struggle to find programs in disk collections
-2. **SID testing** — Current music workflows lack proper silence verification
-3. **Graphics extraction** — Users want to analyze and reuse sprites/charsets from programs
-4. **Debug streaming** — Highly valuable but requires significant infrastructure
-
-### Decision: High-Impact, Low-Effort First
-
-New approach prioritizes:
-
-- Quick wins (35-45 minute tools with high impact)
-- Foundation tools that enable agent creativity (find programs, compose music)
-- Tools with clear, testable outcomes
-- Deferring infrastructure-heavy work (debug streaming)
-
-See `analysis.md` for detailed impact breakdown.
-
-## Implementation Patterns
-
-### Meta Tool Anatomy
-
-Each meta tool typically:
-
-1. **Composes** existing MCP tools (no direct REST calls when possible)
-2. **Maintains state** agent-side (snapshots, buffers, registries)
-3. **Provides retry logic** and error recovery
-4. **Returns structured results** with metadata and URIs
-5. **Respects hardware safeguards** (pause/resume, timeouts, mutual exclusion)
-
-### Testing Strategy
-
-- Unit tests for tool logic (parameter validation, error handling)
-- Integration tests with mock C64Client
-- No hardware required for CI/CD
-- Real hardware testing manual (for now)
-
-### Documentation Requirements
-
-For each implemented tool:
-
-- [ ] Entry in `catalog.md` with full specification
-- [ ] Checkbox in `rollout.md` marked complete
-- [ ] Tests covering happy path and one failure case
-- [ ] Usage examples in tool description
-- [ ] Dependencies clearly documented
-
-## Technical Decisions
-
-### Background Tasks Registry
-
-**Decision**: In-memory registry with optional persistence to disk
-
-**Rationale**: Simplicity for MVP; disk persistence can be added later if needed
-
-**Trade-offs**: Tasks lost on restart, but acceptable for experimental features
-
-### Container-Aware Filesystem Tools
-
-**Decision**: Implement discovery that recurses into D64/D71/D81/T64 containers
-
-**Rationale**: C64 programs are often stored in disk images, not loose files
-
-**Implementation**: Use wildcards when firmware supports them; fall back to mount+BASIC scraping when necessary
-
-### Debug Streaming Infrastructure
-
-**Decision**: Defer all debug streaming tools to Post-GA
-
-**Rationale**: Requires UDP ingest, backpressure handling, performance validation (~72 hours of infrastructure work)
-
-**Alternative considered**: Implement basic version with TCP — rejected because packet loss handling is essential
-
-**Next steps**: Plan dedicated infrastructure sprint before tackling Phase 5 debug tools
-
-### Meta Tool File Layout
-
-**Decision**: Keep meta tools in `src/tools/meta/` submodule structure
-
-**Rationale**:
-
-- Clear separation from core tools
-- Easy to mark as experimental/beta
-- Modular structure by domain (diagnostics, screen, memory, etc.)
-- No impact on MCP tool registration (all tools exposed equally)
-
-**Trade-offs**: Slightly deeper import paths, but better organization
-
-## Lessons Learned
-
-### From Phase 0-1 Implementation
-
-1. **Background tasks are versatile** — Can schedule any tool, not just specific operations
-2. **Verification patterns reusable** — verify_and_write_memory pattern applies to many tools
-3. **Screen polling essential** — wait_for_screen_text foundation for many workflows
-4. **Artifacts bundling popular** — bundle_run_artifacts frequently requested by users
-
-### From Impact Analysis
-
-1. **Filesystem navigation is critical** — Most common agent failure: "I can't find that program"
-2. **SID testing needs improvement** — Silence verification missing causes flaky tests
-3. **Debug streaming is desirable but complex** — High demand, but infrastructure not ready
-4. **Graphics tools have broad appeal** — Sprite/charset extraction enables creative reuse
-
-## Future Considerations
-
-### Potential Improvements
-
-1. **Meta tool composition** — Allow meta tools to call other meta tools
-2. **Persistent background tasks** — Survive server restarts
-3. **Progress callbacks** — Report progress during long-running operations
-4. **Cancellation** — Abort in-progress meta tools gracefully
-5. **Dry-run mode** — Preview actions without executing (especially for destructive ops)
-
-### Infrastructure Needs
-
-For debug streaming (Phase 5):
-
-- UDP packet receiver with reassembly
-- Backpressure and flow control
-- Circular buffer for trace windows
-- Packet loss detection and reporting
-- Performance benchmarks and load tests
-- Observability (metrics, logging, tracing)
-
-### Documentation Gaps
-
-- No architecture diagram for meta tool system
-- Limited examples of meta tool composition patterns
-- No performance guidelines (when to avoid meta tools)
-- Testing best practices not documented
-
-## Open Questions
-
-1. **Should meta tools be separately versioned?** Currently experimental, but what's the graduation criteria?
-2. **How to handle breaking changes?** Meta tools compose other tools — cascade impacts?
-3. **Rate limiting?** Some meta tools could issue many requests — need throttling?
-4. **Observability?** How to monitor meta tool usage and performance in production?
-
-## References
-
-- `catalog.md` — Full meta tool definitions with effort/benefit matrix
-- `rollout.md` — Implementation checklist with dependencies
-- `analysis.md` — Impact analysis and prioritization rationale
-- `doc/improve-knowledge/` — Similar documentation structure pattern
-- `doc/agent-state-spec.md` — Background task registry specification
-- `src/tools/meta/` — Implementation source code