Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(antigravity): bound transcript recovery

AkitaOnRails35ec4854eda7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a673e9d..a394cdc4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -113,8 +113,10 @@ version in [`docs/changelog/`](docs/changelog/):
conversation. The native hook now reads each turn's prompts from the
conversation's own transcript (`transcriptPath`, only under
`~/.gemini/<app>/brain/<conversationId>/`, no symlinks out of it, 8 MiB per
- hook) and records them as user prompts, so summaries and handoffs carry
- them. A `Stop` that finished the turn (`NO_TOOL_CALL` or `model_stop`) with
+ hook and a 100 ms filesystem deadline) and records them as user prompts,
+ so summaries and handoffs carry them. A timed-out read leaves its cursor
+ untouched and retries on the next hook. A `Stop` that finished the turn
+ (`NO_TOOL_CALL` or `model_stop`) with
`fullyIdle: true` writes a turn checkpoint, the path OpenCode 2 uses: the
summary page and one handoff are refreshed and the conversation stays open,
so `finalize-session` is no longer needed for normal use. It remains the
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rs
index bdada3e3..7c7ab5a0 100644
--- a/crates/ai-memory-cli/src/commands/hook.rs
+++ b/crates/ai-memory-cli/src/commands/hook.rs
@@ -596,6 +596,12 @@ fn claim_conversation_start(marker: &Path) -> bool {
/// the next read of its conversation start over, and the server's ingest
/// keys drop the prompts it already has.
const MAX_ANTIGRAVITY_TRANSCRIPT_CURSORS: usize = 256;
+/// Cursor files are tiny JSON objects. Refuse a corrupted or replaced file
+/// before it can make a lifecycle hook allocate without a useful bound.
+const MAX_ANTIGRAVITY_TRANSCRIPT_CURSOR_BYTES: u64 = 16 * 1024;
+/// Filesystem work for transcript recovery must not hold up the harness. A
+/// timeout leaves the cursor untouched, so the next hook retries the read.
+const ANTIGRAVITY_TRANSCRIPT_READ_BUDGET: Duration = Duration::from_millis(100);
/// `<data_dir>/hook-state/antigravity-transcripts/<conversationId>.json`.
fn antigravity_transcript_cursor_path(data_dir: &Path, conversation: &str) -> PathBuf {
@@ -606,28 +612,26 @@ fn antigravity_transcript_cursor_path(data_dir: &Path, conversation: &str) -> Pa
}
fn load_antigravity_transcript_cursor(path: &Path) -> ai_memory_hooks::TranscriptCursor {
- fs::read(path)
- .ok()
- .and_then(|bytes| serde_json::from_slice(&bytes).ok())
- .unwrap_or_default()
+ let Some(bytes) = fs::File::open(path).ok().and_then(|file| {
+ let mut bytes = Vec::new();
+ file.take(MAX_ANTIGRAVITY_TRANSCRIPT_CURSOR_BYTES + 1)
+ .read_to_end(&mut bytes)
+ .ok()?;
+ (bytes.len() as u64 <= MAX_ANTIGRAVITY_TRANSCRIPT_CURSOR_BYTES).then_some(bytes)
+ }) else {
+ return ai_memory_hooks::TranscriptCursor::default();
+ };
+ serde_json::from_slice(&bytes).unwrap_or_default()
}
-/// Atomic (tmp + rename) and best effort, with bounded retention: a lost
-/// write only makes the next read repeat prompts the server drops by key.
+/// Atomic (private random temp + fsync + rename + parent fsync) and best
+/// effort, with bounded retention: a lost write only makes the next read
+/// repeat prompts the server drops by key.
fn store_antigravity_transcript_cursor(path: &Path, cursor: &ai_memory_hooks::TranscriptCursor) {
let (Some(dir), Ok(bytes)) = (path.parent(), serde_json::to_vec(cursor)) else {
return;
};
- if fs::create_dir_all(dir).is_err() {
- return;
- }
- let tmp = path.with_extension(format!("json.tmp-{}", std::process::id()));
- let written = fs::File::create(&tmp).and_then(|mut file| {
- std::io::Write::write_all(&mut file, &bytes)?;
- file.sync_all()
- });
- if written.is_err() || fs::rename(&tmp, path).is_err() {
- let _ = fs::remove_file(&tmp);
+ if ai_memory_wiki::write_atomic(path, &bytes).is_err() {
return;
}
let Ok(entries) = fs::read_dir(dir) else {
@@ -635,7 +639,11 @@ fn store_antigravity_transcript_cursor(path: &Path, cursor: &ai_memory_hooks::Tr
};
let mut others = entries
.filter_map(Result::ok)
- .filter(|entry| entry.path() != path)
+ .filter(|entry| {
+ entry.path() != path
+ && entry.path().extension().and_then(|ext| ext.to_str()) == Some("json")
+ && entry.file_type().is_ok_and(|kind| kind.is_file())
+ })
.filter_map(|entry| Some((entry.metadata().ok()?.modified().ok()?, entry.path())))
.collect::<Vec<_>>();
others.sort_by_key(|(modified, _)| std::cmp::Reverse(*modified));
@@ -694,6 +702,20 @@ struct AntigravityPromptEvents {
cursor: ai_memory_hooks::TranscriptCursor,
}
+fn run_before_deadline<T: Send + 'static>(
+ budget: Duration,
+ task: impl FnOnce() -> T + Send + 'static,
+) -> Option<T> {
+ let (sender, receiver) = std::sync::mpsc::sync_channel(1);
+ std::thread::Builder::new()
+ .name("ai-memory-antigravity-transcript".into())
+ .spawn(move || {
+ let _ = sender.send(task());
+ })
+ .ok()?;
+ receiver.recv_timeout(budget).ok()
+}
+
/// The `user-prompt` events for the prompts Antigravity wrote to this
/// conversation's transcript since the last read. Antigravity puts no
/// prompt in any hook payload; `transcriptPath` names the transcript and is
@@ -707,13 +729,21 @@ fn antigravity_transcript_prompt_events(
home: Option<&Path>,
raw: &serde_json::Value,
) -> Option<AntigravityPromptEvents> {
- let conversation = ai_memory_hooks::antigravity_conversation_id(raw)?;
- let transcript = ai_memory_hooks::antigravity_transcript_path(raw, home?)?;
- let cursor_path = antigravity_transcript_cursor_path(data_dir, conversation);
- let read = ai_memory_hooks::read_transcript_prompts(
- &transcript,
- &load_antigravity_transcript_cursor(&cursor_path),
- )?;
+ let conversation = ai_memory_hooks::antigravity_conversation_id(raw)?.to_owned();
+ let declared = raw.get("transcriptPath")?.as_str()?.to_owned();
+ let request = serde_json::json!({
+ "conversationId": conversation.clone(),
+ "transcriptPath": declared,
+ });
+ let home = home?.to_owned();
+ let cursor_path = antigravity_transcript_cursor_path(data_dir, &conversation);
+ let (cursor_path, read) =
+ run_before_deadline(ANTIGRAVITY_TRANSCRIPT_READ_BUDGET, move || {
+ let transcript = ai_memory_hooks::antigravity_transcript_path(&request, &home)?;
+ let cursor = load_antigravity_transcript_cursor(&cursor_path);
+ let read = ai_memory_hooks::read_transcript_prompts(&transcript, &cursor)?;
+ Some((cursor_path, read))
+ })??;
let mut events = Vec::with_capacity(read.prompts.len());
for prompt in &read.prompts {
let mut body = serde_json::Map::new();
@@ -729,7 +759,7 @@ fn antigravity_transcript_prompt_events(
let mut body = serde_json::Value::Object(body);
ai_memory_hooks::cap_lifecycle_body_for_client(&mut body, HookEvent::UserPrompt);
events.push((
- antigravity_prompt_ingest_key(conversation, prompt),
+ antigravity_prompt_ingest_key(&conversation, prompt),
serde_json::to_string(&body).ok()?,
));
}
@@ -6908,6 +6938,17 @@ mod tests {
load_antigravity_transcript_cursor(&path),
ai_memory_hooks::TranscriptCursor::default()
);
+ std::fs::write(
+ &path,
+ vec![0_u8; (MAX_ANTIGRAVITY_TRANSCRIPT_CURSOR_BYTES + 1) as usize],
+ )
+ .unwrap();
+ assert_eq!(
+ load_antigravity_transcript_cursor(&path),
+ ai_memory_hooks::TranscriptCursor::default()
+ );
+ let unrelated = dir.join("keep.lock");
+ std::fs::write(&unrelated, b"not a cursor").unwrap();
for n in 0..MAX_ANTIGRAVITY_TRANSCRIPT_CURSORS + 5 {
store_antigravity_transcript_cursor(
&antigravity_transcript_cursor_path(tmp.path(), &format!("c{n}")),
@@ -6917,6 +6958,7 @@ mod tests {
let names = std::fs::read_dir(&dir)
.unwrap()
.map(|entry| entry.unwrap().file_name().into_string().unwrap())
+ .filter(|name| name.ends_with(".json"))
.collect::<Vec<_>>();
assert!(
names.len() <= MAX_ANTIGRAVITY_TRANSCRIPT_CURSORS,
@@ -6927,6 +6969,24 @@ mod tests {
names.iter().all(|name| name.ends_with(".json")),
"{names:?}"
);
+ assert_eq!(std::fs::read(unrelated).unwrap(), b"not a cursor");
+ assert!(!std::fs::read_dir(&dir).unwrap().any(|entry| {
+ entry
+ .unwrap()
+ .file_name()
+ .to_string_lossy()
+ .contains(".tmp")
+ }));
+ }
+
+ #[test]
+ fn antigravity_transcript_read_deadline_does_not_wait_for_blocked_work() {
+ assert_eq!(run_before_deadline(Duration::from_secs(1), || 42), Some(42));
+
+ let (release, blocked) = std::sync::mpsc::channel::<()>();
+ let result = run_before_deadline(Duration::from_millis(20), move || blocked.recv());
+ drop(release);
+ assert!(result.is_none());
}
#[tokio::test]
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 6827d8e5..0391d8cc 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -14329,7 +14329,13 @@ pub(crate) mod tests {
assert_eq!(handoff.origin.from_agent, AgentKind::AntigravityCli);
assert_eq!(handoff.origin.from_session_id, Some(session));
assert!(
- handoff.content.summary.contains(text),
+ handoff.content.summary.contains(text)
+ || handoff
+ .content
+ .open_questions
+ .iter()
+ .chain(&handoff.content.next_steps)
+ .any(|item| item.contains(text)),
"{:?}",
handoff.content
);
diff --git a/docs/install.md b/docs/install.md
index 1685a90d..de73a1e3 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1395,9 +1395,11 @@ The transcript is read only when `transcriptPath` names the conversation's own
(or the `transcript_full.jsonl` beside it, which the CLI reports), with
`<app>` one of `antigravity`, `antigravity-cli` or `antigravity-ide`. Another
file, another conversation's transcript and a symlinked directory that leads
-out of the conversation are refused. One hook reads at most 8 MiB, and a
-cursor under `<data_dir>/hook-state/antigravity-transcripts/` resumes where
-the previous read stopped. Steps a hook injected are skipped, the text inside
+out of the conversation are refused. One hook reads at most 8 MiB under a
+100 ms filesystem deadline; a timeout leaves the cursor untouched so the next
+hook retries. The bounded cursor under
+`<data_dir>/hook-state/antigravity-transcripts/` resumes where the previous
+read stopped. Steps a hook injected are skipped, the text inside
the CLI's `<USER_REQUEST>` wrapper is kept, and each prompt is capped and
scrubbed like any other before the server sanitizes it again. Its ingest key
comes from the conversation and step, so a repeated read stores it once. The
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index e2887956..ab03d1d8 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -138,7 +138,7 @@ means the boundary is not built yet.
| 26 | Cross-harness native-history continuation stays checkout-scoped and client-local | `ai-memory-store/src/workstream.rs` `prepare_run` selects the newest current native session only when its harness differs from the destination and pins that typed identity on the run before destination linking can change recency; `ai-memory-cli/src/commands/run.rs` validates the returned `NativeSessionIdentity`, resolves only known adapter flavors, requires `native_session_in_checkout`, exports through the bounded read-only adapter, and writes an untrusted-history dossier to a private temporary directory exposed only to the child as `AI_MEMORY_PREVIOUS_SESSION_HISTORY`; the server wire type deliberately has no path/content field and same-harness launches select no source; `ai-memory-hooks/src/router.rs` keeps the server-authored resume directive outside the untrusted-history fence while fencing the transcript evidence itself, and `ai-memory-core/src/routing_snippet.rs` gives installed project instructions the same wrapper-variable-gated fallback | Core `prepare_response_carries_only_previous_native_identity`, `older_prepare_response_defaults_to_no_adoption`, and `snippets_route_managed_continue_to_the_previous_native_history`; store `managed_adoption_stops_after_any_harness_links_the_workstream` (switch control, destination-link recency cannot replace the pinned source, same-harness refusal); hooks `managed_context_points_at_local_history_on_a_harness_switch` (no session id rendered, directive precedes the untrusted fence); CLI `previous_session_history_is_private_local_and_checkout_scoped` (legitimate control, foreign checkout refused, private local file removed with its owner) | STRONG for checkout isolation, prompt-boundary placement, and server path/content privacy. The dossier is a bounded visible-history projection, not raw hidden reasoning; if the source store is absent, remote, unreadable, or over bounds, the child receives only the portable ledger and handoff |
| 27 | Plain-HTTP human authentication stays fail-closed beyond loopback unless the operator supplies the dedicated dangerous override (#1383) | `ai-memory-cli/src/cli.rs` exposes `serve --allow-insecure-human-auth` separately from `--allow-insecure-no-auth`; `serve.rs` `validate_http_exposure` accepts it only when authentication and human mode are both active and the listener is non-loopback with a Non-Secure cookie, while the ordinary unauthenticated guard still runs otherwise. `HttpExposure::InsecureHumanAuthByOverride` gives that path its own unconditional stderr banner and structured warning, naming passwords, API credentials, session cookies, and memory data as plaintext. The default remains refusal, and `secure_cookie=true` or loopback remains the safe path | `serve.rs` `human_auth_non_loopback_requires_secure_cookie_posture` (default refusal, the no-auth override cannot substitute, the dedicated override succeeds, and that override cannot expose a server with no authentication even under inconsistent human-mode input; secure-cookie and loopback controls), `every_unsafe_exposure_produces_an_operator_banner` (the dedicated banner names the flag and session-cookie risk), and `cli.rs` `serve_parses_insecure_transport_overrides` (both dangerous flags remain distinct) | STRONG for the startup boundary. This is an explicit operator acceptance of transport risk, not encryption; authorization, CSRF, rate limits, Host validation, and the unauthenticated exposure refusal are unchanged |
| 27a | Provider credentials stay on the configured origin | `ai-memory-llm/src/redirect.rs` `same_origin_redirects`, set on every provider and embedder client (`anthropic.rs`, `codex.rs`, `copilot.rs`, `embedding.rs`, `gemini.rs`, `google.rs`, `openai.rs`, `openai_oauth.rs`, `opencode.rs`): a redirect is followed only when scheme, host and port match the previous request, with reqwest's ten-hop limit; any other redirect fails the request. reqwest's own guard strips only `Authorization`, cookies and the proxy headers, so `x-api-key`, `x-goog-api-key` and `llm_headers` values depend on this one. The local model download (`local.rs`) carries no credential and keeps the default policy for its CDN redirects; OIDC and CLI login requests refuse every redirect on clients of their own (`oidc.rs`, `auth.rs` `auth_http_client`) | `ai-memory-llm` `tests/suite/redirect_credentials.rs` `gemini_api_key_does_not_follow_a_cross_origin_redirect`, `anthropic_api_key_does_not_follow_a_cross_origin_redirect`, `operator_headers_do_not_follow_a_cross_origin_redirect` (with `Authorization` stripped as the control), `google_embedder_key_does_not_follow_a_cross_origin_redirect`, `a_refused_redirect_says_where_it_pointed`; legitimate control `a_same_origin_redirect_still_reaches_the_provider` (the key follows a path redirect on one origin); each cross-origin test fails with the policy removed | STRONG for the provider and embedder clients in `ai-memory-llm` |
-| 28 | An Antigravity hook reads, and uploads as prompts, only the named conversation's own transcript, within bounds | `ai-memory-hooks/src/antigravity.rs` `antigravity_transcript_path` accepts the payload's `transcriptPath` only when it is absolute, has no `..`, names `transcript.jsonl` or `transcript_full.jsonl`, and its canonical directory equals `canonical(<home>/.gemini/<app>/brain)/<conversationId>/.system_generated/logs` for `<app>` `antigravity`, `antigravity-cli` or `antigravity-ide`, with `conversationId` a plain id (`antigravity_conversation_id`); `read_transcript_prompts` opens only a regular, non-symlink file that is still the same file once open (`open_regular_file`, opened with `O_NOFOLLOW | O_NONBLOCK` so a symlink or FIFO swapped in after the check is refused without blocking, and on Linux only when the opened descriptor's `/proc/self/fd` path is the checked one, so a directory swapped for a symlink after the containment check is refused too), reads at most `MAX_TRANSCRIPT_SCAN_BYTES` per hook and parses lines up to `MAX_TRANSCRIPT_LINE_BYTES`, and returns only `USER_INPUT` steps whose `source` is absent or `USER_EXPLICIT`; `ai-memory-cli/src/commands/hook.rs` `antigravity_transcript_prompt_events` runs inside the spool block, so after the capture allowlist, routing, server-profile and external-capture gates, with the home `run_with_payload` resolved once; each prompt is capped and scrubbed client-side, keyed by conversation and step, and sanitized again by the server (row 7) | `antigravity.rs` `transcript_path_refuses_anything_outside_the_conversations_own_logs` (another conversation's transcript, the same layout outside the home, another file in the logs directory, an unknown app directory, `..`, a traversal or empty id, a relative path, a missing or non-string path; the conversation's own transcript is the control), `transcript_path_refuses_symlinked_directories_that_leave_the_conversation` (a symlinked `.system_generated` and `brain/<id>` refused; a symlinked `~/.gemini` accepted as the control), `transcript_reader_refuses_symlinks_and_special_files` (a symlinked transcript and a directory refused; the same bytes as a regular file are read), `skips_injected_malformed_empty_and_non_prompt_steps`, `a_line_longer_than_the_scan_budget_is_skipped_across_reads`, `one_read_returns_a_bounded_number_of_prompts`; `hook.rs` `antigravity_transcript_reads_are_confined_to_the_conversations_own_logs` (end to end through the native hook: a forged path outside the home, another conversation's transcript and an arbitrary JSONL file under the home spool no prompt; the conversation's own transcript spools one), `antigravity_transcript_prompts_follow_the_capture_allowlist` (a repository the allowlist leaves out is not read) | STRONG on Unix; the symlink cases are `cfg(unix)`, and elsewhere the canonical-directory check still runs; `antigravity.rs` `transcript_reader_refuses_fifos_and_swapped_directories` |
+| 28 | An Antigravity hook reads, and uploads as prompts, only the named conversation's own transcript, within bounds | `ai-memory-hooks/src/antigravity.rs` `antigravity_transcript_path` accepts the payload's `transcriptPath` only when it is absolute, has no `..`, names `transcript.jsonl` or `transcript_full.jsonl`, and its canonical directory equals `canonical(<home>/.gemini/<app>/brain)/<conversationId>/.system_generated/logs` for `<app>` `antigravity`, `antigravity-cli` or `antigravity-ide`, with `conversationId` a plain id (`antigravity_conversation_id`); `read_transcript_prompts` opens only a regular, non-symlink file that is still the same file once open (`open_regular_file`, opened with `O_NOFOLLOW | O_NONBLOCK` so a symlink or FIFO swapped in after the check is refused without blocking, and on Linux only when the opened descriptor's `/proc/self/fd` path is the checked one, so a directory swapped for a symlink after the containment check is refused too), reads at most `MAX_TRANSCRIPT_SCAN_BYTES` per hook and parses lines up to `MAX_TRANSCRIPT_LINE_BYTES`, and returns only `USER_INPUT` steps whose `source` is absent or `USER_EXPLICIT`; `ai-memory-cli/src/commands/hook.rs` `antigravity_transcript_prompt_events` runs inside the spool block, so after the capture allowlist, routing, server-profile and external-capture gates, with the home `run_with_payload` resolved once; its path checks, bounded cursor load and transcript read run behind `ANTIGRAVITY_TRANSCRIPT_READ_BUDGET`, and a timeout advances no cursor so a later hook retries; cursor replacement uses the canonical atomic writer; each prompt is capped and scrubbed client-side, keyed by conversation and step, and sanitized again by the server (row 7) | `antigravity.rs` `transcript_path_refuses_anything_outside_the_conversations_own_logs` (another conversation's transcript, the same layout outside the home, another file in the logs directory, an unknown app directory, `..`, a traversal or empty id, a relative path, a missing or non-string path; the conversation's own transcript is the control), `transcript_path_refuses_symlinked_directories_that_leave_the_conversation` (a symlinked `.system_generated` and `brain/<id>` refused; a symlinked `~/.gemini` accepted as the control), `transcript_reader_refuses_symlinks_and_special_files` (a symlinked transcript and a directory refused; the same bytes as a regular file are read), `skips_injected_malformed_empty_and_non_prompt_steps`, `a_line_longer_than_the_scan_budget_is_skipped_across_reads`, `one_read_returns_a_bounded_number_of_prompts`; `hook.rs` `antigravity_transcript_reads_are_confined_to_the_conversations_own_logs` (end to end through the native hook: a forged path outside the home, another conversation's transcript and an arbitrary JSONL file under the home spool no prompt; the conversation's own transcript spools one), `antigravity_transcript_prompts_follow_the_capture_allowlist` (a repository the allowlist leaves out is not read), `antigravity_transcript_read_deadline_does_not_wait_for_blocked_work`, and `antigravity_transcript_cursor_store_is_atomic_and_bounded` (oversized cursor refused) | STRONG on Linux, including the opened descriptor path. Stable symlink escapes and special files are refused on every platform; without Linux `/proc/self/fd`, a same-user process able to replace an ancestor in the narrow interval between canonicalization and open could redirect the read, which still remains size- and time-bounded. The directory-swap bite test is Linux-only; the other symlink cases are `cfg(unix)` |
### IBM Bob evidence