harn-serve 0.10.166

Shared outbound workflow server core for Harn adapters
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
//! ACP capability metadata and prompt content normalization.
pub const ACP_SCHEMA_COMPATIBILITY: &str =
    "agentclientprotocol/agent-client-protocol schema v0.12.2";

pub const ACP_SESSION_UPDATE_VARIANTS: &[&str] = &[
    "user_message",
    "user_message_chunk",
    "agent_message_chunk",
    "agent_thought_chunk",
    "tool_call",
    "tool_call_update",
    "plan",
    "available_commands_update",
    "current_mode_update",
    "config_option_update",
    "session_info_update",
    "session_redo",
    "session_rollback",
    "session_truncated",
];

pub const HARN_SESSION_UPDATE_EXTENSIONS: &[&str] = &[
    "artifact",
    "available_commands_update",
    "fs_watch",
    "handoff",
    "hitl_request",
    "hitl_resolved",
    "live_session_client",
    "log",
    "progress",
    "reminder_emitted",
    "skill_activated",
    "skill_deactivated",
    "skill_narrow",
    "skill_scope_tools",
    "stance_transition",
    "tool_search_query",
    "tool_search_result",
    "transcript_compacted",
    "transcript_projected",
    "worker_update",
];

/// JSON-RPC method name for the ACP `ExtNotification` envelope that
/// carries Harn pipeline-loop milestones. The leading `_` puts it in
/// the ACP-reserved extension namespace, so strict clients that don't
/// know the method MUST ignore it gracefully (per the ACP
/// extensibility spec). Callers should never hardcode the literal —
/// reference this constant so a future rename ripples through the
/// adapter, fixtures, tests, and capability advertisement together.
pub const HARN_AGENT_EVENT_METHOD: &str = "_harn/agentEvent";
pub const HARN_PROVIDER_CATALOG_METHOD: &str = "_harn/providerCatalog";

/// Harn event kinds the adapter currently emits via `_harn/agentEvent`.
/// The list is stable wire vocabulary — adding a new kind is additive and
/// SHOULD be treated by clients as "unknown kind, ignore." Keep it sorted
/// for diff-friendliness and keep it in lockstep with the match arm in
/// `events.rs`.
pub const HARN_AGENT_EVENT_KINDS: &[&str] = &[
    "boundary_failure",
    "budget_circuit_breaker",
    "budget_exhausted",
    "code_librarian_query_nl_fallback",
    "composition_child_call",
    "composition_child_result",
    "composition_error",
    "composition_finish",
    "composition_start",
    "compass_routing_decision",
    "control_outcome",
    "daemon_watchdog_tripped",
    "feedback_injected",
    "final_wrapup",
    "host_attachment",
    "host_tool_result",
    "input_guardrail_verdict",
    "iteration_end",
    "session_health",
    "iteration_start",
    "judge_decision",
    "judge_started",
    "loop_control_decision",
    "loop_stuck",
    "mcp_auth_required",
    "mcp_catalog_changed",
    "mcp_notification",
    "model_job",
    "orchestration_decision",
    "pack_thinking_stripped",
    "progress_reported",
    "purpose_label",
    "repair_output_contract_applied",
    "require_successful_tools_violation",
    "reserved_terminal_verify",
    "scope_classifier_verdict",
    "self_consistency_tie",
    "session_closed",
    "structural_validator_decision",
    "subagent_join",
    "subagent_stop",
    "step_judge_decision",
    "tool_batch_disposition",
    "tool_call_audit",
    "tool_format_override",
    "turn_phase_changed",
    "typed_checkpoint",
];

pub const HARN_TOOL_LIFECYCLE_EXTENSION_FIELDS: &[&str] = &[
    "audit",
    "changedPaths",
    "data",
    "durationMs",
    "error",
    "errorCategory",
    "executionDurationMs",
    "executor",
    "health",
    "intent",
    "mutationStatus",
    "parsing",
    "rawInputPartial",
];

pub const HARN_CONTENT_EXTENSION_FIELDS: &[&str] =
    &["permission_preview", "visible_delta", "visible_text"];
pub const HARN_PROMPT_RESULT_EXTENSION_FIELDS: &[&str] = &["terminal"];
pub const HARN_STAGED_WRITES_PENDING_FIELDS: &[&str] =
    &["pendingCount", "totalBytes", "pendingWrites"];
pub const HARN_STAGED_WRITE_FIELDS: &[&str] = &["path", "kind", "byteDelta", "snapshotId"];
pub(super) fn harn_acp_extension_meta() -> serde_json::Value {
    serde_json::json!({
        "harn": {
            "schemaCompatibility": ACP_SCHEMA_COMPATIBILITY,
            "sessionUpdateExtensions": HARN_SESSION_UPDATE_EXTENSIONS,
            "toolLifecycleExtensionFields": HARN_TOOL_LIFECYCLE_EXTENSION_FIELDS,
            "contentExtensionFields": HARN_CONTENT_EXTENSION_FIELDS,
            "promptResultExtensionFields": HARN_PROMPT_RESULT_EXTENSION_FIELDS,
            "stagedWritesPendingFields": HARN_STAGED_WRITES_PENDING_FIELDS,
            "stagedWriteFields": HARN_STAGED_WRITE_FIELDS,
            // Whether this engine's host can confine the commands it spawns,
            // and the refusal an `os_hardened` spawn gets when it cannot. A
            // client reads it once at bring-up to warn before the first turn.
            "sandboxConfinement": harn_vm::llm::vm_value_to_json(
                &harn_vm::process_sandbox::host_confinement(),
            ),
            // Whether this server's own process is confined, and to what.
            "processConfinement": super::confinement::initialize_meta(),
            // ACP `ExtNotification` methods this server emits beyond the
            // canonical `session/update` stream. Clients that recognize
            // the method consume the payload; clients that don't MUST
            // ignore it (per ACP extensibility spec). Keys are method
            // names; values are static descriptors so a client can
            // version-check before subscribing.
            "extensionMethods": {
                HARN_AGENT_EVENT_METHOD: {
                    "description": "Harn agent events that have no \
                                    canonical ACP session/update mapping.",
                    "kinds": HARN_AGENT_EVENT_KINDS,
                    "schema": "https://harnlang.com/spec/harn-extensions/agent-event/v1",
                },
                HARN_PROVIDER_CATALOG_METHOD: {
                    "description": "Return the normalized provider/model catalog used by this runtime.",
                    "schema": harn_vm::provider_catalog::PROVIDER_CATALOG_SCHEMA_ID,
                    "schemaVersion": harn_vm::provider_catalog::PROVIDER_CATALOG_SCHEMA_VERSION,
                },
                super::types::ACP_METHOD_SESSION_PLAN_DOCUMENT_MUTATE: {
                    "description": "Optimistically edit, comment on, resolve, reopen, or approve the canonical collaborative plan document.",
                    "resultSchema": harn_vm::llm::plan::PLAN_DOCUMENT_SCHEMA_VERSION,
                    "conflict": {
                        "code": super::types::ACP_PLAN_REVISION_CONFLICT_CODE,
                        "schemaVersion": super::types::ACP_PLAN_REVISION_CONFLICT_SCHEMA,
                    },
                },
                harn_vm::orchestration::SESSION_VIEW_QUERY_METHOD: {
                    "description": "Return the harn.session_view.v1 projection for a live or persisted session.",
                    "schema": harn_vm::orchestration::SESSION_VIEW_SCHEMA,
                    "schemaVersion": harn_vm::orchestration::SESSION_VIEW_SCHEMA_VERSION,
                },
                harn_vm::agent_sessions::CANONICAL_HISTORY_BOUNDARIES_METHOD: {
                    "description": "Acknowledge canonical history positions after the owning transcript journal flushes.",
                    "schema": harn_vm::agent_sessions::CANONICAL_HISTORY_BOUNDARIES_SCHEMA,
                    "schemaVersion": 1,
                },
            },
            "hostCapabilityOperations": {
                "hypothesis": ["attest_event"],
                "process": [
                    "exec",
                    "list_shells",
                    "get_default_shell",
                    "set_default_shell",
                    "shell_invocation"
                ]
            },
            "extensionContract": "https://harnlang.com/spec/harn-extensions/v1",
        }
    })
}

pub(super) fn non_empty_env(name: &str) -> Option<String> {
    std::env::var(name)
        .ok()
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty())
}

pub(super) fn configured_llm_route_for_capabilities(
) -> Result<(String, String), harn_vm::llm_config::ModelResolutionError> {
    let provider = non_empty_env("HARN_LLM_PROVIDER")
        .filter(|provider| !provider.eq_ignore_ascii_case("auto"))
        .or_else(|| {
            if std::env::var("LOCAL_LLM_BASE_URL").is_ok()
                && (non_empty_env("HARN_LLM_MODEL").is_some()
                    || non_empty_env("LOCAL_LLM_MODEL").is_some())
            {
                Some("local".to_string())
            } else {
                None
            }
        })
        .or_else(|| {
            non_empty_env("HARN_LLM_MODEL").map(|model| {
                let resolved = harn_vm::llm_config::resolve_model_info(&model);
                resolved.provider
            })
        })
        .unwrap_or_else(harn_vm::llm_config::default_provider);

    let raw_model = non_empty_env("HARN_LLM_MODEL").or_else(|| {
        if provider == "local" {
            non_empty_env("LOCAL_LLM_MODEL")
        } else {
            None
        }
    });
    let model = raw_model
        .map(|model| harn_vm::llm_config::resolve_model(&model).0)
        .map_or_else(
            || harn_vm::llm_config::default_model_for_provider(&provider),
            Ok,
        )?;

    Ok((provider, model))
}

pub(super) fn acp_prompt_capabilities() -> serde_json::Value {
    let capabilities = configured_llm_route_for_capabilities()
        .map(|(provider, model)| harn_vm::llm::capabilities::lookup(&provider, &model))
        .unwrap_or_default();
    serde_json::json!({
        "image": capabilities.vision || capabilities.vision_supported,
        "audio": capabilities.audio,
        "embeddedContext": capabilities.pdf || capabilities.files_api_supported,
    })
}

pub(super) fn acp_agent_capabilities() -> serde_json::Value {
    serde_json::json!({
        "_meta": harn_acp_extension_meta(),
        "loadSession": true,
        "session": {
            "inject": {
                "modes": ["queue", "steer", "interrupt_immediate"],
                "pending": {
                    "replace": true,
                },
            },
            "injectHostEvent": {
                "kinds": ["host_tool_result", "host_attachment"],
                "delivery": ["turn_boundary", "immediate", "after_next_tool_call"],
            },
            "remind": {
                "modes": ["interrupt_immediate", "finish_step", "audit_only"],
                "pending": {
                    "list": true,
                    "revoke": true,
                },
            },
        },
        "promptCapabilities": acp_prompt_capabilities(),
        "mcpCapabilities": {
            "http": true,
            "sse": true,
        },
        "sessionCapabilities": {
            "close": {},
            "list": {},
            "resume": {},
            "rollback": {},
            "redo": {},
            "restoreToolCall": {},
            "cancelToolCall": {},
        },
    })
}

#[derive(Clone, Debug, PartialEq)]
pub(super) struct NormalizedAcpPrompt {
    pub(super) text: String,
    pub(super) content: Vec<serde_json::Value>,
    pub(super) messages: Vec<serde_json::Value>,
    pub(super) correlation: super::AcpPromptCorrelation,
}

pub(super) fn normalize_acp_prompt(
    params: &serde_json::Value,
) -> Result<NormalizedAcpPrompt, String> {
    let correlation: super::AcpPromptCorrelation = serde_json::from_value(params.clone())
        .map_err(|error| format!("session/prompt: invalid caller message identity: {error}"))?;
    let Some(prompt) = params.get("prompt") else {
        return Ok(NormalizedAcpPrompt {
            text: String::new(),
            content: Vec::new(),
            messages: prompt_messages_for_content(&[], &correlation),
            correlation,
        });
    };
    let blocks = prompt.as_array().ok_or_else(|| {
        "session/prompt: prompt must be an array of ACP content blocks".to_string()
    })?;

    let mut content = Vec::new();
    for block in blocks {
        content.push(normalize_acp_prompt_block(block)?);
    }

    let text = prompt_text_from_content(&content);
    let messages = prompt_messages_for_content(&content, &correlation);
    Ok(NormalizedAcpPrompt {
        text,
        content,
        messages,
        correlation,
    })
}

pub(super) fn normalize_acp_prompt_block(
    block: &serde_json::Value,
) -> Result<serde_json::Value, String> {
    match block.get("type").and_then(|value| value.as_str()) {
        Some("text") => Ok(serde_json::json!({
            "type": "text",
            "text": required_string(block, "text", "text prompt block")?,
        })),
        Some("image") => normalize_binary_prompt_block(block, "image"),
        Some("audio") => normalize_binary_prompt_block(block, "audio"),
        Some("resource") => {
            let mut normalized = normalize_embedded_resource_block(block)?;
            // The rendered text is a model projection, not the resource's
            // durable input. Replay clients recover the original block without
            // parsing that text or maintaining a second attachment store.
            normalized["_harn"] = serde_json::json!({"source_content": block});
            Ok(normalized)
        }
        Some("resource_link") => normalize_resource_link_block(block),
        Some(other) => Err(format!(
            "session/prompt: unsupported content block type `{other}`"
        )),
        None => Err("session/prompt: content block is missing required `type`".to_string()),
    }
}

pub(super) fn normalize_binary_prompt_block(
    block: &serde_json::Value,
    block_type: &str,
) -> Result<serde_json::Value, String> {
    let media_type = required_media_type(block, block_type)?;
    let data = block
        .get("data")
        .or_else(|| block.get("base64"))
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty());
    let uri = block
        .get("uri")
        .or_else(|| block.get("url"))
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty());

    let mut normalized = serde_json::json!({
        "type": block_type,
        "media_type": media_type,
    });
    if let Some(data) = data {
        normalized["base64"] = serde_json::json!(data);
        if let Some(uri) = uri {
            normalized["source_uri"] = serde_json::json!(uri);
        }
    } else if let Some(uri) = uri {
        normalized["url"] = serde_json::json!(uri);
    } else {
        return Err(format!(
            "session/prompt: {block_type} block requires `data` or `uri`"
        ));
    }
    if block_type == "image" {
        if let Some(detail) = block.get("detail").and_then(|value| value.as_str()) {
            normalized["detail"] = serde_json::json!(detail);
        }
    }
    Ok(normalized)
}

pub(super) fn normalize_embedded_resource_block(
    block: &serde_json::Value,
) -> Result<serde_json::Value, String> {
    let resource = block
        .get("resource")
        .and_then(|value| value.as_object())
        .ok_or_else(|| "session/prompt: resource block requires `resource` object".to_string())?;
    let uri = resource
        .get("uri")
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty())
        .ok_or_else(|| "session/prompt: embedded resource requires `uri`".to_string())?;
    let media_type = resource
        .get("mimeType")
        .or_else(|| resource.get("media_type"))
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty());

    if let Some(text) = resource.get("text").and_then(|value| value.as_str()) {
        return Ok(serde_json::json!({
            "type": "text",
            "text": render_embedded_text_resource(uri, media_type, text),
            "uri": uri,
            "media_type": media_type,
        }));
    }

    let blob = resource
        .get("blob")
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty())
        .ok_or_else(|| "session/prompt: embedded resource requires `text` or `blob`".to_string())?;
    let Some(media_type) = media_type else {
        return Ok(serde_json::json!({
            "type": "text",
            "text": format!("Embedded binary resource: {uri}\nMIME type: unknown"),
            "uri": uri,
        }));
    };
    if media_type.starts_with("image/") {
        Ok(serde_json::json!({
            "type": "image",
            "base64": blob,
            "media_type": media_type,
            "source_uri": uri,
        }))
    } else if media_type.starts_with("audio/") {
        Ok(serde_json::json!({
            "type": "audio",
            "base64": blob,
            "media_type": media_type,
            "source_uri": uri,
        }))
    } else if media_type == "application/pdf" {
        Ok(serde_json::json!({
            "type": "pdf",
            "base64": blob,
            "media_type": media_type,
            "source_uri": uri,
        }))
    } else {
        Ok(serde_json::json!({
            "type": "text",
            "text": format!("Embedded binary resource: {uri}\nMIME type: {media_type}"),
            "uri": uri,
            "media_type": media_type,
        }))
    }
}

pub(super) fn normalize_resource_link_block(
    block: &serde_json::Value,
) -> Result<serde_json::Value, String> {
    let uri = required_string(block, "uri", "resource_link prompt block")?;
    let mut lines = vec![format!("Resource link: {uri}")];
    for key in ["name", "title", "description", "mimeType", "media_type"] {
        if let Some(value) = block.get(key).and_then(|value| value.as_str()) {
            if !value.is_empty() {
                lines.push(format!("{key}: {value}"));
            }
        }
    }
    if let Some(size) = block.get("size").and_then(|value| value.as_u64()) {
        lines.push(format!("size: {size}"));
    }
    Ok(serde_json::json!({
        "type": "text",
        "text": lines.join("\n"),
        "uri": uri,
    }))
}

pub(super) fn render_embedded_text_resource(
    uri: &str,
    media_type: Option<&str>,
    text: &str,
) -> String {
    let mut rendered = format!("Embedded resource: {uri}");
    if let Some(media_type) = media_type {
        rendered.push_str(&format!("\nMIME type: {media_type}"));
    }
    rendered.push_str("\n\n");
    rendered.push_str(text);
    rendered
}

pub(super) fn required_media_type(
    block: &serde_json::Value,
    block_type: &str,
) -> Result<String, String> {
    block
        .get("mimeType")
        .or_else(|| block.get("media_type"))
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty())
        .map(str::to_string)
        .ok_or_else(|| format!("session/prompt: {block_type} block requires `mimeType`"))
}

pub(super) fn required_string(
    value: &serde_json::Value,
    key: &str,
    context: &str,
) -> Result<String, String> {
    value
        .get(key)
        .and_then(|value| value.as_str())
        .filter(|value| !value.is_empty())
        .map(str::to_string)
        .ok_or_else(|| format!("session/prompt: {context} requires `{key}`"))
}

pub(super) fn retarget_prompt_text(prompt: &mut NormalizedAcpPrompt, text: String) {
    if let Some(block) = prompt
        .content
        .iter_mut()
        .find(|block| block.get("type").and_then(|value| value.as_str()) == Some("text"))
    {
        block["text"] = serde_json::json!(text);
    } else {
        prompt.content.insert(
            0,
            serde_json::json!({
                "type": "text",
                "text": text,
            }),
        );
    }
    prompt.text = prompt_text_from_content(&prompt.content);
    prompt.messages = prompt_messages_for_content(&prompt.content, &prompt.correlation);
}

pub(super) fn prompt_text_from_content(content: &[serde_json::Value]) -> String {
    content
        .iter()
        .filter_map(|block| {
            if block.get("type").and_then(|value| value.as_str()) == Some("text") {
                block.get("text").and_then(|value| value.as_str())
            } else {
                None
            }
        })
        .collect::<Vec<_>>()
        .join("\n")
}

pub(super) fn prompt_messages_for_content(
    content: &[serde_json::Value],
    correlation: &super::AcpPromptCorrelation,
) -> Vec<serde_json::Value> {
    let message_content = if content.is_empty() {
        serde_json::Value::String(String::new())
    } else {
        serde_json::Value::Array(content.to_vec())
    };
    let mut message = serde_json::json!({
        "role": "user",
        "content": message_content,
    });
    if let Some(message_id) = &correlation.message_id {
        message["messageId"] = serde_json::json!(message_id);
    }
    vec![message]
}

#[cfg(test)]
mod tests {
    #[tokio::test(flavor = "current_thread")]
    async fn prompt_resource_source_survives_canonical_persistence() {
        use harn_session_store::{AppendEvent, CreateSession, SessionEventKind, SessionStore};
        use harn_vm::session_timeline::{query_session_store_timeline, SessionTimelineQuery};

        let root = tempfile::tempdir().unwrap();
        let store = harn_vm::open_canonical_store(root.path()).unwrap();
        store
            .create(CreateSession {
                id: Some("resource-source".into()),
                ..Default::default()
            })
            .await
            .unwrap();
        let resource = serde_json::json!({
            "type": "resource",
            "resource": {
                "uri": "burin-attachment://draft/target",
                "mimeType": "application/vnd.burin.sketch+json",
                "text": "{\n\"label\": \"MIME type: inside the drawing\"\n}",
            },
        });
        let prompt = super::normalize_acp_prompt(&serde_json::json!({
            "messageId": "authored-turn",
            "prompt": [resource.clone(), {"type": "text", "text": "Preserve this through reopen."}],
        }))
        .unwrap();
        assert!(prompt.content[0]["text"]
            .as_str()
            .unwrap()
            .starts_with("Embedded resource:"));
        assert_eq!(prompt.content[0]["_harn"]["source_content"], resource);
        store
            .append(
                "resource-source",
                AppendEvent::new(
                    SessionEventKind::Message,
                    serde_json::json!({"raw_message": prompt.messages[0]}),
                ),
            )
            .await
            .unwrap();
        let timeline = query_session_store_timeline(
            &store,
            SessionTimelineQuery::for_session("resource-source"),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(
            timeline.nodes.len(),
            1,
            "one admitted message, not a shadow resource event"
        );
        let restored =
            &timeline.nodes[0].attributes["raw_message"]["content"][0]["_harn"]["source_content"];
        assert_eq!(restored, &resource);
        let replay =
            super::normalize_acp_prompt(&serde_json::json!({"prompt": [restored]})).unwrap();
        assert_eq!(
            replay.content[0], prompt.content[0],
            "replay never parses or rewraps rendered prose"
        );

        let plain = super::normalize_acp_prompt_block(&serde_json::json!({
            "type": "text", "text": "Embedded resource: authored plain text",
        }))
        .unwrap();
        assert!(
            plain.get("_harn").is_none(),
            "similar prose cannot acquire resource identity"
        );
        assert!(
            super::normalize_acp_prompt_block(&serde_json::json!({
                "type": "resource", "resource": {"text": "missing URI"},
            }))
            .is_err(),
            "preserving source never bypasses resource validation"
        );
    }

    #[test]
    fn caller_identity_survives_multimodal_prompt_retargeting() {
        let image = serde_json::json!({"type": "image", "mimeType": "image/png", "data": "AAAA"});
        let normalized_image =
            serde_json::json!({"type": "image", "media_type": "image/png", "base64": "AAAA"});
        let mut prompt = super::normalize_acp_prompt(&serde_json::json!({
            "messageId": "opaque caller identity",
            "prompt": [{"type": "text", "text": "same request"}, image],
        }))
        .unwrap();
        assert_eq!(prompt.messages[0]["messageId"], "opaque caller identity");
        assert_eq!(prompt.messages[0]["content"][1], normalized_image);
        super::retarget_prompt_text(&mut prompt, "rewritten request".into());
        assert_eq!(prompt.messages[0]["messageId"], "opaque caller identity");
        assert_eq!(prompt.messages[0]["content"][1], normalized_image);
        assert_eq!(prompt.text, "rewritten request");
    }

    #[test]
    fn absent_caller_identity_is_not_inferred_and_malformed_identity_refuses() {
        let absent = super::normalize_acp_prompt(&serde_json::json!({
            "prompt": [{"type": "text", "text": "same request"}],
        }))
        .unwrap();
        assert!(absent.messages[0].get("messageId").is_none());
        for identity in [
            serde_json::Value::Null,
            serde_json::json!(42),
            serde_json::json!({}),
            serde_json::json!(""),
            serde_json::json!("   "),
        ] {
            assert!(super::normalize_acp_prompt(&serde_json::json!({
                "messageId": identity,
                "prompt": [],
            }))
            .is_err());
        }
    }

    /// A client warns at bring-up from this field, so it must be the runtime's
    /// own confinement fact and must name the refusal exactly when it applies.
    #[test]
    fn initialize_meta_carries_the_hosts_sandbox_confinement() {
        let meta = super::harn_acp_extension_meta();
        let confinement = &meta["harn"]["sandboxConfinement"];
        assert_eq!(
            confinement,
            &harn_vm::llm::vm_value_to_json(&harn_vm::process_sandbox::host_confinement())
        );
        assert_eq!(
            confinement["schema"],
            harn_vm::process_sandbox::SANDBOX_CONFINEMENT_SCHEMA
        );
        let confines = confinement["confines_processes"]
            .as_bool()
            .expect("confines_processes is a boolean");
        assert_eq!(confinement["os_hardened_refusal"].is_null(), confines);
    }
}