fix: gateway_execute args schema so callers can actually pass arguments

[getappz]

Summary

• GatewayExecuteRequest.args was typed as bare serde_json::Value, which schemars renders with no type constraint — callers had no signal to send a nested JSON object, so gateway_execute could never actually be invoked with arguments (confirmed live via dogfooding against the engram backend).
• Retyped to Option<serde_json::Map<String, serde_json::Value>>, which schemars renders as {"type": ["object", "null"]}. Runtime semantics are unchanged (accept Object or Null, reject anything else).

Test plan

• cargo test — 206/206 passing
• Live dogfood: gateway_search → gateway_execute(engram, memory_context, {...}) succeeds end-to-end post-fix

Summary by CodeRabbit

• New Features

  • Added clearer session-start guidance for on-demand memory lookup, including how to search and execute tools when needed.

• Bug Fixes

  • Improved tool argument handling by representing tool arguments as structured object maps and correctly treating omitted arguments as null.
  • Updated and extended validation so generated request schemas match the new argument behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a “Memory on-demand” line to the session-start message and updates gateway_execute so args is an optional typed object map, with matching test and schema updates.

Changes

Memory nudge and typed gateway args

Layer / File(s)	Summary
Session-start memory guidance src/hook.rs	Adds a “Memory on-demand” line to session_start_message explaining the gateway_search(query) to gateway_execute(server="engram") flow, plus a test that checks the message text.
Typed gateway_execute args src/mcp_server.rs	Changes GatewayExecuteRequest.args to Option<serde_json::Map<String, serde_json::Value>>, converts it to Value::Object or Value::Null in gateway_execute, updates existing request tests, and adds a schema test for the object-or-null shape.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• getappz/agentflare#103: Also updates src/hook.rs session-start guidance and its tests around tool usage instructions.
• getappz/agentflare#104: Closely related to the gateway_execute request shape, serialization, and schema behavior in src/mcp_server.rs.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: fixing gateway_execute args schema so callers can pass arguments.
Description check	✅ Passed	The description covers Summary and Test plan well, but it omits the template's Notes for reviewers section.
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-gateway-execute-args

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/mcp_server.rs (1)

73-80: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Add a schema regression test for args.

This PR’s key contract is the generated schema hint, but the updated tests only exercise runtime construction. Please lock the args schema to object/null so future type changes don’t silently reintroduce the typeless Value schema.

Example regression check

+    #[test]
+    fn gateway_execute_args_schema_is_object_or_null() {
+        let schema = schemars::schema_for!(GatewayExecuteRequest);
+        let schema_json = serde_json::to_value(&schema).unwrap();
+        let args_schema = schema_json
+            .get("properties")
+            .and_then(|properties| properties.get("args"))
+            .expect("args schema should be present");
+
+        let rendered = args_schema.to_string();
+        assert!(rendered.contains("\"object\""), "{rendered}");
+        assert!(rendered.contains("\"null\""), "{rendered}");
+    }

🤖 Prompt for 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.

In `@src/mcp_server.rs` around lines 73 - 80, Add a schema regression test for the
`args` field in `McpServer` so the generated schemars output is locked to an
object-or-null shape. Extend the existing test coverage around `args:
Option<serde_json::Map<String, serde_json::Value>>` to assert the schema
includes an object hint rather than a typeless `Value` schema, and verify the
`McpServer`/`args` contract directly so future type changes are caught.

🤖 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.

Nitpick comments:
In `@src/mcp_server.rs`:
- Around line 73-80: Add a schema regression test for the `args` field in
`McpServer` so the generated schemars output is locked to an object-or-null
shape. Extend the existing test coverage around `args:
Option<serde_json::Map<String, serde_json::Value>>` to assert the schema
includes an object hint rather than a typeless `Value` schema, and verify the
`McpServer`/`args` contract directly so future type changes are caught.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9503b312-1bd2-41be-a6bf-5121f63fafb4

📥 Commits

Reviewing files that changed from the base of the PR and between 2cb527a and 23e3571.

📒 Files selected for processing (2)

• src/hook.rs
• src/mcp_server.rs

[coderabbitai]

🧹 Nitpick comments (1)

src/mcp_server.rs (1)

738-741: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Assert the schema type structurally.

to_string().contains(...) can pass if "object"/"null" appear outside the actual type constraint. Since this test locks the public gateway_execute.args contract, inspect the type field directly.

Proposed test tightening

-        let rendered = args_schema.to_string();
-        assert!(rendered.contains("\"object\""), "{rendered}");
-        assert!(rendered.contains("\"null\""), "{rendered}");
+        let mut types: Vec<_> = args_schema
+            .get("type")
+            .and_then(serde_json::Value::as_array)
+            .expect("args schema type array")
+            .iter()
+            .filter_map(serde_json::Value::as_str)
+            .collect();
+        types.sort_unstable();
+        assert_eq!(types, vec!["null", "object"], "{args_schema}");

🤖 Prompt for 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.

In `@src/mcp_server.rs` around lines 738 - 741, The test in the schema assertion
block is too loose because it checks the rendered JSON string for "object" and
"null" instead of validating the actual type structure. Update the assertions
around the args schema in the relevant test to inspect the schema JSON directly
via the args_schema value, specifically checking the type field (or equivalent
structural representation) for the expected object/null shape. Keep the change
localized to the test that verifies the gateway_execute.args contract.

🤖 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.

Nitpick comments:
In `@src/mcp_server.rs`:
- Around line 738-741: The test in the schema assertion block is too loose
because it checks the rendered JSON string for "object" and "null" instead of
validating the actual type structure. Update the assertions around the args
schema in the relevant test to inspect the schema JSON directly via the
args_schema value, specifically checking the type field (or equivalent
structural representation) for the expected object/null shape. Keep the change
localized to the test that verifies the gateway_execute.args contract.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 75c60914-0468-4da5-8b92-6a0c73c7a1cd

📥 Commits

Reviewing files that changed from the base of the PR and between 23e3571 and 4eb174e.

📒 Files selected for processing (1)

• src/mcp_server.rs