feat(clients): keep the search envelope and read as an agent

[eldad-caura-ai]

Why

This PR fixes the SDK group from the 2026-10-01 audit: L-173 (from the search and query-cost batch, B33) and all of B35 (L-03, L-93, L-94). All four are in the Python and TypeScript clients' search() and recall(), or in the interviewer that ships with the Python client, so they ship as one commit.

What changes

Both SDKs

• L-173: recall() sends items_alias: false. The server otherwise repeats the result list under items, about half of each response, and both SDKs read memories. Passing items_alias=True (Python) or items_alias: true (TypeScript) still asks for the copy.

• L-94: search() returns a SearchResult (newly exported in both SDKs). It is still a list of Memory (an array in TypeScript), so code that iterates, indexes or compares results is unchanged. It also carries the response envelope, which was dropped before:

  • recall_tracked (recallTracked);
  • diagnostic, which a diagnostic=True search returns;
  • warnings, for example a parameter the server ignored;
  • raw, the whole body.

  An envelope field the server omits reads as None (null).

• L-03: search() and recall() take caller_agent_id (callerAgentId). It lets a tenant-key client read an agent's scope_agent memories. Eldad chose opt-in (2026-10-08): the client's agent_id is never sent as the reader on its own. Asserting it makes the server register the agent if it is new, and hold the read to that agent's fleet and trust level. That would narrow or refuse reads for existing tenant-key clients that set agent_id. Both READMEs explain this.

Python interviewer (L-93)

• On a default server, which submits asynchronously, each window gets accepted with memories_written 0, and the memories are written in the background.
• FileResult counts those windows (windows_accepted). The run summary reports them as "accepted for synthesis in the background" instead of the old "0 memories written". It still reports "memories written" for windows a synchronous server interviewed in-line.
• The README, submit_interview()'s docstring and the runner's protocol notes now describe the async default. The README no longer promises "never a gap": a window whose background synthesis keeps failing is parked for an operator.

Docs: docs/api-surfaces.md notes that both SDKs now send items_alias: false.

Rollout notes

• Compatibility: SearchResult is a list (array) subclass, so existing callers keep working. TypeScript's SearchResult is Memory[] & SearchEnvelope, assignable to Memory[].
• Visible change: recall()'s raw no longer contains items unless items_alias=True is passed.
• Older servers: both request bodies accept unknown keys (extra="allow"). A server that predates items_alias or caller_agent_id ignores them and says so in its warnings.
• Versions: no package versions are bumped here.

Evidence

The tests were pushed before the fixes, so each new case was seen failing first.

• Tests only (4612518):
  • Python (run 37794273352): on 3.9 through 3.13, exactly the 7 new cases failed and 203 passed, and ruff passed.
  • TypeScript (run 37794273398): on Node 18, 20 and 22, exactly the 5 new cases failed and 55 passed, and the prettier check and tsc passed.
• The failures were these:
  • L-173: the body had no items_alias.
  • L-94: 'list' object has no attribute 'recall_tracked', and no envelope fields on the TypeScript array.
  • L-03: Python's search() and recall() had no caller_agent_id parameter, and TypeScript sent callerAgentId verbatim.
  • L-93: FileResult had no windows_accepted, and there was no summary-line function.
• The TypeScript tests read the envelope through a plain record, so they compiled on main and failed at runtime rather than at build time.
• Existing tests changed with the code: the fake interview server in test_interviewer_runner.py can answer accepted, as the default server does.

🤖 Generated with Claude Code

[github-actions]

Claude Code Review — skipped: draft PR

[github-actions]

🤖 Review by Claude Code

Claude Code Review ✅ No issues found.

---

Reviewed by claude-sonnet-5-5 · cost $0.23945374999999997

[eldad-caura-ai]

@erni-a please aprprove