[codex] Add agent context handoff

[qyinm]

Summary

Adds Agent Context Handoff v0 so MirrorNote can turn source-backed project memory into handoff.json and handoff.md for the next agent task.

Why

MirrorNote needs a concrete handoff layer before full in-app agent execution. This lets a future Codex, Claude Code, Cursor, or in-app agent session receive concise context from existing project memory without re-explaining prior decisions, constraints, questions, and risks.

Changes

• Add AgentContextHandoff types and prepare_agent_context_handoff() in the Rust context packet module.
• Generate projects/<project-id>/handoffs/handoff.json and handoff.md from project memory.
• Categorize active decisions, tasks/commitments, open questions, constraints, preferences, risks, additional context, and related source records.
• Exclude resolved/superseded memory objects from handoffs.
• Emit warnings for missing source references and weak evidence.
• Add prepareAgentContext to MirrorNoteAgentServer so the daemon can prepare handoffs without implementing a full agent window.
• Add contract tests for handoff generation and agent-server command handling.

Validation:

• CARGO_TARGET_DIR=target cargo fmt --check in native/native-host-rust
• CARGO_TARGET_DIR=target cargo fmt --check in native/agent-server-rust
• CARGO_TARGET_DIR=target cargo test in native/native-host-rust
• CARGO_TARGET_DIR=target cargo test in native/agent-server-rust
• npm run native:build
• git diff --check

Summary by CodeRabbit

• New Features

  • Agent context handoff preparation: request handoff generation to produce persisted JSON and Markdown summaries of project context, memory, categorizations, and per-item warnings (e.g., missing sources); resolved items are excluded.

• Behavior

  • Hand-off generation validates inputs and enforces a project-memory lock/timeout to avoid concurrent conflicts.

• Tests

  • Added tests for successful handoff output, missing-project-memory failure (no files written), and lock/timeout behavior.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Free

Run ID: 1c9a5c83-6fab-4630-b5ca-c3931746cd23

📥 Commits

Reviewing files that changed from the base of the PR and between 030cf05 and bb9b942.

📒 Files selected for processing (2)

• native/native-host-rust/src/context_packet.rs
• native/native-host-rust/tests/context_packet_contract.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• native/native-host-rust/src/context_packet.rs

---

📝 Walkthrough

Walkthrough

Adds an Agent Context Handoff feature: new request command and request fields in the server, new handoff data types and a handoff-preparation implementation that filters project memory, generates warnings, renders JSON/Markdown, writes files under a project's handoffs/ directory, and returns the handoff result.

Changes

Agent Context Handoff Feature

Layer / File(s)	Summary
Data Structures native/native-host-rust/src/context_packet.rs	Introduces AgentContextHandoffPaths, AgentContextHandoffInput, AgentContextHandoffWarning, AgentContextHandoff, AgentContextHandoffResult and constants for handoffs/, handoff.json, handoff.md.
Markdown Escaping native/native-host-rust/src/context_packet.rs	markdown_inline updated to escape a broader set of Markdown-special characters.
Core Handoff Implementation native/native-host-rust/src/context_packet.rs	Adds prepare_agent_context_handoff(...): loads project memory JSONL, selects active objects (excludes resolved/superseded), categorizes into sections (decisions, tasks/commitments, open questions, constraints/requirements, preferences, risks, additional context), collects related sources, emits warnings (missing source refs, weak evidence/low confidence), builds AgentContextHandoff, and returns AgentContextHandoffResult. Writes pretty handoff.json and generated handoff.md into project_directory/handoffs/.
Request/Response Extensions native/agent-server-rust/src/main.rs	AgentRequest gains optional meetings_root, task, project_hint, working_directory; AgentCommand adds PrepareAgentContext; AgentPayload includes optional handoff.
Server Wiring native/agent-server-rust/src/main.rs	handle_request routes PrepareAgentContext to new prepare_agent_context function which validates inputs (requires meetings_root and non-empty task), constructs AgentContextHandoffInput, calls prepare_agent_context_handoff, and returns handoff or formatted error.
Tests / Contracts native/native-host-rust/tests/context_packet_contract.rs, native/agent-server-rust/src/main.rs	Adds tests: verifies handoff selection/categories/warnings and that handoff.json/handoff.md are written; asserts missing project memory yields error without writing files; tests lock behavior when .project-memory.lock is present. Server-level test verifies request handling and persisted files.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Server as Agent Server
    participant Handler as Handoff Handler
    participant FS as File System

    Client->>Server: PrepareAgentContext request {meetings_root, task, project_hint, working_directory}
    activate Server
    Server->>Server: Validate inputs (meetings_root present, non-empty task)
    Server->>Handler: prepare_agent_context_handoff(meetings_root, input)
    activate Handler
    Handler->>FS: Read project memory JSONL files
    FS-->>Handler: Project memory objects
    Handler->>Handler: Filter active objects & categorize
    Handler->>Handler: Generate warnings & render Markdown/JSON
    Handler->>FS: Write handoff.json and handoff.md (atomic)
    Handler-->>Server: AgentContextHandoffResult {handoff, paths}
    deactivate Handler
    Server-->>Client: 200 OK {handoff}
    deactivate Server

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 I nibble through memory, sorting each thread,
I write JSON and Markdown so agents are fed,
Warnings like carrots to show what is weak,
Handoffs neatly packaged for whoever will peek,
Hop, render, and save — a tidy context spread.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces the Agent Context Handoff feature in the agent-server-rust and native-host-rust crates, which aggregates project memory—including decisions, tasks, and constraints—into JSON and Markdown formats for agent consumption. It adds a new PrepareAgentContext command to the agent server, implements logic to filter active memory objects, and includes tests to verify the handoff generation. Feedback focuses on improving error handling by verifying the existence of project directories before file operations to prevent the creation of empty directories and recommends escaping markdown special characters in source-derived text to ensure correct document formatting.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 030cf056ac

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".