1. 1use std::collections::{BTreeMap, HashMap, HashSet};
2. 2use std::sync::{Mutex, OnceLock};
3. 3
4. 4pub(crate) use vak_intent::control::{clean_scaffolding, is_scaffolding_line};
5. 5
6. 6use vak_agent::AgentEvent;
7. 7use vak_delivery::{
8. 8 ArtifactRef, ArtifactStatus, DeliveryAction, OutputContent, OutputItem, OutputKind,
9. 9 OutputProvenance, OutputRole, OutputStatus, OutputStreamEvent, OutputTimeline,
10. 10 PresentationDocument, PresentationPlanner, ResultOutcome, SignalContext, built_in_adapters,
11. 11 compile_markdown, link_previews_from_text, signals_from_context, structured_markdown,
12. 12 structured_outputs_from_text, structured_outputs_from_tool_result_with,
13. 13};
14. 14
15. 15fn status_for_completion(completion: Option<&str>) -> OutputStatus {
16. 16 if completion.is_none() || completion.is_some_and(|value| value.trim() == "complete") {
17. 17 OutputStatus::Succeeded
18. 18 } else {
19. 19 OutputStatus::Partial
20. 20 }
21. 21}
22. 22
23. 23fn result_outcome(
24. 24 result_id: impl Into<String>,
25. 25 status: OutputStatus,
26. 26 admitted: Option<&vak_intent::OutcomeSpec>,
27. 27 evaluation: Option<&str>,
28. 28 evidence_state: Option<&String>,
29. 29 human_review: Option<&String>,
30. 30) -> ResultOutcome {
31. 31 let completion = evaluation
32. 32 .and_then(|value| value.split('|').nth(3))
33. 33 .map(str::to_owned);
34. 34 ResultOutcome {
35. 35 result_id: result_id.into(),
36. 36 status,
37. 37 completion,
38. 38 evidence_state: evidence_state.cloned(),
39. 39 requirement_ids: admitted
40. 40 .map(|outcome| {
41. 41 outcome
42. 42 .requirements
43. 43 .iter()
44. 44 .map(|item| item.id.clone())
45. 45 .collect()
46. 46 })
47. 47 .unwrap_or_default(),
48. 48 evidence_receipt_ids: evaluation
49. 49 .and_then(|value| value.split('|').nth(2))
50. 50 .map(|value| {
51. 51 value
52. 52 .split(',')
53. 53 .filter(|item| !item.is_empty())
54. 54 .map(str::to_owned)
55. 55 .collect()
56. 56 })
57. 57 .unwrap_or_default(),
58. 58 evidence: Vec::new(),
59. 59 human_review: human_review.cloned(),
60. 60 }
61. 61}
62. 62use vak_llm::{ContentBlock, Role};
63. 63use vak_session::{ActivityKind, ActivityStatus, EntryPayload, SessionLog};
64. 64
65. 65fn sandbox_artifact_actions(
66. 66 execution_id: &str,
67. 67 path: &str,
68. 68 reviewable: bool,
69. 69) -> Vec<DeliveryAction> {
70. 70 let mut open_data = BTreeMap::new();
71. 71 open_data.insert("path".into(), path.into());
72. 72 let mut review_data = BTreeMap::new();
73. 73 review_data.insert("execution_id".into(), execution_id.into());
74. 74 let mut actions = vec![DeliveryAction {
75. 75 id: format!("open-{execution_id}-{path}"),
76. 76 label: "Open".into(),
77. 77 verb: "open_artifact".into(),
78. 78 data: open_data,
79. 79 }];
80. 80 if reviewable {
81. 81 actions.push(DeliveryAction {
82. 82 id: format!("review-{execution_id}"),
83. 83 label: "Review draft".into(),
84. 84 verb: "review_draft".into(),
85. 85 data: review_data,
86. 86 });
87. 87 }
88. 88 actions
89. 89}
90. 90
91. 91/// One tool call as the timeline needs it: name, input, result text, and
92. 92/// whether the result was an error. Named because the inline tuple was wide
93. 93/// enough that a reader had to count commas to find the error flag.
94. 94type TurnTool = (String, String, serde_json::Value, Option<String>, bool);
95. 95
96. 96/// The text a surface that cannot render cards natively — a chat channel, a
97. 97/// webhook, the inbox, a scheduled routine's summary — gets for a finished run.
98. 98///
99. 99/// A card emitted through an `emit_*_card` call is not in the model's final
100. 100/// text (that is only a line of narration), so delivering just that text drops
101. 101/// the card entirely. This takes the cards of the latest turn from the same
102. 102/// projection the desktop renders (so retries are superseded and nothing is
103. 103/// counted twice) and puts their deterministic text form ahead of the
104. 104/// narration.
105. 105pub(crate) fn text_with_run_cards(session: &SessionLog, narration: String) -> String {
106. 106 let session_id = session
107. 107 .header()
108. 108 .map(|header| header.session_id.clone())
109. 109 .unwrap_or_default();
110. 110 let timeline = snapshot(&session_id, session);
111. 111 let Some(turn) = timeline
112. 112 .items
113. 113 .iter()
114. 114 .rev()
115. 115 .find(|item| item.role == OutputRole::User)
116. 116 .map(|item| item.turn_id.clone())
117. 117 else {
118. 118 return narration;
119. 119 };
120. 120 let cards: Vec<&str> = timeline
121. 121 .items
122. 122 .iter()
123. 123 .filter(|item| {
124. 124 item.turn_id == turn
125. 125 && item.kind == OutputKind::Card
126. 126 && item
127. 127 .provenance
128. 128 .as_ref()
129. 129 .and_then(|p| p.source.as_deref())
130. 130 .is_some_and(|source| source.starts_with("emit_") && source.ends_with("_card"))
131. 131 && matches!(
132. 132 item.content,
133. 133 OutputContent::Structured { .. } | OutputContent::Adaptive { .. }
134. 134 )
135. 135 })
136. 136 .map(|item| item.fallback_text.trim())
137. 137 .filter(|text| !text.is_empty())
138. 138 .collect();
139. 139 if cards.is_empty() {
140. 140 return narration;
141. 141 }
142. 142 let cards = cards.join("\n\n");
143. 143 match vak_delivery::supplemental_card_note(&narration) {
144. 144 Some(note) => format!("{cards}\n\n{note}"),
145. 145 None => cards,
146. 146 }
147. 147}
148. 148
149. 149pub(crate) fn snapshot(session_id: &str, session: &SessionLog) -> OutputTimeline {
150. 150 let builtin = PresentationPlanner {
151. 151 skills: vak_delivery::built_in_skill_registry(),
152. 152 recipes: vak_delivery::built_in_recipes(),
153. 153 };
154. 154 snapshot_inner(session_id, session, &builtin, None)
155. 155}
156. 156
157. 157/// Like [`snapshot`] but uses a plugin-merged `PresentationPlanner` so that
158. 158/// domain-specific recipes and semantic types are recognized during
159. 159/// live projection. Callers with Core access should use this for SSE and
160. 160/// live session handles; historical views without Core can use `snapshot`.
161. 161pub(crate) fn snapshot_with_planner(
162. 162 session_id: &str,
163. 163 session: &SessionLog,
164. 164 planner: &PresentationPlanner,
165. 165) -> OutputTimeline {
166. 166 snapshot_inner(session_id, session, planner, None)
167. 167}
168. 168
169. 169/// Live projection variant with the persisted adaptive library. The legacy
170. 170/// planner remains authoritative for validation; the library only contributes
171. 171/// an optional, auditable selection reference to the same document.
172. 172pub(crate) fn snapshot_with_planner_and_library(
173. 173 session_id: &str,
174. 174 session: &SessionLog,
175. 175 planner: &PresentationPlanner,
176. 176 library: &vak_presentation::PresentationLibrary,
177. 177) -> OutputTimeline {
178. 178 snapshot_inner(session_id, session, planner, Some(library))
179. 179}
180. 180
181. 181/// Rehydrates sandbox-created artifacts into historical presentation views.
182. 182/// Sandbox events are persisted in a sidecar (because they are high-volume
183. 183/// telemetry), so they must be projected explicitly when a session is opened
184. 184/// after its live event bus is gone.
185. 185pub(crate) fn append_sandbox_artifacts(
186. 186 timeline: &mut OutputTimeline,
187. 187 home: &std::path::Path,
188. 188 session_id: &str,
189. 189) {
190. 190 // A sandbox execution id is the brokered tool-call id. Resolve it back
191. 191 // to the durable turn before appending sidecar artifacts, so the result
192. 192 // stays one coherent turn on reconnect. The old synthetic
193. 193 // `sandbox-{execution_id}` turn forced clients to guess the association
194. 194 // from prose and file paths.
195. 195 let execution_context: HashMap<String, (String, String)> = timeline
196. 196 .items
197. 197 .iter()
198. 198 .filter_map(|item| {
199. 199 item.provenance
200. 200 .as_ref()?
201. 201 .tool_call_id
202. 202 .as_ref()
203. 203 .map(|id| (id.clone(), (item.turn_id.clone(), item.timestamp.clone())))
204. 204 })
205. 205 .collect();
206. 206 let result_by_turn: HashMap<String, ResultOutcome> = timeline
207. 207 .items
208. 208 .iter()
209. 209 .filter(|item| item.role == OutputRole::Assistant)
210. 210 .filter_map(|item| {
211. 211 item.outcome
212. 212 .clone()
213. 213 .map(|outcome| (item.turn_id.clone(), outcome))
214. 214 })
215. 215 .collect();
216. 216 let path = home
217. 217 .join("sandbox")
218. 218 .join("executions")
219. 219 .join(format!("{session_id}.jsonl"));
220. 220 let Ok(text) = std::fs::read_to_string(path) else {
221. 221 return;
222. 222 };
223. 223 let events = text
224. 224 .lines()
225. 225 .filter_map(|line| serde_json::from_str::<vak_tools::SandboxEvent>(line).ok())
226. 226 .collect::<Vec<_>>();
227. 227 let reviewable_roots = events
228. 228 .iter()
229. 229 .filter_map(|event| match event {
230. 230 vak_tools::SandboxEvent::ExecutionStarted {
231. 231 execution_id,
232. 232 scratch_dir,
233. 233 ..
234. 234 } if std::path::Path::new(scratch_dir).is_dir() => {
235. 235 Some((execution_id.clone(), scratch_dir.clone()))
236. 236 }
237. 237 _ => None,
238. 238 })
239. 239 .collect::<HashMap<_, _>>();
240. 240 // Unreadable records leave every draft's status unknown rather than
241. 241 // reporting a version the records may contradict.
242. 242 let drafts = vak_sandbox::load_records(&home.join("sandbox").join("records.jsonl"))
243. 243 .ok()
244. 244 .map(|records| DraftVersions::new(records, session_id));
245. 245 for event in events {
246. 246 let vak_tools::SandboxEvent::ArtifactGenerated {
247. 247 execution_id,
248. 248 path,
249. 249 mime_type,
250. 250 size_bytes,
251. 251 } = event
252. 252 else {
253. 253 continue;
254. 254 };
255. 255 let id = format!("artifact-{execution_id}-{path}");
256. 256 if timeline.items.iter().any(|item| item.id == id) {
257. 257 continue;
258. 258 }
259. 259 let name = std::path::Path::new(&path)
260. 260 .file_name()
261. 261 .and_then(|name| name.to_str())
262. 262 .unwrap_or(&path)
263. 263 .to_string();
264. 264 let (turn_id, timestamp) = execution_context
265. 265 .get(&execution_id)
266. 266 .cloned()
267. 267 .unwrap_or_else(|| {
268. 268 (
269. 269 format!("sandbox-{execution_id}"),
270. 270 "1970-01-01T00:00:00+00:00".into(),
271. 271 )
272. 272 });
273. 273 // Only an execution that ran inside `.vak/scratch/` holds a draft to
274. 274 // review; one that worked in the workspace already put its files
275. 275 // where they belong, and candidate export refuses it.
276. 276 let scratch = reviewable_roots
277. 277 .get(&execution_id)
278. 278 .filter(|root| draft_relative_path(&path, root).is_some());
279. 279 let reviewable = scratch.is_some();
280. 280 let status = match scratch {
281. 281 Some(root) => drafts
282. 282 .as_ref()
283. 283 .map(|drafts| drafts.status(&execution_id, &path, root)),
284. 284 None => Some(ArtifactStatus::InFolder),
285. 285 };
286. 286 // A successful write/edit is already projected from the durable tool
287. 287 // result. Its sandbox event is stronger evidence about the same file,
288. 288 // not a second artifact. Merge the sidecar metadata and actions so a
289. 289 // result presents one file and one Canvas entry point.
290. 290 if let Some(existing) = timeline.items.iter_mut().find(|item| {
291. 291 if item.kind != OutputKind::Artifact
292. 292 || item
293. 293 .provenance
294. 294 .as_ref()
295. 295 .and_then(|p| p.tool_call_id.as_deref())
296. 296 != Some(execution_id.as_str())
297. 297 {
298. 298 return false;
299. 299 }
300. 300 let OutputContent::Artifact { artifact } = &item.content else {
301. 301 return false;
302. 302 };
303. 303 artifact.path.as_deref().is_some_and(|existing_path| {
304. 304 let existing = std::path::Path::new(existing_path);
305. 305 let observed = std::path::Path::new(&path);
306. 306 existing == observed || existing.ends_with(observed) || observed.ends_with(existing)
307. 307 })
308. 308 }) {
309. 309 existing.turn_id = turn_id.clone();
310. 310 existing.timestamp = timestamp;
311. 311 existing.outcome = result_by_turn.get(&turn_id).cloned();
312. 312 existing.actions = sandbox_artifact_actions(&execution_id, &path, reviewable);
313. 313 existing.fallback_text = format!("Generated artifact: {path}");
314. 314 if let OutputContent::Artifact { artifact } = &mut existing.content {
315. 315 artifact.path = Some(path.clone());
316. 316 artifact.media_type = Some(mime_type);
317. 317 artifact.description = None;
318. 318 artifact.size_bytes = Some(size_bytes);
319. 319 artifact.status = status;
320. 320 }
321. 321 continue;
322. 322 }
323. 323 timeline.items.push(OutputItem {
324. 324 id,
325. 325 timestamp,
326. 326 turn_id: turn_id.clone(),
327. 327 role: OutputRole::Tool,
328. 328 kind: OutputKind::Artifact,
329. 329 status: OutputStatus::Succeeded,
330. 330 outcome: result_by_turn.get(&turn_id).cloned(),
331. 331 content: OutputContent::Artifact {
332. 332 artifact: ArtifactRef {
333. 333 name,
334. 334 path: Some(path.clone()),
335. 335 media_type: Some(mime_type),
336. 336 description: None,
337. 337 size_bytes: Some(size_bytes),
338. 338 status,
339. 339 },
340. 340 },
341. 341 provenance: Some(OutputProvenance {
342. 342 session_id: Some(session_id.to_string()),
343. 343 entry_id: None,
344. 344 tool_call_id: Some(execution_id.clone()),
345. 345 source: Some("sandbox_artifact".into()),
346. 346 presentation_id: None,
347. 347 }),
348. 348 actions: sandbox_artifact_actions(&execution_id, &path, reviewable),
349. 349 fallback_text: format!("Generated artifact: {path}"),
350. 350 });
351. 351 }
352. 352 deduplicate_file_artifacts(&mut timeline.items);
353. 353}
354. 354
355. 355/// The saved versions of each execution's draft in one conversation, in the
356. 356/// order the durable records hold them. Versions of one draft are
357. 357/// alternatives, so an acceptance settles every version saved before it and
358. 358/// a version saved afterwards starts a new round; undoing an acceptance
359. 359/// reopens its round. This is the rule Review applies
360. 360/// (`vak-client-ui/src/candidateVersions.ts`), so the card and Review agree.
361. 361struct DraftVersions {
362. 362 versions: HashMap<String, Vec<vak_sandbox::CandidateManifest>>,
363. 363 /// Per execution, the version index a live (not undone) acceptance
364. 364 /// settled, and whether a version was saved after it.
365. 365 accepted: HashMap<String, (usize, bool)>,
366. 366}
367. 367
368. 368impl DraftVersions {
369. 369 fn new(records: Vec<vak_sandbox::DurableRecord>, session_id: &str) -> Self {
370. 370 use vak_sandbox::DurableRecord;
371. 371 let undone: HashSet<String> = records
372. 372 .iter()
373. 373 .filter_map(|record| match record {
374. 374 DurableRecord::PromotionUndo(undo) if undo.session_id == session_id => {
375. 375 Some(undo.candidate_id.clone())
376. 376 }
377. 377 _ => None,
378. 378 })
379. 379 .collect();
380. 380 let mut owner: HashMap<String, (String, usize)> = HashMap::new();
381. 381 let mut versions: HashMap<String, Vec<vak_sandbox::CandidateManifest>> = HashMap::new();
382. 382 let mut accepted: HashMap<String, (usize, bool)> = HashMap::new();
383. 383 for record in records {
384. 384 match record {
385. 385 DurableRecord::Candidate(candidate) if candidate.session_id == session_id => {
386. 386 let list = versions.entry(candidate.execution_id.clone()).or_default();
387. 387 owner.insert(
388. 388 candidate.candidate.candidate_id.clone(),
389. 389 (candidate.execution_id.clone(), list.len()),
390. 390 );
391. 391 list.push(candidate.candidate);
392. 392 if let Some(state) = accepted.get_mut(&candidate.execution_id) {
393. 393 state.1 = true;
394. 394 }
395. 395 }
396. 396 DurableRecord::Promotion(promotion)
397. 397 if promotion.session_id == session_id
398. 398 && !undone.contains(&promotion.candidate_id) =>
399. 399 {
400. 400 if let Some((execution, index)) = owner.get(&promotion.candidate_id) {
401. 401 accepted.insert(execution.clone(), (*index, false));
402. 402 }
403. 403 }
404. 404 _ => {}
405. 405 }
406. 406 }
407. 407 Self { versions, accepted }
408. 408 }
409. 409
410. 410 /// The status of the file at `path`, produced by `execution_id` in the
411. 411 /// scratch directory `scratch`.
412. 412 fn status(&self, execution_id: &str, path: &str, scratch: &str) -> ArtifactStatus {
413. 413 let versions = self
414. 414 .versions
415. 415 .get(execution_id)
416. 416 .map(Vec::as_slice)
417. 417 .unwrap_or_default();
418. 418 let saved_as = |index: usize| {
419. 419 let relative = draft_relative_path(path, scratch)?;
420. 420 versions
421. 421 .get(index)?
422. 422 .files
423. 423 .iter()
424. 424 .find(|file| std::path::Path::new(&file.path) == relative)
425. 425 .map(|file| vak_delivery::VersionFile {
426. 426 version_id: versions[index].candidate_id.clone(),
427. 427 path: file.path.clone(),
428. 428 })
429. 429 };
430. 430 match self.accepted.get(execution_id) {
431. 431 Some(&(index, false)) => ArtifactStatus::Accepted {
432. 432 version: version_number(index),
433. 433 saved_as: saved_as(index),
434. 434 },
435. 435 _ if versions.is_empty() => ArtifactStatus::Draft {
436. 436 version: 1,
437. 437 saved_as: None,
438. 438 },
439. 439 _ => ArtifactStatus::Draft {
440. 440 version: version_number(versions.len() - 1),
441. 441 saved_as: saved_as(versions.len() - 1),
442. 442 },
443. 443 }
444. 444 }
445. 445}
446. 446
447. 447fn version_number(index: usize) -> u32 {
448. 448 u32::try_from(index).map_or(u32::MAX, |index| index.saturating_add(1))
449. 449}
450. 450
451. 451/// `path` (absolute, or relative to the workspace) relative to the scratch
452. 452/// directory it was written in, which is how a saved version names it.
453. 453fn draft_relative_path<'a>(path: &'a str, scratch: &str) -> Option<&'a std::path::Path> {
454. 454 let artifact = std::path::Path::new(path);
455. 455 let scratch = std::path::Path::new(scratch);
456. 456 if artifact.is_absolute() {
457. 457 return artifact.strip_prefix(scratch).ok();
458. 458 }
459. 459 let workspace = scratch
460. 460 .ancestors()
461. 461 .find(|p| p.file_name().is_some_and(|n| n == ".vak"))
462. 462 .and_then(std::path::Path::parent)?;
463. 463 artifact
464. 464 .strip_prefix(scratch.strip_prefix(workspace).ok()?)
465. 465 .ok()
466. 466}
467. 467
468. 468/// Repeated successful writes to one file within a turn are revisions of the
469. 469/// same deliverable. Keep the newest observed artifact and its actions, while
470. 470/// leaving identically named files in other turns or directories distinct.
471. 471fn deduplicate_file_artifacts(items: &mut Vec<OutputItem>) {
472. 472 let mut seen = HashSet::new();
473. 473 let mut latest_first = Vec::with_capacity(items.len());
474. 474 for item in items.drain(..).rev() {
475. 475 let duplicate = if let OutputContent::Artifact { artifact } = &item.content {
476. 476 artifact
477. 477 .path
478. 478 .as_ref()
479. 479 .is_some_and(|path| !seen.insert((item.turn_id.clone(), path.clone())))
480. 480 } else {
481. 481 false
482. 482 };
483. 483 if !duplicate {
484. 484 latest_first.push(item);
485. 485 }
486. 486 }
487. 487 latest_first.reverse();
488. 488 *items = latest_first;
489. 489}
490. 490
491. 491/// Returns a concise, transport-neutral artifact list for channel delivery.
492. 492/// The browser can resolve richer previews, while text surfaces still need an
493. 493/// explicit record that the generated files exist and where they live.
494. 494pub(crate) fn sandbox_artifact_markdown(
495. 495 home: &std::path::Path,
496. 496 session_id: &str,
497. 497) -> Option<String> {
498. 498 let path = home
499. 499 .join("sandbox")
500. 500 .join("executions")
501. 501 .join(format!("{session_id}.jsonl"));
502. 502 let text = std::fs::read_to_string(path).ok()?;
503. 503 let mut rows = Vec::new();
504. 504 for line in text.lines() {
505. 505 let Ok(event) = serde_json::from_str::<vak_tools::SandboxEvent>(line) else {
506. 506 continue;
507. 507 };
508. 508 let vak_tools::SandboxEvent::ArtifactGenerated {
509. 509 path,
510. 510 mime_type,
511. 511 size_bytes,
512. 512 ..
513. 513 } = event
514. 514 else {
515. 515 continue;
516. 516 };
517. 517 let row = format!("- `{path}` ({mime_type}, {size_bytes} bytes)");
518. 518 if !rows.contains(&row) {
519. 519 rows.push(row);
520. 520 }
521. 521 }
522. 522 (!rows.is_empty()).then(|| format!("\n\nGenerated artifacts\n\n{}", rows.join("\n")))
523. 523}
524. 524
525. 525/// Declared domains for `tool_name`, accumulated from the chain's
526. 526/// `TurnCapabilitiesBound` entries — never guessed from the tool's name
527. 527/// (docs/design/68-context-engine.md §9's `SignalContext.domains` note).
528. 528fn tool_domain_refs<'a>(
529. 529 tool_domains: &'a HashMap<String, Vec<String>>,
530. 530 tool_name: Option<&str>,
531. 531) -> Vec<&'a str> {
532. 532 tool_name
533. 533 .and_then(|name| tool_domains.get(name))
534. 534 .map(|domains| domains.iter().map(String::as_str).collect())
535. 535 .unwrap_or_default()
536. 536}
537. 537
538. 538fn snapshot_inner(
539. 539 session_id: &str,
540. 540 session: &SessionLog,
541. 541 planner: &PresentationPlanner,
542. 542 adaptive_library: Option<&vak_presentation::PresentationLibrary>,
543. 543) -> OutputTimeline {
544. 544 let chain = session.chain_to_root();
545. 545 // Presentations are ledger entries (docs/design/68-context-engine.md
546. 546 // §10): the card a tool call displayed is read from its own written
547. 547 // entry, keyed by `tool_use_id` — never rebuilt from the call's
548. 548 // arguments at display time.
549. 549 // The map's value keeps the Presentation entry's OWN id alongside the
550. 550 // record: `presentation_id` on the projected item is this id, not the
551. 551 // id of the message entry the tool call rode in on (docs/design/68 §10:
552. 552 // feedback/selection key on the ledger fact, i.e. this entry).
553. 553 let presentation_by_tool_use_id: HashMap<
554. 554 String,
555. 555 (String, &vak_session::types::PresentationRecord),
556. 556 > = session
557. 557 .presentations()
558. 558 .into_iter()
559. 559 .filter_map(|(entry_id, record)| match &record.source {
560. 560 vak_session::types::PresentationSource::ToolCall { tool_use_id } => {
561. 561 Some((tool_use_id.clone(), (entry_id, record)))
562. 562 }
563. 563 vak_session::types::PresentationSource::Fence { .. }
564. 564 | vak_session::types::PresentationSource::Delegated { .. } => None,
565. 565 })
566. 566 .collect();
567. 567 // A delegated call (`task`) may carry several cards: the ones its worker
568. 568 // showed, recorded in this ledger when the worker ended.
569. 569 let mut delegated_by_tool_use_id: HashMap<
570. 570 String,
571. 571 Vec<(String, &vak_session::types::PresentationRecord)>,
572. 572 > = HashMap::new();
573. 573 for (entry_id, record) in session.presentations() {
574. 574 if let vak_session::types::PresentationSource::Delegated { tool_use_id, .. } =
575. 575 &record.source
576. 576 {
577. 577 delegated_by_tool_use_id
578. 578 .entry(tool_use_id.clone())
579. 579 .or_default()
580. 580 .push((entry_id, record));
581. 581 }
582. 582 }
583. 583 let mut tool_results: HashMap<String, (String, bool)> = HashMap::new();
584. 584 let mut tool_inputs: HashMap<String, (String, serde_json::Value)> = HashMap::new();
585. 585 let mut turn_outcomes: HashMap<usize, vak_intent::OutcomeSpec> = HashMap::new();
586. 586 let mut turn_evaluations: HashMap<usize, String> = HashMap::new();
587. 587 let mut turn_evidence_state: HashMap<usize, String> = HashMap::new();
588. 588 let mut turn_human_review: HashMap<usize, String> = HashMap::new();
589. 589 let mut turn_review_verdict: HashMap<usize, String> = HashMap::new();
590. 590 // Declared domains per tool name, accumulated from every
591. 591 // `TurnCapabilitiesBound` entry in the chain (docs/design/68-context-
592. 592 // engine.md §9's `SignalContext.domains` note): delivery signals derive
593. 593 // from what a capability declared it serves, never from its name.
594. 594 let mut tool_domains: HashMap<String, Vec<String>> = HashMap::new();
595. 595 let mut selected_presentation: Option<(String, u64)> = None;
596. 596 let mut successful_runs = std::collections::HashSet::new();
597. 597 let mut scan_turn = 0usize;
598. 598 let mut assistant_tool_context: HashMap<String, TurnTool> = HashMap::new();
599. 599 let mut pending_tool_context: Option<TurnTool> = None;
600. 600 // Tracks, per semantic_type, the id of the most recently pushed
601. 601 // tool-emitted `Structured` card within the CURRENT logical answer —
602. 602 // reset on a genuine new user request. Paired with `repair_armed`
603. 603 // below: a same-type card is only ever superseded (not just recorded)
604. 604 // while armed, i.e. strictly after a `[fence-check]`/
605. 605 // `[duplicate-card-check]` repair-nudge fired for this answer. Without
606. 606 // that guard, two intentionally distinct same-type cards the model
607. 607 // emits back-to-back in one turn (e.g. "here's revenue, and here's
608. 608 // cost", both `chart`) would be wrongly collapsed to one — nothing
609. 609 // else in this projection distinguishes "two calls in one batch" from
610. 610 // "a retry of the same call".
611. 611 //
612. 612 // Why this exists: a weak/small local model sometimes "retries" a
613. 613 // repair nudge by calling the same `emit_*_card` tool again rather
614. 614 // than only fixing its prose (observed live against gemma4:e2b-mlx),
615. 615 // which otherwise leaves two separate `Structured` items for what the
616. 616 // user experiences as one card. See `ids_to_remove` below: the earlier
617. 617 // attempt is dropped in favor of the retry's result, mirroring
618. 618 // `vak-agent`'s own bounded repair-turn semantics (the model's LATEST
619. 619 // attempt is authoritative).
620. 620 let mut card_group_by_type: HashMap<String, String> = HashMap::new();
621. 621 let mut seen_cards: std::collections::HashSet<String> = std::collections::HashSet::new();
622. 622 let mut repair_armed = false;
623. 623 let mut ids_to_remove: std::collections::HashSet<String> = std::collections::HashSet::new();
624. 624 for entry in &chain {
625. 625 match &entry.payload {
626. 626 EntryPayload::Message(record) => {
627. 627 // What the user wrote versus what the runtime authored is a
628. 628 // typed fact on the record (`vak_intent::control`), not
629. 629 // something to re-derive from the text.
630. 630 let control = record.control_kind();
631. 631 if record.message.role == Role::User
632. 632 && control.is_none()
633. 633 && record.message.content.iter().any(|block| match block {
634. 634 ContentBlock::Text { text } => !clean_scaffolding(text).is_empty(),
635. 635 _ => false,
636. 636 })
637. 637 {
638. 638 scan_turn += 1;
639. 639 pending_tool_context = None;
640. 640 card_group_by_type.clear();
641. 641 seen_cards.clear();
642. 642 repair_armed = false;
643. 643 }
644. 644 if control.is_some_and(|kind| kind.retries_answer()) {
645. 645 repair_armed = true;
646. 646 }
647. 647 for block in &record.message.content {
648. 648 match block {
649. 649 ContentBlock::ToolUse { id, name, input } => {
650. 650 tool_inputs.insert(id.clone(), (name.clone(), input.clone()));
651. 651 }
652. 652 ContentBlock::ToolResult {
653. 653 tool_use_id,
654. 654 content,
655. 655 is_error,
656. 656 } => {
657. 657 tool_results.insert(tool_use_id.clone(), (content.clone(), *is_error));
658. 658 if let Some((name, input)) = tool_inputs.get(tool_use_id) {
659. 659 let context = (
660. 660 tool_use_id.clone(),
661. 661 name.clone(),
662. 662 input.clone(),
663. 663 Some(content.clone()),
664. 664 *is_error,
665. 665 );
666. 666 pending_tool_context = Some(context);
667. 667 }
668. 668 }
669. 669 _ => {}
670. 670 }
671. 671 }
672. 672 if record.message.role == Role::Assistant
673. 673 && record
674. 674 .message
675. 675 .content
676. 676 .iter()
677. 677 .any(|block| matches!(block, ContentBlock::Text { .. }))
678. 678 && let Some(context) = pending_tool_context.take()
679. 679 {
680. 680 assistant_tool_context.insert(entry.id.clone(), context);
681. 681 }
682. 682 }
683. 683 EntryPayload::Intent(record) => {
684. 684 if let Some(outcome) = &record.outcome {
685. 685 // Core records admission immediately before the user
686. 686 // message that starts the turn. Attach it to that next
687. 687 // turn rather than decorating the previous answer.
688. 688 turn_outcomes.insert(scan_turn + 1, outcome.clone());
689. 689 }
690. 690 }
691. 691 EntryPayload::TurnCapabilitiesBound(bound) => {
692. 692 for (name, domains) in &bound.tool_domains {
693. 693 tool_domains
694. 694 .entry(name.clone())
695. 695 .or_insert_with(|| domains.clone());
696. 696 }
697. 697 }
698. 698 EntryPayload::Activity(activity)
699. 699 if activity.kind == ActivityKind::Diagnostic
700. 700 && activity.label == "Outcome evaluation" =>
701. 701 {
702. 702 if let Some(turn) = activity.turn {
703. 703 if let Some(status) = activity.data.get("status") {
704. 704 turn_evaluations.insert(turn, status.clone());
705. 705 }
706. 706 if let Some(evidence_state) = activity.data.get("evidence_state") {
707. 707 turn_evidence_state.insert(turn, evidence_state.clone());
708. 708 }
709. 709 if let Some(review) = activity.data.get("human_review") {
710. 710 turn_human_review.insert(turn, review.clone());
711. 711 }
712. 712 if let Some(evaluation) = activity.data.get("evaluation") {
713. 713 let evaluation_status = match activity.data.get("status") {
714. 714 Some(value) => value.as_str(),
715. 715 None => "unknown",
716. 716 };
717. 717 turn_evaluations
718. 718 .insert(turn, format!("{}|{}", evaluation_status, evaluation));
719. 719 }
720. 720 if let Some(receipts) = activity.data.get("evidence_receipts") {
721. 721 let evaluation_status = activity
722. 722 .data
723. 723 .get("status")
724. 724 .map_or("unknown", |value| value.as_str());
725. 725 let evaluation = activity
726. 726 .data
727. 727 .get("evaluation")
728. 728 .map_or("[]", |value| value.as_str());
729. 729 let completion = activity
730. 730 .data
731. 731 .get("completion")
732. 732 .map_or("unknown", |value| value.as_str());
733. 733 turn_evaluations.insert(
734. 734 turn,
735. 735 format!(
736. 736 "{}|{}|{}|{}",
737. 737 evaluation_status, evaluation, receipts, completion
738. 738 ),
739. 739 );
740. 740 }
741. 741 }
742. 742 }
743. 743 EntryPayload::Activity(activity)
744. 744 if activity.kind == ActivityKind::PresentationSelection =>
745. 745 {
746. 746 if let (Some(spec_id), Some(revision)) = (
747. 747 activity.data.get("spec_id"),
748. 748 activity
749. 749 .data
750. 750 .get("revision")
751. 751 .and_then(|value| value.parse().ok()),
752. 752 ) {
753. 753 selected_presentation = Some((spec_id.clone(), revision));
754. 754 }
755. 755 }
756. 756 EntryPayload::Activity(activity)
757. 757 if activity.kind == ActivityKind::Diagnostic
758. 758 && activity.label == "Outcome review" =>
759. 759 {
760. 760 if let Some(turn) = activity.turn
761. 761 && let Some(verdict) = activity.data.get("verdict")
762. 762 {
763. 763 turn_review_verdict.insert(turn, verdict.clone());
764. 764 }
765. 765 }
766. 766 EntryPayload::Activity(activity)
767. 767 if activity.kind == ActivityKind::Run
768. 768 && activity.status == ActivityStatus::Succeeded =>
769. 769 {
770. 770 if let Some(turn) = activity.turn {
771. 771 successful_runs.insert(turn);
772. 772 }
773. 773 }
774. 774 _ => {}
775. 775 }
776. 776 }
777. 777
778. 778 let mut timeline = OutputTimeline::empty(session_id);
779. 779 timeline.goal = session.goal_state();
780. 780 let mut turn = 0usize;
781. 781 // An answer the runtime sent back for a redo (a `retries_answer` nudge
782. 782 // followed it) is an internal draft, not something to show: the user sees
783. 783 // the redone answer, never both. `last_assistant_entry` is the answer the
784. 784 // next such nudge would be rejecting.
785. 785 let mut last_assistant_entry: Option<String> = None;
786. 786 let mut rejected_drafts: std::collections::HashSet<String> = std::collections::HashSet::new();
787. 787 for entry in chain {
788. 788 match &entry.payload {
789. 789 EntryPayload::Message(record) => {
790. 790 let control = record.control_kind();
791. 791 if control.is_some_and(|kind| kind.retries_answer())
792. 792 && let Some(draft) = last_assistant_entry.take()
793. 793 {
794. 794 rejected_drafts.insert(draft);
795. 795 }
796. 796 if record.message.role == Role::Assistant
797. 797 && record.message.content.iter().any(|block| {
798. 798 matches!(block, ContentBlock::Text { text } if !text.trim().is_empty())
799. 799 })
800. 800 {
801. 801 last_assistant_entry = Some(entry.id.clone());
802. 802 }
803. 803 if record.message.role == Role::User
804. 804 && control.is_none()
805. 805 && record.message.content.iter().any(|block| match block {
806. 806 ContentBlock::Text { text } => !clean_scaffolding(text).is_empty(),
807. 807 _ => false,
808. 808 })
809. 809 {
810. 810 turn += 1;
811. 811 }
812. 812 let turn_id = format!("turn-{turn}");
813. 813 for (index, block) in record.message.content.iter().enumerate() {
814. 814 match block {
815. 815 ContentBlock::Text { text } if !text.trim().is_empty() => {
816. 816 if control.is_some() {
817. 817 continue;
818. 818 }
819. 819 let assistant = record.message.role == Role::Assistant;
820. 820 // A short presentation envelope is ledger metadata, not prose.
821. 821 // Projecting it creates a duplicate, empty-looking Answer card.
822. 822 if assistant && is_presentation_envelope(text) {
823. 823 continue;
824. 824 }
825. 825 let cleaned_text_storage = clean_scaffolding(text);
826. 826 if cleaned_text_storage.is_empty() {
827. 827 continue;
828. 828 }
829. 829 let text = &cleaned_text_storage;
830. 830 let mut candidates = if assistant {
831. 831 structured_outputs_from_text(text)
832. 832 } else {
833. 833 Vec::new()
834. 834 };
835. 835 if assistant {
836. 836 candidates.extend(link_previews_from_text(text));
837. 837 }
838. 838 let assistant_tool_call_id = assistant_tool_context
839. 839 .get(&entry.id)
840. 840 .map(|(id, ..)| id.clone());
841. 841 let (tool_name, tool_input, tool_output, is_error) =
842. 842 assistant_tool_context
843. 843 .get(&entry.id)
844. 844 .map(|(_, name, input, output, err)| {
845. 845 (Some(name.as_str()), Some(input), output.as_deref(), *err)
846. 846 })
847. 847 .unwrap_or((None, None, None, false));
848. 848 let tool_domain_refs = tool_domain_refs(&tool_domains, tool_name);
849. 849 let ctx = SignalContext {
850. 850 text,
851. 851 tool_name,
852. 852 tool_input,
853. 853 tool_output,
854. 854 is_error,
855. 855 domains: &tool_domain_refs,
856. 856 };
857. 857 let signals = signals_from_context(&ctx);
858. 858 let plan = planner.plan(&signals, "desktop", &[], &candidates);
859. 859 let mut projected_outcome = turn_outcomes.get(&turn).cloned();
860. 860 let mut rejected_outcome_requirements = Vec::new();
861. 861 if let Some(outcome) = projected_outcome.as_mut() {
862. 862 rejected_outcome_requirements =
863. 863 plan.merge_outcome_requirements(outcome);
864. 864 }
865. 865 // An activation is the user's standing choice for this
866. 866 // scope. Use it automatically for the first compatible
867. 867 // typed result; explicit session selection still wins.
868. 868 let selected_for_output = selected_presentation.clone().or_else(|| {
869. 869 adaptive_library.and_then(|library| {
870. 870 let workspace_owner = session
871. 871 .header()
872. 872 .map(|header| {
873. 873 header.contract_cwd().to_string_lossy().into_owned()
874. 874 })
875. 875 .unwrap_or_else(|| "workspace".into());
876. 876 plan.accepted.iter().find_map(|candidate| {
877. 877 library
878. 878 .select_preferred(
879. 879 &candidate.semantic_type,
880. 880 "user",
881. 881 &workspace_owner,
882. 882 )
883. 883 .filter(|stored| {
884. 884 stored.spec.metadata.get("seed").map(String::as_str)
885. 885 != Some("true")
886. 886 || stored
887. 887 .spec
888. 888 .metadata
889. 889 .get("certified")
890. 890 .map(String::as_str)
891. 891 == Some("true")
892. 892 })
893. 893 .map(|stored| {
894. 894 (stored.spec.id.clone(), stored.spec.revision)
895. 895 })
896. 896 })
897. 897 })
898. 898 });
899. 899 let output_status = status_for_completion(
900. 900 turn_evaluations
901. 901 .get(&turn)
902. 902 .and_then(|value| value.split('|').nth(3)),
903. 903 );
904. 904 timeline.items.push(OutputItem {
905. 905 id: format!("{}-text-{index}", entry.id),
906. 906 timestamp: entry.ts.to_rfc3339(),
907. 907 turn_id: turn_id.clone(),
908. 908 role: if assistant {
909. 909 OutputRole::Assistant
910. 910 } else {
911. 911 OutputRole::User
912. 912 },
913. 913 kind: if assistant {
914. 914 OutputKind::Outcome
915. 915 } else {
916. 916 OutputKind::Message
917. 917 },
918. 918 status: output_status,
919. 919 content: OutputContent::Document {
920. 920 document: {
921. 921 let mut document = compile_markdown(text.clone());
922. 922 if let Some(library) = adaptive_library {
923. 923 let available = plan
924. 924 .accepted
925. 925 .iter()
926. 926 .filter(|candidate| {
927. 927 library.definitions().any(|stored| {
928. 928 stored.spec.accepts.iter().any(|kind| {
929. 929 kind == &candidate.semantic_type
930. 930 })
931. 931 })
932. 932 })
933. 933 .count();
934. 934 if available > 0 {
935. 935 document.metadata.insert(
936. 936 "adaptive_definitions_available".into(),
937. 937 available.to_string(),
938. 938 );
939. 939 }
940. 940 if let Some((spec_id, revision)) = selected_for_output
941. 941 .as_ref()
942. 942 && library.definitions().any(|stored| {
943. 943 stored.spec.id == *spec_id
944. 944 && stored.spec.revision == *revision
945. 945 })
946. 946 {
947. 947 document.metadata.insert(
948. 948 "adaptive_selected_spec".into(),
949. 949 format!("{spec_id}@{revision}"),
950. 950 );
951. 951 }
952. 952 }
953. 953 if let Some(decision) = plan.recipe.as_ref() {
954. 954 document.metadata.insert(
955. 955 "recipe_id".into(),
956. 956 decision.recipe_id.clone(),
957. 957 );
958. 958 document.metadata.insert(
959. 959 "recipe_version".into(),
960. 960 decision.recipe_version.clone(),
961. 961 );
962. 962 document.metadata.insert(
963. 963 "matched_signals".into(),
964. 964 decision.matched_signals.join(","),
965. 965 );
966. 966 document.metadata.insert(
967. 967 "renderer".into(),
968. 968 decision.renderer.clone(),
969. 969 );
970. 970 document.metadata.insert(
971. 971 "renderer_blocks".into(),
972. 972 plan.renderers
973. 973 .iter()
974. 974 .map(|render| {
975. 975 format!(
976. 976 "{}={} ({:?})",
977. 977 render.semantic_type,
978. 978 render.renderer,
979. 979 render.disposition
980. 980 )
981. 981 })
982. 982 .collect::<Vec<_>>()
983. 983 .join(", "),
984. 984 );
985. 985 }
986. 986 if let Some(outcome) = projected_outcome.as_ref() {
987. 987 document.metadata.insert(
988. 988 "outcome_objective".into(),
989. 989 outcome.objective.clone(),
990. 990 );
991. 991 document.metadata.insert(
992. 992 "outcome_revision".into(),
993. 993 outcome.revision.to_string(),
994. 994 );
995. 995 document.metadata.insert(
996. 996 "outcome_requirements".into(),
997. 997 outcome
998. 998 .requirements
999. 999 .iter()
1000. 1000 .map(|requirement| requirement.id.as_str())