feat(agent-history): add Antigravity CLI (agy) history reader

[dorokuma]

What

Adds an AgentHistoryReader for Antigravity CLI (agy), allowing Shepherd to surface structured transcript history and last assistant messages for agy agents managed through Herdr.

How

• Transcript parsing (AgyHistoryReader):
  • Parses ${HOME}/.gemini/antigravity-cli/brain/<sessionId>/.system_generated/logs/transcript.jsonl.
  • Line mapping: USER_INPUT maps to user role; PLANNER_RESPONSE with text content maps to assistant role.
  • tool_calls in PLANNER_RESPONSE do not synthesize immediate dummy tool results. Instead, tool names are queued into a FIFO list (pendingToolCalls) and sequentially paired with subsequent tool execution log entries (such as LIST_DIRECTORY, RUN_COMMAND, VIEW_FILE, or ERROR_MESSAGE).
  • When pendingToolCalls is empty or generic/unknown log entries are encountered, only known tool execution types (such as RUN_COMMAND, VIEW_FILE, LIST_DIRECTORY, ERROR_MESSAGE, etc.) consume the pending queue or produce tool_result messages; unknown/generic entries are omitted without shifting pendingToolCalls.
  • Tool execution results capture full output, exit codes, and error status (isError), falling back gracefully if no execution result was produced.
  • Skips malformed lines and internal system/ephemeral entry types.
• Fail-closed directory auto-discovery:
  • Discovers candidate transcripts by reading ${HOME}/.gemini/antigravity-cli/conversation_summaries.db (read-only SQLite).
  • Fails closed: if the database is missing, corrupted, or unreadable, or if cwd is null, discovery returns no history (null) rather than guessing an unrelated transcript.
  • Normalizes workspace URIs (handling file:// scheme and trailing slashes) and requires exact cwd path equality (matchesWorkspaceUri), preventing cross-directory mismatches between root, parent, and subdirectories.
• Service & contract integration:
  • Extends AgentHistoryRef source union with "agy-jsonl".
  • Maps agy and antigravity agent/source session refs to "agy-jsonl" in historySourceFromSessionRef.
  • Resolves kind: "agent_session" with session ID or path.
  • Registers AgyHistoryReader in default createAgentHistoryService.
• Documentation:
  • Updated README.md and README.ja.md to list Antigravity among supported agent history sources.

Testing

• 17 new unit tests:
  • Multi-turn conversation parsing with actual user, assistant, and paired tool execution outputs.
  • Tool error detection and isError flag verification across error types and nonzero exit codes.
  • Sequential FIFO matching for multiple tool calls in a single turn.
  • Tool calls without following execution results (omits fake tool results).
  • Filtering of orphan generic/unknown log entries when no tool call is pending while preserving known execution types.
  • Interleaved generic/unknown log entries preserving pending tool call queue FIFO alignment.
  • Structured array content and empty text filtering in responses.
  • Empty file handling, malformed JSONL line skipping, and missing file handling.
  • Session ID transcript path resolution.
  • Agent history service registration and discovery integration.
  • Fail-closed behavior when conversation_summaries.db is missing, unreadable, or corrupted.
  • Fail-closed behavior on null cwd or non-matching cwd.
  • Exact workspace URI normalization and boundary isolation (preventing root vs. child and parent vs. child cross-matches).
• Full test suite: 30 test files, 247 passing tests (pnpm typecheck and pnpm test clean).

[ryonakae]

Thanks for working on Antigravity history support. I verified that the agy agent name and herdr:antigravity_cli session source match Herdr's integration, and this would be a useful addition to Shepherd.

I found a few correctness issues that should be addressed before merging:

1. PLANNER_RESPONSE.tool_calls[].args is currently emitted as a tool_result. These are tool inputs, not execution results. Actual results appear in separate transcript entries such as LIST_DIRECTORY. This can make agent read, lastToolResult, and wake notifications report incorrect information. Please parse actual result entries, or omit tool results when they cannot be represented correctly. Tests should cover actual output, errors, and multiple tool calls.

2. When conversation_summaries.db is missing or unreadable, discovery falls back to the newest transcript across the entire brain directory. Since these transcripts do not contain a cwd, this can attribute a conversation from another workspace to the current agent. Please fail closed in this case: returning no history is preferable to returning another agent's history.

3. Workspace URI matching currently accepts parent/child relationships in both directions and treats / as matching everything. This can mix root and subproject conversations. Please use proper file URI/path normalization and restrict matching to an unambiguous relationship.

Please also update the supported-agent list in README.md and README.ja.md.

The overall feature is worth merging; these are correctness issues rather than a rejection of the approach. I'll be happy to review an updated version.

[dorokuma]

Closing as stale — this work has moved to a separate repository.