feat(mcp): knowledge fact import + session snapshot in flare_handoff

[getappz]

Recovers work from item #218 that never landed anywhere reachable — it was sitting uncommitted in a stash from a prior session (correctly kept off master, but never given a branch). Reviewed per item #220, one bug fixed.

Changes

HandoffRequest (types.rs) gains 6 optional fields: facts, summary, findings, decisions, files_touched, evidence.

handoff.rs:

• Fact import: iterates facts before backend work, calls handle_remember for each, titles prefixed [sender]. Best-effort — logs and continues on error, never fails the handoff.
• Session snapshot: embeds the 5 snapshot fields into the asset's meta JSON so the recipient gets context from the attachment without extra round-trips.

Review fix

HandoffRequest.facts's #[schemars(description = ...)] was copy-pasted from the unrelated memory tool's action-enum text ("Single consolidated tool with action field (compact|context|curate|...)") — would've leaked a nonsensical description into the MCP tool schema shown to callers. Replaced with an accurate description and added the topic_key? sub-field the code reads but the old text omitted.

Verification

• cargo build — clean
• cargo fmt --check — clean
• cargo clippy -D warnings — clean (only pre-existing unrelated claude_settings dead_code)
• cargo test --workspace --lib --bins — all green, incl. 16 handoff tests
  • workspace doctests hit a pre-existing, unrelated stale-cache E0460 in skill-registry; not touched by this change

Closes item #220.

Summary by CodeRabbit

• New Features
  • Handoffs can now carry session context (summary, findings, decisions, files touched, and evidence) and include it directly in handoff metadata.
  • Handoffs can also accept a set of provided facts to import into the recipient’s memory for smoother continuity.
• Reliability
  • Fact/memory-import failures are handled best-effort and no longer interrupt or fail the handoff.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: af9bb447-c09b-45db-af1c-e10d47d96a43

📥 Commits

Reviewing files that changed from the base of the PR and between 82d3a09 and 581b89f.

📒 Files selected for processing (2)

• src/mcp_server.rs
• src/mcp_server/types.rs

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

• src/mcp_server/types.rs
• src/mcp_server.rs

---

📝 Walkthrough

Walkthrough

The MCP handoff request now accepts optional facts and session snapshot fields. Facts are imported into recipient memory on a best-effort basis, while snapshot fields are stored in attachment metadata and documented in the tool description.

Changes

Handoff session context enrichment

Layer / File(s)	Summary
Handoff request contract src/mcp_server/types.rs, src/mcp_server.rs	HandoffRequest accepts optional facts and session snapshot fields, and the tool description documents their use.
Fact import during handoff src/mcp_server/handoff.rs	Supplied facts are mapped to RememberInput values and written to recipient memory without failing the handoff when a write errors.
Session snapshot attachment metadata src/mcp_server/handoff.rs	Provided summary, findings, decisions, files-touched, and evidence fields are conditionally added to attachment metadata.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant handoff_impl
  participant handle_remember
  participant Attachment
  Caller->>handoff_impl: HandoffRequest with facts and snapshot fields
  handoff_impl->>handle_remember: RememberInput for each fact
  handle_remember-->>handoff_impl: Memory write result
  handoff_impl->>Attachment: Store session snapshot in meta
  handoff_impl-->>Caller: Handoff outcome

Loading

Possibly related PRs

• getappz/agentflare#254: Extends the handoff handler and related types modified by this change.
• getappz/agentflare#169: Changes handoff attachment handling for items and versioned assets.
• getappz/agentflare#185: Modifies MCP memory and handoff request plumbing extended by this change.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise, specific, and matches the fact import and session snapshot changes.
Description check	✅ Passed	The description covers the summary, review fix, and verification results, with only the reviewer-notes section not fully formalized.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/handoff-facts-import

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp_server.rs`:
- Line 412: Update the public handoff description assigned to the tool around
the facts payload to document the optional topic_key field alongside title,
content, and type. Keep the existing description and behavior unchanged while
making the advertised facts contract match the request schema and handler.

In `@src/mcp_server/handoff.rs`:
- Around line 46-79: Move the knowledge-fact import block around the visible
handoff success path so it runs only after with_backend_db successfully resolves
the item and creates the asset. Preserve the existing best-effort
handle_remember behavior and error logging, while ensuring any backend or
storage failure returns before facts are persisted.
- Around line 62-72: Update the handoff memory flow around RememberInput so
imported facts are associated with the handoff recipient by passing the
appropriate recipient-specific session, project, scope, or agent context through
the memory API. Ensure the recipient value is propagated into the memory layer
rather than leaving all context fields unset; alternatively, revise the handoff
contract and documentation to explicitly define these facts as shared memory.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d38aa94f-1df9-473e-b3e1-619bcc49b2fa

📥 Commits

Reviewing files that changed from the base of the PR and between 5003210 and 1703171.

📒 Files selected for processing (3)

• src/mcp_server.rs
• src/mcp_server/handoff.rs
• src/mcp_server/types.rs