openhuman/docs/tinyagents-full-migration-plan/HANDOFF-2026-07-03.md

Handoff — TinyAgents migration wave 1 (2026-07-03)

Context file for picking this work up in a fresh session. Read together with CONTINUATION-2026-07.md (the plan this wave executes) and 99-deletion-ledger.md.

What this session did

1. Audit — ground-truth audit of post-#4249 main, TinyAgents crate re-inventory (1.4.0 published: graph::goals/graph::todos/graph resilience; 1.5.0: NoProgressTracker extracted from our #4389), and a critical re-review of the deletion ledger's "never delete" list. Product of that: CONTINUATION-2026-07.md (workstreams C0–C7, ~29k-line reclaim) with a coverage-sweep appendix for previously unreferenced harness files.
2. Vendored the SDK — vendor/tinyagents git submodule pinned at tag v1.5.0; [patch.crates-io] tinyagents = { path = ... } in BOTH Cargo worlds (root Cargo.toml, app/src-tauri/Cargo.toml); Dockerfile now COPY vendor/ vendor/; release-production/staging docker jobs run a targeted git submodule update --init vendor/tinyagents. All other cargo-running CI jobs already checkout submodules: recursive; the mobile crates (app/src-tauri-mobile) do NOT depend on the core crate, so their submodules: false stays. Agents can now edit SDK source in-tree and PR upstream from the submodule (do this in C5).
3. Executed wave 1 via a 6-agent workflow (run id wf_df08984c-139, scripts under the session dir; all agents completed).
4. agent-diff-v0.58.7-to-HEAD.diff at repo root (gitignored) — full diff of src/openhuman/agent/ since the last release, for review.

Branch map (local; base → children)

• feat/tinyagents-c0-15-baseline ← base for everything below; branched from docs/tinyagents-migration-continuation (which holds the plan docs and branched from upstream/main).
  • c7f287380 bump tinyagents 1.5.0 (+ .diff gitignore)
  • e2f010cba vendor submodule + [patch.crates-io] both worlds
  • 4c2895801 RepeatedToolFailureMiddleware → crate NoProgressTracker driver (in-house identical/varied/hard-reject ladder deleted; Nudge→ SteeringCommand::Redirect, Halt→HaltSummarySlot+Pause+reset; 25 middleware tests green)
  • fbafad2d3 CI docker submodule fixes
  • dd63b3a66 with_node_retry(RetryPolicy::default().with_max_attempts(1)) on delegation + spawn-parallel graphs (behavior-preserving seam; raise attempts later; backoff sleeping off)
  • 02be67b06 plan corrections from C3 (below)
• feat/tinyagents-c1-dual-writes — 04.1 done. Live turns dual-write to {workspace}/tinyagents_store/{kv,journal} (session.{stem}.messages + descriptor upsert, via session_import/convert.rs normalization). New config flag agent.session_dual_write (serde default ON); OPENHUMAN_SESSION_DUAL_WRITE is a pure kill switch (can force off, never on), read per-turn. Parity test: session_import::live_tests (2 pass). Read path untouched.
• feat/tinyagents-c2-goals — thread_goals/crate_adapter.rs dual-write mirror into ns graph.goals (keys byte-identical to the crate reader, proven by reading back via tinyagents::graph::goals::store::get); idempotent migrate_legacy_goals_into_crate_store (callable, NOT wired to boot); shadow tool surface flag-gated OFF. Legacy store authoritative.
• feat/tinyagents-c2-todos — todos/graph_shadow.rs mirrors boards into ns graph.todos at <workspace>/tinyagents_graph_store; claim_card CAS shadow through the single refactored todos::ops::claim_card chokepoint (apply_claim helper), divergence warn-logged; parity note C2b-todos-parity.md (what maps vs product residue). Legacy authoritative.
• feat/tinyagents-c3-middleware-dedupe — PARTIAL by design: CacheAlignMiddleware deleted (−147 lines; crate cache guard already installed). See "plan corrections" for the two refusals.
• feat/tinyagents-c4-journals — restart-stable event ids (EventSink::with_stream_id(run_id) → {run_id}-evt-{offset}), run id minted once via journal::mint_run_id; FileStatusStore records thread_id (HarnessRunStatus::with_thread) so list_by_thread answers; late-attach replay test reconstructs from the store alone.

All slice branches were created FROM feat/tinyagents-c0-15-baseline (worktree HEADs were stale; agents rebased themselves correctly).

Plan corrections discovered during execution (already committed, 02be67b06)

• MicrocompactMiddleware is NOT crate-superseded — tinyagents 1.5.0 has no tool-result body-clearing; local one is live at turn/core.rs (~:885, keep_recent=5). Moved to C5: extract into the crate first, then delete.
• Unknown-tool is already done — sentinel + rewrite middleware deleted in 01.2; live policy UnknownToolPolicy::ReturnToolError deliberately kept over Rewrite (preserves #4419 attempted-name UX; Rewrite needs a catch-all target tool). Rationale comment at run_policy_for.
• C3's shadow-parity investigation: exposure-shadow parity logs exist but are not yet asserted divergence-free — flipping ContextualToolSelectionMiddleware to owner still needs a parity-log audit.

Known debt / gotchas for the next session

• Worktrees + submodule: fresh worktrees leave vendor/tinyagents empty → cargo fails on the patch path. Always git submodule update --init vendor/tinyagents first.
• Test invocation: RUST_MIN_STACK=16777216 … --test-threads=1 (deep sub-agent futures overflow default stacks); GGML_NATIVE=OFF for cargo on Apple Silicon. Full suites were deliberately NOT run — targeted module tests only (user directive). Integration debt is listed per-slice in the workflow reports and belongs to the final conformance pass (plan §11).
• C1's RunContext.stores session-KV registration has no in-run consumer until 04.2 (StoreChatHistory adoption was deferred as read-path work).
• C4 follow-ups: replay RPC (agent.run_events) unexposed; parent/root run-id lineage still 05.2/05.3.
• The five slice branches will conflict lightly in tinyagents/middleware.rs / mod.rs when merged together — merge C0 first, then slices one at a time, resolving against C0's tree.

Wave 1 (merged)

All five wave-1 slice branches were MERGED into feat/tinyagents-c0-15-baseline and pushed to PR #4473, which landed the entire wave-1 scope into tinyhumansai/openhuman:main.

Wave 2 status (2026-07-04) — DONE, on feat/tinyagents-wave2

All four wave-2 slices are implemented and integrated onto ONE branch feat/tinyagents-wave2 (off upstream/main), one focused commit each, and opened as a single combined PR. Adapter-first throughout: legacy authoritative, crate features shadow + log divergence, deletions gated on proven parity.

1. W2-microcompact-upstream — done. The generic MicrocompactMiddleware (caller-supplied placeholder, opt-in Compressed event, idempotent tool-body clearing) was implemented IN the vendored crate and pushed to tinyhumansai/tinyagents@feat/microcompact-middleware (commit ac73382) BEFORE the gitlink bump. OpenHuman swapped to the crate type (constructed with CLEARED_PLACEHOLDER, events off → byte-identical); local struct+impl deleted, OpenHuman tests retargeted as the parity contract. Crate tests: 5 green. Ledger row ticked.
2. W2-shadow-reads — done. 04.2 phase 2 store-backed shadow reader beside the legacy transcript reader; [session_shadow_read] divergence logging; flag agent.session_shadow_reads (default OFF) + OPENHUMAN_SESSION_SHADOW_READS kill switch. Legacy authoritative. (Flip → reads-from-store is phase 3, the ~9k-line deletion unlock.)
3. W2-budget-dedupe — done. Event bridge records each model call's usage exactly once (dedupe guard keyed on the run-scoped iteration cursor); crate BudgetMiddleware installed observe-only (empty BudgetLimits); local CostBudgetMiddleware demoted to a [budget_shadow] divergence logger, still authoritative for enforcement. Three flip criteria documented at the tinyagents/mod.rs registration site + in the ledger.
4. W2-replay-rpc — done. Read-only openhuman.agent_run_events (paged, next_offset, capped limit), agent_run_status, agent_runs_active controllers over the C4 journal/status seams; direct AgentObservation/ HarnessRunStatus serde projection (no PII); registered via src/core/all.rs per the controller-migration checklist. (Resolves the "replay RPC unexposed" C4 follow-up.)

Test note: targeted crate tests (microcompact) ran green locally; the full core-crate test binary would not link locally under this box's memory ceiling (single-rustc codegen thrash), so cargo check --lib --tests is the local compile gate and CI runs the actual targeted + full suites + coverage.

Merge / PR state

• feat/tinyagents-wave2 pushed to origin (senamakel fork); ONE combined PR vs upstream (--head senamakel:feat/tinyagents-wave2): PR #4483 (tinyhumansai/openhuman#4483).
• Submodule branch feat/microcompact-middleware pushed to tinyhumansai/tinyagents; gitlink bumped to ac73382. Fresh worktrees must git submodule update --init vendor/tinyagents.
• Git etiquette (user rules): push to origin, PR against upstream with --head senamakel:<branch>; explicit git add <paths>; never commit on main.

Suggested next steps (wave 3)

1. Flip session_shadow_reads → reads-from-store once the fixture-matrix divergence logs are clean (biggest deletion unlock, ~9k incl. dispatcher/parse/pformat).
2. Flip crate BudgetMiddleware → enforcing owner once the 3 documented criteria hold; delete local CostBudgetMiddleware + turn_subagent_usage.rs.
3. Open a tinyagents PR for feat/microcompact-middleware (currently a pushed branch, not merged) so the gitlink can later track a tagged release.
4. Continue C5 upstream extractions (multimodal resolver, dialect layer, overflow-to-artifact, hooks traits) + C2 shadow → authoritative flips.