Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

pa-core/pa-daemon: semantic-edge ledger + model request ids (TS semantic-edges.ts producer port) (#3212)

Sebastian Müllercfe398105ed8
diff --git a/.changes/feat-rust-semantic-edges.md b/.changes/feat-rust-semantic-edges.md
new file mode 100644
index 0000000000..1067e66c40
--- /dev/null
+++ b/.changes/feat-rust-semantic-edges.md
@@ -0,0 +1 @@
+- Each model request now carries a request id header, and each session writes a semantic-edge ledger (request, subagent and compaction events) matching the TS agent.
diff --git a/crates/pa-agent/src/agent_loop/response.rs b/crates/pa-agent/src/agent_loop/response.rs
index dd748121a6..1509ae1ecf 100644
--- a/crates/pa-agent/src/agent_loop/response.rs
+++ b/crates/pa-agent/src/agent_loop/response.rs
@@ -151,6 +151,7 @@ async fn stream_assistant_response_inner(
// composes them per request at the `StreamFn` boundary instead.
on_payload: None,
on_response: None,
+ headers: None,
};
let mut response = race_with_abort(
diff --git a/crates/pa-agent/src/proxy.rs b/crates/pa-agent/src/proxy.rs
index ada0d0605e..293e869437 100644
--- a/crates/pa-agent/src/proxy.rs
+++ b/crates/pa-agent/src/proxy.rs
@@ -229,6 +229,8 @@ struct ProxyRequestOptions {
session_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
service_tier: Option<crate::types::ServiceTier>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ headers: Option<std::collections::BTreeMap<String, String>>,
}
#[derive(serde::Serialize)]
@@ -266,6 +268,7 @@ async fn proxy_run(
},
session_id: options.session_id.clone(),
service_tier: options.service_tier,
+ headers: options.headers.clone(),
};
let body = serde_json::json!({
"model": model,
@@ -1015,6 +1018,7 @@ mod tests {
signal: AbortSignal::never(),
on_payload: None,
on_response: None,
+ headers: None,
}
}
@@ -1246,6 +1250,7 @@ mod tests {
reasoning: ThinkingLevelWire::High,
session_id: Some("session".to_string()),
service_tier: Some(ServiceTier::Flex),
+ headers: Some([("X-ACP-Model-Request-ID".to_string(), "id".to_string())].into()),
};
let value = serde_json::to_value(&options).expect("serialize");
let keys: std::collections::BTreeSet<String> =
@@ -1253,6 +1258,7 @@ mod tests {
assert_eq!(
keys,
[
+ "headers",
"maxTokens",
"reasoning",
"serviceTier",
diff --git a/crates/pa-agent/src/stream.rs b/crates/pa-agent/src/stream.rs
index 4f50a71aba..17f2a039de 100644
--- a/crates/pa-agent/src/stream.rs
+++ b/crates/pa-agent/src/stream.rs
@@ -154,10 +154,10 @@ pub type OnResponseHook = std::sync::Arc<dyn Fn(ProviderResponse, &Model) + Send
/// Stream request options (subset of the TS `SimpleStreamOptions` the loop
/// uses, plus the request hooks the TS options carry). Every option is
/// either serialized into the proxy request (`temperature`, `max_tokens`,
-/// `reasoning`, `session_id`, `service_tier` — see [`crate::proxy`]) or
-/// client-local (`api_key`, `signal`); TS `PROXY_SERIALIZED_OPTIONS` marks
-/// the same classification so a new shared option cannot be silently
-/// dropped by the proxy transport.
+/// `reasoning`, `session_id`, `service_tier`, `headers` — see
+/// [`crate::proxy`]) or client-local (`api_key`, `signal`); TS
+/// `PROXY_SERIALIZED_OPTIONS` marks the same classification so a new
+/// shared option cannot be silently dropped by the proxy transport.
#[derive(Clone)]
pub struct StreamRequestOptions {
pub temperature: Option<f64>,
@@ -177,6 +177,9 @@ pub struct StreamRequestOptions {
/// Response-headers hook (TS `SimpleStreamOptions.onResponse`). Invoked
/// once per request after the response headers arrive.
pub on_response: Option<OnResponseHook>,
+ /// Extra request headers (TS `SimpleStreamOptions.headers`), merged
+ /// over the provider's auth-resolved headers at the adapter seam.
+ pub headers: Option<std::collections::BTreeMap<String, String>>,
}
impl std::fmt::Debug for StreamRequestOptions {
@@ -191,6 +194,7 @@ impl std::fmt::Debug for StreamRequestOptions {
.field("signal", &self.signal)
.field("on_payload", &self.on_payload.is_some())
.field("on_response", &self.on_response.is_some())
+ .field("headers", &self.headers)
.finish()
}
}
@@ -207,6 +211,7 @@ impl Default for StreamRequestOptions {
signal: crate::abort::AbortSignal::never(),
on_payload: None,
on_response: None,
+ headers: None,
}
}
}
diff --git a/crates/pa-cli/src/print_boundary/tests.rs b/crates/pa-cli/src/print_boundary/tests.rs
index b732b33212..1d3e0339d5 100644
--- a/crates/pa-cli/src/print_boundary/tests.rs
+++ b/crates/pa-cli/src/print_boundary/tests.rs
@@ -115,6 +115,7 @@ async fn faux_engine_with_telemetry(
})
.expect("a session manager");
let engine = create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
steering_mode: None,
follow_up_mode: None,
diff --git a/crates/pa-cli/src/print_goal.rs b/crates/pa-cli/src/print_goal.rs
index 257e678915..f66b2c5fb4 100644
--- a/crates/pa-cli/src/print_goal.rs
+++ b/crates/pa-cli/src/print_goal.rs
@@ -896,6 +896,7 @@ mod tests {
let engine = Arc::new(
pa_core::session_engine::engine::create_session(
pa_core::session_engine::engine::SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
telemetry: None,
cwd: dir.path().to_path_buf(),
@@ -1458,6 +1459,7 @@ mod tests {
let engine = Arc::new(
pa_core::session_engine::engine::create_session(
pa_core::session_engine::engine::SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
telemetry: None,
cwd: dir.path().to_path_buf(),
diff --git a/crates/pa-cli/src/print_runtime.rs b/crates/pa-cli/src/print_runtime.rs
index 1902f22188..411e919a17 100644
--- a/crates/pa-cli/src/print_runtime.rs
+++ b/crates/pa-cli/src/print_runtime.rs
@@ -600,9 +600,27 @@ async fn build_headless_engine_with(
.map_err(|error| format!("MCP manager construction failed: {error}"))?;
std::sync::Arc::new(std::sync::Mutex::new(manager))
};
+ // TS print mode records too (`semanticEdgeLedgerPath`): the session
+ // id names the ledger under the session artifact dir; `--no-session`
+ // runs on the in-memory manager (no artifact dir), so the identity is
+ // ledger-less but the request ids still go on the wire.
+ let session_manager = session_manager
+ .unwrap_or_else(|| pa_core::session::manager::SessionManager::in_memory(&config.cwd));
+ let semantic_edges = Some(
+ pa_core::session_engine::semantic_edges::SemanticEdgeIdentity {
+ session_id: session_manager.get_session_id().to_string(),
+ ledger_path: pa_core::session_engine::semantic_edges::semantic_edge_ledger_path(
+ None,
+ session_manager.get_session_artifact_dir().as_deref(),
+ ),
+ parent_session_id: None,
+ spawned_by_request_id: None,
+ },
+ );
let engine = pa_core::session_engine::engine::create_session(
pa_core::session_engine::engine::SessionEngineConfig {
cron_store: None,
+ semantic_edges,
telemetry,
steering_mode,
follow_up_mode,
@@ -617,7 +635,7 @@ async fn build_headless_engine_with(
prompt_guidelines: config.append_system_prompt.clone(),
generic_mcp_servers: vec![],
allow_recursion: None,
- session_manager,
+ session_manager: Some(session_manager),
extra_host_handlers: None,
conversation_log_path: None,
additional_skill_paths: config
@@ -1658,6 +1676,7 @@ async fn build_faux_engine_with(
pa_core::session_engine::engine::SessionEngineConfig {
cron_store: None,
// Faux verification harness: no product telemetry.
+ semantic_edges: None,
steering_mode: None,
follow_up_mode: None,
telemetry: None,
diff --git a/crates/pa-cli/src/print_session_command.rs b/crates/pa-cli/src/print_session_command.rs
index 327bee6247..40bcc82403 100644
--- a/crates/pa-cli/src/print_session_command.rs
+++ b/crates/pa-cli/src/print_session_command.rs
@@ -353,6 +353,7 @@ mod tests {
let engine = Arc::new(
pa_core::session_engine::engine::create_session(
pa_core::session_engine::engine::SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
telemetry: None,
cwd: dir.path().to_path_buf(),
diff --git a/crates/pa-cli/tests/chat_agents_chat_roundtrip_e2e.rs b/crates/pa-cli/tests/chat_agents_chat_roundtrip_e2e.rs
index 34f4e2ea70..43d5598a09 100644
--- a/crates/pa-cli/tests/chat_agents_chat_roundtrip_e2e.rs
+++ b/crates/pa-cli/tests/chat_agents_chat_roundtrip_e2e.rs
@@ -348,6 +348,9 @@ async fn the_roundtrip_reentry_renders_the_same_transcript() {
/// sequence, and the transcript-unchanged sojourn's re-entry still
/// adopts — the re-entry's first draw serves the held packs (the
/// observable the byte-identical frames cannot prove on their own).
+/// The turn is submitted through the settle barrier, so the exit stashes
+/// under the worker's final sequence (the settle update after
+/// `agent_end`).
#[tokio::test]
async fn a_post_turn_sojourn_reentry_still_serves_the_held_packs() {
let _handoff_guard = HANDOFF_E2E_LOCK.lock().await;
@@ -381,8 +384,10 @@ async fn a_post_turn_sojourn_reentry_still_serves_the_held_packs() {
needle: "flow audit clean".to_string(),
timeout_ms: 20_000,
},
- HeadlessStep::Submit("one more turn".to_string()),
- HeadlessStep::WaitIdle { timeout_ms: 30_000 },
+ HeadlessStep::SubmitAndSettle {
+ text: "one more turn".to_string(),
+ timeout_ms: 30_000,
+ },
HeadlessStep::WaitRender {
needle: "the live turn reply".to_string(),
timeout_ms: 20_000,
diff --git a/crates/pa-cli/tests/subagent_panel_nested_count_e2e.rs b/crates/pa-cli/tests/subagent_panel_nested_count_e2e.rs
index 0be8da6580..88b1504be4 100644
--- a/crates/pa-cli/tests/subagent_panel_nested_count_e2e.rs
+++ b/crates/pa-cli/tests/subagent_panel_nested_count_e2e.rs
@@ -237,6 +237,7 @@ fn spawn_request(name: &str, prompt: &str) -> RlmSpawnRequest {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
}
}
diff --git a/crates/pa-core/README.md b/crates/pa-core/README.md
index 92d35d0d92..c249f76779 100644
--- a/crates/pa-core/README.md
+++ b/crates/pa-core/README.md
@@ -74,7 +74,7 @@ only: nothing wires it to a user-facing cloud toggle yet.
No provider HTTP (pa-ai), no loop policy (pa-agent), no daemon supervision (pa-daemon), no TUI (pa-tui). No update coordination (the pa-cli coordinator owns the FSM; the update-flow seam here is the daemon-free support layer: `update::version` (semver/channel policy), `update::install` (the managed install-root layout), `update::release` (the channel manifest fetch), `update::download` (sha256-verified archive download + staging)). The package manager installs sources and resolves resource paths only. No workspace snapshot upload, transport, or remote materialization (staging and verification live here; the cloud attach surface owns the transport when it ships).
## Public API
-`SessionEngine` (message in -> events out), `export_html` (the HTML exporter plus its renderer seam: `tools_section`, `pre_render_custom_tools` + `ToolHtmlRenderer`/`RenderedToolHtml`/`RenderedToolResult`, and `ansi_to_html::ansi_lines_to_html`/`tool_render::trim_rendered_result_lines` for renderer implementers), `ToolRegistry`, kernel manager, settings (`SettingsManager`), packages (`packages::PackageManager` + source types), `platform` (process control, file locking, permissions, shell selection - usable by higher crates, e.g. pa-cli's detached spawn), `session_engine::rlm_host::RlmSubagentHost` (implemented by pa-daemon for supervisor-backed children; the default is no children), `mcp::McpManager` (the session's host-side MCP manager, exposed as `SessionEngine.mcp_manager`: auth gating for built-in integrations, the `mcpServers` setting seam, and the `mcp.*` host-request handlers - `mcp.config`/`mcp.refresh`/optional `mcp.begin_login` - the kernel's generic MCP client resolves through), `mcp::McpManager::connection_roster` + `mcp::McpConnectionEntry` (the `/mcp` view's roster: every resolved integration with its connected state, display kind, transport, and generic-listable flag), `mcp::McpManager::service_catalog_views` + `service_catalog_diagnostics` (the `/mcp` view's resolved service-catalog cards and their diagnostics, answered from local state - the TS `buildServiceCatalogViews` parity; the picker never round-trips the kernel), `mcp::McpManager::api_key_credential_views` + `mcp::API_KEY_CREDENTIALS`/`McpCredentialView` (the `/mcp` view's api-key credential rows - the stored keys the surface manages alongside the connections, e.g. the web-search key - configured from the shared auth store), `models` (the registry and resolver, plus `models::order_for_picker`: the picker-catalog order the composition root applies to its snapshot), `session_engine::provider_adapter` (`switchable_stream_fn`/`ProviderTarget`: the live provider-target slot a host swaps on `set_model`; the adapter bridges the loop's abort into pa-ai's `StreamOptions::signal` cancellation token, so a turn abort cancels the in-flight HTTP fetch at the transport — closed by `ModelStream::close` and the stream's drop), `session_engine::ipython_state` (the post-compaction `ipython_state` kernel-persistence notice: the `CompactionKernelProbe` view of the kernel provisioner the engine wiring binds via `AgentSession::set_kernel_state_probe`, and the notice row that rides `CompactRun` for the surfaces to broadcast). `session_engine::session_commands` (the `/compact`/`/refine`/`/goal`/`/autonomous` executor: the durable echo/result rows with their persistence order - the echo ahead of the command so its own work sees it - the compaction/refinement/goal/autonomous arms, and the post-execution live-context rebuild that keeps the rows in the agent state; hosts own the wire surface), `session_engine::auto_refine_trigger` (the compact-trigger auto-refine machine on `AgentSession`: the arm/discard/increment accessors and `consume_compact_auto_refine`, the shared gate/review/stamp sequence every scheduling surface applies - TS `_compactAutoRefinePending`/`_lastAutoRefineReviewAt`/`_assistantTurnsSinceAutoRefine` plus `_maybeAutoRefine`'s compact arm, the serialized checkpoint's compact step, and dispose's serialized drain, with the surface parameter carrying the one behavioral difference between a boundary and a disposal). `session_engine::goal_boundary` (the goal arms of the natural turn end on `SessionEngine`: the `--goal` construction seed with its next-turn context row - TS `_pendingNextTurnMessages` on `AgentSession` - the usage accounting, the budget-limit steer mint, the natural continuation mint with its slot rollback, and the terminal-error finish; the transports - the print driver's in-loop hook, the ACP settle loop, the daemon worker's queue - drive the one goal driver through these methods). `SessionEngine::expand_skill_submission` + `AgentSession`'s prompt-path expansion (the `/skill:<name>` submission seam, TS `_expandSkillCommand`: `skills::expand_skill_command` builds the `<skill ...>` block over the shared `pa_types::skill_blocks` parse, the accepted-turn row and the admitted user message agree on the expanded text, and the `skill_use_count` session counter counts at the admission). `workspace_snapshot` (`create_workspace_snapshot`: bounded, secret/nested-repo/submodule/symlink-ancestor-excluding capture of a git worktree into an owner-private staging directory, with the caller-chosen `BaselineMode` (HEAD-tree content verified against HEAD's object ids, or explicit external) and a `ConcurrentMutation` error when the worktree changes under the capture; `verify_workspace_snapshot`: offline manifest/blob/baseline integrity check; the `SnapshotManifest`/`WorkspaceSnapshot`/`SnapshotLimits`/`BaselineMode`/`SnapshotError` types). All subsystem internals `pub(crate)`; the engine is the only facade - subsystems must not import each other directly (the package manager consumes the public settings API only).
+`SessionEngine` (message in -> events out), `export_html` (the HTML exporter plus its renderer seam: `tools_section`, `pre_render_custom_tools` + `ToolHtmlRenderer`/`RenderedToolHtml`/`RenderedToolResult`, and `ansi_to_html::ansi_lines_to_html`/`tool_render::trim_rendered_result_lines` for renderer implementers), `ToolRegistry`, kernel manager, settings (`SettingsManager`), packages (`packages::PackageManager` + source types), `platform` (process control, file locking, permissions, shell selection - usable by higher crates, e.g. pa-cli's detached spawn), `session_engine::rlm_host::RlmSubagentHost` (implemented by pa-daemon for supervisor-backed children; the default is no children), `session_engine::semantic_edges` (the TS `semantic-edges.ts` WRITER: `SemanticEdgeRecorder`/`SemanticEdgeIdentity`, `semantic_edge_ledger_path` + `last_committed_request_id`, and the `X-ACP-Model-Request-ID`/`Idempotency-Key` constants — one durable per-session ledger of model-request events, byte-compatible with the TS lines; the fold and any publishing stay downstream), `mcp::McpManager` (the session's host-side MCP manager, exposed as `SessionEngine.mcp_manager`: auth gating for built-in integrations, the `mcpServers` setting seam, and the `mcp.*` host-request handlers - `mcp.config`/`mcp.refresh`/optional `mcp.begin_login` - the kernel's generic MCP client resolves through), `mcp::McpManager::connection_roster` + `mcp::McpConnectionEntry` (the `/mcp` view's roster: every resolved integration with its connected state, display kind, transport, and generic-listable flag), `mcp::McpManager::service_catalog_views` + `service_catalog_diagnostics` (the `/mcp` view's resolved service-catalog cards and their diagnostics, answered from local state - the TS `buildServiceCatalogViews` parity; the picker never round-trips the kernel), `mcp::McpManager::api_key_credential_views` + `mcp::API_KEY_CREDENTIALS`/`McpCredentialView` (the `/mcp` view's api-key credential rows - the stored keys the surface manages alongside the connections, e.g. the web-search key - configured from the shared auth store), `models` (the registry and resolver, plus `models::order_for_picker`: the picker-catalog order the composition root applies to its snapshot), `session_engine::provider_adapter` (`switchable_stream_fn`/`ProviderTarget`: the live provider-target slot a host swaps on `set_model`; the adapter bridges the loop's abort into pa-ai's `StreamOptions::signal` cancellation token, so a turn abort cancels the in-flight HTTP fetch at the transport — closed by `ModelStream::close` and the stream's drop), `session_engine::ipython_state` (the post-compaction `ipython_state` kernel-persistence notice: the `CompactionKernelProbe` view of the kernel provisioner the engine wiring binds via `AgentSession::set_kernel_state_probe`, and the notice row that rides `CompactRun` for the surfaces to broadcast). `session_engine::session_commands` (the `/compact`/`/refine`/`/goal`/`/autonomous` executor: the durable echo/result rows with their persistence order - the echo ahead of the command so its own work sees it - the compaction/refinement/goal/autonomous arms, and the post-execution live-context rebuild that keeps the rows in the agent state; hosts own the wire surface), `session_engine::auto_refine_trigger` (the compact-trigger auto-refine machine on `AgentSession`: the arm/discard/increment accessors and `consume_compact_auto_refine`, the shared gate/review/stamp sequence every scheduling surface applies - TS `_compactAutoRefinePending`/`_lastAutoRefineReviewAt`/`_assistantTurnsSinceAutoRefine` plus `_maybeAutoRefine`'s compact arm, the serialized checkpoint's compact step, and dispose's serialized drain, with the surface parameter carrying the one behavioral difference between a boundary and a disposal). `session_engine::goal_boundary` (the goal arms of the natural turn end on `SessionEngine`: the `--goal` construction seed with its next-turn context row - TS `_pendingNextTurnMessages` on `AgentSession` - the usage accounting, the budget-limit steer mint, the natural continuation mint with its slot rollback, and the terminal-error finish; the transports - the print driver's in-loop hook, the ACP settle loop, the daemon worker's queue - drive the one goal driver through these methods). `SessionEngine::expand_skill_submission` + `AgentSession`'s prompt-path expansion (the `/skill:<name>` submission seam, TS `_expandSkillCommand`: `skills::expand_skill_command` builds the `<skill ...>` block over the shared `pa_types::skill_blocks` parse, the accepted-turn row and the admitted user message agree on the expanded text, and the `skill_use_count` session counter counts at the admission). `workspace_snapshot` (`create_workspace_snapshot`: bounded, secret/nested-repo/submodule/symlink-ancestor-excluding capture of a git worktree into an owner-private staging directory, with the caller-chosen `BaselineMode` (HEAD-tree content verified against HEAD's object ids, or explicit external) and a `ConcurrentMutation` error when the worktree changes under the capture; `verify_workspace_snapshot`: offline manifest/blob/baseline integrity check; the `SnapshotManifest`/`WorkspaceSnapshot`/`SnapshotLimits`/`BaselineMode`/`SnapshotError` types). All subsystem internals `pub(crate)`; the engine is the only facade - subsystems must not import each other directly (the package manager consumes the public settings API only).
## Depends on
pa-types, pa-ai, pa-agent (one-way).
diff --git a/crates/pa-core/src/session_engine/compact_session.rs b/crates/pa-core/src/session_engine/compact_session.rs
index 67df9f41af..68120b0c1c 100644
--- a/crates/pa-core/src/session_engine/compact_session.rs
+++ b/crates/pa-core/src/session_engine/compact_session.rs
@@ -92,6 +92,11 @@ pub struct CompactOptions<'a> {
/// one-shot completion — the summarizer call itself is identical
/// either way; only the stream consumption differs.
pub summary_delta: Option<SummaryDeltaSink>,
+ /// The session's semantic-edge recorder (TS `semanticCompaction` in
+ /// `_performCompaction`): each summary wire call carries its own
+ /// request id, and the compaction's terminal event lands before the
+ /// compaction entry persists. `None` records nothing.
+ pub semantic_edges: Option<std::sync::Arc<super::semantic_edges::SemanticEdgeRecorder>>,
}
/// The model-visible message produced by a session entry (summarizer input).
@@ -183,6 +188,12 @@ pub async fn execute_compaction(
Ok(preparation) => preparation,
Err(skip) => return Ok(CompactOutcome::Skipped(skip.user_message())),
};
+ // TS `beginCompaction` after the preparation resolved: a skipped
+ // compaction makes no events (the begin comes after the skip throw).
+ let mut semantic_compaction = options
+ .semantic_edges
+ .as_ref()
+ .map(|recorder| recorder.begin_compaction(options.abort));
let cut = preparation.cut;
let previous_summary = preparation.previous_summary;
let recent_state_anchor = preparation.recent_state_anchor;
@@ -337,14 +348,23 @@ pub async fn execute_compaction(
recent_state_anchor.as_deref(),
options.settings.reserve_tokens,
);
- complete_summary_call(
- &model,
- api_key.clone(),
+ // Each summary wire call carries its own request id under the
+ // compaction's guard (TS `summaryCall`): the id's headers merge
+ // over the routed model's.
+ super::semantic_edges::summary_slice_call(
+ semantic_compaction.as_ref(),
summary_headers.clone(),
- history_max_tokens,
- request,
- options.summary_delta.clone(),
- "Summarization failed",
+ |headers| {
+ complete_summary_call(
+ &model,
+ api_key.clone(),
+ headers,
+ history_max_tokens,
+ request,
+ options.summary_delta.clone(),
+ "Summarization failed",
+ )
+ },
)
.await
};
@@ -353,21 +373,27 @@ pub async fn execute_compaction(
return Ok::<Option<SummarySlice>, anyhow::Error>(None);
}
let request = build_turn_prefix_request(&turn_prefix_messages);
- let slice = complete_summary_call(
- &model,
- api_key.clone(),
+ let slice = super::semantic_edges::summary_slice_call(
+ semantic_compaction.as_ref(),
summary_headers.clone(),
- turn_prefix_max_tokens,
- request,
- // The turn-prefix call never streams live: the split join
- // runs it concurrently with the history call, and its chunks
- // interleaved into the live sink would land out of the
- // final order (the committed summary is history, split
- // marker, prefix). The completed prefix flushes through the
- // sink after the join, so the live block converges to the
- // exact committed summary.
- None,
- "Turn prefix summarization failed",
+ |headers| {
+ complete_summary_call(
+ &model,
+ api_key.clone(),
+ headers,
+ turn_prefix_max_tokens,
+ request,
+ // The turn-prefix call never streams live: the split join
+ // runs it concurrently with the history call, and its chunks
+ // interleaved into the live sink would land out of the
+ // final order (the committed summary is history, split
+ // marker, prefix). The completed prefix flushes through the
+ // sink after the join, so the live block converges to the
+ // exact committed summary.
+ None,
+ "Turn prefix summarization failed",
+ )
+ },
)
.await?;
Ok(Some(slice))
@@ -465,6 +491,12 @@ pub async fn execute_compaction(
harness_digest,
harness_state_fingerprint,
);
+ // Ledger before effect (TS: `compactionRecorded` and the terminal
+ // event land before `appendCompaction`): a failed persist still
+ // leaves a completed compaction on the ledger, exactly like TS.
+ if let Some(compaction) = semantic_compaction.as_mut() {
+ compaction.commit();
+ }
// TS `appendCompaction` persists the full record: `details`,
// `fromHook`, `customInstructions`, `usage`, and the `harnessDigest`
// snapshot ride on the durable row alongside the summary, boundary,
diff --git a/crates/pa-core/src/session_engine/compact_session/tests/auxiliary_model.rs b/crates/pa-core/src/session_engine/compact_session/tests/auxiliary_model.rs
index d675c0b9f8..6831db0f30 100644
--- a/crates/pa-core/src/session_engine/compact_session/tests/auxiliary_model.rs
+++ b/crates/pa-core/src/session_engine/compact_session/tests/auxiliary_model.rs
@@ -62,6 +62,7 @@ async fn compaction_auxiliary_selector_equal_to_the_session_model_runs_on_the_se
abort: None,
harness_digest: None,
auxiliary: Some(&aux),
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -110,6 +111,7 @@ async fn compaction_auxiliary_selector_unusable_falls_back_to_the_session_model(
abort: None,
harness_digest: None,
auxiliary: Some(&aux),
+ semantic_edges: None,
summary_delta: None,
},
)
diff --git a/crates/pa-core/src/session_engine/compact_session/tests/execute_compaction.rs b/crates/pa-core/src/session_engine/compact_session/tests/execute_compaction.rs
index 7cc386600b..b60a3f139a 100644
--- a/crates/pa-core/src/session_engine/compact_session/tests/execute_compaction.rs
+++ b/crates/pa-core/src/session_engine/compact_session/tests/execute_compaction.rs
@@ -24,6 +24,7 @@ async fn execute_compaction_persists_and_rebuilds() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -113,6 +114,7 @@ async fn rebuilt_live_context_prevents_repeat_auto_compaction_until_new_usage()
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -201,6 +203,7 @@ async fn execute_compaction_streams_summary_deltas_to_the_sink() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: Some(sink),
},
)
@@ -310,6 +313,7 @@ async fn split_turn_compaction_streams_in_final_order_and_converges() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: Some(sink),
},
)
@@ -434,6 +438,7 @@ async fn execute_compaction_attaches_harness_digest_snapshot() {
abort: None,
harness_digest: Some(inputs),
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -548,6 +553,7 @@ async fn execute_compaction_fails_on_an_error_summarizer_response() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -588,6 +594,7 @@ async fn durable_compaction_row_carries_the_ts_record() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
diff --git a/crates/pa-core/src/session_engine/compact_session/tests/second_compaction.rs b/crates/pa-core/src/session_engine/compact_session/tests/second_compaction.rs
index b4d62c7a1f..92eddd69ad 100644
--- a/crates/pa-core/src/session_engine/compact_session/tests/second_compaction.rs
+++ b/crates/pa-core/src/session_engine/compact_session/tests/second_compaction.rs
@@ -67,6 +67,7 @@ async fn second_compaction_updates_the_prior_summary_over_new_history() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -95,6 +96,7 @@ async fn second_compaction_updates_the_prior_summary_over_new_history() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -232,6 +234,7 @@ async fn second_compaction_request_carries_the_anchor_and_strips_file_blocks() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -293,6 +296,7 @@ async fn second_compaction_request_carries_the_anchor_and_strips_file_blocks() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -408,6 +412,7 @@ async fn second_compaction_split_turn_history_updates_prefix_does_not() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -442,6 +447,7 @@ async fn second_compaction_split_turn_history_updates_prefix_does_not() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
diff --git a/crates/pa-core/src/session_engine/compact_session/tests/skip_guards.rs b/crates/pa-core/src/session_engine/compact_session/tests/skip_guards.rs
index 5a0b206bfa..ffa2847b82 100644
--- a/crates/pa-core/src/session_engine/compact_session/tests/skip_guards.rs
+++ b/crates/pa-core/src/session_engine/compact_session/tests/skip_guards.rs
@@ -28,6 +28,7 @@ async fn execute_compaction_with_pre_aborted_signal_never_runs_the_summarizer()
abort: Some(&signal),
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -83,6 +84,7 @@ async fn execute_compaction_with_late_abort_cancels_before_the_commit() {
abort: Some(&signal),
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -118,6 +120,7 @@ async fn execute_compaction_skips_short_sessions() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -161,6 +164,7 @@ async fn execute_compaction_skips_when_already_compacted() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
diff --git a/crates/pa-core/src/session_engine/compact_session/tests/split_turn.rs b/crates/pa-core/src/session_engine/compact_session/tests/split_turn.rs
index 344c83d5f9..638b3f942c 100644
--- a/crates/pa-core/src/session_engine/compact_session/tests/split_turn.rs
+++ b/crates/pa-core/src/session_engine/compact_session/tests/split_turn.rs
@@ -4,6 +4,13 @@
//! no-history prefix-only arm.
use super::*;
+use std::sync::Arc;
+
+use crate::session_engine::semantic_edges::{
+ CompactionStatus, SemanticEdgeIdentity, SemanticEdgeLedgerEvent as LedgerEvent,
+ SemanticEdgeRecorder, SEMANTIC_EDGES_LEDGER_FILENAME,
+};
+
/// A turn-spanning cut is a split turn: the compaction runs TWO
/// summarizer calls — the history checkpoint call and the turn-prefix
/// call under its own instruction — and the merged summary carries the
@@ -106,6 +113,7 @@ async fn split_turn_compaction_runs_two_summarizer_calls_and_merges_the_turn_con
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -279,6 +287,7 @@ async fn injected_custom_turn_cuts_whole_turns_the_double_row_splits() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -336,6 +345,7 @@ async fn injected_custom_turn_cuts_whole_turns_the_double_row_splits() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -454,6 +464,7 @@ async fn split_turn_without_history_makes_only_the_prefix_call() {
abort: None,
harness_digest: None,
auxiliary: None,
+ semantic_edges: None,
summary_delta: None,
},
)
@@ -496,3 +507,280 @@ async fn split_turn_without_history_makes_only_the_prefix_call() {
);
registration.unregister();
}
+
+/// One recorder over a ledger in `dir` (the semantic-edge tests' fixture).
+fn semantic_fixture(dir: &std::path::Path) -> (SemanticEdgeIdentity, Arc<SemanticEdgeRecorder>) {
+ let identity = SemanticEdgeIdentity {
+ session_id: "compact-session".to_string(),
+ ledger_path: Some(dir.join(SEMANTIC_EDGES_LEDGER_FILENAME)),
+ parent_session_id: None,
+ spawned_by_request_id: None,
+ };
+ let recorder = Arc::new(SemanticEdgeRecorder::open(identity.clone()));
+ (identity, recorder)
+}
+
+fn ledger_events(identity: &SemanticEdgeIdentity) -> Vec<LedgerEvent> {
+ let contents = std::fs::read_to_string(identity.ledger_path.as_ref().unwrap()).unwrap();
+ contents
+ .lines()
+ .filter(|line| !line.is_empty())
+ .map(|line| serde_json::from_str(line).unwrap())
+ .collect()
+}
+
+fn begun_compaction_id(events: &[LedgerEvent]) -> String {
+ events
+ .iter()
+ .find_map(|event| match event {
+ LedgerEvent::CompactionBegun { compaction_id, .. } => Some(compaction_id.clone()),
+ _ => None,
+ })
+ .expect("the compaction began")
+}
+
+/// The split-turn compaction's two summary slices each carry their own
+/// request id under one compaction — on the ledger AND on the wire (the
+/// summary requests' `X-ACP-Model-Request-ID`/`Idempotency-Key` pair) —
+/// and both commit before the compaction's `completed` event (TS
+/// `summaryCall` + `compactionRecorded`: the ledger lands before the
+/// compaction entry).
+#[tokio::test]
+async fn a_split_turn_compaction_commits_both_summary_slices_before_its_entry() {
+ let registration = faux_registration();
+ let model = registration.get_model();
+ let tmp = tempfile::tempdir().unwrap();
+ let mut session = SessionManager::in_memory(tmp.path());
+ let user = |text: &str| {
+ AgentMessage::User(pa_types::ai::UserMessage {
+ content: UserContent::Text(text.to_string()),
+ timestamp: 0,
+ rest: serde_json::Map::default(),
+ })
+ };
+ let reply = |text: &str| {
+ AgentMessage::Assistant(AssistantMessage {
+ content: vec![pa_types::ai::AssistantContentBlock::Text(
+ pa_types::ai::TextContent {
+ text: text.to_string(),
+ text_signature: None,
+ rest: serde_json::Map::default(),
+ },
+ )],
+ api: "faux".to_string(),
+ provider: "faux".to_string(),
+ model: "compact-m".to_string(),
+ response_model: None,
+ response_id: None,
+ diagnostics: None,
+ usage: pa_types::ai::Usage::default(),
+ stop_reason: pa_types::ai::StopReason::Stop,
+ stop_reason_raw: None,
+ error_message: None,
+ timestamp: 0,
+ rest: serde_json::Map::default(),
+ })
+ };
+ session.append_message(user("turn one")).unwrap();
+ session.append_message(reply("reply one")).unwrap();
+ session
+ .append_message(user(&format!("big turn {}", "x".repeat(4_000))))
+ .unwrap();
+ session
+ .append_message(reply(&format!("reply {}", "y".repeat(4_000))))
+ .unwrap();
+ let (cut, _) = compute_cut(&session, 10);
+ assert!(cut.is_split_turn, "the cut spans the big turn");
+ let (identity, recorder) = semantic_fixture(tmp.path());
+ // Two scripted summaries; each factory call records its request's
+ // headers, so the wire pair is captured regardless of issue order.
+ let seen_headers: Arc<std::sync::Mutex<Vec<std::collections::HashMap<String, String>>>> =
+ Arc::default();
+ let make_step = |response: &'static str| {
+ let seen_headers = seen_headers.clone();
+ pa_ai::faux::FauxResponseStep::Factory(Arc::new(
+ move |_context: &pa_types::ai::Context,
+ options: Option<&pa_ai::types::StreamOptions>,
+ _call: u64,
+ _model: &pa_types::ai::Model| {
+ seen_headers.lock().unwrap().push(
+ options
+ .and_then(|options| options.headers.clone())
+ .unwrap_or_default(),
+ );
+ Ok(pa_ai::faux::faux_assistant_text_message(
+ response,
+ pa_ai::faux::FauxAssistantMessageOptions::default(),
+ ))
+ },
+ ))
+ };
+ registration.set_responses(vec![
+ make_step("the history summary"),
+ make_step("the turn prefix summary"),
+ ]);
+ let outcome = execute_compaction(
+ &mut session,
+ CompactOptions {
+ model,
+ api_key: None,
+ custom_instructions: None,
+ settings: super::super::compaction::CompactionSettings {
+ keep_recent_tokens: 10,
+ ..Default::default()
+ },
+ abort: None,
+ harness_digest: None,
+ auxiliary: None,
+ semantic_edges: Some(Arc::clone(&recorder)),
+ summary_delta: None,
+ },
+ )
+ .await
+ .unwrap();
+ assert!(matches!(outcome, CompactOutcome::Ran(_)));
+ // The two slices run concurrently, so their started/finished pairs
+ // interleave; the order that is deterministic is the frame: the
+ // registration, one compaction, and its `completed` event last.
+ let events = ledger_events(&identity);
+ assert_eq!(
+ events.first(),
+ Some(&LedgerEvent::SessionRegistered {
+ session_id: "compact-session".to_string(),
+ parent_session_id: None,
+ spawned_by_request_id: None,
+ })
+ );
+ let compaction_id = begun_compaction_id(&events);
+ let mut slice_ids = Vec::new();
+ for event in &events {
+ if let LedgerEvent::RequestStarted {
+ request_id,
+ compaction_id: started_compaction,
+ ..
+ } = event
+ {
+ assert_eq!(started_compaction.as_deref(), Some(compaction_id.as_str()));
+ slice_ids.push(request_id.clone());
+ }
+ }
+ assert_eq!(slice_ids.len(), 2, "both split-turn slices started");
+ // The wire pair: each summary request carried its slice's id on both
+ // headers, even though the faux target resolves no headers of its own.
+ let header_sets = seen_headers.lock().unwrap().clone();
+ assert_eq!(header_sets.len(), 2);
+ for headers in &header_sets {
+ let id = headers
+ .get("X-ACP-Model-Request-ID")
+ .expect("the summary request carries the request id");
+ assert_eq!(headers.get("Idempotency-Key"), Some(id));
+ assert!(slice_ids.contains(id), "the wire id is a ledger slice id");
+ }
+ let finished: Vec<_> = events
+ .iter()
+ .filter_map(|event| match event {
+ LedgerEvent::RequestFinished { request_id } => Some(request_id.clone()),
+ _ => None,
+ })
+ .collect();
+ assert_eq!(finished.len(), 2, "both slices committed");
+ assert!(slice_ids.iter().all(|id| finished.contains(id)));
+ assert_eq!(
+ events.last(),
+ Some(&LedgerEvent::CompactionFinished {
+ compaction_id,
+ status: CompactionStatus::Completed,
+ })
+ );
+ registration.unregister();
+}
+
+/// An aborted compaction fails its succeeded-but-uncommitted slice and
+/// records `cancelled` (TS's catch: the abort settles the compaction, and
+/// no summary request stays committed for the next turn to attach to).
+#[tokio::test]
+async fn an_aborted_compaction_fails_its_slices_and_records_cancelled() {
+ let registration = faux_registration();
+ let model = registration.get_model();
+ // The delayed response resolves after the abort lands, so the slice
+ // succeeded but never committed when the abort cancels the run.
+ registration.set_responses(vec![pa_ai::faux::FauxResponseStep::Delayed {
+ message: pa_ai::faux::faux_assistant_text_message(
+ "## Goal\nsummarized goal",
+ pa_ai::faux::FauxAssistantMessageOptions::default(),
+ ),
+ delay_ms: 200,
+ }]);
+ let controller = pa_agent::abort::AbortController::new();
+ let signal = controller.signal();
+ let aborter = {
+ let controller = controller.clone();
+ tokio::spawn(async move {
+ tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+ controller.abort();
+ })
+ };
+ let tmp = tempfile::tempdir().unwrap();
+ let mut session = session_with_turns(tmp.path(), 3);
+ let (identity, recorder) = semantic_fixture(tmp.path());
+ let error = execute_compaction(
+ &mut session,
+ CompactOptions {
+ model,
+ api_key: None,
+ custom_instructions: None,
+ settings: super::super::compaction::CompactionSettings {
+ keep_recent_tokens: 20,
+ ..Default::default()
+ },
+ abort: Some(&signal),
+ harness_digest: None,
+ auxiliary: None,
+ semantic_edges: Some(Arc::clone(&recorder)),
+ summary_delta: None,
+ },
+ )
+ .await
+ .unwrap_err();
+ aborter.await.unwrap();
+ assert!(pa_agent::abort::is_abort_error(&error), "{error:#}");
+ let events = ledger_events(&identity);
+ let compaction_id = begun_compaction_id(&events);
+ let slice_id = events
+ .iter()
+ .find_map(|event| match event {
+ LedgerEvent::RequestStarted { request_id, .. } => Some(request_id.clone()),
+ _ => None,
+ })
+ .expect("the slice started");
+ // The succeeded slice was failed by the abort settle, and the
+ // compaction recorded `cancelled` — deterministic: the single slice
+ // runs alone, so the whole sequence is pinned.
+ assert_eq!(
+ events,
+ vec![
+ LedgerEvent::SessionRegistered {
+ session_id: "compact-session".to_string(),
+ parent_session_id: None,
+ spawned_by_request_id: None,
+ },
+ LedgerEvent::CompactionBegun {
+ compaction_id: compaction_id.clone(),
+ session_id: "compact-session".to_string(),
+ },
+ LedgerEvent::RequestStarted {
+ request_id: slice_id.clone(),
+ session_id: "compact-session".to_string(),
+ compaction_id: Some(compaction_id.clone()),
+ },
+ LedgerEvent::RequestFailed {
+ request_id: slice_id,
+ },
+ LedgerEvent::CompactionFinished {
+ compaction_id,
+ status: CompactionStatus::Cancelled,
+ },
+ ]
+ );
+ registration.unregister();
+}
diff --git a/crates/pa-core/src/session_engine/compaction_arms.rs b/crates/pa-core/src/session_engine/compaction_arms.rs
index 4ca830de35..545c008437 100644
--- a/crates/pa-core/src/session_engine/compaction_arms.rs
+++ b/crates/pa-core/src/session_engine/compaction_arms.rs
@@ -226,6 +226,7 @@ impl AgentSession {
harness_digest: digest_inputs,
auxiliary: self.auxiliary_model.as_ref(),
summary_delta,
+ semantic_edges: self.semantic_edges(),
},
)
.await?
diff --git a/crates/pa-core/src/session_engine/engine.rs b/crates/pa-core/src/session_engine/engine.rs
index ea07196afb..2c5d7502c1 100644
--- a/crates/pa-core/src/session_engine/engine.rs
+++ b/crates/pa-core/src/session_engine/engine.rs
@@ -117,6 +117,12 @@ pub struct SessionEngineConfig {
/// the daemon worker stays `None` because its turn dispatch owns
/// routing (its queued lanes re-dispatch every batch).
pub image_model_router: Option<super::image_model_routing::ImageModelRouter>,
+ /// The session's semantic-edge identity (TS
+ /// `semanticEdgeLedgerPath` + `semanticParentSessionId` +
+ /// `semanticSpawnedByRequestId`): the recorder's ledger location and
+ /// spawn provenance. `None` keeps the session off the ledger (no
+ /// request ids on the wire).
+ pub semantic_edges: Option<super::semantic_edges::SemanticEdgeIdentity>,
}
/// An assembled, running session.
@@ -616,6 +622,25 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
&config.agent_dir,
)),
);
+ // Semantic edges (TS `semantic-edges.ts`): the recorder opens this
+ // session's request-id ledger, and its stream wrapper goes OUTERMOST
+ // over the timing-instrumented fn (TS `sdk.ts` instruments first, the
+ // `AgentSession` constructor wraps semantic edges over it). The side
+ // question keeps the pre-semantic fn, so its calls carry no id.
+ let timing_stream_fn = super::request_timing::instrument_stream_fn(
+ std::sync::Arc::clone(&request_timing_wiring),
+ stream_fn,
+ );
+ let side_question_stream_fn = std::sync::Arc::clone(&timing_stream_fn);
+ let semantic_recorder = config.semantic_edges.take().map(|identity| {
+ std::sync::Arc::new(super::semantic_edges::SemanticEdgeRecorder::open(identity))
+ });
+ let agent_stream_fn = match &semantic_recorder {
+ Some(recorder) => {
+ super::semantic_edges::wrap_stream_fn(std::sync::Arc::clone(recorder), timing_stream_fn)
+ }
+ None => timing_stream_fn,
+ };
let agent = Agent::new(AgentOptions {
initial_state: AgentInitialState {
system_prompt: Some(system_prompt.clone()),
@@ -624,10 +649,7 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
tools: Some(tools),
messages: initial_messages,
},
- stream_fn: Some(super::request_timing::instrument_stream_fn(
- std::sync::Arc::clone(&request_timing_wiring),
- stream_fn,
- )),
+ stream_fn: Some(agent_stream_fn),
// The session conversion rules apply at the loop's LLM boundary
// (TS `convertToLlm`): bookkeeping custom rows drop, everything
// else (the harness digest included) becomes a user turn.
@@ -666,6 +688,19 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
});
let agent = Arc::new(agent);
+ // TS `_startRlmChildRun`'s spawn anchor: the `rlm.spawn` host handler
+ // names the parent's in-flight turn through this weak seam (the
+ // bridge is built before the agent exists, and a strong edge would
+ // cycle the bridge -> agent -> kernel -> bridge graph).
+ if let Some(recorder) = &semantic_recorder {
+ let _ = wiring
+ .rlm
+ .semantic_spawn
+ .set(super::rlm_host::SemanticSpawnAnchor {
+ agent: Arc::downgrade(&agent),
+ recorder: std::sync::Arc::clone(recorder),
+ });
+ }
let telemetry_agent = std::sync::Arc::clone(&agent);
let mut session = AgentSession::from_session_arc(
agent.clone(),
@@ -721,6 +756,11 @@ pub async fn create_session(mut config: SessionEngineConfig) -> anyhow::Result<S
// The embedding's image-model routing seam (the headless surfaces
// install theirs; the daemon worker's turn dispatch owns routing).
session.set_image_model_router(config.image_model_router.clone());
+ // The semantic-edge handoff: the daemon's child registry and retry
+ // park read the recorder; the side question keeps the pre-semantic
+ // fn so its calls carry no id.
+ session.set_semantic_edges(semantic_recorder);
+ session.set_side_question_stream_fn(side_question_stream_fn);
// The armed image route never outlives the run that armed it (TS
// `_clearModelOverrideWhenIdle`: the override drops once the turn is
// idle, so a picker switch between turns is live immediately — the
diff --git a/crates/pa-core/src/session_engine/engine/tests.rs b/crates/pa-core/src/session_engine/engine/tests.rs
index f02d9f732f..c9bfb24223 100644
--- a/crates/pa-core/src/session_engine/engine/tests.rs
+++ b/crates/pa-core/src/session_engine/engine/tests.rs
@@ -55,6 +55,7 @@ async fn engine_runs_tool_loop_and_persists() {
let cwd = tmp.path().join("project");
std::fs::create_dir_all(&cwd).unwrap();
let engine = create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
@@ -154,6 +155,7 @@ async fn spawned_child_prompt_stamps_its_depth() {
let cwd = tmp.path().join("project");
std::fs::create_dir_all(&cwd).unwrap();
let engine = create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
@@ -220,6 +222,7 @@ async fn oauth_creds_unlock_generic_mcp_gating_in_new_sessions() {
stream_fn: pa_agent::stream::StreamFn,
) -> SessionEngineConfig {
SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
diff --git a/crates/pa-core/src/session_engine/mod.rs b/crates/pa-core/src/session_engine/mod.rs
index ee987e4955..7b121a73c6 100644
--- a/crates/pa-core/src/session_engine/mod.rs
+++ b/crates/pa-core/src/session_engine/mod.rs
@@ -38,6 +38,7 @@ pub mod rlm_notices;
pub mod rlm_usage;
pub mod runtime;
pub mod runtime_wiring;
+pub mod semantic_edges;
pub mod session_commands;
pub mod session_events;
pub mod side_question;
@@ -204,6 +205,17 @@ pub struct AgentSession {
/// summarizer completion — no deltas, no broadcast, no behavior
/// change.
compaction_summary_sink: std::sync::Mutex<Option<compaction_exec::SummaryDeltaSink>>,
+ /// The session's semantic-edge recorder (TS
+ /// `AgentSession._semanticEdges`): `None` in sessions the engine
+ /// built without a semantic identity (verification harnesses
+ /// building the loop directly).
+ semantic_edges: std::sync::Mutex<Option<std::sync::Arc<semantic_edges::SemanticEdgeRecorder>>>,
+ /// TS `unwrapSemanticEdgeStreamFn(streamFn)`: the timing-instrumented,
+ /// pre-semantic stream fn calls outside session history run on (a side
+ /// question carries no request id). `None` until the engine wires it;
+ /// a side question on an unwired session fails with the model-selection
+ /// error (no fallback to the agent's id-carrying fn).
+ side_question_stream_fn: std::sync::Mutex<Option<pa_agent::stream::StreamFn>>,
/// The session's agent dir (the settings root): the refine flow
/// resolves the `factory.enabled` opt-in from its settings.json on
/// every run, immediately before the plan applies, mirroring the
@@ -277,6 +289,8 @@ impl AgentSession {
skill_telemetry: None,
image_model_router: None,
compaction_summary_sink: std::sync::Mutex::new(None),
+ semantic_edges: std::sync::Mutex::new(None),
+ side_question_stream_fn: std::sync::Mutex::new(None),
agent_dir: None,
};
this.ensure_harness_digest_context().await?;
diff --git a/crates/pa-core/src/session_engine/provider_adapter.rs b/crates/pa-core/src/session_engine/provider_adapter.rs
index f94e103930..c485b346c6 100644
--- a/crates/pa-core/src/session_engine/provider_adapter.rs
+++ b/crates/pa-core/src/session_engine/provider_adapter.rs
@@ -180,8 +180,19 @@ pub fn stream_once(
on_payload: options.on_payload.map(agent_payload_hook_to_ai),
on_response: options.on_response.map(agent_response_hook_to_ai),
// StreamOptions carries a plain map; the target's ordered
- // (BTreeMap) resolution converts here.
- headers: headers.map(|headers| headers.into_iter().collect()),
+ // (BTreeMap) resolution converts here, with the request's own
+ // headers (the semantic request id) merged over it — TS
+ // providers' `mergeHeaders(..., optionsHeaders)` order, the
+ // options win.
+ headers: {
+ let mut merged = headers;
+ if let Some(request_headers) = options.headers.clone() {
+ merged
+ .get_or_insert_with(std::collections::BTreeMap::new)
+ .extend(request_headers);
+ }
+ merged.map(|headers| headers.into_iter().collect())
+ },
metadata: None,
timeout_ms: None,
},
diff --git a/crates/pa-core/src/session_engine/rlm_host.rs b/crates/pa-core/src/session_engine/rlm_host.rs
index 0192cff0d6..968b13655c 100644
--- a/crates/pa-core/src/session_engine/rlm_host.rs
+++ b/crates/pa-core/src/session_engine/rlm_host.rs
@@ -139,6 +139,9 @@ pub struct RlmSpawnRequest {
pub model: Option<String>,
/// Validated thinking level; the host checks model support.
pub thinking: Option<String>,
+ /// The parent's in-flight turn request the spawn anchors to (TS
+ /// `spawnedByRequestId`): `None` for a spawn outside an active run.
+ pub spawned_by_request_id: Option<String>,
pub cell_source_code: Option<String>,
}
@@ -289,6 +292,15 @@ pub fn utf16_length(message: &str) -> usize {
// Handler registration
// ---------------------------------------------------------------------------
+/// The parent-side spawn anchor (TS `_startRlmChildRun`'s
+/// `spawnedByRequestId` snapshot): the in-flight turn's request id a
+/// mid-turn `rlm.spawn` names. The bridge is built before the session's
+/// agent exists, so the engine sets this once the agent is built.
+pub(crate) struct SemanticSpawnAnchor {
+ pub(crate) agent: std::sync::Weak<pa_agent::agent::Agent>,
+ pub(crate) recorder: Arc<super::semantic_edges::SemanticEdgeRecorder>,
+}
+
/// Session-scoped RLM state the handlers share.
pub struct RlmHostBridge {
registry: Arc<ModelRegistry>,
@@ -297,6 +309,9 @@ pub struct RlmHostBridge {
/// The child-usage attribution producer `rlm.spawn` registers into
/// and the daemon's child observation drives.
pub usage: Arc<super::rlm_usage::RlmChildUsageAttributions>,
+ /// The spawn anchor [`register_run`] reads the in-flight turn from
+ /// (`None` until the engine built the session's agent).
+ pub(crate) semantic_spawn: std::sync::OnceLock<SemanticSpawnAnchor>,
}
impl RlmHostBridge {
@@ -311,6 +326,7 @@ impl RlmHostBridge {
notes: Arc::new(RlmProgressNotes::default()),
host: host.unwrap_or_else(|| Arc::new(NoRlmChildren)),
usage,
+ semantic_spawn: std::sync::OnceLock::new(),
}
}
}
@@ -405,13 +421,11 @@ fn register_progress_note(handlers: &mut HostRequestHandlers, bridge: &Arc<RlmHo
}
fn register_run(handlers: &mut HostRequestHandlers, bridge: &Arc<RlmHostBridge>) {
- let host = Arc::clone(&bridge.host);
- let usage = Arc::clone(&bridge.usage);
+ let bridge = Arc::clone(bridge);
handlers.register(
"rlm.run",
host_handler(move |payload| {
- let host = Arc::clone(&host);
- let usage = Arc::clone(&usage);
+ let bridge = Arc::clone(&bridge);
Box::pin(async move {
let data = &payload.data;
let Some(prompt) = data.get("prompt").and_then(Value::as_str) else {
@@ -419,12 +433,29 @@ fn register_run(handlers: &mut HostRequestHandlers, bridge: &Arc<RlmHostBridge>)
};
let mut request = spawn_request_from_payload(prompt, data)?;
request.cell_source_code = payload.cell_source_code.clone();
- let handle = host.spawn(request).await?;
+ // TS `_startRlmChildRun`: the spawning request is the turn
+ // whose tool call is executing now (the anchor is computed
+ // before the spawn admission's first await); a spawn
+ // outside an active run has no such turn, and an absent
+ // edge beats a wrong one.
+ request.spawned_by_request_id = match bridge.semantic_spawn.get() {
+ Some(anchor) => {
+ let agent = anchor.agent.upgrade();
+ match agent {
+ Some(agent) if agent.state().await.is_streaming => {
+ anchor.recorder.last_turn_request_id()
+ }
+ _ => None,
+ }
+ }
+ None => None,
+ };
+ let handle = bridge.host.spawn(request).await?;
// TS `_findLastAssistantMessage` at spawn: the spawning
// assistant row (persisted at `message_end` before tool
// execution) is the target every child-usage attribution
// folds into.
- usage.register_spawn(&handle.rlm_child_id).await;
+ bridge.usage.register_spawn(&handle.rlm_child_id).await;
serde_json::to_value(&handle).map_err(anyhow::Error::new)
})
}),
@@ -453,6 +484,7 @@ fn spawn_request_from_payload(prompt: &str, data: &Value) -> anyhow::Result<RlmS
name,
model,
thinking,
+ spawned_by_request_id: None,
cell_source_code: None,
})
}
diff --git a/crates/pa-core/src/session_engine/semantic_edges.rs b/crates/pa-core/src/session_engine/semantic_edges.rs
new file mode 100644
index 0000000000..2838b6a186
--- /dev/null
+++ b/crates/pa-core/src/session_engine/semantic_edges.rs
@@ -0,0 +1,438 @@
+//! The ACP semantic-edge ledger (TS `semantic-edges.ts`, the WRITER only):
+//! a durable per-session append-only log of model-request events, plus the
+//! ids that thread them onto the wire and through child spawns.
+//!
+//! Ledger events are written before the effects they describe (ledger
+//! before wire, a child's return before the notice that triggers the
+//! parent's next turn). Provenance is best-effort: the first ledger
+//! failure permanently disables the recorder with one warning, and
+//! callers stop emitting request ids on the wire rather than weakening
+//! that invariant. Edge semantics (the pure fold over one or more
+//! ledgers) stay in TS: nothing in the Rust product reads or derives
+//! edges yet, so the fold is not ported.
+//!
+//! The ledger is a SEPARATE owner from the spawn ledger (`rlm_ledger.rs`):
+//! topology (spawn/delete records) and request semantics (this ledger)
+//! share no records or ids. `ledger.rs` owns the on-disk tail rule,
+//! `stream.rs` the stream wrapper, `compaction.rs` the compaction guard,
+//! and the tests live in `semantic_edges/tests.rs`.
+
+mod compaction;
+mod ledger;
+mod stream;
+
+#[cfg(test)]
+mod tests;
+
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, MutexGuard};
+
+use serde::{Deserialize, Serialize};
+
+pub(crate) use compaction::summary_slice_call;
+pub(crate) use stream::wrap_stream_fn;
+
+/// The outbound request-id header (TS `MODEL_REQUEST_ID_HEADER`).
+pub const MODEL_REQUEST_ID_HEADER: &str = "X-ACP-Model-Request-ID";
+/// The idempotency header carrying the same id (TS `IDEMPOTENCY_KEY_HEADER`).
+pub const IDEMPOTENCY_KEY_HEADER: &str = "Idempotency-Key";
+/// The ledger's file name inside its owning directory (TS
+/// `SEMANTIC_EDGES_LEDGER_FILENAME`).
+pub const SEMANTIC_EDGES_LEDGER_FILENAME: &str = "semantic-edges.jsonl";
+
+/// How a compaction settled (TS `CompactionStatus`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CompactionStatus {
+ Completed,
+ Failed,
+ Cancelled,
+}
+
+/// One ledger line. Field order matches the TS object literals so the
+/// serialized bytes are identical (`JSON.stringify` insertion order).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum SemanticEdgeLedgerEvent {
+ SessionRegistered {
+ session_id: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ parent_session_id: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ spawned_by_request_id: Option<String>,
+ },
+ RequestStarted {
+ request_id: String,
+ session_id: String,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ compaction_id: Option<String>,
+ },
+ RequestFinished {
+ request_id: String,
+ },
+ RequestFailed {
+ request_id: String,
+ },
+ CompactionBegun {
+ compaction_id: String,
+ session_id: String,
+ },
+ CompactionFinished {
+ compaction_id: String,
+ status: CompactionStatus,
+ },
+ ChildReturned {
+ session_id: String,
+ child_session_id: String,
+ request_id: String,
+ },
+ /// An event a newer writer appended (TS `JSON.parse` accepts any line
+ /// and the replay ignores unknown types): forward-compatible resume.
+ #[serde(other)]
+ Unknown,
+}
+
+/// The one derivation of where a session's ledger lives (TS
+/// `semanticEdgeLedgerPath`, "recorder and outbox must agree"): the RLM
+/// session dir when the session is a spawned child, else the session
+/// artifact dir. `None` keeps the recorder in memory-only mode (ids are
+/// still minted and sent, events are not).
+#[must_use]
+pub fn semantic_edge_ledger_path(
+ rlm_session_dir: Option<&Path>,
+ session_artifact_dir: Option<&Path>,
+) -> Option<PathBuf> {
+ rlm_session_dir
+ .or(session_artifact_dir)
+ .map(|dir| dir.join(SEMANTIC_EDGES_LEDGER_FILENAME))
+}
+
+/// One session's ledger identity: the durable session id the events name,
+/// where the ledger lives, and the spawn provenance a child registers with
+/// (TS `SemanticEdgeRecorder`'s constructor options).
+#[derive(Debug, Clone)]
+pub struct SemanticEdgeIdentity {
+ pub session_id: String,
+ pub ledger_path: Option<PathBuf>,
+ pub parent_session_id: Option<String>,
+ pub spawned_by_request_id: Option<String>,
+}
+
+/// A minted id (TS `mintId`: `randomUUID().replaceAll("-", "")`, 32
+/// lowercase hex).
+fn mint_id() -> String {
+ uuid::Uuid::new_v4().simple().to_string()
+}
+
+/// The two id-carrying headers one request sends (TS `modelRequestHeaders`).
+#[must_use]
+pub(crate) fn model_request_headers(
+ request_id: &str,
+) -> std::collections::BTreeMap<String, String> {
+ [
+ (MODEL_REQUEST_ID_HEADER, request_id),
+ (IDEMPOTENCY_KEY_HEADER, request_id),
+ ]
+ .into_iter()
+ .map(|(header, id)| (header.to_string(), id.to_string()))
+ .collect()
+}
+
+/// The in-flight turn a parked retry may reuse (TS `_lastTurn`): the id,
+/// the recorder epoch it minted in, and the turn-body fingerprint captured
+/// before the wire call (a replayed turn has none, so it is never reused).
+#[derive(Debug, Clone)]
+struct Turn {
+ request_id: String,
+ epoch: u64,
+ fingerprint: Option<[u8; 32]>,
+}
+
+#[derive(Debug, Default)]
+struct RecorderState {
+ disabled: bool,
+ epoch: u64,
+ last_turn: Option<Turn>,
+ parked_retry: Option<Turn>,
+ open_compactions: HashSet<String>,
+}
+
+/// Append-only semantic-edge recorder for one session (TS
+/// `SemanticEdgeRecorder`): it only WRITES events; edge semantics live in
+/// the TS fold. Constructing one over an existing ledger replays it;
+/// registration is idempotent across resumes.
+pub struct SemanticEdgeRecorder {
+ session_id: String,
+ ledger_path: Option<PathBuf>,
+ state: Mutex<RecorderState>,
+}
+
+impl SemanticEdgeRecorder {
+ /// Open (or reopen) this session's recorder: replay the ledger, fold the
+ /// replayed events back into memory, and register the session when its
+ /// id is not yet on the ledger. A missing or absent ledger starts empty;
+ /// a corrupt interior line or an unwritable ledger permanently disables
+ /// the recorder with one warning (TS `_disable`).
+ #[must_use]
+ pub fn open(identity: SemanticEdgeIdentity) -> Self {
+ let mut state = RecorderState::default();
+ let mut existing = Vec::new();
+ let replay_failed = match identity.ledger_path.as_deref() {
+ None => false,
+ Some(path) => match ledger::read_events(path) {
+ Ok(None) => false,
+ Ok(Some(events)) => {
+ existing = events;
+ false
+ }
+ Err(error) => {
+ disable(&mut state, path, &error.to_string());
+ true
+ }
+ },
+ };
+ if !replay_failed {
+ let registered = existing.iter().any(|event| {
+ matches!(
+ event,
+ SemanticEdgeLedgerEvent::SessionRegistered { session_id, .. }
+ if session_id == &identity.session_id
+ )
+ });
+ if registered {
+ for event in &existing {
+ replay_event(&mut state, &identity.session_id, event);
+ }
+ } else {
+ append_locked(
+ &mut state,
+ &identity.session_id,
+ identity.ledger_path.as_deref(),
+ &SemanticEdgeLedgerEvent::SessionRegistered {
+ session_id: identity.session_id.clone(),
+ parent_session_id: identity.parent_session_id.clone(),
+ spawned_by_request_id: identity.spawned_by_request_id.clone(),
+ },
+ );
+ }
+ }
+ Self {
+ session_id: identity.session_id,
+ ledger_path: identity.ledger_path,
+ state: Mutex::new(state),
+ }
+ }
+
+ fn state(&self) -> MutexGuard<'_, RecorderState> {
+ self.state
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ }
+
+ /// Durable append first, in-memory state second (TS `_append`): a
+ /// failed write must not leave commit state pointing at events that
+ /// never reached the ledger. Requires the state lock; returns whether
+ /// the event recorded (a disabled or failed recorder records nothing).
+ fn append(&self, state: &mut RecorderState, event: &SemanticEdgeLedgerEvent) -> bool {
+ append_locked(state, &self.session_id, self.ledger_path.as_deref(), event)
+ }
+
+ /// Mint (or, for a body-identical retry, reuse) the id for one turn
+ /// call (TS `startTurnRequest`). `None` means the recorder is disabled:
+ /// the call carries no id. A reused retry re-logs `request_started` so
+ /// the fold re-claims the failed attempt's returned pending edges.
+ pub(crate) fn start_turn_request(&self, fingerprint: [u8; 32]) -> Option<String> {
+ let mut state = self.state();
+ // A parked retry is consumed only by the body it parked for, in
+ // the epoch it parked in (TS `startTurnRequest`'s reuse gate).
+ let epoch = state.epoch;
+ let request_id = state
+ .parked_retry
+ .take_if(|parked| parked.epoch == epoch && parked.fingerprint == Some(fingerprint))
+ .map_or_else(mint_id, |parked| parked.request_id);
+ let recorded = self.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::RequestStarted {
+ request_id: request_id.clone(),
+ session_id: self.session_id.clone(),
+ compaction_id: None,
+ },
+ );
+ if !recorded {
+ return None;
+ }
+ state.last_turn = Some(Turn {
+ request_id: request_id.clone(),
+ epoch: state.epoch,
+ fingerprint: Some(fingerprint),
+ });
+ Some(request_id)
+ }
+
+ /// Park the last turn so the upcoming auto-retry reuses its id (TS
+ /// `prepareTurnRetry`).
+ pub fn prepare_turn_retry(&self) {
+ let mut state = self.state();
+ let parked = state.last_turn.clone();
+ state.parked_retry = parked;
+ }
+
+ /// Drop the parked retry (TS `clearTurnRetry`).
+ pub fn clear_turn_retry(&self) {
+ self.state().parked_retry = None;
+ }
+
+ /// Commit one request (TS `finishRequest`).
+ pub(crate) fn finish_request(&self, request_id: &str) {
+ let mut state = self.state();
+ self.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::RequestFinished {
+ request_id: request_id.to_string(),
+ },
+ );
+ }
+
+ /// Fail one request (TS `failRequest`).
+ pub(crate) fn fail_request(&self, request_id: &str) {
+ let mut state = self.state();
+ self.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::RequestFailed {
+ request_id: request_id.to_string(),
+ },
+ );
+ }
+
+ /// The last turn's request id (TS `lastTurnRequestId`): the id a
+ /// mid-turn child spawn anchors to.
+ #[must_use]
+ pub(crate) fn last_turn_request_id(&self) -> Option<String> {
+ self.state()
+ .last_turn
+ .as_ref()
+ .map(|turn| turn.request_id.clone())
+ }
+
+ /// The parent claims a child's return (TS `recordChildReturned`): the
+ /// child's last committed request, captured at the success point. A
+ /// child with nothing committed returns nothing (the no-op).
+ pub fn record_child_returned(
+ &self,
+ child_session_id: &str,
+ child_last_committed_request_id: Option<String>,
+ ) {
+ let Some(request_id) = child_last_committed_request_id else {
+ return;
+ };
+ let mut state = self.state();
+ self.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::ChildReturned {
+ session_id: self.session_id.clone(),
+ child_session_id: child_session_id.to_string(),
+ request_id,
+ },
+ );
+ }
+}
+
+/// The last `request_finished` in a ledger: the parent's read of a child's
+/// last committed request (the cross-process form of TS's in-process
+/// `child.semanticEdges.lastCommittedRequestId`), through the same parser
+/// the recorder replays with. A missing ledger, a torn final line, or a
+/// corrupt read yields `None` — an absent edge beats a wrong one.
+#[must_use]
+pub fn last_committed_request_id(ledger_path: &Path) -> Option<String> {
+ match ledger::read_events(ledger_path) {
+ Ok(None) | Err(_) => None,
+ Ok(Some(events)) => events.into_iter().rev().find_map(|event| match event {
+ SemanticEdgeLedgerEvent::RequestFinished { request_id } => Some(request_id),
+ _ => None,
+ }),
+ }
+}
+
+/// Durable append first, in-memory state second (TS `_append`): a failed
+/// write must not leave commit state pointing at events that never reached
+/// the ledger. Requires the state lock.
+fn append_locked(
+ state: &mut RecorderState,
+ session_id: &str,
+ ledger_path: Option<&Path>,
+ event: &SemanticEdgeLedgerEvent,
+) -> bool {
+ if state.disabled {
+ return false;
+ }
+ if let Some(path) = ledger_path {
+ if let Err(error) = ledger::append_event(path, event) {
+ disable(state, path, &error.to_string());
+ return false;
+ }
+ }
+ replay_event(state, session_id, event);
+ true
+}
+
+/// Fold one event back into the in-memory state (TS `_replay`): restores
+/// turn attribution and compaction epochs after a resume.
+fn replay_event(state: &mut RecorderState, session_id: &str, event: &SemanticEdgeLedgerEvent) {
+ match event {
+ // Restores spawn attribution after resume; the fingerprint is
+ // unknowable on disk, so a replayed turn is never reused as a
+ // parked retry.
+ SemanticEdgeLedgerEvent::RequestStarted {
+ request_id,
+ session_id: event_session_id,
+ compaction_id: None,
+ } if event_session_id == session_id => {
+ state.last_turn = Some(Turn {
+ request_id: request_id.clone(),
+ epoch: state.epoch,
+ fingerprint: None,
+ });
+ }
+ SemanticEdgeLedgerEvent::CompactionBegun {
+ compaction_id,
+ session_id: event_session_id,
+ } if event_session_id == session_id => {
+ state.open_compactions.insert(compaction_id.clone());
+ }
+ SemanticEdgeLedgerEvent::CompactionFinished {
+ compaction_id,
+ status,
+ } => {
+ if state.open_compactions.remove(compaction_id)
+ && *status == CompactionStatus::Completed
+ {
+ state.epoch += 1;
+ }
+ }
+ SemanticEdgeLedgerEvent::RequestStarted { .. }
+ | SemanticEdgeLedgerEvent::RequestFinished { .. }
+ | SemanticEdgeLedgerEvent::RequestFailed { .. }
+ | SemanticEdgeLedgerEvent::SessionRegistered { .. }
+ | SemanticEdgeLedgerEvent::CompactionBegun { .. }
+ | SemanticEdgeLedgerEvent::ChildReturned { .. }
+ | SemanticEdgeLedgerEvent::Unknown => {}
+ }
+}
+
+/// Permanently disable all writes with one warning (TS `_disable`), so the
+/// ledger-before-wire invariant is preserved rather than weakened.
+fn disable(state: &mut RecorderState, ledger_path: &Path, error: &str) {
+ if state.disabled {
+ return;
+ }
+ state.disabled = true;
+ // A disabled recorder names no turn: a later spawn would otherwise
+ // anchor to a request that is not the in-flight one (TS keeps
+ // `_lastTurn`; an absent edge beats a wrong one).
+ state.last_turn = None;
+ eprintln!(
+ "pa-core: semantic-edge ledger disabled at {}: {error}",
+ ledger_path.display()
+ );
+}
diff --git a/crates/pa-core/src/session_engine/semantic_edges/compaction.rs b/crates/pa-core/src/session_engine/semantic_edges/compaction.rs
new file mode 100644
index 0000000000..4ef0e86dbd
--- /dev/null
+++ b/crates/pa-core/src/session_engine/semantic_edges/compaction.rs
@@ -0,0 +1,207 @@
+//! The compaction half of the ledger (TS `agent-session.ts`'s
+//! `semanticCompaction` / `uncommittedSlices` / `summaryCall`): the RAII
+//! guard that owns one compaction's events, and the wrapper its summary
+//! wire calls run under.
+
+use std::sync::Arc;
+
+use pa_agent::abort::AbortSignal;
+
+use super::{model_request_headers, SemanticEdgeLedgerEvent, SemanticEdgeRecorder};
+
+impl SemanticEdgeRecorder {
+ /// Begin one compaction and return its RAII guard (TS `beginCompaction`):
+ /// every wire summary slice is minted through the guard, and the
+ /// compaction's terminal event lands exactly once — at `commit`, or at
+ /// the guard's drop on every `?`/abort exit (TS settles the same paths
+ /// through its try/catch).
+ pub(crate) fn begin_compaction(
+ self: &Arc<Self>,
+ abort: Option<&AbortSignal>,
+ ) -> SemanticCompaction {
+ let compaction_id = super::mint_id();
+ let mut state = self.state();
+ self.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::CompactionBegun {
+ compaction_id: compaction_id.clone(),
+ session_id: self.session_id.clone(),
+ },
+ );
+ SemanticCompaction {
+ recorder: Arc::clone(self),
+ compaction_id,
+ open_slices: std::sync::Mutex::new(Vec::new()),
+ committed: false,
+ abort: abort.cloned(),
+ }
+ }
+}
+
+/// One compaction's ledger guard: slices mint their ids through it, and
+/// the compaction's terminal event lands exactly once — `commit()` before
+/// the compaction entry persists, or the drop (failed / cancelled) on every
+/// early exit, exactly like the TS try/catch that settles the same paths.
+pub(crate) struct SemanticCompaction {
+ recorder: Arc<SemanticEdgeRecorder>,
+ compaction_id: String,
+ /// Every started slice that has not settled on the ledger (TS
+ /// `uncommittedSlices`, widened to cover a slice whose future is
+ /// dropped mid-call): a failure removes and fails its own id, commit
+ /// finishes the rest, and the drop fails the rest — so no
+ /// `request_started{compaction_id}` is ever left without a terminal
+ /// event. A resolved slice moves to the tail (TS pushes
+ /// `uncommittedSlices` on resolve), so commit finishes the slices in
+ /// resolve order. A split turn's two slices run concurrently on one
+ /// task, so the list is interior-mutable.
+ open_slices: std::sync::Mutex<Vec<String>>,
+ committed: bool,
+ /// The run's abort signal: a dropped guard records `cancelled` only
+ /// when it aborted, `failed` otherwise (TS's catch classification).
+ abort: Option<AbortSignal>,
+}
+
+impl SemanticCompaction {
+ /// Mint one summary wire call's id (TS `startCompactionRequest`):
+ /// `None` when the recorder is disabled — the call carries no id.
+ pub(crate) fn start_slice(&self) -> Option<String> {
+ let request_id = super::mint_id();
+ let mut state = self.recorder.state();
+ let recorded = self.recorder.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::RequestStarted {
+ request_id: request_id.clone(),
+ session_id: self.recorder.session_id.clone(),
+ compaction_id: Some(self.compaction_id.clone()),
+ },
+ );
+ if !recorded {
+ return None;
+ }
+ self.open_slices
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .push(request_id.clone());
+ Some(request_id)
+ }
+
+ /// A wire slice failed (TS `failRequest` in `summaryCall`'s catch):
+ /// it settles now, so commit and drop no longer own it.
+ pub(crate) fn slice_failed(&self, request_id: &str) {
+ self.open_slices
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .retain(|open| open != request_id);
+ self.recorder.fail_request(request_id);
+ }
+
+ /// A wire slice resolved (TS pushes `uncommittedSlices` on resolve):
+ /// it moves to the tail, so `commit` finishes the slices in resolve
+ /// order and the last-resolved slice is the session's last commit (the
+ /// compaction edge's source).
+ fn slice_resolved(&self, request_id: &str) {
+ let mut open = self
+ .open_slices
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ open.retain(|open| open != request_id);
+ open.push(request_id.to_string());
+ }
+
+ /// The compaction committed (ledger before effect: TS marks
+ /// `compactionRecorded` first, finishes the slices, then appends the
+ /// `compaction_finished` event, all ahead of `appendCompaction`).
+ pub(crate) fn commit(&mut self) {
+ self.committed = true;
+ for request_id in self.take_open_slices() {
+ self.recorder.finish_request(&request_id);
+ }
+ let mut state = self.recorder.state();
+ self.recorder.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::CompactionFinished {
+ compaction_id: self.compaction_id.clone(),
+ status: super::CompactionStatus::Completed,
+ },
+ );
+ }
+}
+
+impl SemanticCompaction {
+ /// Drain the unsettled slice ids (commit and drop both consume them).
+ fn take_open_slices(&self) -> Vec<String> {
+ std::mem::take(
+ &mut *self
+ .open_slices
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner),
+ )
+ }
+}
+
+impl Drop for SemanticCompaction {
+ fn drop(&mut self) {
+ if self.committed {
+ return;
+ }
+ for request_id in self.take_open_slices() {
+ self.recorder.fail_request(&request_id);
+ }
+ let status = if self
+ .abort
+ .as_ref()
+ .is_some_and(pa_agent::abort::AbortSignal::is_aborted)
+ {
+ super::CompactionStatus::Cancelled
+ } else {
+ super::CompactionStatus::Failed
+ };
+ let mut state = self.recorder.state();
+ self.recorder.append(
+ &mut state,
+ &SemanticEdgeLedgerEvent::CompactionFinished {
+ compaction_id: self.compaction_id.clone(),
+ status,
+ },
+ );
+ }
+}
+
+/// Run one summary wire call under its compaction's ledger (TS
+/// `summaryCall`): mint the slice's id, merge its headers into the call's,
+/// and report the outcome. Without a guard (no semantic identity, or a
+/// disabled recorder) the call runs unchanged.
+///
+/// # Errors
+///
+/// Returns the wrapped call's error after the guard recorded the failed
+/// slice.
+pub(crate) async fn summary_slice_call<T, F, Fut>(
+ compaction: Option<&SemanticCompaction>,
+ summary_headers: Option<std::collections::BTreeMap<String, String>>,
+ call: F,
+) -> anyhow::Result<T>
+where
+ F: FnOnce(Option<std::collections::BTreeMap<String, String>>) -> Fut,
+ Fut: std::future::Future<Output = anyhow::Result<T>>,
+{
+ let Some(compaction) = compaction else {
+ return call(summary_headers).await;
+ };
+ // A disabled recorder mints no id: the call carries the plain summary
+ // headers, exactly like TS's `requestId === undefined` arm.
+ let Some(request_id) = compaction.start_slice() else {
+ return call(summary_headers).await;
+ };
+ // The id's headers win over the routed model's (TS
+ // `{ ...summarization.headers, ...modelRequestHeaders(requestId) }`),
+ // and they ride even a headerless target (the common direct-key case).
+ let mut headers = summary_headers.unwrap_or_default();
+ headers.extend(model_request_headers(&request_id));
+ let result = call(Some(headers)).await;
+ match &result {
+ Ok(_) => compaction.slice_resolved(&request_id),
+ Err(_) => compaction.slice_failed(&request_id),
+ }
+ result
+}
diff --git a/crates/pa-core/src/session_engine/semantic_edges/ledger.rs b/crates/pa-core/src/session_engine/semantic_edges/ledger.rs
new file mode 100644
index 0000000000..d6b70f0e83
--- /dev/null
+++ b/crates/pa-core/src/session_engine/semantic_edges/ledger.rs
@@ -0,0 +1,168 @@
+//! The on-disk ledger tail rule (TS `event-log.ts`, this ledger only):
+//! append-only JSONL, one `O_APPEND` write per event, no fsync (TS
+//! `appendSync` without `durable`).
+//!
+//! Tail rule: an unterminated final line is an uncommitted append —
+//! skipped on replay even when it parses, truncated at its byte offset
+//! before the next append, never newline-completed (completion would
+//! turn a line a strict parser rejects into permanent interior poison).
+//! Interior malformed lines fail closed. Repair runs only on append,
+//! never on read: a viewer may replay a live writer's log.
+
+use std::io::Write;
+use std::path::Path;
+
+use super::SemanticEdgeLedgerEvent;
+
+/// Read every terminated line (the missing-file decision at the open: no
+/// check-then-read window). A torn final line is skipped; an interior
+/// line that fails the parse fails the whole read.
+///
+/// # Errors
+///
+/// Returns the underlying I/O error, or an `InvalidData` error naming the
+/// corrupt line for a parse failure.
+pub(super) fn read_events(path: &Path) -> std::io::Result<Option<Vec<SemanticEdgeLedgerEvent>>> {
+ let contents = match std::fs::read(path) {
+ Ok(contents) => contents,
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+ Err(error) => return Err(error),
+ };
+ let ends_with_newline = contents.last() == Some(&b'\n');
+ let lines = String::from_utf8_lossy(&contents);
+ let lines = lines.split('\n').collect::<Vec<_>>();
+ let mut events = Vec::new();
+ for (index, line) in lines.iter().enumerate() {
+ let line = line.trim();
+ if line.is_empty() {
+ continue;
+ }
+ // The unterminated final line (the last split element when the
+ // contents do not end in a newline): an uncommitted append.
+ if index == lines.len() - 1 && !ends_with_newline {
+ continue;
+ }
+ let event: SemanticEdgeLedgerEvent = serde_json::from_str(line).map_err(|error| {
+ std::io::Error::other(format!(
+ "corrupt semantic-edge ledger line {}: {error}",
+ index + 1
+ ))
+ })?;
+ events.push(event);
+ }
+ Ok(Some(events))
+}
+
+/// Append one event as a single `O_APPEND` write, repairing a torn tail
+/// first (TS `appendSync`). The ledger dir is created private (`0o700`)
+/// and the file private (`0o600`) where mode bits exist.
+///
+/// # Errors
+///
+/// Returns the underlying I/O error when the dir, the repair, or the
+/// append fails.
+pub(super) fn append_event(path: &Path, event: &SemanticEdgeLedgerEvent) -> std::io::Result<()> {
+ let mut line = serde_json::to_string(event).map_err(|error| {
+ std::io::Error::other(format!("semantic-edge event not serializable: {error}"))
+ })?;
+ line.push('\n');
+ if let Some(parent) = path.parent() {
+ crate::platform::perms::create_dir_all_private(parent)?;
+ }
+ repair_torn_tail(path)?;
+ let mut options = std::fs::OpenOptions::new();
+ options.create(true).append(true);
+ crate::platform::perms::set_private_mode(&mut options);
+ let mut file = options.open(path)?;
+ write_line_once(&mut file, line.as_bytes(), path)
+}
+
+/// Issue exactly one write: a short append cannot be completed safely after
+/// another writer's append, and must disable the recorder instead (TS
+/// `EventLog.appendSync`'s short-write check).
+fn write_line_once(writer: &mut impl Write, line: &[u8], path: &Path) -> std::io::Result<()> {
+ let written = writer.write(line)?;
+ if written != line.len() {
+ return Err(std::io::Error::other(format!(
+ "semantic-edge ledger {}: short write ({written} of {} bytes)",
+ path.display(),
+ line.len()
+ )));
+ }
+ Ok(())
+}
+
+/// Truncate an unterminated tail at its byte offset (all offsets are BYTE
+/// offsets: string indices diverge from them as soon as any record carries
+/// multi-byte UTF-8). The healthy path reads one byte (TS `appendSync`
+/// stats and checks the final byte); only a torn tail reads the file.
+///
+/// # Errors
+///
+/// Returns the underlying I/O error when the read or the truncate fails.
+fn repair_torn_tail(path: &Path) -> std::io::Result<()> {
+ use std::io::{Read as _, Seek as _};
+ let mut file = match std::fs::OpenOptions::new()
+ .read(true)
+ .write(true)
+ .open(path)
+ {
+ Ok(file) => file,
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+ Err(error) => return Err(error),
+ };
+ if file.metadata()?.len() == 0 {
+ return Ok(());
+ }
+ file.seek(std::io::SeekFrom::End(-1))?;
+ let mut last = [0u8; 1];
+ file.read_exact(&mut last)?;
+ if last[0] == b'\n' {
+ return Ok(());
+ }
+ file.seek(std::io::SeekFrom::Start(0))?;
+ let mut contents = Vec::new();
+ file.read_to_end(&mut contents)?;
+ let keep = contents
+ .iter()
+ .rposition(|byte| *byte == b'\n')
+ .map_or(0, |position| position + 1);
+ file.set_len(keep as u64)
+}
+
+#[cfg(test)]
+mod tests {
+ use std::io::{self, Write};
+
+ use super::write_line_once;
+
+ /// A partial append must not be retried: a rival's complete line could
+ /// land between writes and turn two valid records into interior poison.
+ struct ShortWriter {
+ writes: usize,
+ }
+
+ impl Write for ShortWriter {
+ fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
+ self.writes += 1;
+ Ok(bytes.len() / 2)
+ }
+
+ fn flush(&mut self) -> io::Result<()> {
+ Ok(())
+ }
+ }
+
+ #[test]
+ fn short_append_fails_without_a_second_write() {
+ let mut writer = ShortWriter { writes: 0 };
+ let error = write_line_once(
+ &mut writer,
+ b"{\"type\":\"request_started\"}\n",
+ std::path::Path::new("ledger"),
+ )
+ .expect_err("a short append must fail");
+ assert_eq!(writer.writes, 1);
+ assert!(error.to_string().contains("short write"));
+ }
+}
diff --git a/crates/pa-core/src/session_engine/semantic_edges/stream.rs b/crates/pa-core/src/session_engine/semantic_edges/stream.rs
new file mode 100644
index 0000000000..d4ba8acc7e
--- /dev/null
+++ b/crates/pa-core/src/session_engine/semantic_edges/stream.rs
@@ -0,0 +1,152 @@
+//! The stream wrapper that binds one session's recorder to its provider
+//! turns (TS `wrapStreamFnWithSemanticEdges`).
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+use pa_agent::stream::{
+ AssistantMessageEvent, LlmContext, ModelStream, StreamFn, StreamRequestOptions,
+};
+use pa_agent::types::{AssistantMessage, Model, StopReason};
+use sha2::{Digest as _, Sha256};
+
+use super::{model_request_headers, SemanticEdgeRecorder};
+
+/// Bind a stream function to one session's recorder (TS
+/// `wrapStreamFnWithSemanticEdges`; the Rust engine wraps it OUTERMOST,
+/// over the timing-instrumented fn). `request_started` is appended before
+/// the wire call; the request commits or fails when its stream resolves
+/// (an error/aborted final message is a failure). A disabled recorder
+/// leaves the call untouched: no id, no headers, no event.
+pub(crate) fn wrap_stream_fn(recorder: Arc<SemanticEdgeRecorder>, inner: StreamFn) -> StreamFn {
+ Arc::new(move |model, context, mut options| {
+ let recorder = Arc::clone(&recorder);
+ let inner = Arc::clone(&inner);
+ Box::pin(async move {
+ let fingerprint = turn_fingerprint(&model, &context, &options);
+ let Some(request_id) = recorder.start_turn_request(fingerprint) else {
+ return inner(model, context, options).await;
+ };
+ let headers = options.headers.get_or_insert_with(BTreeMap::new);
+ headers.extend(model_request_headers(&request_id));
+ match inner(model, context, options).await {
+ Err(error) => {
+ recorder.fail_request(&request_id);
+ Err(error)
+ }
+ Ok(stream) => Ok(Box::new(SemanticStream {
+ inner: stream,
+ recorder,
+ request_id,
+ settled: false,
+ }) as Box<dyn ModelStream>),
+ }
+ })
+ })
+}
+
+/// A provider stream observed by the recorder: `result()` settles the
+/// request by its final stop reason, and an unsettled stream fails at
+/// `close()` or drop — TS observes an abort as a failed request, not a
+/// stuck in-flight one.
+struct SemanticStream {
+ inner: Box<dyn ModelStream>,
+ recorder: Arc<SemanticEdgeRecorder>,
+ request_id: String,
+ settled: bool,
+}
+
+impl SemanticStream {
+ /// Settle a resolved stream by its final stop reason (TS observe: an
+ /// error/aborted final message is a failed request).
+ fn settle_by_stop_reason(&mut self, message: &AssistantMessage) {
+ if self.settled {
+ return;
+ }
+ self.settled = true;
+ if matches!(message.stop_reason, StopReason::Error | StopReason::Aborted) {
+ self.recorder.fail_request(&self.request_id);
+ } else {
+ self.recorder.finish_request(&self.request_id);
+ }
+ }
+
+ /// Settle an unresolved stream as failed (a rejected result, a close,
+ /// or the drop).
+ fn fail(&mut self) {
+ if self.settled {
+ return;
+ }
+ self.settled = true;
+ self.recorder.fail_request(&self.request_id);
+ }
+}
+
+impl ModelStream for SemanticStream {
+ fn next_event(&mut self) -> pa_agent::BoxFut<'_, Option<AssistantMessageEvent>> {
+ self.inner.next_event()
+ }
+
+ fn result(&mut self) -> pa_agent::BoxFut<'_, anyhow::Result<AssistantMessage>> {
+ Box::pin(async move {
+ let message = self.inner.result().await;
+ match &message {
+ Ok(message) => self.settle_by_stop_reason(message),
+ Err(_) => self.fail(),
+ }
+ message
+ })
+ }
+
+ fn close(&mut self) {
+ self.fail();
+ self.inner.close();
+ }
+}
+
+impl Drop for SemanticStream {
+ fn drop(&mut self) {
+ self.fail();
+ }
+}
+
+fn sha256(bytes: &[u8]) -> [u8; 32] {
+ let mut hasher = Sha256::new();
+ hasher.update(bytes);
+ hasher.finalize().into()
+}
+
+/// sha256 over the canonical JSON of one fingerprint input (TS
+/// `digestJson`).
+fn digest_json(value: &impl serde::Serialize) -> [u8; 32] {
+ sha256(&serde_json::to_vec(value).unwrap_or_default())
+}
+
+/// Fingerprint of one turn call body (TS `hashTurnBody`, in-memory only —
+/// never on disk): the recorder reuses a parked retry's id only for an
+/// equal fingerprint. It hashes a bounded subset (model, options,
+/// system-prompt digest, message count, last-message digest, tools
+/// digest) so the full body is never re-serialized per request; the
+/// fingerprint only gates parked-retry id reuse within one retry window.
+fn turn_fingerprint(
+ model: &Model,
+ context: &LlmContext,
+ options: &StreamRequestOptions,
+) -> [u8; 32] {
+ let body = serde_json::json!({
+ "provider": model.provider,
+ "model": model.id,
+ "reasoning": options.reasoning,
+ "temperature": options.temperature,
+ "maxTokens": options.max_tokens,
+ "serviceTier": options.service_tier,
+ "systemPromptDigest": context
+ .system_prompt
+ .as_deref()
+ .map(|prompt| sha256(prompt.as_bytes())),
+ "messageCount": context.messages.len(),
+ "lastMessageDigest": context.messages.last().map(digest_json),
+ "toolsDigest": digest_json(&context.tools),
+ });
+ sha256(&serde_json::to_vec(&body).unwrap_or_default())
+}
diff --git a/crates/pa-core/src/session_engine/semantic_edges/tests.rs b/crates/pa-core/src/session_engine/semantic_edges/tests.rs
new file mode 100644
index 0000000000..d27fe35af2
--- /dev/null
+++ b/crates/pa-core/src/session_engine/semantic_edges/tests.rs
@@ -0,0 +1,403 @@
+//! The semantic-edge recorder battery: the ledger lifecycle and replay,
+//! retry parking, the torn-tail rule, and the stream wrapper.
+
+use std::sync::{Arc, Mutex};
+
+use pa_agent::stream::{
+ AssistantMessageEvent, LlmContext, ModelStream, StreamFn, StreamRequestOptions,
+};
+use pa_agent::types::{AssistantMessage, Model, StopReason, Usage};
+use tempfile::TempDir;
+
+use super::{
+ model_request_headers, wrap_stream_fn, SemanticEdgeIdentity, SemanticEdgeLedgerEvent,
+ SemanticEdgeRecorder, IDEMPOTENCY_KEY_HEADER, MODEL_REQUEST_ID_HEADER,
+};
+
+const FINGERPRINT_A: [u8; 32] = [1; 32];
+const FINGERPRINT_B: [u8; 32] = [2; 32];
+
+/// One identity over a fresh tempdir ledger.
+fn identity(session_id: &str) -> (SemanticEdgeIdentity, TempDir) {
+ let dir = TempDir::new().unwrap();
+ let identity = SemanticEdgeIdentity {
+ session_id: session_id.to_string(),
+ ledger_path: Some(dir.path().join(super::SEMANTIC_EDGES_LEDGER_FILENAME)),
+ parent_session_id: Some("parent-session".to_string()),
+ spawned_by_request_id: Some("parent-request".to_string()),
+ };
+ (identity, dir)
+}
+
+fn read_ledger(identity: &SemanticEdgeIdentity) -> Vec<SemanticEdgeLedgerEvent> {
+ super::ledger::read_events(identity.ledger_path.as_ref().unwrap())
+ .unwrap()
+ .unwrap_or_default()
+}
+
+fn session_registered(session_id: &str) -> SemanticEdgeLedgerEvent {
+ SemanticEdgeLedgerEvent::SessionRegistered {
+ session_id: session_id.to_string(),
+ parent_session_id: Some("parent-session".to_string()),
+ spawned_by_request_id: Some("parent-request".to_string()),
+ }
+}
+
+fn request_started(session_id: &str, request_id: &str) -> SemanticEdgeLedgerEvent {
+ SemanticEdgeLedgerEvent::RequestStarted {
+ request_id: request_id.to_string(),
+ session_id: session_id.to_string(),
+ compaction_id: None,
+ }
+}
+
+fn request_started_slice(
+ session_id: &str,
+ compaction_id: &str,
+ request_id: &str,
+) -> SemanticEdgeLedgerEvent {
+ SemanticEdgeLedgerEvent::RequestStarted {
+ request_id: request_id.to_string(),
+ session_id: session_id.to_string(),
+ compaction_id: Some(compaction_id.to_string()),
+ }
+}
+
+#[test]
+fn a_turn_lifecycle_is_ledgered_and_reopening_replays_without_reregistering() {
+ let (identity, _dir) = identity("session-a");
+ let recorder = SemanticEdgeRecorder::open(identity.clone());
+ let first = recorder
+ .start_turn_request(FINGERPRINT_A)
+ .expect("the recorder mints ids");
+ recorder.finish_request(&first);
+ let second = recorder
+ .start_turn_request(FINGERPRINT_A)
+ .expect("the recorder mints ids");
+ recorder.fail_request(&second);
+ drop(recorder);
+ // Reopen: the ledger replays without re-registering, and the last
+ // replayed request_started restores the in-flight turn a resumed
+ // child's spawn anchors to.
+ let reopened = SemanticEdgeRecorder::open(identity.clone());
+ assert_eq!(
+ reopened.last_turn_request_id().as_deref(),
+ Some(second.as_str())
+ );
+ assert_eq!(
+ read_ledger(&identity),
+ vec![
+ session_registered("session-a"),
+ request_started("session-a", &first),
+ SemanticEdgeLedgerEvent::RequestFinished {
+ request_id: first.clone(),
+ },
+ request_started("session-a", &second),
+ SemanticEdgeLedgerEvent::RequestFailed { request_id: second },
+ ]
+ );
+}
+
+#[test]
+fn a_parked_retry_reuses_its_id_only_for_an_identical_body_in_the_same_epoch() {
+ let (identity, _dir) = identity("session-b");
+ let recorder = Arc::new(SemanticEdgeRecorder::open(identity.clone()));
+ let first = recorder
+ .start_turn_request(FINGERPRINT_A)
+ .expect("the recorder mints ids");
+ // The parked retry reuses the id for the identical body and re-logs
+ // its request_started; a different body mints a fresh id.
+ recorder.prepare_turn_retry();
+ assert_eq!(
+ recorder.start_turn_request(FINGERPRINT_A).as_deref(),
+ Some(first.as_str())
+ );
+ let different_body = recorder
+ .start_turn_request(FINGERPRINT_B)
+ .expect("the recorder mints ids");
+ assert_ne!(different_body, first);
+ // A completed compaction bumps the epoch: a parked id from the old
+ // epoch is not reused even for an identical body.
+ recorder.begin_compaction(None).commit();
+ recorder.prepare_turn_retry();
+ let post_compaction = recorder
+ .start_turn_request(FINGERPRINT_B)
+ .expect("the recorder mints ids");
+ assert_ne!(post_compaction, different_body);
+ let ledger = read_ledger(&identity);
+ let compaction_id = ledger
+ .iter()
+ .find_map(|event| match event {
+ SemanticEdgeLedgerEvent::CompactionBegun { compaction_id, .. } => {
+ Some(compaction_id.clone())
+ }
+ _ => None,
+ })
+ .expect("the compaction began");
+ assert_eq!(
+ ledger,
+ vec![
+ session_registered("session-b"),
+ request_started("session-b", &first),
+ request_started("session-b", &first),
+ request_started("session-b", &different_body),
+ SemanticEdgeLedgerEvent::CompactionBegun {
+ compaction_id: compaction_id.clone(),
+ session_id: "session-b".to_string(),
+ },
+ SemanticEdgeLedgerEvent::CompactionFinished {
+ compaction_id,
+ status: super::CompactionStatus::Completed,
+ },
+ request_started("session-b", &post_compaction),
+ ]
+ );
+}
+
+#[tokio::test]
+async fn split_summary_slices_commit_in_resolve_order() {
+ let (identity, _dir) = identity("session-g");
+ let recorder = Arc::new(SemanticEdgeRecorder::open(identity.clone()));
+ let mut compaction = recorder.begin_compaction(None);
+ let (release_first, first_gate) = tokio::sync::oneshot::channel::<()>();
+ let mut first = Box::pin(super::summary_slice_call(
+ Some(&compaction),
+ None,
+ move |_| async move {
+ let _gate = first_gate.await;
+ Ok::<(), anyhow::Error>(())
+ },
+ ));
+ // The first slice starts (ledger) and parks on its gate; the second
+ // starts and resolves while the first is still in flight.
+ assert!(futures::poll!(first.as_mut()).is_pending());
+ super::summary_slice_call(Some(&compaction), None, |_| async {
+ Ok::<(), anyhow::Error>(())
+ })
+ .await
+ .expect("the second slice resolves");
+ release_first.send(()).expect("the parked slice's gate");
+ first.await.expect("the parked slice resolves");
+ compaction.commit();
+ // The started ids in start order; commit finishes them in resolve
+ // order (TS pushes `uncommittedSlices` on resolve): b then a.
+ let ledger = read_ledger(&identity);
+ let compaction_id = ledger
+ .iter()
+ .find_map(|event| match event {
+ SemanticEdgeLedgerEvent::CompactionBegun { compaction_id, .. } => {
+ Some(compaction_id.clone())
+ }
+ _ => None,
+ })
+ .expect("the compaction began");
+ let slices: Vec<String> = ledger
+ .iter()
+ .filter_map(|event| match event {
+ SemanticEdgeLedgerEvent::RequestStarted {
+ request_id,
+ compaction_id: Some(_),
+ ..
+ } => Some(request_id.clone()),
+ _ => None,
+ })
+ .collect();
+ let (a, b) = (&slices[0], &slices[1]);
+ assert_eq!(
+ read_ledger(&identity),
+ vec![
+ session_registered("session-g"),
+ SemanticEdgeLedgerEvent::CompactionBegun {
+ compaction_id: compaction_id.clone(),
+ session_id: "session-g".to_string(),
+ },
+ request_started_slice("session-g", &compaction_id, a),
+ request_started_slice("session-g", &compaction_id, b),
+ SemanticEdgeLedgerEvent::RequestFinished {
+ request_id: b.clone()
+ },
+ SemanticEdgeLedgerEvent::RequestFinished {
+ request_id: a.clone()
+ },
+ SemanticEdgeLedgerEvent::CompactionFinished {
+ compaction_id,
+ status: super::CompactionStatus::Completed,
+ },
+ ]
+ );
+}
+
+#[test]
+fn a_ledger_failure_drops_the_spawn_anchor() {
+ let (identity, _dir) = identity("session-e");
+ let recorder = SemanticEdgeRecorder::open(identity.clone());
+ recorder
+ .start_turn_request(FINGERPRINT_A)
+ .expect("the recorder mints ids");
+ // A directory at the ledger path fails the next append (works as
+ // root too).
+ let path = identity.ledger_path.as_ref().unwrap();
+ std::fs::remove_file(path).unwrap();
+ std::fs::create_dir(path).unwrap();
+ assert_eq!(
+ (
+ recorder.start_turn_request(FINGERPRINT_B),
+ recorder.last_turn_request_id()
+ ),
+ (None, None)
+ );
+}
+
+#[test]
+fn a_torn_final_line_is_ignored_on_replay_and_truncated_before_the_next_append() {
+ let (identity, _dir) = identity("session-c");
+ let registered = session_registered("session-c");
+ let mut torn = serde_json::to_string(&registered).unwrap();
+ torn.push('\n');
+ torn.push_str("{\"type\":\"request_st");
+ std::fs::write(identity.ledger_path.as_ref().unwrap(), torn).unwrap();
+ // The replay skips the unterminated final line even though its prefix
+ // parses: no turn is restored.
+ let recorder = SemanticEdgeRecorder::open(identity.clone());
+ assert_eq!(recorder.last_turn_request_id(), None);
+ let request_id = recorder
+ .start_turn_request(FINGERPRINT_A)
+ .expect("the recorder mints ids");
+ // The append truncated the torn tail at its byte offset first: the
+ // file bytes are exactly the registered line and the new event.
+ let mut expected = serde_json::to_string(&registered).unwrap().into_bytes();
+ expected.push(b'\n');
+ expected.extend(
+ serde_json::to_string(&request_started("session-c", &request_id))
+ .unwrap()
+ .into_bytes(),
+ );
+ expected.push(b'\n');
+ let bytes = std::fs::read(identity.ledger_path.as_ref().unwrap()).unwrap();
+ assert_eq!(bytes, expected);
+}
+
+/// A stream fn that records the request options and serves the scripted
+/// events as one stream (an empty script serves a closed, unsettled
+/// stream).
+fn capturing_stream_fn(
+ events: Vec<AssistantMessageEvent>,
+) -> (Arc<Mutex<Vec<StreamRequestOptions>>>, StreamFn) {
+ let captured: Arc<Mutex<Vec<StreamRequestOptions>>> = Arc::new(Mutex::new(Vec::new()));
+ let stream_fn: StreamFn = {
+ let captured = Arc::clone(&captured);
+ Arc::new(move |_model, _context, options| {
+ let captured = Arc::clone(&captured);
+ let events = events.clone();
+ Box::pin(async move {
+ captured.lock().unwrap().push(options);
+ let (handle, stream) = pa_agent::stream::event_stream();
+ for event in events {
+ handle.push(event);
+ }
+ handle.end(None);
+ Ok(Box::new(stream) as Box<dyn ModelStream>)
+ })
+ })
+ };
+ (captured, stream_fn)
+}
+
+fn terminal_event(reason: StopReason) -> AssistantMessageEvent {
+ let message = AssistantMessage {
+ content: Vec::new(),
+ api: "test".to_string(),
+ provider: "test".to_string(),
+ model: "m".to_string(),
+ response_model: None,
+ response_id: None,
+ diagnostics: None,
+ usage: Usage::zero(),
+ stop_reason: reason,
+ stop_reason_raw: None,
+ error_message: None,
+ timestamp: 0,
+ };
+ match reason {
+ StopReason::Error | StopReason::Aborted => AssistantMessageEvent::Error {
+ reason,
+ error: message,
+ },
+ _ => AssistantMessageEvent::Done { reason, message },
+ }
+}
+
+/// The request id a wrapped call carried (both headers present, equal).
+fn bound_request_id(captured: &Mutex<Vec<StreamRequestOptions>>) -> String {
+ let options = captured.lock().unwrap().first().expect("one call").clone();
+ let headers = options.headers.expect("the wrapped call carries headers");
+ let id = headers
+ .get(MODEL_REQUEST_ID_HEADER)
+ .expect("the request-id header");
+ assert_eq!(
+ id,
+ headers
+ .get(IDEMPOTENCY_KEY_HEADER)
+ .expect("the idempotency key")
+ );
+ assert_eq!(headers, model_request_headers(id));
+ id.clone()
+}
+
+async fn wrapped_call(
+ recorder: &Arc<SemanticEdgeRecorder>,
+ inner: StreamFn,
+) -> Box<dyn ModelStream> {
+ wrap_stream_fn(Arc::clone(recorder), inner)(
+ Model::unknown(),
+ LlmContext::default(),
+ StreamRequestOptions::default(),
+ )
+ .await
+ .expect("the wrapped stream starts")
+}
+
+#[tokio::test]
+async fn turn_requests_carry_both_headers_and_settle_by_stop_reason() {
+ let (identity, _dir) = identity("session-d");
+ let recorder = Arc::new(SemanticEdgeRecorder::open(identity.clone()));
+ // A stop stream commits, an error stream fails, and a dropped
+ // unsettled stream fails.
+ let (captured_stop, stop_fn) = capturing_stream_fn(vec![terminal_event(StopReason::Stop)]);
+ let (captured_error, error_fn) = capturing_stream_fn(vec![terminal_event(StopReason::Error)]);
+ let (captured_dropped, dropped_fn) = capturing_stream_fn(Vec::new());
+ let committed_id = {
+ let mut stream = wrapped_call(&recorder, stop_fn).await;
+ stream.result().await.expect("the stop result");
+ bound_request_id(&captured_stop)
+ };
+ let failed_id = {
+ let mut stream = wrapped_call(&recorder, error_fn).await;
+ stream.result().await.expect("the error result");
+ bound_request_id(&captured_error)
+ };
+ let dropped_id = {
+ let stream = wrapped_call(&recorder, dropped_fn).await;
+ let id = bound_request_id(&captured_dropped);
+ drop(stream);
+ id
+ };
+ assert_eq!(
+ read_ledger(&identity),
+ vec![
+ session_registered("session-d"),
+ request_started("session-d", &committed_id),
+ SemanticEdgeLedgerEvent::RequestFinished {
+ request_id: committed_id,
+ },
+ request_started("session-d", &failed_id),
+ SemanticEdgeLedgerEvent::RequestFailed {
+ request_id: failed_id,
+ },
+ request_started("session-d", &dropped_id),
+ SemanticEdgeLedgerEvent::RequestFailed {
+ request_id: dropped_id,
+ },
+ ]
+ );
+}
diff --git a/crates/pa-core/src/session_engine/side_question.rs b/crates/pa-core/src/session_engine/side_question.rs
index 4ca7c351b1..e9e95f06e9 100644
--- a/crates/pa-core/src/session_engine/side_question.rs
+++ b/crates/pa-core/src/session_engine/side_question.rs
@@ -111,11 +111,15 @@ fn assistant_text(message: &AssistantMessage) -> String {
/// Run one side question against a clone of the parent conversation.
///
-/// The run streams partial answers to `sink` (returning `false` aborts the
-/// run), honors `signal` for external aborts, and retries provider failures
-/// per `retry_policy`. It never mutates the parent agent or its history.
+/// The side calls run on `stream_fn` (TS `unwrapSemanticEdgeStreamFn`: the
+/// parent's pre-semantic fn, so a side call carries no request id and its
+/// ledger stays untouched). The run streams partial answers to `sink`
+/// (returning `false` aborts the run), honors `signal` for external
+/// aborts, and retries provider failures per `retry_policy`. It never
+/// mutates the parent agent or its history.
pub async fn run_side_question(
parent: &Arc<Agent>,
+ stream_fn: pa_agent::stream::StreamFn,
question: &str,
previous_turns: &[SideQuestionTurn],
retry_policy: &ProviderRetryPolicy,
@@ -129,12 +133,6 @@ pub async fn run_side_question(
"Select a model before asking a side question".to_string(),
);
}
- let Some(stream_fn) = parent.stream_fn().cloned() else {
- return SideQuestionResult::failed(
- String::new(),
- "Select a model before asking a side question".to_string(),
- );
- };
// Each turn re-clones the live main conversation, so follow-ups always see
// the newest main-thread context; earlier side turns replay after it.
@@ -570,8 +568,13 @@ mod tests {
signal: &AbortSignal,
sink: &SideQuestionSink,
) -> SideQuestionResult {
+ let stream_fn = parent
+ .stream_fn()
+ .cloned()
+ .expect("the parent agent has a stream fn");
run_side_question(
parent,
+ stream_fn,
question,
previous_turns,
&fast_retry_policy(),
diff --git a/crates/pa-core/src/session_engine/wiring.rs b/crates/pa-core/src/session_engine/wiring.rs
index 9ad3423ba5..1275d672fc 100644
--- a/crates/pa-core/src/session_engine/wiring.rs
+++ b/crates/pa-core/src/session_engine/wiring.rs
@@ -1,6 +1,6 @@
use super::{
auxiliary_model, compaction, compaction_exec, image_model_routing, ipython_state,
- provider_adapter, refine, telemetry, AgentSession, PromptBatchRow,
+ provider_adapter, refine, semantic_edges, telemetry, AgentSession, PromptBatchRow,
};
impl AgentSession {
@@ -205,4 +205,47 @@ impl AgentSession {
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
+
+ /// Install the session's semantic-edge recorder (the engine build's
+ /// handoff; the daemon's child registry and retry park read it back
+ /// through [`AgentSession::semantic_edges`]).
+ pub fn set_semantic_edges(
+ &self,
+ recorder: Option<std::sync::Arc<semantic_edges::SemanticEdgeRecorder>>,
+ ) {
+ *self
+ .semantic_edges
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner) = recorder;
+ }
+
+ /// The session's semantic-edge recorder, when the engine built the
+ /// session with a semantic identity.
+ #[must_use]
+ pub fn semantic_edges(&self) -> Option<std::sync::Arc<semantic_edges::SemanticEdgeRecorder>> {
+ self.semantic_edges
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .clone()
+ }
+
+ /// Install the pre-semantic stream fn calls outside session history run
+ /// on (TS `unwrapSemanticEdgeStreamFn`; the engine wires the
+ /// timing-instrumented fn it wrapped semantic edges around).
+ pub fn set_side_question_stream_fn(&self, stream_fn: pa_agent::stream::StreamFn) {
+ *self
+ .side_question_stream_fn
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(stream_fn);
+ }
+
+ /// The pre-semantic stream fn for calls outside session history (side
+ /// questions carry no request id).
+ #[must_use]
+ pub fn side_question_stream_fn(&self) -> Option<pa_agent::stream::StreamFn> {
+ self.side_question_stream_fn
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .clone()
+ }
}
diff --git a/crates/pa-core/tests/abort_kernel_cell.rs b/crates/pa-core/tests/abort_kernel_cell.rs
index 95a0d072a0..7f10e87313 100644
--- a/crates/pa-core/tests/abort_kernel_cell.rs
+++ b/crates/pa-core/tests/abort_kernel_cell.rs
@@ -153,6 +153,7 @@ async fn abort_during_a_kernel_cell_settles_the_turn_immediately() {
provider.push_text_turn("the cell completed");
let engine = create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
steering_mode: None,
follow_up_mode: None,
diff --git a/crates/pa-core/tests/turn_boundary_kernel.rs b/crates/pa-core/tests/turn_boundary_kernel.rs
index a4ba008d84..e030b82dde 100644
--- a/crates/pa-core/tests/turn_boundary_kernel.rs
+++ b/crates/pa-core/tests/turn_boundary_kernel.rs
@@ -193,6 +193,7 @@ async fn turn_boundary_host_requests_round_trip_through_a_real_kernel() {
provider.push_text_turn("boundary reached");
let engine = create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
diff --git a/crates/pa-daemon/src/acp/autorefine.rs b/crates/pa-daemon/src/acp/autorefine.rs
index acc0e7626e..e75a219e32 100644
--- a/crates/pa-daemon/src/acp/autorefine.rs
+++ b/crates/pa-daemon/src/acp/autorefine.rs
@@ -212,6 +212,7 @@ mod tests {
session_manager.materialize_session_file(Some(dir.path().join("sessions")));
let engine = std::sync::Arc::new(
create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
diff --git a/crates/pa-daemon/src/acp/compaction_arms/tests.rs b/crates/pa-daemon/src/acp/compaction_arms/tests.rs
index b367c0bd1a..acf910a5c8 100644
--- a/crates/pa-daemon/src/acp/compaction_arms/tests.rs
+++ b/crates/pa-daemon/src/acp/compaction_arms/tests.rs
@@ -68,6 +68,7 @@ async fn acp_test_bed(
let stream_fn = real_stream_fn(None, model.clone());
let engine = std::sync::Arc::new(
create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
diff --git a/crates/pa-daemon/src/acp/goal_continuation.rs b/crates/pa-daemon/src/acp/goal_continuation.rs
index d4d48c02de..7221fb747c 100644
--- a/crates/pa-daemon/src/acp/goal_continuation.rs
+++ b/crates/pa-daemon/src/acp/goal_continuation.rs
@@ -259,6 +259,7 @@ mod tests {
session_manager.materialize_session_file(Some(dir.path().join("sessions")));
let engine = std::sync::Arc::new(
create_session(SessionEngineConfig {
+ semantic_edges: None,
cron_store: None,
queued_steering_probe: None,
image_model_router: None,
diff --git a/crates/pa-daemon/src/agent_engine.rs b/crates/pa-daemon/src/agent_engine.rs
index 98bc2d5c43..af1a7de400 100644
--- a/crates/pa-daemon/src/agent_engine.rs
+++ b/crates/pa-daemon/src/agent_engine.rs
@@ -453,4 +453,12 @@ pub struct AgentSessionEngine {
/// this worker emits through one lazily-built client.
pub(crate) model_refusal_telemetry:
std::sync::Arc<crate::model_allowlist::ModelRefusalTelemetry>,
+ /// This session's semantic-edge identity (TS
+ /// `semanticEdgeLedgerPath`/`semanticParentSessionId`/
+ /// `semanticSpawnedByRequestId`): stamped by `configure_rlm_identity`
+ /// from the create's semantic spawn origin and read once per session
+ /// build, so every build's recorder reopens the same ledger and
+ /// re-registration stays idempotent.
+ pub(crate) semantic_identity:
+ std::sync::Mutex<Option<pa_core::session_engine::semantic_edges::SemanticEdgeIdentity>>,
}
diff --git a/crates/pa-daemon/src/agent_engine/lifecycle.rs b/crates/pa-daemon/src/agent_engine/lifecycle.rs
index 0518364b8b..ab8d8e8175 100644
--- a/crates/pa-daemon/src/agent_engine/lifecycle.rs
+++ b/crates/pa-daemon/src/agent_engine/lifecycle.rs
@@ -220,6 +220,7 @@ impl AgentSessionEngine {
auto_compaction_abort: std::sync::Mutex::new(None),
compaction_summary_sink: std::sync::Mutex::new(None),
model_refusal_telemetry,
+ semantic_identity: std::sync::Mutex::new(None),
})
}
@@ -472,6 +473,10 @@ impl AgentSessionEngine {
)));
*self.usage_producer.lock().expect("usage producer lock") =
Some(std::sync::Arc::clone(&built.rlm_usage));
+ // The semantic-edge handoff (the same per-build pattern): the
+ // settle watcher records a returned child's last committed
+ // request into this recorder.
+ children.set_semantic_edges(built.session.semantic_edges());
}
// The eager-abort target rides the same mirror (see
// [`Self::turn_agent`]).
@@ -1117,7 +1122,16 @@ impl AgentSessionEngine {
}
}) as pa_core::kernel::shared::BackgroundWorkSettledCallback
});
+ // The semantic-edge identity stamped by `configure_rlm_identity`
+ // (the create's provenance): every build's recorder reopens the
+ // same ledger, so a rebuild replays instead of re-registering.
+ let semantic_edges = self
+ .semantic_identity
+ .lock()
+ .expect("semantic identity lock")
+ .clone();
pa_core::session_engine::engine::create_session(SessionEngineConfig {
+ semantic_edges,
telemetry,
cwd,
// TS settings.imageModel routing: the daemon owns the routing
diff --git a/crates/pa-daemon/src/agent_engine/session_engine_impl.rs b/crates/pa-daemon/src/agent_engine/session_engine_impl.rs
index cdc3ccfe51..a8db5e8057 100644
--- a/crates/pa-daemon/src/agent_engine/session_engine_impl.rs
+++ b/crates/pa-daemon/src/agent_engine/session_engine_impl.rs
@@ -995,6 +995,46 @@ impl SessionEngine for AgentSessionEngine {
})
.unwrap_or((u64::from(DEFAULT_RLM_MAX_DEPTH), "default"));
*self.rlm_max_depth_source.lock().expect("depth source lock") = source;
+ // The semantic-edge identity (TS `semanticEdgeLedgerPath` +
+ // provenance): a spawned child's ledger lives in its rlm session
+ // dir (the session file's parent), a top-level session's in its
+ // artifact dir; the durable session id is the ledger identity
+ // (the in-memory engine manager's id is per-build). A session
+ // without a durable id records nothing.
+ let semantic_identity = identity.session_id.clone().map(|session_id| {
+ let rlm_session_dir = match &identity.semantic_spawn {
+ Some(_) => identity
+ .session_file
+ .as_deref()
+ .map(std::path::Path::new)
+ .and_then(std::path::Path::parent),
+ None => None,
+ };
+ let artifact_dir = identity
+ .session_file
+ .as_deref()
+ .map(std::path::Path::new)
+ .and_then(pa_core::session_engine::harness_digest::session_artifact_dir_for_log);
+ pa_core::session_engine::semantic_edges::SemanticEdgeIdentity {
+ session_id,
+ ledger_path: pa_core::session_engine::semantic_edges::semantic_edge_ledger_path(
+ rlm_session_dir,
+ artifact_dir.as_deref(),
+ ),
+ parent_session_id: identity
+ .semantic_spawn
+ .as_ref()
+ .and_then(|spawn| spawn.parent_session_id.clone()),
+ spawned_by_request_id: identity
+ .semantic_spawn
+ .as_ref()
+ .and_then(|spawn| spawn.spawned_by_request_id.clone()),
+ }
+ });
+ *self
+ .semantic_identity
+ .lock()
+ .expect("semantic identity lock") = semantic_identity;
if let Some(children) = &self.children {
let parent = ParentIdentity {
rlm_depth: identity.rlm_depth,
@@ -1064,10 +1104,28 @@ impl SessionEngine for AgentSessionEngine {
let question = request.question.clone();
let previous_turns = request.previous_turns;
let retry_policy = pa_core::session_engine::provider_retry::DEFAULT_PROVIDER_RETRY_POLICY;
+ // TS `unwrapSemanticEdgeStreamFn`: the side call runs on the
+ // session's pre-semantic stream fn, so it carries no request id
+ // and the ledger records nothing. The engine build always wires
+ // it; no fallback to the agent's own fn, which would leak the
+ // id-carrying wrapper into the side call.
+ let side_stream_fn = {
+ let guard = self.session.blocking_lock();
+ guard
+ .as_deref()
+ .and_then(|engine| engine.session.side_question_stream_fn())
+ };
+ let Some(side_stream_fn) = side_stream_fn else {
+ return SideQuestionOutcome::Failed {
+ answer: String::new(),
+ error: "Select a model before asking a side question".to_string(),
+ };
+ };
let result =
self.runtime
.block_on(pa_core::session_engine::side_question::run_side_question(
&agent,
+ side_stream_fn,
&question,
&previous_turns,
&retry_policy,
diff --git a/crates/pa-daemon/src/agent_engine/turn/model.rs b/crates/pa-daemon/src/agent_engine/turn/model.rs
index 71c80b06a1..b2726f8f46 100644
--- a/crates/pa-daemon/src/agent_engine/turn/model.rs
+++ b/crates/pa-daemon/src/agent_engine/turn/model.rs
@@ -148,9 +148,18 @@ impl AgentSessionEngine {
};
// Retry/failover adoption telemetry (TS `auto_retry_start` counting):
// retries increment `retry_count`, provider switches `failover_count`.
- let telemetry = {
+ // The semantic-edge recorder rides the same snapshot (TS
+ // `prepareTurnRetry` / `clearTurnRetry` ride the retry events: the
+ // parked id makes the retried call reuse the failed attempt's
+ // idempotency key).
+ let (telemetry, semantic_edges) = {
let guard = self.session.blocking_lock();
- guard.as_deref().and_then(|engine| engine.telemetry.clone())
+ (
+ guard.as_deref().and_then(|engine| engine.telemetry.clone()),
+ guard
+ .as_deref()
+ .and_then(|engine| engine.session.semantic_edges()),
+ )
};
// The failover-captured primary target state (TS `_backupModel`):
// the model, its thinking level, and its resolved request auth,
@@ -240,7 +249,25 @@ impl AgentSessionEngine {
|event| {
let mut emit = emit_cell.borrow_mut();
let telemetry = telemetry.clone();
+ let semantic_edges = semantic_edges.clone();
async move {
+ // TS parks the id at `auto_retry_start` and clears
+ // it at the settle (`_resolveRetry`), so a
+ // body-identical retry reuses the failed
+ // attempt's id; the parked id lives until the
+ // next turn mints over it otherwise.
+ if let Some(recorder) = &semantic_edges {
+ match &event {
+ pa_core::session_engine::auto_retry::AutoRetryEvent::Start {
+ ..
+ } => recorder.prepare_turn_retry(),
+ pa_core::session_engine::auto_retry::AutoRetryEvent::End {
+ ..
+ } => {
+ recorder.clear_turn_retry();
+ }
+ }
+ }
if let Some(telemetry) = &telemetry {
// One retry event in, one telemetry seam out: the
// Start counts the retry (plus a backup-provider
diff --git a/crates/pa-daemon/src/engine.rs b/crates/pa-daemon/src/engine.rs
index 310eded70a..7d5ceb2334 100644
--- a/crates/pa-daemon/src/engine.rs
+++ b/crates/pa-daemon/src/engine.rs
@@ -27,8 +27,8 @@ pub use wire::{
BashCompletionSink, BashConsumedNotice, BashConsumedSink, BranchSummaryOutcome,
BranchSummaryRequest, BranchSummaryRun, CompactionOutcome, CompactionRequest, CompactionRun,
EngineEvent, EngineModelSelection, GoalAdmissionSink, GoalContinuation, GoalTurnEndWork,
- PromptBatchRow, PromptRequest, RlmSessionIdentity, SavedSessionContext, SessionInputProbe,
- SideQuestionOutcome, SideQuestionRequest, SIDE_QUESTION_STATUS_CANCELLED,
+ PromptBatchRow, PromptRequest, RlmSessionIdentity, SavedSessionContext, SemanticSpawnOrigin,
+ SessionInputProbe, SideQuestionOutcome, SideQuestionRequest, SIDE_QUESTION_STATUS_CANCELLED,
SIDE_QUESTION_STATUS_COMPLETE, SIDE_QUESTION_STATUS_ERROR, SIDE_QUESTION_STATUS_RUNNING,
};
diff --git a/crates/pa-daemon/src/engine/wire.rs b/crates/pa-daemon/src/engine/wire.rs
index 2c3d54d01c..c21eca5272 100644
--- a/crates/pa-daemon/src/engine/wire.rs
+++ b/crates/pa-daemon/src/engine/wire.rs
@@ -329,6 +329,22 @@ pub struct RlmSessionIdentity {
/// `sessionConfig`; the harness analog carries the create's
/// `childScript` down the recursion). Product sessions carry `None`.
pub child_script: Option<String>,
+ /// The session's semantic-edge spawn origin (TS
+ /// `semanticParentSessionId` + `semanticSpawnedByRequestId`, carried
+ /// by a subagent create): `Some` only for a create whose runtime
+ /// metadata declares `kind: "subagent"` — a resumed saved subagent
+ /// file is a top-level runtime and spawns no edge, and a replacement
+ /// runtime has none.
+ pub semantic_spawn: Option<SemanticSpawnOrigin>,
+}
+
+/// A created session's semantic-edge provenance (TS
+/// `semanticParentSessionId`/`semanticSpawnedByRequestId`): the parent's
+/// durable session id and the request whose turn spawned this child.
+#[derive(Debug, Clone)]
+pub struct SemanticSpawnOrigin {
+ pub parent_session_id: Option<String>,
+ pub spawned_by_request_id: Option<String>,
}
/// The resource snapshot for a session without a resource surface (the TS
diff --git a/crates/pa-daemon/src/rlm_children.rs b/crates/pa-daemon/src/rlm_children.rs
index 98b5c99a3e..dd854798d6 100644
--- a/crates/pa-daemon/src/rlm_children.rs
+++ b/crates/pa-daemon/src/rlm_children.rs
@@ -379,6 +379,13 @@ struct SupervisorChildSessionsInner {
/// `/context` children immediately, not ride out the next background
/// refresh.
delete_notifier: std::sync::Mutex<Option<DeleteNotifier>>,
+ /// The parent session's semantic-edge recorder (wired once the session
+ /// engine is built; the settle watcher records a returned child's last
+ /// committed request into it). `None` until the build or for sessions
+ /// without a semantic identity.
+ semantic_edges: std::sync::Mutex<
+ Option<std::sync::Arc<pa_core::session_engine::semantic_edges::SemanticEdgeRecorder>>,
+ >,
}
impl Clone for SupervisorChildSessions {
@@ -413,6 +420,7 @@ impl SupervisorChildSessions {
model_refusal_telemetry,
usage_sink: std::sync::Mutex::new(None),
delete_notifier: std::sync::Mutex::new(None),
+ semantic_edges: std::sync::Mutex::new(None),
}),
}
}
@@ -467,6 +475,26 @@ impl SupervisorChildSessions {
*self.inner.usage_sink.lock().expect("usage sink lock") = Some(sink);
}
+ /// Wire the parent session's semantic-edge recorder (the per-build
+ /// handoff beside the usage sink): the settle watcher records a
+ /// returned child's last committed request into it.
+ ///
+ /// # Panics
+ ///
+ /// Panics when the semantic-edges mutex is poisoned.
+ pub fn set_semantic_edges(
+ &self,
+ recorder: Option<
+ std::sync::Arc<pa_core::session_engine::semantic_edges::SemanticEdgeRecorder>,
+ >,
+ ) {
+ *self
+ .inner
+ .semantic_edges
+ .lock()
+ .expect("semantic edges lock") = recorder;
+ }
+
/// Whether a spawn-name reservation currently holds `name` (the TS
/// test peeks `_pendingRlmSubagentSessionNames`; the reservation must
/// span the whole admission and release at its settle).
diff --git a/crates/pa-daemon/src/rlm_children/host.rs b/crates/pa-daemon/src/rlm_children/host.rs
index 3e6d1791d6..548b94fa64 100644
--- a/crates/pa-daemon/src/rlm_children/host.rs
+++ b/crates/pa-daemon/src/rlm_children/host.rs
@@ -123,6 +123,7 @@ impl RlmSubagentHost for SupervisorChildSessions {
thinking,
&cwd,
&child_dir,
+ request.spawned_by_request_id.as_deref(),
Some(runtime_metadata),
&identity,
)
diff --git a/crates/pa-daemon/src/rlm_children/lifecycle.rs b/crates/pa-daemon/src/rlm_children/lifecycle.rs
index 0c39f8aeac..1ae2ecc28d 100644
--- a/crates/pa-daemon/src/rlm_children/lifecycle.rs
+++ b/crates/pa-daemon/src/rlm_children/lifecycle.rs
@@ -68,6 +68,10 @@ impl SupervisorChildSessionsInner {
thinking: Option<&str>,
cwd: &str,
session_dir: &Path,
+ // The parent's in-flight turn request the child anchors to (TS
+ // `spawnedByRequestId` rides the child's session options, never
+ // the runtime metadata).
+ spawned_by_request_id: Option<&str>,
runtime_metadata: Option<Value>,
identity: &ParentIdentity,
) -> Result<CreatedChild> {
@@ -89,6 +93,9 @@ impl SupervisorChildSessionsInner {
if let Some(parent_file) = &identity.session_file {
config["parentSessionPath"] = json!(parent_file);
}
+ if let Some(request_id) = spawned_by_request_id {
+ config["spawnedByRequestId"] = json!(request_id);
+ }
if let Some(script) = &identity.child_script {
config["script"] = json!(script);
// The scripted engine rides the identity down the recursion
@@ -168,6 +175,7 @@ impl SupervisorChildSessionsInner {
thinking,
cwd,
session_dir,
+ /*spawned_by_request_id*/ None,
runtime_metadata,
identity,
)
@@ -436,6 +444,10 @@ impl SupervisorChildSessionsInner {
// notice rides the parent's follow-up route (TS: the run
// task's `finally` flushes pending usage at settlement).
self.emit_child_usage(record).await;
+ // TS records the return before delivering the notice: the
+ // pending edge must be on the parent's ledger before the
+ // notice's follow-up turn mints its own request.
+ self.record_child_return(record).await;
// Only a successful run completes the display (TS
// `completeRlmSubagentRuntime`); a cancelled or failed run
// stays `running`, which a restart relists as `error`.
@@ -508,6 +520,51 @@ impl SupervisorChildSessionsInner {
}
}
+ /// Record a settled child's return in the parent's semantic-edge ledger
+ /// (TS `recordChildReturned` at the run-settle sites): the child's last
+ /// committed request, read from the child's own ledger file (the
+ /// cross-process form of TS's in-process
+ /// `child.semanticEdges.lastCommittedRequestId`). Only a `done` or
+ /// `error` settle returns — TS never records a cancelled run (its done
+ /// arm throws on `run.error` and the record gates on `status ===
+ /// "error"`). A child without a durable session id, or a parent
+ /// without a recorder, records nothing.
+ async fn record_child_return(&self, record: &Arc<Mutex<ChildRecord>>) {
+ let recorder = self
+ .semantic_edges
+ .lock()
+ .expect("semantic edges lock")
+ .clone();
+ let Some(recorder) = recorder else {
+ return;
+ };
+ let (child_session_id, child_dir) = {
+ let record = record.lock().await;
+ if !matches!(record.settled_status, Some("done" | "error")) {
+ return;
+ }
+ (record.session_id.clone(), record.session_dir.clone())
+ };
+ let Some(child_session_id) = child_session_id else {
+ return;
+ };
+ let ledger_path = pa_core::session_engine::semantic_edges::semantic_edge_ledger_path(
+ Some(Path::new(&child_dir)),
+ None,
+ );
+ // The file read stays off the async workers (the usage walk's
+ // discipline).
+ let last_committed = tokio::task::spawn_blocking(move || {
+ ledger_path
+ .as_deref()
+ .and_then(pa_core::session_engine::semantic_edges::last_committed_request_id)
+ })
+ .await
+ .ok()
+ .flatten();
+ recorder.record_child_returned(&child_session_id, last_committed);
+ }
+
/// Deliver the no-reply terminal notice for a settled child that never
/// sent an agent message to the parent. Exactly-once: the record's
/// notice claim collapses the races between the watcher, a natural
@@ -576,6 +633,10 @@ impl SupervisorChildSessionsInner {
record.error = Some(error);
message
};
+ // TS records a failed child's return too (`recordChildReturned` in
+ // the thrown-run arm): a child that committed requests before
+ // failing still returns them; a zero-commit child records nothing.
+ self.record_child_return(record).await;
self.deliver_terminal_notice(message).await;
self.fire_settle_hook(record).await;
true
diff --git a/crates/pa-daemon/src/rlm_children/spawn_name_reservation_tests.rs b/crates/pa-daemon/src/rlm_children/spawn_name_reservation_tests.rs
index 5b002cbc55..d02ac25529 100644
--- a/crates/pa-daemon/src/rlm_children/spawn_name_reservation_tests.rs
+++ b/crates/pa-daemon/src/rlm_children/spawn_name_reservation_tests.rs
@@ -147,6 +147,7 @@ fn spawn_request(name: &str, prompt: &str) -> RlmSpawnRequest {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
}
}
diff --git a/crates/pa-daemon/src/rlm_children/watch_tests.rs b/crates/pa-daemon/src/rlm_children/watch_tests.rs
index a5adc8e842..7bea6b1412 100644
--- a/crates/pa-daemon/src/rlm_children/watch_tests.rs
+++ b/crates/pa-daemon/src/rlm_children/watch_tests.rs
@@ -301,6 +301,7 @@ async fn spawn_child(sessions: &SupervisorChildSessions) -> RlmSpawnHandle {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn must succeed against the fake supervisor")
diff --git a/crates/pa-daemon/src/supervisor/worker_lifecycle.rs b/crates/pa-daemon/src/supervisor/worker_lifecycle.rs
index fbf04bae27..2ce8ab0891 100644
--- a/crates/pa-daemon/src/supervisor/worker_lifecycle.rs
+++ b/crates/pa-daemon/src/supervisor/worker_lifecycle.rs
@@ -254,6 +254,10 @@ impl Supervisor {
// The scripted-parent verification seam: a dropped key leaves
// spawned children scriptless.
"childScript",
+ // The semantic-edge spawn anchor rides the durable create so a
+ // respawned child keeps its provenance (its ledger
+ // re-registers idempotently either way).
+ "spawnedByRequestId",
"systemPrompt",
"appendSystemPrompt",
"skills",
diff --git a/crates/pa-daemon/src/worker/create.rs b/crates/pa-daemon/src/worker/create.rs
index c0dd01e5d2..53543ab199 100644
--- a/crates/pa-daemon/src/worker/create.rs
+++ b/crates/pa-daemon/src/worker/create.rs
@@ -158,26 +158,41 @@ impl Worker {
// The subagent runtime identity (TS `runtimeMetadata` on the create
// command): the child id and the parent's live/persisted ids ride
// the session summaries so the roster can key children
- // `parentPath#childId` like TS `rosterAgentIdForSummary`.
- let (rlm_child_id, parent_active_session_id, parent_session_id) = match payload
- .get("runtimeMetadata")
- {
- Some(metadata) if metadata.get("kind").and_then(Value::as_str) == Some("subagent") => (
- metadata
- .get("rlmChildId")
- .and_then(Value::as_str)
- .map(str::to_string),
- metadata
- .get("parentActiveSessionId")
- .and_then(Value::as_str)
- .map(str::to_string),
- metadata
- .get("parentSessionId")
- .and_then(Value::as_str)
- .map(str::to_string),
- ),
- _ => (None, None, None),
- };
+ // `parentPath#childId` like TS `rosterAgentIdForSummary`. The
+ // semantic spawn origin (TS `semanticParentSessionId` +
+ // `semanticSpawnedByRequestId`) exists only for this arm: a
+ // resumed saved subagent file is a top-level runtime and spawns
+ // no edge.
+ let (rlm_child_id, parent_active_session_id, parent_session_id, semantic_spawn) =
+ match payload.get("runtimeMetadata") {
+ Some(metadata)
+ if metadata.get("kind").and_then(Value::as_str) == Some("subagent") =>
+ {
+ let parent_session_id = metadata
+ .get("parentSessionId")
+ .and_then(Value::as_str)
+ .map(str::to_string);
+ (
+ metadata
+ .get("rlmChildId")
+ .and_then(Value::as_str)
+ .map(str::to_string),
+ metadata
+ .get("parentActiveSessionId")
+ .and_then(Value::as_str)
+ .map(str::to_string),
+ parent_session_id.clone(),
+ Some(crate::engine::SemanticSpawnOrigin {
+ parent_session_id,
+ spawned_by_request_id: payload
+ .get("spawnedByRequestId")
+ .and_then(Value::as_str)
+ .map(str::to_string),
+ }),
+ )
+ }
+ _ => (None, None, None, None),
+ };
let thinking = payload
.get("thinking")
.and_then(Value::as_str)
@@ -643,6 +658,7 @@ impl Worker {
session_file: summary.session_file.clone(),
thinking,
child_script: child_script.clone(),
+ semantic_spawn,
}) {
return response_failure(None, "create", &error.to_string(), None);
}
diff --git a/crates/pa-daemon/src/worker/lifecycle.rs b/crates/pa-daemon/src/worker/lifecycle.rs
index abd1160f78..d444bc9896 100644
--- a/crates/pa-daemon/src/worker/lifecycle.rs
+++ b/crates/pa-daemon/src/worker/lifecycle.rs
@@ -364,6 +364,8 @@ impl Worker {
session_file: summary.session_file.clone(),
thinking: None,
child_script,
+ // A TS replacement runtime has no semantic spawn.
+ semantic_spawn: None,
}) {
Ok(()) => self.reseed_rlm_children().await,
Err(error) => eprintln!("pa-daemon: replacement identity rebind failed: {error:#}"),
diff --git a/crates/pa-daemon/tests/agent_family_e2e.rs b/crates/pa-daemon/tests/agent_family_e2e.rs
index 38edafb38d..82d74d3596 100644
--- a/crates/pa-daemon/tests/agent_family_e2e.rs
+++ b/crates/pa-daemon/tests/agent_family_e2e.rs
@@ -469,6 +469,7 @@ async fn parent_child_agent_message_round_trip_end_to_end() {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn the child");
@@ -855,6 +856,7 @@ async fn family_edges_never_cross_families_end_to_end() {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn the child");
@@ -912,7 +914,12 @@ async fn family_edges_never_cross_families_end_to_end() {
)
.expect("kid artifact dir")
.flatten()
- .filter(|entry| entry.path().extension().and_then(|ext| ext.to_str()) == Some("jsonl"))
+ // The semantic-edge ledger rides the same dir (TS: the child's
+ // rlm session dir owns it); only the durable session row counts.
+ .filter(|entry| {
+ entry.path().extension().and_then(|ext| ext.to_str()) == Some("jsonl")
+ && entry.file_name().to_string_lossy() != "semantic-edges.jsonl"
+ })
.collect();
assert_eq!(kid_files.len(), 1, "one kid session file: {kid_files:?}");
kids.push((
@@ -1012,6 +1019,7 @@ async fn family_edges_never_cross_families_end_to_end() {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn the grandchild");
diff --git a/crates/pa-daemon/tests/agents_view_roster_e2e.rs b/crates/pa-daemon/tests/agents_view_roster_e2e.rs
index 155bc82823..1fc26564c2 100644
--- a/crates/pa-daemon/tests/agents_view_roster_e2e.rs
+++ b/crates/pa-daemon/tests/agents_view_roster_e2e.rs
@@ -451,6 +451,7 @@ async fn rlm_children_key_the_roster_by_parent_path_and_child_id() {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn child");
diff --git a/crates/pa-daemon/tests/idle_passivation_e2e.rs b/crates/pa-daemon/tests/idle_passivation_e2e.rs
index 66aba37dab..770a56ec63 100644
--- a/crates/pa-daemon/tests/idle_passivation_e2e.rs
+++ b/crates/pa-daemon/tests/idle_passivation_e2e.rs
@@ -297,6 +297,7 @@ async fn a_settled_child_passivates_stays_listable_and_revives_by_agent_message(
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn the child");
diff --git a/crates/pa-daemon/tests/rlm_children_e2e.rs b/crates/pa-daemon/tests/rlm_children_e2e.rs
index 14de1c9db4..1038ef71ab 100644
--- a/crates/pa-daemon/tests/rlm_children_e2e.rs
+++ b/crates/pa-daemon/tests/rlm_children_e2e.rs
@@ -249,6 +249,7 @@ fn spawn_request(name: &str, prompt: &str) -> RlmSpawnRequest {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
}
}
diff --git a/crates/pa-daemon/tests/rlm_children_parent_death_e2e.rs b/crates/pa-daemon/tests/rlm_children_parent_death_e2e.rs
index d388be3128..0f798d133c 100644
--- a/crates/pa-daemon/tests/rlm_children_parent_death_e2e.rs
+++ b/crates/pa-daemon/tests/rlm_children_parent_death_e2e.rs
@@ -64,6 +64,8 @@ use std::path::{Path, PathBuf};
use std::process::{Child, Command, Stdio};
use std::time::{Duration, Instant};
+use pa_core::session_engine::semantic_edges::SemanticEdgeLedgerEvent as LedgerEvent;
+
use serde_json::{json, Value};
struct Daemon {
@@ -289,12 +291,15 @@ fn run_turn(client: &mut Client, session_id: &str, message: &str, id: &str) {
assert_eq!(idle["success"], true, "wait_for_idle failed: {idle}");
}
-/// Poll for a kernel cell's receipt content (the cell writes its verdict).
+/// Poll for a kernel cell's receipt content (the cell writes its verdict;
+/// an empty read is the create-before-write window, not a verdict yet).
fn await_receipt(receipt: &Path) -> String {
let deadline = Instant::now() + Duration::from_mins(1);
loop {
if let Ok(content) = std::fs::read_to_string(receipt) {
- return content;
+ if !content.is_empty() {
+ return content;
+ }
}
assert!(
Instant::now() < deadline,
@@ -665,3 +670,225 @@ fn sigkill_keeps_a_created_root_session_running() {
});
assert_eq!(survivor["sessionName"], "rootkid");
}
+
+/// The kernel cell of the spawn turn for the semantic-edge e2e: spawn one
+/// RLM child through the product surface and record its id + session dir.
+fn semantic_spawn_cell(receipt: &Path, error_receipt: &Path) -> String {
+ format!(
+ "import json, traceback\ntry:\n handle = await rlm.spawn(\"child task text\", name=\"kid\")\n open({receipt:?}, \"w\").write(json.dumps({{\"rlm_child_id\": handle.rlm_child_id, \"session_dir\": str(handle.session_dir)}}))\n print(handle.rlm_child_id)\nexcept Exception:\n open({error_receipt:?}, \"w\").write(traceback.format_exc())\n raise",
+ receipt = receipt.display().to_string(),
+ error_receipt = error_receipt.display().to_string(),
+ )
+}
+
+/// Parse one semantic-edge ledger file into its events. A file that does
+/// not exist yet reads as empty: the settle poll runs ahead of the
+/// parent's return recording.
+fn semantic_ledger(path: &Path) -> Vec<LedgerEvent> {
+ let Ok(contents) = std::fs::read_to_string(path) else {
+ return Vec::new();
+ };
+ contents
+ .lines()
+ .filter(|line| !line.is_empty())
+ .map(|line| serde_json::from_str(line).expect("ledger line"))
+ .collect()
+}
+
+/// A spawned child's ledger names the spawning request, and the parent
+/// records the child's return before its next request starts (TS
+/// `semanticParentSessionId`/`spawnedByRequestId` +
+/// `recordChildReturned`; the spawn runs mid-turn through the product
+/// `rlm.spawn` surface, and both engines are real over the faux
+/// provider).
+#[test]
+fn a_spawned_child_ledger_names_its_spawning_request_and_the_parent_records_the_return() {
+ let Some(kernel_python) = kernel_python() else {
+ return;
+ };
+ let dir = tempfile::TempDir::new().expect("temp dir");
+ let agent_dir = dir.path().join("agent");
+ std::fs::create_dir_all(&agent_dir).expect("agent dir");
+ let socket = dir.path().join("supervisor.sock");
+ let receipts = dir.path().join("receipts");
+ std::fs::create_dir_all(&receipts).expect("receipts dir");
+ let spawn_receipt = receipts.join("spawn.json");
+ let spawn_error = receipts.join("spawn.error");
+
+ // A real-engine child over the faux provider (the same engine choice
+ // as the parent): it builds a session, records its own ledger, and
+ // settles with its scripted reply.
+ let child_script = dir.path().join("child.json");
+ std::fs::write(
+ &child_script,
+ json!({
+ "engine": "faux",
+ "responses": [ { "text": "child reply", "delayMs": 30 } ],
+ })
+ .to_string(),
+ )
+ .expect("write child script");
+ let parent_script = write_parent_script(
+ dir.path(),
+ &semantic_spawn_cell(&spawn_receipt, &spawn_error),
+ );
+ let _daemon = spawn_supervisor(&socket, &agent_dir, &kernel_python);
+ wait_socket_ready(&socket);
+ let (mut client, hello) = Client::connect(&socket);
+ assert_eq!(hello["type"], "daemon_hello");
+ let parent = create_parent(&mut client, dir.path(), &parent_script, &child_script, "c1");
+ let parent_id = parent["activeSessionId"]
+ .as_str()
+ .or_else(|| parent["id"].as_str())
+ .expect("parent active session id")
+ .to_string();
+ let parent_session_id = parent["sessionId"]
+ .as_str()
+ .expect("parent session id")
+ .to_string();
+ let parent_session_file = parent["sessionFile"]
+ .as_str()
+ .expect("parent session file")
+ .to_string();
+
+ // Turn 1: the kernel cell spawns the child mid-turn through the
+ // product `rlm.spawn` surface.
+ run_turn(&mut client, &parent_id, "spawn the kid", "t1");
+ let spawned: Value =
+ serde_json::from_str(&await_receipt(&spawn_receipt)).expect("spawn receipt json");
+ assert!(
+ !spawn_error.exists(),
+ "the spawn cell failed: {}",
+ std::fs::read_to_string(&spawn_error).unwrap_or_default()
+ );
+ let child_id = spawned["rlm_child_id"]
+ .as_str()
+ .expect("child id")
+ .to_string();
+ let child_session_dir = spawned["session_dir"]
+ .as_str()
+ .expect("child session dir")
+ .to_string();
+
+ // The child settles (its scripted reply ends its run), then its
+ // no-reply notice rides the parent's follow-up route.
+ // The registry row carries the RAW run status (`done`, not the
+ // kernel roster's `completed`).
+ let settle_deadline = Instant::now() + Duration::from_mins(2);
+ loop {
+ if rlm_children_rows(&mut client, "g1", &parent_id)
+ .into_iter()
+ .any(|row| row["id"] == json!(child_id) && row["status"] == "done")
+ {
+ break;
+ }
+ assert!(
+ Instant::now() < settle_deadline,
+ "the child never settled: rows {:?}; agent dir {}",
+ rlm_children_rows(&mut client, "g1", &parent_id),
+ agent_dir.display()
+ );
+ std::thread::sleep(Duration::from_millis(200));
+ }
+ // The ledger paths are spelled independently of the product's
+ // derivation on purpose: byte-compatible LOCATIONS are part of the TS
+ // parity contract this e2e pins.
+ let parent_ledger_path = std::path::Path::new(&parent_session_file)
+ .parent()
+ .and_then(Path::parent)
+ .map(|sessions| sessions.join("session-artifacts").join(&parent_session_id))
+ .map(|artifacts| artifacts.join("semantic-edges.jsonl"))
+ .expect("parent ledger path");
+ let child_ledger_path = Path::new(&child_session_dir).join("semantic-edges.jsonl");
+ // The registry marks `done` before the parent records the return, and
+ // the notice's follow-up turn starts later still: poll until the
+ // parent ledger holds the return AND a later request (the same
+ // deadline; the terminal shape, not a fixed delay).
+ let (parent_ledger, child_ledger) = loop {
+ let parent_ledger = semantic_ledger(&parent_ledger_path);
+ let child_ledger = semantic_ledger(&child_ledger_path);
+ let returned_at = parent_ledger
+ .iter()
+ .position(|event| matches!(event, LedgerEvent::ChildReturned { .. }));
+ let next_turn_started = returned_at.is_some_and(|at| {
+ parent_ledger[at + 1..]
+ .iter()
+ .any(|event| matches!(event, LedgerEvent::RequestStarted { .. }))
+ });
+ if next_turn_started {
+ break (parent_ledger, child_ledger);
+ }
+ assert!(
+ Instant::now() < settle_deadline,
+ "the parent never recorded the return and its notice turn: parent {parent_ledger:?}; child {child_ledger:?}"
+ );
+ std::thread::sleep(Duration::from_millis(200));
+ };
+
+ // The parent's first turn is the spawning request (the cell runs
+ // inside it, so the anchor names it).
+ let spawning_request = parent_ledger
+ .iter()
+ .find_map(|event| match event {
+ LedgerEvent::RequestStarted {
+ request_id,
+ compaction_id: None,
+ ..
+ } => Some(request_id.clone()),
+ _ => None,
+ })
+ .expect("the parent's first request_started");
+ let child_session_id = child_ledger_session_id(&child_ledger);
+ assert_eq!(
+ child_ledger.first(),
+ Some(&LedgerEvent::SessionRegistered {
+ session_id: child_session_id.clone(),
+ parent_session_id: Some(parent_session_id),
+ spawned_by_request_id: Some(spawning_request.clone()),
+ })
+ );
+ let child_last_committed = child_ledger
+ .iter()
+ .rev()
+ .find_map(|event| match event {
+ LedgerEvent::RequestFinished { request_id } => Some(request_id.clone()),
+ _ => None,
+ })
+ .expect("the child committed its reply turn");
+ // The parent recorded the child's return with the child's last
+ // committed request, after the spawning turn committed and BEFORE the
+ // notice's follow-up turn minted the parent's next request (the
+ // pending edge must exist before that turn's request_started).
+ let returned_at = parent_ledger
+ .iter()
+ .position(|event| {
+ matches!(
+ event,
+ LedgerEvent::ChildReturned {
+ session_id: _,
+ child_session_id: returned_child,
+ request_id,
+ } if returned_child == &child_session_id && request_id == &child_last_committed
+ )
+ })
+ .unwrap_or_else(|| panic!("the parent recorded the child's return: {parent_ledger:?}"));
+ assert!(
+ parent_ledger[..returned_at]
+ .iter()
+ .any(|event| matches!(event, LedgerEvent::RequestFinished { request_id } if request_id == &spawning_request)),
+ "the spawning turn committed before the return: {parent_ledger:?}"
+ );
+}
+
+/// The durable session id the child's `session_registered` names (the
+/// parent-side `child_returned` assertions pin the same id across both
+/// ledgers).
+fn child_ledger_session_id(ledger: &[LedgerEvent]) -> String {
+ ledger
+ .iter()
+ .find_map(|event| match event {
+ LedgerEvent::SessionRegistered { session_id, .. } => Some(session_id.clone()),
+ _ => None,
+ })
+ .expect("the child registered")
+}
diff --git a/crates/pa-daemon/tests/rlm_roster_walk_e2e.rs b/crates/pa-daemon/tests/rlm_roster_walk_e2e.rs
index b662495dc6..0b1461654f 100644
--- a/crates/pa-daemon/tests/rlm_roster_walk_e2e.rs
+++ b/crates/pa-daemon/tests/rlm_roster_walk_e2e.rs
@@ -377,6 +377,7 @@ async fn subscribe_after_spawn_then_shutdown_seeds_the_passive_child() {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
})
.await
.expect("spawn child");
diff --git a/crates/pa-daemon/tests/rlm_spawn_replacement_e2e.rs b/crates/pa-daemon/tests/rlm_spawn_replacement_e2e.rs
index f791a036b9..0f7a51214e 100644
--- a/crates/pa-daemon/tests/rlm_spawn_replacement_e2e.rs
+++ b/crates/pa-daemon/tests/rlm_spawn_replacement_e2e.rs
@@ -268,6 +268,7 @@ fn spawn_request(name: &str, prompt: &str) -> RlmSpawnRequest {
model: None,
thinking: None,
cell_source_code: None,
+ spawned_by_request_id: None,
}
}
diff --git a/crates/pa-tui/src/interactive.rs b/crates/pa-tui/src/interactive.rs
index d958d17fc9..ac6cab7402 100644
--- a/crates/pa-tui/src/interactive.rs
+++ b/crates/pa-tui/src/interactive.rs
@@ -562,6 +562,11 @@ enum UiInput {
/// the source).
Mouse(crate::mouse::MouseEvent),
Submit(String),
+ /// The headless `SubmitAndSettle` step (see [`HeadlessStep`]).
+ SubmitAndSettle {
+ text: String,
+ timeout_ms: u64,
+ },
/// One materialized input-idle tick (the headless `SettleIdle` step).
SettleIdle,
WaitIdle {
diff --git a/crates/pa-tui/src/interactive/headless.rs b/crates/pa-tui/src/interactive/headless.rs
index bd81758977..2523fd6888 100644
--- a/crates/pa-tui/src/interactive/headless.rs
+++ b/crates/pa-tui/src/interactive/headless.rs
@@ -25,6 +25,19 @@ pub struct HeadlessPlan {
pub enum HeadlessStep {
/// Submit text (the same editor submit path as a user typing it).
Submit(String),
+ /// Submit `text` as a `prompt_and_wait` and hold until this run has
+ /// processed every event the turn emitted (each daemon request and the
+ /// event drain are each bounded by `timeout_ms`):
+ /// the daemon answers the wait only at the turn's full settle (after
+ /// its queue-projection update), `get_rlm_children` then reports the
+ /// session's final event sequence, and the barrier releases once the
+ /// run's live tracker reaches it. The supervisor races its response
+ /// and event queues in one select, so the barrier compares sequence
+ /// values instead of trusting arrival order. The run is parked while
+ /// the turn runs (the loop neither paints nor drains events during
+ /// the submit); use `Submit` to observe mid-turn frames. `Submit`
+ /// stays the composer path.
+ SubmitAndSettle { text: String, timeout_ms: u64 },
/// Type text character by character (raw editor input, so autocomplete
/// and editor state react exactly as to a keystroke).
Type(String),
diff --git a/crates/pa-tui/src/interactive/onboarding.rs b/crates/pa-tui/src/interactive/onboarding.rs
index aa4eba3d96..e39e11243b 100644
--- a/crates/pa-tui/src/interactive/onboarding.rs
+++ b/crates/pa-tui/src/interactive/onboarding.rs
@@ -338,6 +338,7 @@ async fn drive_onboarding_pane(
// (the headless harness replays them against the session
// screen once the pane releases).
UiInput::Submit(_)
+ | UiInput::SubmitAndSettle { .. }
| UiInput::SettleIdle
| UiInput::Mouse(_)
| UiInput::WaitIdle { .. }
diff --git a/crates/pa-tui/src/interactive/render.rs b/crates/pa-tui/src/interactive/render.rs
index 0e41d4f58b..f51c636d08 100644
--- a/crates/pa-tui/src/interactive/render.rs
+++ b/crates/pa-tui/src/interactive/render.rs
@@ -257,6 +257,14 @@ impl Renderer {
return;
}
}
+ HeadlessStep::SubmitAndSettle { text, timeout_ms } => {
+ if ui_tx
+ .send(UiInput::SubmitAndSettle { text, timeout_ms })
+ .is_err()
+ {
+ return;
+ }
+ }
HeadlessStep::Type(text) => {
for key in typed_keys(&text) {
if ui_tx.send(UiInput::Key(key)).is_err() {
diff --git a/crates/pa-tui/src/interactive/run.rs b/crates/pa-tui/src/interactive/run.rs
index c774c488d3..b04a79e9b4 100644
--- a/crates/pa-tui/src/interactive/run.rs
+++ b/crates/pa-tui/src/interactive/run.rs
@@ -150,6 +150,61 @@ async fn run_interactive_route(
}
}
+/// The `SubmitAndSettle` barrier's daemon round trip: submit the message
+/// as a `prompt_and_wait`, then read the session's event sequence through
+/// `get_rlm_children` — the one read-only command that reports it. Both
+/// requests are bounded by `timeout_ms`.
+async fn settled_sequence(
+ client: &DaemonClient,
+ active_session_id: String,
+ message: String,
+ timeout_ms: u64,
+) -> anyhow::Result<u64> {
+ let input = pa_types::daemon::PromptInput {
+ content: None,
+ images: None,
+ streaming_behavior: Some(pa_types::daemon::StreamingBehavior::Steer),
+ queue_if_busy: Some(true),
+ expand_prompt_templates: None,
+ source: None,
+ agent_message_id: None,
+ custom_message: None,
+ queue_key: None,
+ prefix_messages: None,
+ admission_id: None,
+ rlm_notice_nonce: None,
+ };
+ let waited = client
+ .request_with_timeout(
+ pa_types::daemon::DaemonCommand::PromptAndWait {
+ id: None,
+ active_session_id: active_session_id.clone(),
+ message,
+ input,
+ rest: serde_json::Map::default(),
+ },
+ timeout_ms,
+ )
+ .await?;
+ anyhow::ensure!(waited.success, "prompt_and_wait failed: {:?}", waited.error);
+ let children = client
+ .request_with_timeout(
+ pa_types::daemon::DaemonCommand::GetRlmChildren {
+ id: None,
+ active_session_id,
+ rest: serde_json::Map::default(),
+ },
+ timeout_ms,
+ )
+ .await?;
+ children
+ .data
+ .as_ref()
+ .and_then(|data| data.get("eventSequence"))
+ .and_then(serde_json::Value::as_u64)
+ .ok_or_else(|| anyhow::anyhow!("get_rlm_children carried no eventSequence"))
+}
+
async fn run_interactive_surface(
options: InteractiveOptions,
ui: UiMode,
@@ -631,6 +686,8 @@ async fn run_interactive_surface(
let mut hint_painted = false;
let mut running = true;
let mut wait_idle_deadline: Option<Instant> = None;
+ // The headless `SubmitAndSettle` barrier's target and deadline.
+ let mut settle_target: Option<(u64, Instant)> = None;
// The headless render barrier's armed state: its deadline, and the
// frames captured at arming (the `WaitRender` condition scans only
// frames rendered after the barrier became the queue's head, so a
@@ -741,6 +798,45 @@ async fn run_interactive_surface(
wait_idle_deadline = None;
pending.pop_front();
}
+ } else if let Some((text, timeout_ms)) = match pending.front() {
+ Some(UiInput::SubmitAndSettle { text, timeout_ms }) => {
+ Some((text.clone(), *timeout_ms))
+ }
+ _ => None,
+ } {
+ // The supervisor races its response and event queues in
+ // one select, so the response arriving proves nothing:
+ // hold until this run has processed the settled sequence.
+ let Some((settled, deadline)) = settle_target else {
+ match settled_sequence(
+ &session.client,
+ session.active_session_id.clone(),
+ text,
+ timeout_ms,
+ )
+ .await
+ {
+ Ok(settled) => {
+ settle_target =
+ Some((settled, Instant::now() + Duration::from_millis(timeout_ms)));
+ }
+ Err(error) => {
+ session.note(&format!("settle barrier failed: {error:#}"), &mut view);
+ pending.pop_front();
+ }
+ }
+ continue;
+ };
+ if session.last_event_sequence >= settled {
+ settle_target = None;
+ pending.pop_front();
+ } else if Instant::now() > deadline {
+ session.note("timed out waiting for the turn to settle", &mut view);
+ settle_target = None;
+ pending.pop_front();
+ } else {
+ inputs_pending = false;
+ }
} else if let Some((needle, timeout_ms, present)) = match pending.front() {
Some(UiInput::WaitRender { needle, timeout_ms }) => {
Some((needle.clone(), *timeout_ms, true))
@@ -1029,7 +1125,9 @@ async fn run_interactive_surface(
view.set_terminal_rows(height);
}
}
- UiInput::WaitIdle { .. } => unreachable!("barrier handled above"),
+ UiInput::WaitIdle { .. } | UiInput::SubmitAndSettle { .. } => {
+ unreachable!("barrier handled above")
+ }
}
// Paint the handled input in this iteration: the select below can
// otherwise wait out its 50ms tick before the next draw, and
@@ -1174,9 +1272,13 @@ async fn run_interactive_surface(
if session.dirty && render_deadline.is_none() {
render_deadline = Some(Instant::now());
}
- for deadline in [wait_idle_deadline, wait_render_deadline]
- .into_iter()
- .flatten()
+ for deadline in [
+ wait_idle_deadline,
+ wait_render_deadline,
+ settle_target.map(|(_, deadline)| deadline),
+ ]
+ .into_iter()
+ .flatten()
{
if render_deadline.is_none_or(|armed| deadline < armed) {
render_deadline = Some(deadline);