Skip to main content

dekopon_agent/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg_attr(test, allow(clippy::unwrap_used))]
3#![cfg_attr(
4    test,
5    allow(
6        clippy::disallowed_methods,
7        clippy::disallowed_types,
8        reason = "tests spawn, join and drain freely; production sites carry their own expectation"
9    )
10)]
11use std::collections::BTreeMap;
12use std::time::Duration;
13
14#[cfg(unix)]
15use std::{
16    collections::BTreeSet,
17    collections::hash_map::RandomState,
18    hash::{BuildHasher as _, Hasher as _},
19    sync::atomic::{AtomicU32, Ordering},
20    time::{Instant, SystemTime, UNIX_EPOCH},
21};
22
23use dekopon_broker_protocol::TraceParent;
24#[cfg(unix)]
25use dekopon_broker_protocol::{
26    Attestation, BrokerClient, ChatMemorySurface, ClientError, ERROR_UNAUTHENTICATED,
27    InvocationOutcome, InvocationRequest, SessionSurface, Upcall, UpcallExit, UpcallStreams,
28};
29#[cfg(unix)]
30use dekopon_core::{CapabilityId, InvocationId, PrincipalId, TraceId};
31use dekopon_process::{
32    CallBudget, CancelSignal, ExitCode, Limits as ShellLimits, ShellThreads, ThreadName,
33    TreeContext,
34};
35#[cfg(unix)]
36use dekopon_shell::CapabilityDescription;
37use dekopon_shell::{
38    CapabilityCallResult, CapabilityInvoker, Interpreter, JobControl, ScriptOutcome,
39};
40use serde_json::Value;
41#[cfg(unix)]
42use std::os::fd::OwnedFd;
43#[cfg(unix)]
44use std::sync::Arc;
45#[cfg(unix)]
46use thiserror::Error;
47
48#[cfg(unix)]
49use crate::attachment::{ChatAssetInputs, ChatAssetRefusal, ReplyAttachments};
50use crate::{meta::EffectiveCapabilityView, prompt::ScriptRuntime};
51
52pub mod attachment;
53pub mod improvement;
54pub mod memory;
55pub mod memory_tools;
56pub mod meta;
57pub mod progress;
58pub mod prompt;
59pub mod skills;
60pub mod wake;
61
62pub use crate::progress::{
63    BudgetLimit, CancelSource, CancelVia, CommandWord, FailureClass, ProgressEvent, ProgressNote,
64    ProgressSink, SessionOutcome, ToolOutcome,
65};
66
67pub struct ShellRuntime<I> {
68    pub invoker: I,
69    pub limits: ShellLimits,
70    pub calls: CallBudget,
71    pub threads: ShellThreads,
72}
73
74impl<I: CapabilityInvoker> ScriptRuntime for ShellRuntime<I> {
75    fn run_script(&self, script: &str, participant: Option<&str>) -> ScriptOutcome {
76        if participant.is_some() {
77            return ScriptOutcome {
78                output: "Unknown participant handle: this runtime has no participant table."
79                    .to_owned(),
80                exit_code: ExitCode::from(2),
81                truncated: false,
82                capability_calls: 0,
83                steps: 0,
84            };
85        }
86        let mut tree = TreeContext::new(self.limits, self.calls.clone(), self.threads.clone())
87            .with_cancel(self.invoker.cancel_signals());
88        self.invoker.script_started(&mut tree);
89        let outcome = Interpreter::new(self.limits, self.threads.clone()).run_with_tree(
90            script,
91            &self.invoker,
92            &tree,
93        );
94        // Call script_finished before returning the outcome, or the next turn's progress event
95        // reports out of order.
96        self.invoker.script_finished();
97        outcome
98    }
99
100    fn capability_calls_used(&self) -> u32 {
101        self.calls.used()
102    }
103
104    fn command_words(&self) -> Vec<String> {
105        self.invoker.command_words()
106    }
107
108    fn command_word_help(&self) -> BTreeMap<String, String> {
109        self.invoker.command_word_help()
110    }
111}
112
113pub struct SessionInvoker<D> {
114    pub direct: D,
115    pub broker: Option<Box<dyn CapabilityInvoker + Send + Sync>>,
116}
117
118impl<D: CapabilityInvoker> CapabilityInvoker for SessionInvoker<D> {
119    fn script_started(&self, tree: &mut TreeContext) {
120        self.direct.script_started(tree);
121        if let Some(broker) = &self.broker {
122            broker.script_started(tree);
123        }
124    }
125
126    fn cancel_signals(&self) -> Vec<CancelSignal> {
127        let mut signals = self.direct.cancel_signals();
128        if let Some(broker) = &self.broker {
129            signals.extend(broker.cancel_signals());
130        }
131        signals
132    }
133
134    fn granted(&self) -> Vec<String> {
135        let mut granted = self.direct.granted();
136        if let Some(broker) = &self.broker {
137            granted.extend(broker.granted());
138        }
139        granted.sort_unstable();
140        granted.dedup();
141        granted
142    }
143
144    fn is_granted(&self, capability: &str) -> bool {
145        self.direct.is_granted(capability)
146            || self
147                .broker
148                .as_ref()
149                .is_some_and(|broker| broker.is_granted(capability))
150    }
151
152    fn has_command_word(&self, word: &str) -> bool {
153        self.direct.has_command_word(word)
154            || self
155                .broker
156                .as_ref()
157                .is_some_and(|broker| broker.has_command_word(word))
158    }
159
160    fn describe(&self, capability: &str) -> Option<dekopon_shell::CapabilityDescription> {
161        self.direct.describe(capability).or_else(|| {
162            self.broker
163                .as_ref()
164                .and_then(|broker| broker.describe(capability))
165        })
166    }
167
168    fn invoke(
169        &self,
170        mut proposal: dekopon_shell::CommandProposal,
171        streams: dekopon_shell::Streams,
172        tree: &dekopon_process::TreeContext,
173    ) -> CapabilityCallResult {
174        let capability = &proposal.capability;
175        // A secret-use proposal must reach only the broker leg; the direct leg has no authorizer to
176        // check it.
177        if proposal.secret_use.is_some() {
178            return match &self.broker {
179                Some(broker) if broker.is_granted(capability) => {
180                    broker.invoke(proposal, streams, tree)
181                }
182                _ => dekopon_shell::secret_use_unsupported(),
183            };
184        }
185        if self.direct.is_granted(capability) {
186            let report = proposal.report.take();
187            let result = self.direct.invoke(proposal, streams, tree);
188            if let Some(report) = report {
189                report.complete(report_outcome(call_outcome(&result)));
190            }
191            return result;
192        }
193        match &self.broker {
194            Some(broker) => broker.invoke(proposal, streams, tree),
195            None => CapabilityCallResult::NotFound,
196        }
197    }
198
199    fn command_words(&self) -> Vec<String> {
200        let mut words = self.direct.command_words();
201        if let Some(broker) = &self.broker {
202            words.extend(broker.command_words());
203        }
204        words.sort_unstable();
205        words.dedup();
206        words
207    }
208
209    fn command_word_help(&self) -> BTreeMap<String, String> {
210        let mut pages = self.direct.command_word_help();
211        if let Some(broker) = &self.broker {
212            pages.extend(broker.command_word_help());
213        }
214        pages
215    }
216
217    fn run(
218        &self,
219        call: dekopon_shell::RunCall,
220        streams: dekopon_shell::Streams,
221        tree: &TreeContext,
222    ) -> dekopon_shell::RunResult {
223        if self.direct.has_command_word(&call.word) {
224            return self.direct.run(call, streams, tree);
225        }
226        match &self.broker {
227            Some(broker) => broker.run(call, streams, tree),
228            None => dekopon_shell::render_command(
229                streams,
230                "",
231                format!("dekopon-shell: {}: command not found\n", call.word),
232                127,
233            ),
234        }
235    }
236
237    fn note(&self, text: &str, eta: Option<Duration>) {
238        if let Some(broker) = &self.broker {
239            broker.note(text, eta);
240        }
241    }
242
243    fn script_finished(&self) {
244        self.direct.script_finished();
245        if let Some(broker) = &self.broker {
246            broker.script_finished();
247        }
248    }
249
250    fn job_control(&self) -> Option<&dyn JobControl> {
251        self.direct
252            .job_control()
253            .or_else(|| self.broker.as_ref()?.job_control())
254    }
255}
256
257#[must_use]
258pub fn current_trace_parent() -> Option<TraceParent> {
259    let parts = dekopon_telemetry::current_trace_context()?;
260    TraceParent::new(parts.trace_id, parts.span_id, parts.flags).ok()
261}
262
263#[must_use]
264pub fn session_trace_parent() -> TraceParent {
265    current_trace_parent().unwrap_or_else(minted_trace_parent)
266}
267
268fn minted_trace_parent() -> TraceParent {
269    let mut bytes = [0_u8; 24];
270    if let Err(error) = getrandom::fill(&mut bytes) {
271        tracing::warn!(
272            event = "session_trace_entropy_unavailable",
273            error = %error,
274            "session.trace.entropy.unavailable"
275        );
276        let nanos = SystemTime::now()
277            .duration_since(UNIX_EPOCH)
278            .map(|elapsed| elapsed.as_nanos())
279            .unwrap_or_default();
280        let seed = RandomState::new();
281        for (index, chunk) in bytes.chunks_mut(8).enumerate() {
282            let mut hasher = seed.build_hasher();
283            hasher.write_usize(index);
284            hasher.write_u32(std::process::id());
285            hasher.write_u128(nanos);
286            chunk.copy_from_slice(&hasher.finish().to_be_bytes());
287        }
288    }
289    let mut trace_id = [0_u8; 16];
290    trace_id.copy_from_slice(&bytes[..16]);
291    let mut parent_id = [0_u8; 8];
292    parent_id.copy_from_slice(&bytes[16..]);
293    // Setting the low bit avoids the one all-zero value W3C forbids for these identifiers, which a
294    // 1-in-2^128 draw does not justify making every caller handle as a failure.
295    trace_id[15] |= 1;
296    parent_id[7] |= 1;
297    TraceParent::new(trace_id, parent_id, 1)
298        .expect("the low bit of each identifier is set, so neither is all zeroes")
299}
300
301#[cfg(unix)]
302#[derive(Debug, Error)]
303pub enum BrokerLegError {
304    #[error(transparent)]
305    Client(#[from] ClientError),
306    #[error("the broker answered with duplicate capability identifiers: {capabilities}")]
307    DuplicateCapabilities { capabilities: String },
308}
309
310#[cfg(unix)]
311pub struct BrokerLeg {
312    client: BrokerClient,
313    runtime: tokio::runtime::Handle,
314    capabilities: BTreeMap<String, CapabilityDescription>,
315    effective_capabilities: Vec<EffectiveCapabilityView>,
316    command_words: BTreeSet<String>,
317    command_word_help: BTreeMap<String, String>,
318    identifiers: IdSequence,
319    attestation: Option<Attestation>,
320    chat_memory: Option<ChatMemorySurface>,
321    principal: Option<PrincipalId>,
322    space: Option<Vec<dekopon_core::CapabilityId>>,
323    cancel: CancelSignal,
324    script_tree: parking_lot::Mutex<Option<TreeContext>>,
325    attachments: Option<Arc<ReplyAttachments>>,
326    asset_inputs: Option<ChatAssetInputs>,
327    progress: Option<Arc<dyn ProgressSink>>,
328    notes_enabled: bool,
329    notes: AtomicU32,
330    calls: CallBudget,
331    jobs: Option<Arc<dyn JobControl>>,
332}
333
334#[cfg(unix)]
335impl BrokerLeg {
336    pub async fn connect(
337        client: BrokerClient,
338        attestation: Option<Attestation>,
339    ) -> Result<Self, BrokerLegError> {
340        let surface = client.session_surface(attestation.clone()).await?;
341        Self::build(client, surface, attestation)
342    }
343
344    fn build(
345        client: BrokerClient,
346        surface: SessionSurface,
347        attestation: Option<Attestation>,
348    ) -> Result<Self, BrokerLegError> {
349        let SessionSurface {
350            capabilities: available,
351            command_words,
352            command_word_help,
353            chat_memory,
354            principal,
355            space,
356        } = surface;
357        let (capabilities, effective_capabilities) = snapshot(available)?;
358        Ok(Self {
359            client,
360            runtime: tokio::runtime::Handle::current(),
361            capabilities,
362            effective_capabilities,
363            command_words: command_words.into_iter().collect(),
364            command_word_help,
365            identifiers: IdSequence::for_session(),
366            attestation,
367            chat_memory,
368            principal,
369            space,
370            cancel: CancelSignal::never(),
371            script_tree: parking_lot::Mutex::new(None),
372            attachments: None,
373            asset_inputs: None,
374            progress: None,
375            notes_enabled: false,
376            notes: AtomicU32::new(0),
377            calls: CallBudget::new(0),
378            jobs: None,
379        })
380    }
381
382    #[must_use]
383    pub fn with_identifiers(mut self, identifiers: IdSequence) -> Self {
384        self.identifiers = identifiers;
385        self
386    }
387
388    #[must_use]
389    pub fn with_participant(mut self, participant: &str) -> Self {
390        if let Some(scope) = self
391            .attestation
392            .as_mut()
393            .and_then(|claim| claim.scope.as_mut())
394        {
395            scope.participant = Some(participant.to_owned());
396        }
397        self
398    }
399
400    pub fn with_cancel_signal(mut self, signal: CancelSignal) -> Self {
401        self.cancel = signal;
402        self
403    }
404
405    #[must_use]
406    pub fn with_job_control(mut self, jobs: Arc<dyn JobControl>) -> Self {
407        self.jobs = Some(jobs);
408        self
409    }
410
411    #[must_use]
412    pub fn with_provider_attachments(mut self, slot: Arc<ReplyAttachments>) -> Self {
413        self.attachments = Some(slot);
414        self
415    }
416
417    #[must_use]
418    pub fn with_chat_asset_inputs(mut self, inputs: ChatAssetInputs) -> Self {
419        self.asset_inputs = Some(inputs);
420        self
421    }
422
423    #[must_use]
424    pub fn with_progress(mut self, sink: Arc<dyn ProgressSink>, calls: CallBudget) -> Self {
425        self.progress = Some(sink);
426        self.calls = calls;
427        self
428    }
429
430    #[must_use]
431    pub fn with_progress_notes(mut self) -> Self {
432        self.notes_enabled = true;
433        self
434    }
435
436    fn emit(&self, event: ProgressEvent) {
437        if let Some(sink) = &self.progress {
438            sink.emit(event);
439        }
440    }
441
442    #[must_use]
443    pub fn effective_capabilities(&self) -> Vec<EffectiveCapabilityView> {
444        self.effective_capabilities.clone()
445    }
446
447    #[must_use]
448    pub fn chat_memory_surface(&self) -> Option<&ChatMemorySurface> {
449        self.chat_memory.as_ref()
450    }
451
452    #[must_use]
453    pub fn space_grants(&self) -> Option<&[dekopon_core::CapabilityId]> {
454        self.space.as_deref()
455    }
456
457    #[must_use]
458    pub fn principal(&self) -> Option<&PrincipalId> {
459        self.principal.as_ref()
460    }
461
462    #[must_use]
463    pub const fn session_trace(&self) -> TraceId {
464        self.identifiers.trace()
465    }
466}
467
468#[cfg(unix)]
469fn bounded_count(count: usize) -> u32 {
470    u32::try_from(count).unwrap_or(u32::MAX)
471}
472
473fn report_outcome(outcome: ToolOutcome) -> dekopon_shell::CommandReportOutcome {
474    match outcome {
475        ToolOutcome::Succeeded => dekopon_shell::CommandReportOutcome::Succeeded,
476        ToolOutcome::Denied => dekopon_shell::CommandReportOutcome::Denied,
477        ToolOutcome::Failed => dekopon_shell::CommandReportOutcome::Failed,
478        ToolOutcome::Cancelled => dekopon_shell::CommandReportOutcome::Cancelled,
479    }
480}
481
482fn call_outcome(result: &CapabilityCallResult) -> ToolOutcome {
483    match result {
484        CapabilityCallResult::Succeeded | CapabilityCallResult::SucceededWithStderr(_) => {
485            ToolOutcome::Succeeded
486        }
487        CapabilityCallResult::Denied { .. } => ToolOutcome::Denied,
488        CapabilityCallResult::Exited { .. }
489        | CapabilityCallResult::Failed { .. }
490        | CapabilityCallResult::NotFound => ToolOutcome::Failed,
491    }
492}
493
494#[cfg(unix)]
495fn snapshot(
496    capabilities: Vec<dekopon_broker_protocol::AvailableCapability>,
497) -> Result<
498    (
499        BTreeMap<String, CapabilityDescription>,
500        Vec<EffectiveCapabilityView>,
501    ),
502    BrokerLegError,
503> {
504    let mut descriptions = BTreeMap::new();
505    let mut duplicates = BTreeSet::new();
506    let mut effective = Vec::with_capacity(capabilities.len());
507    for available in capabilities {
508        let id = available.capability.id.to_string();
509        if descriptions.contains_key(&id) {
510            duplicates.insert(id.clone());
511        }
512        effective.push(EffectiveCapabilityView {
513            id: id.clone(),
514            provider: available.provider.to_string(),
515            description: available.capability.description.clone(),
516            effect: available.capability.effect.to_string(),
517            risk: available.capability.risk.to_string(),
518        });
519        descriptions.insert(
520            id.clone(),
521            CapabilityDescription {
522                capability: id,
523                description: available.capability.description,
524            },
525        );
526    }
527    if !duplicates.is_empty() {
528        return Err(BrokerLegError::DuplicateCapabilities {
529            capabilities: duplicates.into_iter().collect::<Vec<_>>().join(", "),
530        });
531    }
532    effective.sort_by(|left, right| left.id.cmp(&right.id));
533    Ok((descriptions, effective))
534}
535
536#[cfg(unix)]
537impl CapabilityInvoker for BrokerLeg {
538    fn participant_handle(&self) -> Option<&str> {
539        self.attestation
540            .as_ref()?
541            .scope
542            .as_ref()?
543            .participant
544            .as_deref()
545    }
546
547    fn cancel_signals(&self) -> Vec<CancelSignal> {
548        vec![self.cancel.clone()]
549    }
550
551    fn script_started(&self, tree: &mut TreeContext) {
552        let _entered = self.runtime.enter();
553        let mut timer = Box::pin(tokio::time::sleep(tree.remaining()));
554        let _polled = std::future::Future::poll(
555            timer.as_mut(),
556            &mut std::task::Context::from_waker(std::task::Waker::noop()),
557        );
558        *tree = tree.clone().with_script_timer(Some(timer));
559        *self.script_tree.lock() = Some(tree.clone());
560    }
561
562    fn script_finished(&self) {
563        self.script_tree.lock().take();
564        self.notes.store(0, Ordering::Relaxed);
565    }
566
567    fn granted(&self) -> Vec<String> {
568        self.capabilities.keys().cloned().collect()
569    }
570
571    fn is_granted(&self, capability: &str) -> bool {
572        self.capabilities.contains_key(capability)
573    }
574
575    fn describe(&self, capability: &str) -> Option<CapabilityDescription> {
576        self.capabilities.get(capability).cloned()
577    }
578
579    fn command_words(&self) -> Vec<String> {
580        self.command_words.iter().cloned().collect()
581    }
582
583    fn command_word_help(&self) -> BTreeMap<String, String> {
584        self.command_word_help.clone()
585    }
586
587    fn has_command_word(&self, word: &str) -> bool {
588        self.command_words.contains(word)
589    }
590
591    fn run(
592        &self,
593        call: dekopon_shell::RunCall,
594        streams: dekopon_shell::Streams,
595        tree: &TreeContext,
596    ) -> dekopon_shell::RunResult {
597        let reported = self.command_words.contains(&call.word).then(|| {
598            let word = CommandWord::new(&call.word);
599            self.emit(ProgressEvent::ToolStarted {
600                word: word.clone(),
601                argument_count: bounded_count(call.argv.len()),
602                calls_used: self.calls.used(),
603                calls_max: self.calls.maximum(),
604            });
605            (word, Instant::now())
606        });
607        let outcome = self.run_call(call, streams, tree);
608        let result = match &outcome {
609            dekopon_shell::RunResult::Invoked { result, .. }
610            | dekopon_shell::RunResult::Returned(result)
611            | dekopon_shell::RunResult::Uncertain(result) => result,
612        };
613        if let Some((word, started)) = reported {
614            self.emit(ProgressEvent::ToolFinished {
615                word,
616                outcome: call_outcome(result),
617                duration: started.elapsed(),
618            });
619        }
620        outcome
621    }
622
623    fn invoke(
624        &self,
625        proposal: dekopon_shell::CommandProposal,
626        streams: dekopon_shell::Streams,
627        tree: &dekopon_process::TreeContext,
628    ) -> CapabilityCallResult {
629        let dekopon_shell::CommandProposal {
630            capability,
631            input,
632            secret_use,
633            report,
634        } = proposal;
635        let capability = capability.as_str();
636        let cancelled = self.cancel.is_cancelled() || tree.is_cancelled();
637        let calls_used = self.calls.used();
638        // Checks the capability exists before reporting it on the progress surface, since reporting
639        // an unvalidated identifier first would let a model put invented text on a person's chat
640        // line.
641        let reported = report
642            .is_none()
643            .then(|| {
644                self.capabilities.contains_key(capability).then(|| {
645                    let word = CommandWord::new(capability);
646                    self.emit(ProgressEvent::ToolStarted {
647                        word: word.clone(),
648                        argument_count: bounded_count(
649                            input.as_object().map_or(0, serde_json::Map::len),
650                        ),
651                        calls_used,
652                        calls_max: self.calls.maximum(),
653                    });
654                    (word, Instant::now())
655                })
656            })
657            .flatten();
658        let (result, outcome) = if cancelled {
659            (
660                CapabilityCallResult::Denied {
661                    reason: "session-cancelled".to_owned(),
662                },
663                ToolOutcome::Cancelled,
664            )
665        } else {
666            let result = self.submit(capability, input, secret_use, streams, tree);
667            let outcome = call_outcome(&result);
668            (result, outcome)
669        };
670        if let Some(report) = report {
671            report.complete(report_outcome(outcome));
672        }
673        if let Some((word, started)) = reported {
674            self.emit(ProgressEvent::ToolFinished {
675                word,
676                outcome,
677                duration: started.elapsed(),
678            });
679        }
680        result
681    }
682
683    fn note(&self, text: &str, eta: Option<Duration>) {
684        const MAX_NOTES_PER_SCRIPT: u32 = 8;
685        if !self.notes_enabled || self.progress.is_none() {
686            return;
687        }
688        let Some(text) = ProgressNote::new(text) else {
689            tracing::debug!(
690                event = "agent_progress_note_dropped",
691                reason = "empty",
692                "agent.progress.note.dropped"
693            );
694            return;
695        };
696        if self
697            .notes
698            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |count| {
699                (count < MAX_NOTES_PER_SCRIPT).then_some(count + 1)
700            })
701            .is_err()
702        {
703            tracing::debug!(
704                event = "agent_progress_note_dropped",
705                reason = "script-cap",
706                "agent.progress.note.dropped"
707            );
708            return;
709        }
710        self.emit(ProgressEvent::Note { text, eta });
711    }
712
713    fn job_control(&self) -> Option<&dyn JobControl> {
714        self.jobs.as_deref()
715    }
716}
717
718#[cfg(unix)]
719impl BrokerLeg {
720    async fn prepare_run_assets(
721        &self,
722        argv: &[dekopon_shell::Arg],
723        sends_remaining: u8,
724    ) -> Result<attachment::PreparedRun, ChatAssetRefusal> {
725        match &self.asset_inputs {
726            Some(inputs) => inputs.prepare_run(argv, sends_remaining).await,
727            None => {
728                let (argv, ids) = attachment::run_arguments(argv)?;
729                if !ids.is_empty() {
730                    return Err(ChatAssetRefusal::UnknownAsset);
731                }
732                Ok(attachment::PreparedRun {
733                    argv,
734                    assets: dekopon_broker_protocol::InvokeAssets {
735                        sends_remaining,
736                        ..Default::default()
737                    },
738                    pins: Vec::new(),
739                })
740            }
741        }
742    }
743
744    fn run_call(
745        &self,
746        call: dekopon_shell::RunCall,
747        streams: dekopon_shell::Streams,
748        tree: &TreeContext,
749    ) -> dekopon_shell::RunResult {
750        use dekopon_broker_protocol::{RunOutcome, RunRequest};
751        use dekopon_shell::{RunResult, render_command};
752        if self.cancel.is_cancelled() || tree.is_cancelled() {
753            return RunResult::Returned(CapabilityCallResult::Denied {
754                reason: "session-cancelled".to_owned(),
755            });
756        }
757        let word = call.word.clone();
758        let invocation = self.identifiers.next_invocation();
759        let invocation_text = invocation.to_string();
760        let remaining = self.attachments.as_ref().map_or(0, |slot| slot.remaining());
761        let dispatcher = tracing::dispatcher::get_default(Clone::clone);
762        let cancel = &self.cancel;
763        let prepared = self.runtime.block_on(async {
764            tokio::select! {
765                biased;
766                () = cancel.cancelled() => None,
767                () = tokio::time::sleep(tree.remaining()) => None,
768                result = async {
769                    let prepared = self.prepare_run_assets(&call.argv, remaining).await?;
770                    let output = streams.stdout.try_clone().map_err(|error| {
771                        ChatAssetRefusal::Storage(dekopon_model::asset::BlobError::from(error))
772                    })?;
773                    Ok::<_, ChatAssetRefusal>((prepared, output))
774                } => Some(result),
775            }
776        });
777        let (
778            attachment::PreparedRun {
779                argv,
780                mut assets,
781                pins: _pins,
782            },
783            output,
784        ) = match prepared {
785            None => {
786                return RunResult::Returned(CapabilityCallResult::Denied {
787                    reason: "script-cancelled".to_owned(),
788                });
789            }
790            Some(Err(refusal)) => {
791                tracing::warn!(target: "dekopon_agent::audit", { audit.event = "agent.chat_asset_input.refused", reason = refusal.reason() }, "agent.chat_asset_input.refused");
792                return RunResult::Returned(CapabilityCallResult::Denied {
793                    reason: format!(
794                        "the gateway refused this call before it reached the broker: {}",
795                        refusal.note()
796                    ),
797                });
798            }
799            Some(Ok(prepared)) => prepared,
800        };
801        if cancel.is_cancelled() || tree.remaining().is_zero() {
802            return RunResult::Returned(CapabilityCallResult::Denied {
803                reason: "script-cancelled".to_owned(),
804            });
805        }
806        assets.streams = Some(dekopon_broker_protocol::Streams {
807            stdin: streams.stdin,
808            stdout: streams.stdout,
809        });
810        let submitted = upcall_scope(|scope| {
811            self.runtime.block_on(async {
812                tokio::select! {
813                    biased;
814                    outcome = self.client.run(
815                        self.attestation.clone(),
816                        RunRequest { invocation, trace_parent: self.identifiers.trace_parent(), word: call.word, argv },
817                        assets,
818                        async |upcall| self.answer(scope, upcall, tree, &dispatcher).await,
819                    ) => Some(outcome),
820                    () = cancel.cancelled() => None,
821                    () = tokio::time::sleep(tree.remaining()) => None,
822                }
823            })
824        });
825        match submitted {
826            None => RunResult::Uncertain(CapabilityCallResult::Denied {
827                reason: "script-cancelled".to_owned(),
828            }),
829            Some(Err(error))
830                if !matches!(&error, ClientError::Remote { .. }) && !error.may_have_executed() =>
831            {
832                RunResult::Returned(CapabilityCallResult::Failed {
833                    error: error.to_string(),
834                    detail: None,
835                })
836            }
837            Some(Err(error)) => RunResult::Uncertain(CapabilityCallResult::Denied {
838                reason: format!(
839                    "the broker did not record an outcome for this invocation and it may already have taken effect; do not resubmit it ({error})"
840                ),
841            }),
842            Some(Ok(response)) => {
843                let streams = dekopon_shell::Streams {
844                    stdin: None,
845                    stdout: output,
846                };
847                match response.outcome {
848                    RunOutcome::Rendered {
849                        stdout,
850                        stderr,
851                        status,
852                    } => render_command(streams, &stdout, stderr, status),
853                    RunOutcome::Refused { error } => render_command(streams, "", error.message, 2),
854                    RunOutcome::NotFound => render_command(
855                        streams,
856                        "",
857                        format!("dekopon-shell: {word}: command not found\n"),
858                        127,
859                    ),
860                    RunOutcome::NotGranted { capability } => render_command(
861                        streams,
862                        "",
863                        format!(
864                            "dekopon-shell: {word}: requires capability {capability}, which is not granted in this session\n"
865                        ),
866                        127,
867                    ),
868                    RunOutcome::Invoked {
869                        capability,
870                        input,
871                        secret_use,
872                        result,
873                        attached,
874                        removed,
875                        sent,
876                    } => {
877                        let result = self.receive_outcome(
878                            dekopon_broker_protocol::AssetInvocationOutcome {
879                                result,
880                                attached,
881                                removed,
882                                sent,
883                                descriptors: response.descriptors,
884                            },
885                            capability.as_str(),
886                            &invocation_text,
887                        );
888                        RunResult::Invoked {
889                            capability: capability.to_string(),
890                            input,
891                            secret_use,
892                            result,
893                        }
894                    }
895                }
896            }
897        }
898    }
899
900    fn receive_outcome(
901        &self,
902        outcome: dekopon_broker_protocol::AssetInvocationOutcome,
903        capability: &str,
904        invocation: &str,
905    ) -> CapabilityCallResult {
906        let result = outcome.result;
907        match result.outcome {
908            InvocationOutcome::Succeeded => {
909                let note = if let Some(slot) = &self.attachments {
910                    slot.receive(
911                        outcome.attached,
912                        outcome.descriptors,
913                        outcome.removed,
914                        outcome.sent,
915                        capability,
916                        invocation,
917                    )
918                } else if !outcome.attached.is_empty()
919                    || !outcome.removed.is_empty()
920                    || !outcome.sent.is_empty()
921                {
922                    "[gateway: capability executed but this embedder has no asset store; received asset effects could not be retained or delivered; do not repeat the paid call]".to_owned()
923                } else {
924                    String::new()
925                };
926                let mut stderr = result
927                    .detail
928                    .map(|detail| detail.message)
929                    .unwrap_or_default();
930                if !note.is_empty() {
931                    if !stderr.is_empty() && !stderr.ends_with('\n') {
932                        stderr.push('\n');
933                    }
934                    stderr.push_str(&note);
935                    stderr.push('\n');
936                }
937                if stderr.is_empty() {
938                    CapabilityCallResult::Succeeded
939                } else {
940                    CapabilityCallResult::SucceededWithStderr(stderr)
941                }
942            }
943            InvocationOutcome::Denied => CapabilityCallResult::Denied {
944                reason: result
945                    .error
946                    .unwrap_or_else(|| "authorization refused this invocation".to_owned()),
947            },
948            InvocationOutcome::Failed => match result.exit_status {
949                Some(status) => CapabilityCallResult::Exited {
950                    status,
951                    stderr: result
952                        .detail
953                        .map(|detail| detail.message)
954                        .unwrap_or_default(),
955                },
956                None => CapabilityCallResult::Failed {
957                    error: result
958                        .error
959                        .unwrap_or_else(|| "the broker reported a failed invocation".to_owned()),
960                    detail: result.detail,
961                },
962            },
963        }
964    }
965
966    fn submit(
967        &self,
968        capability: &str,
969        input: Value,
970        secret_use: Option<dekopon_core::SecretUseProposal>,
971        streams: dekopon_shell::Streams,
972        tree: &TreeContext,
973    ) -> CapabilityCallResult {
974        let Ok(parsed) = capability.parse::<CapabilityId>() else {
975            return CapabilityCallResult::NotFound;
976        };
977        // This is a visibility check only, not an authorization decision; it just avoids spending
978        // capability-call budget on probes with guessed identifiers, and any real refusal still
979        // comes from the broker.
980        if !self.capabilities.contains_key(capability) {
981            return CapabilityCallResult::NotFound;
982        }
983        // Safe only because this runs on a spawn_blocking thread; calling block_on here from an
984        // ordinary runtime worker would deadlock the executor.
985        let dispatcher = tracing::dispatcher::get_default(Clone::clone);
986        // A child script runs on its own scoped thread, never inside this future: its broker calls
987        // re-enter `Handle::block_on`, which panics on a thread already inside one. Cancel drops this
988        // future and its connection first; the scope then joins a child that sees the same cancel.
989        let cancel = &self.cancel;
990        let submitted = upcall_scope(|scope| {
991            self.runtime.block_on(async {
992                tokio::select! {
993                    result = async {
994                        let mut assets = dekopon_broker_protocol::InvokeAssets {
995                            sends_remaining: self.attachments.as_ref().map_or(0, |slot| slot.remaining()),
996                            ..Default::default()
997                        };
998                        assets.streams = Some(dekopon_broker_protocol::Streams {
999                            stdin: streams.stdin,
1000                            stdout: streams.stdout,
1001                        });
1002                        let request = InvocationRequest {
1003                            id: self.identifiers.next_invocation(),
1004                            capability: parsed,
1005                            trace_parent: self.identifiers.trace_parent(),
1006                            secret_use,
1007                            input,
1008                        };
1009                        let invocation = request.id.to_string();
1010                        let outcome = self.client.invoke(
1011                            self.attestation.clone(),
1012                            request,
1013                            assets,
1014                            async |upcall| self.answer(scope, upcall, tree, &dispatcher).await,
1015                        ).await;
1016                        Ok::<_, ChatAssetRefusal>((outcome, invocation))
1017                    } => Some(result),
1018                    () = cancel.cancelled() => None,
1019                    () = tokio::time::sleep(tree.remaining()) => None,
1020                }
1021            })
1022        });
1023        match submitted {
1024            None => CapabilityCallResult::Denied {
1025                reason: "script-cancelled".to_owned(),
1026            },
1027            // This refusal is permanent, the interpreter's non-retryable Denied rather than a
1028            // retryable Failed, and produces no broker audit record since no proposal was ever
1029            // submitted.
1030            Some(Err(refusal)) => CapabilityCallResult::Denied {
1031                reason: format!(
1032                    "the gateway refused this call before it reached the broker: {}",
1033                    refusal.note()
1034                ),
1035            },
1036            Some(Ok((Ok(outcome), invocation))) => {
1037                self.receive_outcome(outcome, capability, &invocation)
1038            }
1039            Some(Ok((Err(ClientError::Remote { code, message }), _)))
1040                if code == ERROR_UNAUTHENTICATED =>
1041            {
1042                CapabilityCallResult::Denied { reason: message }
1043            }
1044            // A client-side timeout cannot tell whether the call ran, so it is treated as the one
1045            // non-retryable Denied status with an explicit refusal to resubmit, rather than a
1046            // Failed a model would retry.
1047            Some(Ok((Err(error), _))) if error.may_have_executed() => {
1048                CapabilityCallResult::Denied {
1049                    reason: format!(
1050                        "the broker did not record an outcome for this invocation and it may already \
1051                     have taken effect; do not resubmit it ({error})"
1052                    ),
1053                }
1054            }
1055            // Every ClientError renders without the socket path, since this is the one path that
1056            // could otherwise leak DEKOPON_BROKER_SOCKET back into a script.
1057            Some(Ok((Err(error), _))) => CapabilityCallResult::Failed {
1058                error: error.to_string(),
1059                detail: None,
1060            },
1061        }
1062    }
1063}
1064
1065#[cfg(unix)]
1066impl BrokerLeg {
1067    async fn answer<'scope>(
1068        &'scope self,
1069        scope: &'scope std::thread::Scope<'scope, '_>,
1070        upcall: Upcall,
1071        tree: &'scope TreeContext,
1072        dispatcher: &tracing::Dispatch,
1073    ) -> UpcallExit {
1074        let Upcall {
1075            parent,
1076            script,
1077            trace_parent,
1078            streams: UpcallStreams { stdout, stdin },
1079        } = upcall;
1080        let (script_stdin, feed) = match stdin.map(child_stdin).transpose() {
1081            Ok(Some((reader, feed))) => (Some(reader), Some(feed)),
1082            Ok(None) => (None, None),
1083            Err(error) => {
1084                tracing::warn!(
1085                    event = "gateway_child_stdin_unavailable",
1086                    error = %error,
1087                    "gateway.child.stdin.unavailable"
1088                );
1089                return UpcallExit {
1090                    status: ExitCode::FAILURE.get(),
1091                    stderr: "dekopon-shell: the child script's stdin could not be opened"
1092                        .to_owned(),
1093                };
1094            }
1095        };
1096        let span = tracing::info_span!("gateway.upcall", parent = %parent);
1097        if let Some(trace_parent) = trace_parent
1098            && let Err(error) = dekopon_telemetry::parent_remote(
1099                &span,
1100                dekopon_telemetry::TraceContextParts {
1101                    trace_id: trace_parent.trace_id(),
1102                    span_id: trace_parent.parent_id(),
1103                    flags: trace_parent.flags(),
1104                },
1105            )
1106        {
1107            tracing::debug!(
1108                event = "gateway_upcall_trace_parent_ignored",
1109                error = %error,
1110                "gateway.upcall.trace.parent.ignored"
1111            );
1112        }
1113        let (finished, outcome) = tokio::sync::oneshot::channel();
1114        let dispatcher = dispatcher.clone();
1115        let tree = tree.clone().with_parent_cancel(self.cancel.clone());
1116        let [permit] = match tree.shell_threads().reserve() {
1117            Ok(permit) => permit,
1118            Err(limit) => return deliver_child(stdout, ScriptOutcome::refused(limit)).await,
1119        };
1120        let spawned = permit.spawn(scope, UPCALL_THREAD, move || {
1121            let outcome =
1122                tracing::dispatcher::with_default(&dispatcher, || {
1123                    span.in_scope(|| {
1124                        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
1125                            Interpreter::new(*tree.limits(), tree.shell_threads().clone())
1126                                .run_child(&script, script_stdin, self, &tree)
1127                        }))
1128                    })
1129                });
1130            #[allow(
1131                clippy::let_underscore_must_use,
1132                reason = "a closed receiver means the invocation was cancelled and nobody waits"
1133            )]
1134            let _ = finished.send(outcome.ok());
1135        });
1136        if let Err(error) = spawned {
1137            tracing::warn!(
1138                event = "gateway_child_thread_unstarted",
1139                parent = %parent,
1140                error = %error,
1141                "gateway.child.thread.unstarted"
1142            );
1143            return UpcallExit {
1144                status: ExitCode::FAILURE.get(),
1145                stderr: "dekopon-shell: the child script's thread could not start".to_owned(),
1146            };
1147        }
1148        let pumped = async {
1149            if let Some((source, sink)) = feed {
1150                pump_child_stdin(source, sink).await;
1151            }
1152            std::future::pending::<std::convert::Infallible>().await
1153        };
1154        let outcome = tokio::select! {
1155            outcome = outcome => outcome.ok().flatten(),
1156            never = pumped => match never {},
1157        };
1158        let Some(outcome) = outcome else {
1159            tracing::warn!(
1160                event = "gateway_child_script_panicked",
1161                parent = %parent,
1162                "gateway.child.script.panicked"
1163            );
1164            return UpcallExit {
1165                status: CHILD_PANICKED,
1166                stderr: "dekopon-shell: the child script panicked".to_owned(),
1167            };
1168        };
1169        deliver_child(stdout, outcome).await
1170    }
1171}
1172
1173#[cfg(unix)]
1174const UPCALL_THREAD: ThreadName = ThreadName::new("sh-upcall");
1175
1176#[cfg(unix)]
1177#[expect(
1178    clippy::disallowed_methods,
1179    reason = "owner: the broker call, whose scope joins every child-script upcall before returning; bound: each upcall's ShellThreads permit"
1180)]
1181fn upcall_scope<'env, T>(
1182    run: impl for<'scope> FnOnce(&'scope std::thread::Scope<'scope, 'env>) -> T,
1183) -> T {
1184    std::thread::scope(run)
1185}
1186
1187#[cfg(unix)]
1188async fn deliver_child(stdout: OwnedFd, outcome: ScriptOutcome) -> UpcallExit {
1189    let mut text = outcome.output;
1190    if !text.is_empty() && !text.ends_with('\n') {
1191        text.push('\n');
1192    }
1193    if let Err(error) = write_child_stdout(stdout, text.as_bytes()).await {
1194        tracing::debug!(
1195            event = "gateway_child_stdout_unread",
1196            error = %error,
1197            "gateway.child.stdout.unread"
1198        );
1199    }
1200    UpcallExit {
1201        status: outcome.exit_code.get(),
1202        stderr: String::new(),
1203    }
1204}
1205
1206#[cfg(unix)]
1207const CHILD_PANICKED: u8 = 70;
1208
1209#[cfg(unix)]
1210fn child_stdin(
1211    source: OwnedFd,
1212) -> std::io::Result<(
1213    dekopon_shell::ChildStdin,
1214    (OwnedFd, std::os::unix::net::UnixStream),
1215)> {
1216    let (reader, writer) = std::os::unix::net::UnixStream::pair()?;
1217    Ok((dekopon_shell::ChildStdin::adopt(reader)?, (source, writer)))
1218}
1219
1220#[cfg(unix)]
1221fn nonblocking(socket: std::os::unix::net::UnixStream) -> std::io::Result<tokio::net::UnixStream> {
1222    socket.set_nonblocking(true)?;
1223    tokio::net::UnixStream::from_std(socket)
1224}
1225
1226#[cfg(unix)]
1227async fn pump_child_stdin(source: OwnedFd, sink: std::os::unix::net::UnixStream) {
1228    let pumped = async {
1229        let mut source = nonblocking(std::os::unix::net::UnixStream::from(source))?;
1230        let mut sink = nonblocking(sink)?;
1231        tokio::io::copy(&mut source, &mut sink).await
1232    };
1233    if let Err(error) = pumped.await {
1234        tracing::debug!(
1235            event = "gateway_child_stdin_ended",
1236            error = %error,
1237            "gateway.child.stdin.ended"
1238        );
1239    }
1240}
1241
1242#[cfg(unix)]
1243async fn write_child_stdout(stdout: OwnedFd, bytes: &[u8]) -> std::io::Result<()> {
1244    use tokio::io::AsyncWriteExt as _;
1245    let mut stdout = nonblocking(std::os::unix::net::UnixStream::from(stdout))?;
1246    stdout.write_all(bytes).await
1247}
1248
1249#[cfg(unix)]
1250#[derive(Clone)]
1251pub struct IdSequence {
1252    parent: TraceParent,
1253    next: Arc<AtomicU32>,
1254}
1255
1256#[cfg(unix)]
1257impl IdSequence {
1258    #[must_use]
1259    pub fn for_session() -> Self {
1260        Self {
1261            parent: session_trace_parent(),
1262            next: Arc::new(AtomicU32::new(1)),
1263        }
1264    }
1265
1266    #[must_use]
1267    pub const fn trace(&self) -> TraceId {
1268        self.parent.trace()
1269    }
1270
1271    #[must_use]
1272    pub fn trace_parent(&self) -> TraceParent {
1273        current_trace_parent()
1274            .filter(|live| live.trace() == self.parent.trace())
1275            .unwrap_or(self.parent)
1276    }
1277
1278    #[must_use]
1279    pub fn next_invocation(&self) -> InvocationId {
1280        let counter = self.next.fetch_add(1, Ordering::Relaxed);
1281        format!("{}-{counter}", self.parent.trace())
1282            .parse()
1283            .expect("a trace and a counter are a valid invocation identifier")
1284    }
1285}
1286
1287#[cfg(unix)]
1288impl Default for IdSequence {
1289    fn default() -> Self {
1290        Self::for_session()
1291    }
1292}
1293
1294// Always emit duration as whole milliseconds; a mixed type here makes the telemetry backend reject
1295// later records.
1296pub(crate) fn milliseconds(duration: Duration) -> u64 {
1297    u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
1298}
1299
1300#[cfg(test)]
1301mod tests {
1302    use dekopon_shell::{
1303        CapabilityCallResult, CapabilityDescription, CapabilityInvoker, CommandProposal,
1304    };
1305    use serde_json::json;
1306    use std::{io::Read, os::fd::OwnedFd, os::unix::net::UnixStream};
1307
1308    use super::{SessionInvoker, current_trace_parent};
1309
1310    fn streams() -> (dekopon_shell::Streams, UnixStream) {
1311        let (writer, reader) = UnixStream::pair().expect("stdout socketpair");
1312        reader
1313            .set_read_timeout(Some(std::time::Duration::from_secs(5)))
1314            .expect("stdout read timeout");
1315        (
1316            dekopon_shell::Streams {
1317                stdin: None,
1318                stdout: OwnedFd::from(writer),
1319            },
1320            reader,
1321        )
1322    }
1323
1324    fn output(mut reader: UnixStream) -> String {
1325        let mut bytes = Vec::new();
1326        reader
1327            .read_to_end(&mut bytes)
1328            .expect("every stdout writer closes by the time the call returns");
1329        String::from_utf8(bytes).expect("stdout text")
1330    }
1331
1332    #[test]
1333    fn trace_parent_is_absent_without_an_active_exporting_span() {
1334        assert!(current_trace_parent().is_none());
1335    }
1336
1337    struct FakeLeg {
1338        capability: &'static str,
1339        marker: &'static str,
1340        invoked: parking_lot::Mutex<Vec<String>>,
1341        secret_uses: parking_lot::Mutex<Vec<Option<dekopon_core::SecretUseProposal>>>,
1342    }
1343
1344    impl FakeLeg {
1345        fn new(capability: &'static str, marker: &'static str) -> Self {
1346            Self {
1347                capability,
1348                marker,
1349                invoked: parking_lot::Mutex::new(Vec::new()),
1350                secret_uses: parking_lot::Mutex::new(Vec::new()),
1351            }
1352        }
1353    }
1354
1355    impl CapabilityInvoker for FakeLeg {
1356        fn granted(&self) -> Vec<String> {
1357            vec![self.capability.to_owned()]
1358        }
1359
1360        fn describe(&self, capability: &str) -> Option<CapabilityDescription> {
1361            (capability == self.capability).then(|| CapabilityDescription {
1362                capability: capability.to_owned(),
1363                description: self.marker.to_owned(),
1364            })
1365        }
1366
1367        fn invoke(
1368            &self,
1369            proposal: dekopon_shell::CommandProposal,
1370            streams: dekopon_shell::Streams,
1371            _tree: &dekopon_process::TreeContext,
1372        ) -> CapabilityCallResult {
1373            let capability = proposal.capability;
1374            let secret_use = proposal.secret_use;
1375            if capability != self.capability {
1376                return CapabilityCallResult::NotFound;
1377            }
1378            self.invoked.lock().push(capability.to_owned());
1379            self.secret_uses.lock().push(secret_use);
1380            streams.reply(&json!({ "leg": self.marker }))
1381        }
1382    }
1383
1384    #[test]
1385    fn direct_capabilities_are_preferred_over_the_broker() {
1386        let shared = Box::new(FakeLeg::new("shared.capability", "broker"));
1387        let invoker = SessionInvoker {
1388            direct: FakeLeg::new("shared.capability", "direct"),
1389            broker: Some(shared),
1390        };
1391
1392        let (streams, reader) = streams();
1393        assert_eq!(
1394            invoker.invoke(
1395                CommandProposal::new("shared.capability", json!({}), None),
1396                streams,
1397                &dekopon_process::TreeContext::new(
1398                    dekopon_process::Limits::default(),
1399                    dekopon_process::CallBudget::new(64),
1400                    dekopon_test_support::shell_threads()
1401                )
1402            ),
1403            CapabilityCallResult::Succeeded
1404        );
1405        assert_eq!(output(reader), "{\"leg\":\"direct\"}\n");
1406    }
1407
1408    #[test]
1409    fn capabilities_absent_from_direct_mode_fall_through_to_the_broker() {
1410        let invoker = SessionInvoker {
1411            direct: FakeLeg::new("cli-probe.upper", "direct"),
1412            broker: Some(Box::new(FakeLeg::new("http-probe.fetch", "broker"))),
1413        };
1414
1415        let (streams, reader) = streams();
1416        assert_eq!(
1417            invoker.invoke(
1418                CommandProposal::new("http-probe.fetch", json!({}), None),
1419                streams,
1420                &dekopon_process::TreeContext::new(
1421                    dekopon_process::Limits::default(),
1422                    dekopon_process::CallBudget::new(64),
1423                    dekopon_test_support::shell_threads()
1424                )
1425            ),
1426            CapabilityCallResult::Succeeded
1427        );
1428        assert_eq!(output(reader), "{\"leg\":\"broker\"}\n");
1429        assert!(invoker.is_granted("http-probe.fetch"));
1430        assert_eq!(
1431            invoker.granted(),
1432            vec!["cli-probe.upper".to_owned(), "http-probe.fetch".to_owned()]
1433        );
1434        assert_eq!(
1435            invoker
1436                .describe("http-probe.fetch")
1437                .map(|it| it.description),
1438            Some("broker".to_owned())
1439        );
1440    }
1441
1442    #[test]
1443    fn a_word_without_a_broker_stays_behind_admission_when_the_budget_is_spent() {
1444        use crate::prompt::ScriptRuntime as _;
1445
1446        let runtime = crate::ShellRuntime {
1447            invoker: SessionInvoker {
1448                direct: FakeLeg::new("cli-probe.upper", "direct"),
1449                broker: None,
1450            },
1451            limits: dekopon_process::Limits {
1452                max_capability_calls: 0,
1453                ..dekopon_process::Limits::default()
1454            },
1455            calls: dekopon_process::CallBudget::new(0),
1456            threads: dekopon_test_support::shell_threads(),
1457        };
1458        let result = runtime.run_script(
1459            "nosuchword || { echo status=$?; echo fallback; }; echo after",
1460            None,
1461        );
1462        assert_eq!(result.exit_code, dekopon_process::ExitCode::SYNTAX);
1463        assert_eq!(
1464            result.output,
1465            "dekopon-shell: the turn's capability-call budget of 0 is spent"
1466        );
1467        assert_eq!(runtime.calls.used(), 0);
1468    }
1469
1470    #[test]
1471    fn a_session_without_a_broker_is_exactly_as_capable_as_direct_mode() {
1472        let invoker = SessionInvoker {
1473            direct: FakeLeg::new("cli-probe.upper", "direct"),
1474            broker: None,
1475        };
1476
1477        assert_eq!(invoker.granted(), vec!["cli-probe.upper".to_owned()]);
1478        assert!(!invoker.is_granted("http-probe.fetch"));
1479        assert_eq!(
1480            invoker.invoke(
1481                CommandProposal::new("http-probe.fetch", json!({}), None),
1482                streams().0,
1483                &dekopon_process::TreeContext::new(
1484                    dekopon_process::Limits::default(),
1485                    dekopon_process::CallBudget::new(64),
1486                    dekopon_test_support::shell_threads()
1487                )
1488            ),
1489            CapabilityCallResult::NotFound
1490        );
1491    }
1492
1493    #[test]
1494    fn a_secret_use_proposal_reaches_only_a_broker_backed_capability() {
1495        let proposal = dekopon_core::SecretUseProposal::HttpBearer {
1496            secret: "drn:secret:api/token"
1497                .parse::<dekopon_core::SecretDrn>()
1498                .expect("canonical DRN"),
1499        };
1500        let broker = Box::new(FakeLeg::new("http-probe.fetch", "broker"));
1501        let invoker = SessionInvoker {
1502            direct: FakeLeg::new("cli-probe.upper", "direct"),
1503            broker: Some(broker),
1504        };
1505
1506        assert_eq!(
1507            invoker.invoke(
1508                CommandProposal::new("http-probe.fetch", json!({}), Some(proposal.clone())),
1509                streams().0,
1510                &dekopon_process::TreeContext::new(
1511                    dekopon_process::Limits::default(),
1512                    dekopon_process::CallBudget::new(64),
1513                    dekopon_test_support::shell_threads()
1514                )
1515            ),
1516            CapabilityCallResult::Succeeded
1517        );
1518
1519        assert_eq!(
1520            invoker.invoke(
1521                CommandProposal::new("cli-probe.upper", json!({}), Some(proposal)),
1522                streams().0,
1523                &dekopon_process::TreeContext::new(
1524                    dekopon_process::Limits::default(),
1525                    dekopon_process::CallBudget::new(64),
1526                    dekopon_test_support::shell_threads()
1527                )
1528            ),
1529            dekopon_shell::secret_use_unsupported()
1530        );
1531        assert!(
1532            invoker.direct.secret_uses.lock().is_empty(),
1533            "the direct leg was handed a proposal it cannot authorize"
1534        );
1535    }
1536
1537    #[derive(Default)]
1538    struct JobsLeg {
1539        calls: parking_lot::Mutex<Vec<String>>,
1540    }
1541
1542    impl dekopon_shell::JobControl for JobsLeg {
1543        fn start(
1544            &self,
1545            seed: dekopon_shell::JobSeed,
1546        ) -> Result<dekopon_process::JobId, dekopon_shell::JobRefusal> {
1547            self.calls.lock().push(format!("start {}", seed.text()));
1548            Ok(dekopon_process::JobId::new(7))
1549        }
1550
1551        fn list(&self) -> Vec<dekopon_process::JobSummary> {
1552            self.calls.lock().push("list".to_owned());
1553            Vec::new()
1554        }
1555
1556        fn wait(
1557            &self,
1558            ids: &[dekopon_process::JobId],
1559            _keep_waiting: &dyn Fn() -> bool,
1560        ) -> Vec<Result<dekopon_process::JobWait, dekopon_shell::JobRefusal>> {
1561            ids.iter()
1562                .map(|id| {
1563                    self.calls.lock().push(format!("wait {id}"));
1564                    Ok(dekopon_process::JobWait::Interrupted)
1565                })
1566                .collect()
1567        }
1568
1569        fn kill(&self, id: dekopon_process::JobId) -> Result<(), dekopon_shell::JobRefusal> {
1570            self.calls.lock().push(format!("kill {id}"));
1571            Ok(())
1572        }
1573    }
1574
1575    impl CapabilityInvoker for JobsLeg {
1576        fn granted(&self) -> Vec<String> {
1577            Vec::new()
1578        }
1579
1580        fn job_control(&self) -> Option<&dyn dekopon_shell::JobControl> {
1581            Some(self)
1582        }
1583
1584        fn invoke(
1585            &self,
1586            _: CommandProposal,
1587            _streams: dekopon_shell::Streams,
1588            _tree: &dekopon_process::TreeContext,
1589        ) -> CapabilityCallResult {
1590            CapabilityCallResult::NotFound
1591        }
1592    }
1593
1594    #[test]
1595    fn a_session_invoker_reaches_the_job_control_of_its_broker_leg() {
1596        let leg = std::sync::Arc::new(JobsLeg::default());
1597        let invoker = SessionInvoker {
1598            direct: FakeLeg::new("cli-probe.upper", "direct"),
1599            broker: Some(Box::new(std::sync::Arc::clone(&leg))),
1600        };
1601        let outcome = dekopon_shell::Interpreter::new(
1602            dekopon_process::Limits::default(),
1603            dekopon_test_support::shell_threads(),
1604        )
1605        .run("echo a &", &invoker);
1606        assert_eq!(outcome.output, "[7]");
1607        let jobs = invoker.job_control().expect("the broker leg's job control");
1608        let id = dekopon_process::JobId::new(7);
1609        assert!(jobs.list().is_empty());
1610        assert_eq!(
1611            jobs.wait(&[id], &|| false),
1612            [Ok(dekopon_process::JobWait::Interrupted)]
1613        );
1614        assert_eq!(jobs.kill(id), Ok(()));
1615        assert_eq!(
1616            *leg.calls.lock(),
1617            ["start echo a", "list", "wait 7", "kill 7"]
1618        );
1619        let without = SessionInvoker {
1620            direct: FakeLeg::new("cli-probe.upper", "direct"),
1621            broker: None,
1622        };
1623        assert!(without.job_control().is_none());
1624    }
1625
1626    struct CommandLeg {
1627        word: &'static str,
1628        capability: &'static str,
1629    }
1630
1631    impl CapabilityInvoker for CommandLeg {
1632        fn granted(&self) -> Vec<String> {
1633            Vec::new()
1634        }
1635
1636        fn is_granted(&self, capability: &str) -> bool {
1637            capability == self.capability
1638        }
1639
1640        fn command_words(&self) -> Vec<String> {
1641            vec![self.word.to_owned()]
1642        }
1643
1644        fn has_command_word(&self, word: &str) -> bool {
1645            word == self.word
1646        }
1647
1648        fn invoke(
1649            &self,
1650            _: dekopon_shell::CommandProposal,
1651            _streams: dekopon_shell::Streams,
1652            _tree: &dekopon_process::TreeContext,
1653        ) -> CapabilityCallResult {
1654            CapabilityCallResult::NotFound
1655        }
1656    }
1657
1658    #[test]
1659    fn command_words_and_grants_survive_both_legs_rather_than_falling_back_to_the_defaults() {
1660        let invoker = SessionInvoker {
1661            direct: CommandLeg {
1662                word: "probe",
1663                capability: "cli-probe.upper",
1664            },
1665            broker: Some(Box::new(CommandLeg {
1666                word: "gh",
1667                capability: "gh.pr-view",
1668            })),
1669        };
1670
1671        assert_eq!(
1672            invoker.command_words(),
1673            vec!["gh".to_owned(), "probe".to_owned()],
1674            "a word a provider contributed became `command not found`"
1675        );
1676        assert!(invoker.has_command_word("probe"));
1677        assert!(invoker.has_command_word("gh"));
1678        assert!(!invoker.has_command_word("git"));
1679
1680        assert!(invoker.granted().is_empty());
1681        assert!(
1682            invoker.is_granted("cli-probe.upper"),
1683            "the direct leg holds it"
1684        );
1685        assert!(invoker.is_granted("gh.pr-view"), "the broker leg holds it");
1686        assert!(!invoker.is_granted("gh.pr-merge"));
1687    }
1688
1689    #[cfg(unix)]
1690    mod broker_leg {
1691        use super::{output, streams};
1692        use parking_lot::Mutex;
1693        use std::{
1694            collections::{BTreeMap, BTreeSet},
1695            os::unix::fs::PermissionsExt as _,
1696            path::Path,
1697            sync::{Arc, atomic::AtomicU32},
1698            time::Duration,
1699        };
1700
1701        use dekopon_broker_protocol::{
1702            BrokerClient, BrokerRequest, DescriptorStream, ERROR_UNAUTHENTICATED, FrameLimits,
1703            InvocationOutcome, InvocationResult, RequestEnvelope, ResponseEnvelope,
1704        };
1705        use dekopon_capability::DecisionReference;
1706        use dekopon_core::{AgentId, ProviderFailureDetail, SecretDrn, SecretUseProposal, Subject};
1707        use dekopon_process::CancelSignal;
1708        use dekopon_process::ExitCode;
1709        use dekopon_process::Limits;
1710        use dekopon_shell::{
1711            CapabilityCallResult, CapabilityDescription, CapabilityInvoker, CommandProposal,
1712        };
1713        use serde_json::json;
1714        use tokio::{
1715            net::UnixListener,
1716            sync::{mpsc, oneshot},
1717        };
1718
1719        use crate::{
1720            Attestation, BrokerLeg, IdSequence, ProgressEvent, ProgressSink, ShellRuntime,
1721            current_trace_parent, meta::EffectiveCapabilityView, prompt::ScriptRuntime,
1722        };
1723
1724        const CAPABILITY: &str = "http-probe.fetch";
1725        const SUBJECT: &str = "drn:slack:user:t0123abc:u9xyz";
1726
1727        fn server_uid() -> u32 {
1728            rustix::process::geteuid().as_raw()
1729        }
1730
1731        fn private_broker_directory() -> tempfile::TempDir {
1732            let directory = tempfile::tempdir().expect("temporary broker directory");
1733            std::fs::set_permissions(directory.path(), std::fs::Permissions::from_mode(0o700))
1734                .expect("private broker directory");
1735            directory
1736        }
1737
1738        fn result(outcome: InvocationOutcome, error: Option<&str>) -> InvocationResult {
1739            InvocationResult {
1740                invocation: "invoke-stub".parse().expect("valid invocation fixture"),
1741                decision: DecisionReference {
1742                    decision_id: "decision-stub".to_owned(),
1743                    authorized_by: "broker-stub".parse().expect("valid principal fixture"),
1744                    policy_digest: "a".repeat(64),
1745                },
1746                outcome,
1747                exit_status: None,
1748                error: error.map(str::to_owned),
1749                detail: None,
1750                evidence: Vec::new(),
1751            }
1752        }
1753
1754        async fn stub_leg(directory: &Path, responses: Vec<ResponseEnvelope>) -> BrokerLeg {
1755            let (leg, _observed) = stub_leg_observing(directory, responses, None).await;
1756            leg
1757        }
1758
1759        async fn stub_leg_observing(
1760            directory: &Path,
1761            responses: Vec<ResponseEnvelope>,
1762            attestation: Option<Attestation>,
1763        ) -> (BrokerLeg, mpsc::UnboundedReceiver<RequestEnvelope>) {
1764            let socket = directory.join("broker.sock");
1765            let listener = UnixListener::bind(&socket).expect("bind stub broker");
1766            std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600))
1767                .expect("secure stub socket");
1768            let (observed, receiver) = mpsc::unbounded_channel();
1769            tokio::spawn(async move {
1770                let mut responses = responses
1771                    .into_iter()
1772                    .map(|response| (response, Vec::new()))
1773                    .collect();
1774                while !std::collections::VecDeque::is_empty(&responses) {
1775                    let (stream, _) = listener.accept().await.expect("stub broker accepts");
1776                    let mut stream = DescriptorStream::new(stream);
1777                    let (request, _) = stream
1778                        .read_frame::<RequestEnvelope>(FrameLimits::default())
1779                        .await
1780                        .expect("stub broker reads one request");
1781                    let (response, _) =
1782                        dekopon_test_support::next_broker_reply(&request, &mut responses).unwrap();
1783                    drop(observed.send(request));
1784                    stream
1785                        .write_frame(&response, &[], FrameLimits::default())
1786                        .await
1787                        .expect("stub broker writes one response");
1788                }
1789            });
1790
1791            (leg_with(&socket, attestation), receiver)
1792        }
1793
1794        async fn stub_leg_parked(
1795            directory: &Path,
1796        ) -> (
1797            BrokerLeg,
1798            mpsc::UnboundedReceiver<RequestEnvelope>,
1799            oneshot::Sender<()>,
1800        ) {
1801            let socket = directory.join("broker.sock");
1802            let listener = UnixListener::bind(&socket).expect("bind stub broker");
1803            std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600))
1804                .expect("secure stub socket");
1805            let (observed, receiver) = mpsc::unbounded_channel();
1806            let (release, released) = oneshot::channel::<()>();
1807            tokio::spawn(async move {
1808                let (stream, _) = listener.accept().await.expect("stub broker accepts");
1809                let mut stream = DescriptorStream::new(stream);
1810                let (request, _) = stream
1811                    .read_frame::<RequestEnvelope>(FrameLimits::default())
1812                    .await
1813                    .expect("stub broker reads one request");
1814                #[allow(
1815                    clippy::let_underscore_must_use,
1816                    reason = "the test may have finished observing before the stub reports"
1817                )]
1818                let _ = observed.send(request);
1819                #[allow(
1820                    clippy::let_underscore_must_use,
1821                    reason = "a dropped sender and a sent signal both mean the test is done"
1822                )]
1823                let _ = released.await;
1824                drop(stream);
1825            });
1826            (leg_for(&socket), receiver, release)
1827        }
1828
1829        async fn assert_exhausted_word_admission(
1830            outcome: dekopon_broker_protocol::RunOutcome,
1831            word: &'static str,
1832        ) {
1833            let directory = private_broker_directory();
1834            let response = ResponseEnvelope {
1835                api_version: dekopon_broker_protocol::ProtocolVersion::V1Alpha2,
1836                response: dekopon_broker_protocol::BrokerResponse::Ran { outcome },
1837            };
1838            let (leg, mut observed) =
1839                stub_leg_observing(directory.path(), vec![response], None).await;
1840            let calls = dekopon_process::CallBudget::new(0);
1841            let runtime = ShellRuntime {
1842                invoker: leg,
1843                limits: Limits {
1844                    max_capability_calls: 0,
1845                    ..Limits::default()
1846                },
1847                calls: calls.clone(),
1848                threads: dekopon_test_support::shell_threads(),
1849            };
1850            let script = format!("{word} || {{ echo status=$?; echo fallback; }}; echo after");
1851            let result = tokio::task::spawn_blocking(move || runtime.run_script(&script, None))
1852                .await
1853                .expect("the script completes");
1854            assert_eq!(result.exit_code, ExitCode::SYNTAX);
1855            assert_eq!(
1856                result.output,
1857                "dekopon-shell: the turn's capability-call budget of 0 is spent"
1858            );
1859            assert_eq!(calls.used(), 0);
1860            assert!(observed.try_recv().is_err());
1861        }
1862
1863        #[tokio::test(flavor = "multi_thread")]
1864        async fn an_unknown_word_stays_behind_admission_when_the_budget_is_spent() {
1865            assert_exhausted_word_admission(
1866                dekopon_broker_protocol::RunOutcome::NotFound,
1867                "nosuchword",
1868            )
1869            .await;
1870        }
1871
1872        #[tokio::test(flavor = "multi_thread")]
1873        async fn an_ungranted_word_stays_behind_admission_when_the_budget_is_spent() {
1874            assert_exhausted_word_admission(
1875                dekopon_broker_protocol::RunOutcome::Rendered {
1876                    stdout: String::new(),
1877                    stderr: "dekopon-shell: ssh: not granted in this conversation\n".to_owned(),
1878                    status: 127,
1879                },
1880                "ssh",
1881            )
1882            .await;
1883        }
1884
1885        #[tokio::test(flavor = "multi_thread")]
1886        async fn a_run_error_is_uncertain_and_never_refunds_its_call() {
1887            let directory = private_broker_directory();
1888            let (mut leg, mut observed) = stub_leg_observing(
1889                directory.path(),
1890                vec![ResponseEnvelope::error(
1891                    dekopon_broker_protocol::ERROR_BROKER_UNAVAILABLE,
1892                    "unavailable",
1893                )],
1894                None,
1895            )
1896            .await;
1897            leg.command_words.insert("probe".to_owned());
1898            let calls = dekopon_process::CallBudget::new(1);
1899            let tree = dekopon_process::TreeContext::new(
1900                Limits::default(),
1901                calls.clone(),
1902                dekopon_test_support::shell_threads(),
1903            );
1904            let outcome = tokio::task::spawn_blocking(move || {
1905                dekopon_shell::Interpreter::new(
1906                    Limits::default(),
1907                    dekopon_test_support::shell_threads(),
1908                )
1909                .run_with_tree("probe upper", &leg, &tree)
1910            })
1911            .await
1912            .unwrap();
1913            assert_eq!(outcome.exit_code, ExitCode::DENIED);
1914            assert!(outcome.output.contains("do not resubmit it"));
1915            assert_eq!(calls.used(), 1);
1916            assert!(matches!(
1917                observed.recv().await.unwrap().request,
1918                BrokerRequest::Run { .. }
1919            ));
1920        }
1921
1922        #[tokio::test(flavor = "multi_thread")]
1923        async fn cancellation_during_asset_resolution_refunds_without_a_frame() {
1924            use crate::attachment::{ChatAssetInputs, ChatAssetSource, ResolveFuture};
1925            struct PendingAsset(Mutex<Option<oneshot::Sender<()>>>);
1926            impl ChatAssetSource for PendingAsset {
1927                fn resolve_input(&self, _: u64) -> ResolveFuture<'_> {
1928                    let entered = self.0.lock().take().unwrap();
1929                    Box::pin(async move {
1930                        entered.send(()).unwrap();
1931                        std::future::pending().await
1932                    })
1933                }
1934            }
1935            let directory = private_broker_directory();
1936            let socket = directory.path().join("broker.sock");
1937            let listener = std::os::unix::net::UnixListener::bind(&socket).unwrap();
1938            std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600)).unwrap();
1939            listener.set_nonblocking(true).unwrap();
1940            let (entered, resolving) = oneshot::channel();
1941            let (handle, signal) = CancelSignal::pair();
1942            let mut leg = leg_for(&socket)
1943                .with_cancel_signal(signal)
1944                .with_chat_asset_inputs(ChatAssetInputs::new(Arc::new(PendingAsset(Mutex::new(
1945                    Some(entered),
1946                )))));
1947            leg.command_words.insert("probe".to_owned());
1948            let calls = dekopon_process::CallBudget::new(1);
1949            let tree = dekopon_process::TreeContext::new(
1950                Limits::default(),
1951                calls.clone(),
1952                dekopon_test_support::shell_threads(),
1953            );
1954            let run = tokio::task::spawn_blocking(move || {
1955                dekopon_shell::Interpreter::new(
1956                    Limits::default(),
1957                    dekopon_test_support::shell_threads(),
1958                )
1959                .run_with_tree("probe chat-asset:1", &leg, &tree)
1960            });
1961            resolving.await.unwrap();
1962            assert_eq!(calls.used(), 1);
1963            handle.cancel();
1964            let outcome = run.await.unwrap();
1965            assert_eq!(outcome.exit_code, ExitCode::DENIED);
1966            assert_eq!(calls.used(), 0);
1967            assert!(
1968                matches!(listener.accept(), Err(error) if error.kind() == std::io::ErrorKind::WouldBlock)
1969            );
1970        }
1971
1972        #[tokio::test(flavor = "multi_thread")]
1973        async fn cancellation_after_a_run_frame_keeps_its_call_charged() {
1974            let directory = private_broker_directory();
1975            let (mut leg, mut observed, release) = stub_leg_parked(directory.path()).await;
1976            leg.command_words.insert("probe".to_owned());
1977            let (handle, signal) = CancelSignal::pair();
1978            let leg = leg.with_cancel_signal(signal);
1979            let calls = dekopon_process::CallBudget::new(1);
1980            let tree = dekopon_process::TreeContext::new(
1981                Limits::default(),
1982                calls.clone(),
1983                dekopon_test_support::shell_threads(),
1984            );
1985            let run = tokio::task::spawn_blocking(move || {
1986                dekopon_shell::Interpreter::new(
1987                    Limits::default(),
1988                    dekopon_test_support::shell_threads(),
1989                )
1990                .run_with_tree("probe upper", &leg, &tree)
1991            });
1992            assert!(matches!(
1993                observed.recv().await.unwrap().request,
1994                BrokerRequest::Run { .. }
1995            ));
1996            handle.cancel();
1997            let outcome = run.await.unwrap();
1998            assert_eq!(outcome.exit_code, ExitCode::DENIED);
1999            assert_eq!(calls.used(), 1);
2000            drop(release);
2001        }
2002
2003        #[tokio::test(flavor = "multi_thread")]
2004        async fn pre_frame_asset_refusals_emit_one_reason_and_submit_no_frame() {
2005            use crate::attachment::{
2006                ChatAssetInputs, ChatAssetRefusal, ChatAssetSource, ResolveFuture,
2007            };
2008            use tracing_subscriber::prelude::*;
2009            struct UnknownAsset;
2010            impl ChatAssetSource for UnknownAsset {
2011                fn resolve_input(&self, _: u64) -> ResolveFuture<'_> {
2012                    Box::pin(async { Err(ChatAssetRefusal::UnknownAsset) })
2013                }
2014            }
2015            for (script, refusal) in [
2016                (
2017                    "probe --image='data:image/png;base64,AAAA'",
2018                    ChatAssetRefusal::DataUrl,
2019                ),
2020                ("probe chat-asset:9", ChatAssetRefusal::UnknownAsset),
2021                (
2022                    "probe chat-asset:1 chat-asset:2 chat-asset:3 chat-asset:4 chat-asset:5 chat-asset:6",
2023                    ChatAssetRefusal::PerInvocationLimit,
2024                ),
2025            ] {
2026                let directory = private_broker_directory();
2027                let socket = directory.path().join("broker.sock");
2028                let listener = std::os::unix::net::UnixListener::bind(&socket).unwrap();
2029                std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600)).unwrap();
2030                listener.set_nonblocking(true).unwrap();
2031                let mut leg = leg_for(&socket)
2032                    .with_chat_asset_inputs(ChatAssetInputs::new(Arc::new(UnknownAsset)));
2033                leg.command_words.insert("probe".to_owned());
2034                let capture = dekopon_test_support::CaptureLayer::new();
2035                let subscriber = tracing_subscriber::registry().with(capture.clone());
2036                let calls = dekopon_process::CallBudget::new(1);
2037                let tree = dekopon_process::TreeContext::new(
2038                    Limits::default(),
2039                    calls.clone(),
2040                    dekopon_test_support::shell_threads(),
2041                );
2042                let outcome = tokio::task::spawn_blocking(move || {
2043                    tracing::subscriber::with_default(subscriber, || {
2044                        dekopon_shell::Interpreter::new(
2045                            Limits::default(),
2046                            dekopon_test_support::shell_threads(),
2047                        )
2048                        .run_with_tree(script, &leg, &tree)
2049                    })
2050                })
2051                .await
2052                .unwrap();
2053                assert_eq!(outcome.exit_code, ExitCode::DENIED);
2054                assert_eq!(calls.used(), 0);
2055                let events = capture.events_where(
2056                    "dekopon_agent::audit",
2057                    &[("audit.event", "agent.chat_asset_input.refused")],
2058                );
2059                assert_eq!(events.len(), 1);
2060                match &events[0] {
2061                    dekopon_test_support::Record::Event { target, level, .. } => {
2062                        assert_eq!(target, "dekopon_agent::audit");
2063                        assert_eq!(*level, "WARN");
2064                    }
2065                    dekopon_test_support::Record::Span { .. } => panic!("expected a refusal event"),
2066                }
2067                assert_eq!(events[0].field("reason"), Some(refusal.reason()));
2068                assert!(
2069                    matches!(listener.accept(), Err(error) if error.kind() == std::io::ErrorKind::WouldBlock)
2070                );
2071            }
2072        }
2073
2074        fn leg_for(socket: &Path) -> BrokerLeg {
2075            leg_with(socket, None)
2076        }
2077
2078        fn attestation() -> Attestation {
2079            Attestation {
2080                subjects: dekopon_core::AttestedSubject::one(
2081                    SUBJECT
2082                        .parse::<Subject>()
2083                        .expect("canonical subject fixture"),
2084                )
2085                .expect("one-form subject"),
2086                agent: "chat-agent"
2087                    .parse::<AgentId>()
2088                    .expect("valid agent fixture"),
2089                scope: None,
2090                invocation: None,
2091            }
2092        }
2093
2094        fn leg_with(socket: &Path, attestation: Option<Attestation>) -> BrokerLeg {
2095            let mut capabilities = BTreeMap::new();
2096            capabilities.insert(
2097                CAPABILITY.to_owned(),
2098                CapabilityDescription {
2099                    capability: CAPABILITY.to_owned(),
2100                    description: "Fetches one broker-authorized URI".to_owned(),
2101                },
2102            );
2103            BrokerLeg {
2104                client: BrokerClient::new(socket, server_uid(), FrameLimits::default())
2105                    .expect("stub broker client"),
2106                runtime: tokio::runtime::Handle::current(),
2107                capabilities,
2108                effective_capabilities: vec![EffectiveCapabilityView {
2109                    id: CAPABILITY.to_owned(),
2110                    provider: "http-probe".to_owned(),
2111                    description: "Fetches one broker-authorized URI".to_owned(),
2112                    effect: "read-only".to_owned(),
2113                    risk: "Low".to_owned(),
2114                }],
2115                command_words: BTreeSet::new(),
2116                command_word_help: BTreeMap::new(),
2117                identifiers: IdSequence::for_session(),
2118                attestation,
2119                chat_memory: None,
2120                principal: None,
2121                space: None,
2122                cancel: CancelSignal::never(),
2123                script_tree: parking_lot::Mutex::new(None),
2124                attachments: None,
2125                asset_inputs: None,
2126                progress: None,
2127                notes_enabled: false,
2128                notes: AtomicU32::new(0),
2129                calls: dekopon_process::CallBudget::new(0),
2130                jobs: None,
2131            }
2132        }
2133
2134        async fn invoke_with_stdout(
2135            leg: BrokerLeg,
2136            capability: &'static str,
2137        ) -> (CapabilityCallResult, String) {
2138            tokio::task::spawn_blocking(move || {
2139                let (streams, reader) = streams();
2140                let result = leg.invoke(
2141                    CommandProposal::new(capability, json!({"uri": "http://x/"}), None),
2142                    streams,
2143                    &dekopon_process::TreeContext::new(
2144                        dekopon_process::Limits::default(),
2145                        dekopon_process::CallBudget::new(64),
2146                        dekopon_test_support::shell_threads(),
2147                    ),
2148                );
2149                (result, output(reader))
2150            })
2151            .await
2152            .expect("blocking dispatch completes")
2153        }
2154
2155        async fn invoke(leg: BrokerLeg, capability: &'static str) -> CapabilityCallResult {
2156            tokio::task::spawn_blocking(move || {
2157                leg.invoke(
2158                    CommandProposal::new(capability, json!({"uri": "http://x/"}), None),
2159                    streams().0,
2160                    &dekopon_process::TreeContext::new(
2161                        dekopon_process::Limits::default(),
2162                        dekopon_process::CallBudget::new(64),
2163                        dekopon_test_support::shell_threads(),
2164                    ),
2165                )
2166            })
2167            .await
2168            .expect("blocking dispatch completes")
2169        }
2170
2171        mod nesting {
2172            use std::{
2173                io::Write as _,
2174                os::fd::{AsFd as _, OwnedFd},
2175                os::unix::fs::PermissionsExt as _,
2176                path::{Path, PathBuf},
2177                time::Duration,
2178            };
2179
2180            use dekopon_broker_protocol::{
2181                BrokerClient, BrokerRequest, BrokerResponse, ChatScopeClaim, ChatTransportKind,
2182                Conversation, ConversationKind, DescriptorStream, FrameLimits, InvocationOutcome,
2183                ProtocolVersion, RequestEnvelope, ResponseEnvelope, TraceParent, Trigger,
2184                UpcallStdin,
2185            };
2186            use dekopon_process::CancelSignal;
2187            use dekopon_process::ExitCode;
2188            use dekopon_process::{CallBudget, Limits, TreeContext};
2189            use dekopon_shell::{CapabilityCallResult, CapabilityInvoker as _, CommandProposal};
2190            use opentelemetry::trace::TracerProvider as _;
2191            use serde_json::json;
2192            use tokio::{
2193                io::AsyncReadExt as _,
2194                net::{UnixListener, UnixStream},
2195                sync::oneshot,
2196            };
2197            use tracing_subscriber::layer::SubscriberExt as _;
2198
2199            use super::{
2200                CAPABILITY, SUBJECT, leg_with, private_broker_directory, result, server_uid,
2201            };
2202            use crate::{Attestation, BrokerLeg};
2203
2204            struct Call {
2205                stream: DescriptorStream,
2206                run: bool,
2207                uri: String,
2208                attestation: Option<Attestation>,
2209                trace_parent: TraceParent,
2210                descriptors: Vec<OwnedFd>,
2211            }
2212
2213            impl Call {
2214                async fn upcall(
2215                    &mut self,
2216                    script: &str,
2217                    trace_parent: Option<TraceParent>,
2218                ) -> UnixStream {
2219                    let (read, write) =
2220                        std::os::unix::net::UnixStream::pair().expect("child stdout");
2221                    let upcall = ResponseEnvelope {
2222                        api_version: ProtocolVersion::V1Alpha2,
2223                        response: BrokerResponse::Upcall {
2224                            parent: "invoke-parent".parse().expect("invocation"),
2225                            script: script.to_owned(),
2226                            trace_parent,
2227                            stdin: UpcallStdin::None,
2228                        },
2229                    };
2230                    self.stream
2231                        .write_frame(&upcall, &[write.as_fd()], FrameLimits::default())
2232                        .await
2233                        .expect("fake broker writes the upcall");
2234                    drop(write);
2235                    read.set_nonblocking(true)
2236                        .expect("nonblocking child stdout");
2237                    UnixStream::from_std(read).expect("child stdout")
2238                }
2239
2240                async fn upcall_with_stdin(
2241                    &mut self,
2242                    script: &str,
2243                    kind: UpcallStdin,
2244                    source: &std::os::unix::net::UnixStream,
2245                ) -> UnixStream {
2246                    let (read, write) =
2247                        std::os::unix::net::UnixStream::pair().expect("child stdout");
2248                    self.stream
2249                        .write_frame(
2250                            &ResponseEnvelope {
2251                                api_version: ProtocolVersion::V1Alpha2,
2252                                response: BrokerResponse::Upcall {
2253                                    parent: "invoke-parent".parse().expect("invocation"),
2254                                    script: script.to_owned(),
2255                                    trace_parent: None,
2256                                    stdin: kind,
2257                                },
2258                            },
2259                            &[write.as_fd(), source.as_fd()],
2260                            FrameLimits::default(),
2261                        )
2262                        .await
2263                        .expect("fake broker writes stdin upcall");
2264                    drop(write);
2265                    read.set_nonblocking(true)
2266                        .expect("nonblocking child stdout");
2267                    UnixStream::from_std(read).expect("child stdout")
2268                }
2269
2270                async fn child_exit(&mut self, mut stdout: UnixStream) -> (String, u8) {
2271                    let mut text = String::new();
2272                    stdout
2273                        .read_to_string(&mut text)
2274                        .await
2275                        .expect("child stdout text");
2276                    let (request, _) = self
2277                        .stream
2278                        .read_frame::<RequestEnvelope>(FrameLimits::default())
2279                        .await
2280                        .expect("the gateway answers the upcall");
2281                    let BrokerRequest::UpcallResult { status, .. } = request.request else {
2282                        panic!("expected an upcall result");
2283                    };
2284                    (text, status)
2285                }
2286
2287                async fn answer(mut self, outcome: InvocationOutcome, stdout: &str) {
2288                    let mut out = std::os::unix::net::UnixStream::from(
2289                        self.descriptors
2290                            .pop()
2291                            .expect("the invoke carries its stdout"),
2292                    );
2293                    out.write_all(stdout.as_bytes()).expect("provider stdout");
2294                    drop(out);
2295                    self.stream
2296                        .write_frame(
2297                            &if self.run {
2298                                ResponseEnvelope {
2299                                    api_version: ProtocolVersion::V1Alpha2,
2300                                    response: BrokerResponse::Ran {
2301                                        outcome: dekopon_broker_protocol::RunOutcome::Invoked {
2302                                            capability: CAPABILITY.parse().unwrap(),
2303                                            input: json!({"uri":self.uri}),
2304                                            secret_use: None,
2305                                            result: result(outcome, None),
2306                                            attached: Vec::new(),
2307                                            removed: Vec::new(),
2308                                            sent: Vec::new(),
2309                                        },
2310                                    },
2311                                }
2312                            } else {
2313                                ResponseEnvelope::invocation(
2314                                    result(outcome, None),
2315                                    Vec::new(),
2316                                    Vec::new(),
2317                                    Vec::new(),
2318                                )
2319                            },
2320                            &[],
2321                            FrameLimits::default(),
2322                        )
2323                        .await
2324                        .expect("fake broker answers");
2325                }
2326
2327                async fn hung_up(mut self) -> bool {
2328                    self.stream
2329                        .read_frame::<RequestEnvelope>(FrameLimits::default())
2330                        .await
2331                        .is_err()
2332                }
2333            }
2334
2335            fn listen(directory: &Path) -> (UnixListener, PathBuf) {
2336                let socket = directory.join("broker.sock");
2337                let listener = UnixListener::bind(&socket).expect("bind fake broker");
2338                std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600))
2339                    .expect("secure fake socket");
2340                (listener, socket)
2341            }
2342
2343            async fn accept(listener: &UnixListener) -> Call {
2344                let (stream, _) = listener.accept().await.expect("fake broker accepts");
2345                let mut stream = DescriptorStream::new(stream);
2346                let (request, descriptors) = stream
2347                    .read_frame::<RequestEnvelope>(FrameLimits::default())
2348                    .await
2349                    .expect("fake broker reads a request");
2350                let run = matches!(&request.request, BrokerRequest::Run { .. });
2351                let (attestation, invocation) = match request.request {
2352                    BrokerRequest::Run {
2353                        attestation,
2354                        invocation,
2355                        trace_parent,
2356                        argv,
2357                        ..
2358                    } => {
2359                        let uri = match argv.last() {
2360                            Some(dekopon_broker_protocol::Arg::Text(text)) => text.as_str(),
2361                            _ => "",
2362                        };
2363                        (
2364                            attestation,
2365                            dekopon_broker_protocol::InvocationRequest {
2366                                id: invocation,
2367                                trace_parent,
2368                                capability: CAPABILITY.parse().unwrap(),
2369                                input: json!({"uri":uri}),
2370                                secret_use: None,
2371                            },
2372                        )
2373                    }
2374                    BrokerRequest::Invoke {
2375                        attestation,
2376                        invocation,
2377                        ..
2378                    } => (attestation, invocation),
2379                    other @ (BrokerRequest::Capabilities { .. }
2380                    | BrokerRequest::RecordDeliveredTurn { .. }
2381                    | BrokerRequest::UpcallResult { .. }
2382                    | BrokerRequest::PrepareGeneration { .. }
2383                    | BrokerRequest::CommitGeneration { .. }
2384                    | BrokerRequest::AbortGeneration { .. }
2385                    | BrokerRequest::ObserveGeneration) => {
2386                        panic!("unexpected request {other:?}")
2387                    }
2388                };
2389                Call {
2390                    run,
2391                    stream,
2392                    uri: invocation.input["uri"]
2393                        .as_str()
2394                        .unwrap_or_default()
2395                        .to_owned(),
2396                    attestation,
2397                    trace_parent: invocation.trace_parent,
2398                    descriptors,
2399                }
2400            }
2401
2402            fn probe_leg(socket: &Path, attestation: Option<Attestation>) -> BrokerLeg {
2403                let mut leg = leg_with(socket, attestation);
2404                leg.command_words.insert("probe".to_owned());
2405                leg
2406            }
2407
2408            fn tree(calls: &CallBudget) -> TreeContext {
2409                TreeContext::new(
2410                    Limits::default(),
2411                    calls.clone(),
2412                    dekopon_test_support::shell_threads(),
2413                )
2414            }
2415
2416            fn call(leg: &BrokerLeg, tree: &TreeContext) -> CapabilityCallResult {
2417                let (stdout, _reader) = std::os::unix::net::UnixStream::pair().expect("stdout");
2418                leg.invoke(
2419                    CommandProposal::new(CAPABILITY, json!({"uri": "http://a/"}), None),
2420                    dekopon_shell::Streams {
2421                        stdin: None,
2422                        stdout: OwnedFd::from(stdout),
2423                    },
2424                    tree,
2425                )
2426            }
2427
2428            async fn invoke_in(leg: BrokerLeg) -> CapabilityCallResult {
2429                tokio::task::spawn_blocking(move || call(&leg, &tree(&CallBudget::new(64))))
2430                    .await
2431                    .expect("blocking dispatch completes")
2432            }
2433
2434            #[tokio::test(flavor = "multi_thread")]
2435            async fn cancel_depth_two_descendants() {
2436                let directory = private_broker_directory();
2437                let (listener, socket) = listen(directory.path());
2438                let (handle, signal) = CancelSignal::pair();
2439                let leg = probe_leg(&socket, None).with_cancel_signal(signal);
2440                let (reached, depth_two) = oneshot::channel();
2441                let broker = tokio::spawn(async move {
2442                    let mut parent = accept(&listener).await;
2443                    let _parent_stdout = parent.upcall("probe --uri http://b/", None).await;
2444                    let mut child = accept(&listener).await;
2445                    let _child_stdout = child.upcall("probe --uri http://c/", None).await;
2446                    let grandchild = accept(&listener).await;
2447                    reached
2448                        .send(grandchild.uri.clone())
2449                        .expect("the test waits");
2450                    [
2451                        grandchild.hung_up().await,
2452                        child.hung_up().await,
2453                        parent.hung_up().await,
2454                    ]
2455                });
2456                let call = tokio::spawn(invoke_in(leg));
2457                assert_eq!(depth_two.await.expect("depth two reached"), "http://c/");
2458                handle.cancel();
2459                assert!(matches!(
2460                    call.await.expect("the root call returns"),
2461                    CapabilityCallResult::Denied { reason } if reason == "script-cancelled"
2462                ));
2463                let ended = tokio::time::timeout(Duration::from_secs(10), broker)
2464                    .await
2465                    .expect("every connection closes")
2466                    .expect("fake broker");
2467                assert_eq!(ended, [true; 3]);
2468            }
2469
2470            #[tokio::test(flavor = "current_thread", start_paused = true)]
2471            async fn child_280s_gateway_io_270s_paused() {
2472                let directory = private_broker_directory();
2473                let (listener, socket) = listen(directory.path());
2474                let mut leg = probe_leg(&socket, None);
2475                leg.client = BrokerClient::new(
2476                    &socket,
2477                    server_uid(),
2478                    FrameLimits {
2479                        io_timeout: Duration::from_secs(270),
2480                        ..FrameLimits::default()
2481                    },
2482                )
2483                .expect("client");
2484                let (parked, child_parked) = oneshot::channel();
2485                let broker = tokio::spawn(async move {
2486                    let mut parent = accept(&listener).await;
2487                    let stdout = parent.upcall("probe --uri http://slow/", None).await;
2488                    let child = accept(&listener).await;
2489                    let started = tokio::time::Instant::now();
2490                    parked.send(()).expect("the test advances the clock");
2491                    tokio::time::sleep(Duration::from_secs(280)).await;
2492                    child.answer(InvocationOutcome::Succeeded, "slow\n").await;
2493                    let exit = parent.child_exit(stdout).await;
2494                    parent.answer(InvocationOutcome::Succeeded, "").await;
2495                    (exit, started.elapsed())
2496                });
2497                let root = tokio::task::spawn_blocking(move || {
2498                    let limits = Limits {
2499                        timeout: Duration::from_secs(300),
2500                        ..Limits::default()
2501                    };
2502                    call(
2503                        &leg,
2504                        &TreeContext::new(
2505                            limits,
2506                            CallBudget::new(64),
2507                            dekopon_test_support::shell_threads(),
2508                        ),
2509                    )
2510                });
2511                child_parked.await.expect("the child call is parked");
2512                for _ in 0..280 {
2513                    tokio::time::advance(Duration::from_secs(1)).await;
2514                    tokio::task::yield_now().await;
2515                }
2516                assert_eq!(
2517                    root.await.expect("the root call returns"),
2518                    CapabilityCallResult::Succeeded
2519                );
2520                let ((stdout, status), parked) = broker.await.expect("fake broker");
2521                assert_eq!((stdout.as_str(), status), ("slow\n", 0));
2522                assert!(parked >= Duration::from_secs(280));
2523            }
2524
2525            #[tokio::test(flavor = "current_thread", start_paused = true)]
2526            async fn job_and_probe_child_invocations_end_at_tree_deadline() {
2527                for trigger in [Trigger::Job, Trigger::Probe] {
2528                    let directory = private_broker_directory();
2529                    let (listener, socket) = listen(directory.path());
2530                    let scope = ChatScopeClaim {
2531                        participant: None,
2532                        github: None,
2533                        transport: "scientist-slack".parse().expect("transport"),
2534                        kind: ChatTransportKind::Slack,
2535                        conversation: Conversation {
2536                            kind: ConversationKind::Channel,
2537                            container: Some("t0123abc".to_owned()),
2538                            id: "c0123abc".to_owned(),
2539                            thread: None,
2540                        },
2541                        delivery: None,
2542                        trigger,
2543                    };
2544                    let attestation = Attestation::for_chat(
2545                        dekopon_core::AttestedSubject::one(SUBJECT.parse().expect("subject"))
2546                            .expect("subject"),
2547                        "reviewer".parse().expect("agent"),
2548                        scope,
2549                    );
2550                    let leg = probe_leg(&socket, Some(attestation));
2551                    let (parked, child_parked) = oneshot::channel();
2552                    let broker = tokio::spawn(async move {
2553                        let mut parent = accept(&listener).await;
2554                        let stdout = parent.upcall("probe --uri http://child/", None).await;
2555                        let mut child = accept(&listener).await;
2556                        // The guest is waiting for status, not reading stdout. A real host
2557                        // owns the descriptor; discard this fixture's copy to permit EOF.
2558                        child.descriptors.clear();
2559                        parked.send(()).expect("the test advances the clock");
2560                        let ended = child.hung_up().await;
2561                        drop(stdout);
2562                        ended && parent.hung_up().await
2563                    });
2564                    let root = tokio::task::spawn_blocking(move || {
2565                        let limits = Limits {
2566                            timeout: Duration::from_secs(30),
2567                            ..Limits::default()
2568                        };
2569                        call(
2570                            &leg,
2571                            &TreeContext::new(
2572                                limits,
2573                                CallBudget::new(64),
2574                                dekopon_test_support::shell_threads(),
2575                            ),
2576                        )
2577                    });
2578                    child_parked.await.expect("child invocation parked");
2579                    let start = tokio::time::Instant::now();
2580                    tokio::time::advance(Duration::from_secs(30)).await;
2581                    assert!(matches!(
2582                        tokio::time::timeout(Duration::from_secs(1), root)
2583                            .await
2584                            .expect("deadline ends outstanding invocation")
2585                            .expect("blocking call completes"),
2586                        CapabilityCallResult::Denied { reason } if reason == "script-cancelled"
2587                    ));
2588                    assert!(start.elapsed() <= Duration::from_secs(31));
2589                    assert!(broker.await.expect("both connections close"));
2590                }
2591            }
2592
2593            #[tokio::test(flavor = "multi_thread")]
2594            async fn nested_job_and_probe_denied_write() {
2595                for trigger in [Trigger::Probe, Trigger::Job] {
2596                    let directory = private_broker_directory();
2597                    let (listener, socket) = listen(directory.path());
2598                    let scope = ChatScopeClaim {
2599                        participant: None,
2600                        github: None,
2601                        transport: "scientist-slack".parse().expect("transport"),
2602                        kind: ChatTransportKind::Slack,
2603                        conversation: Conversation {
2604                            kind: ConversationKind::Channel,
2605                            container: Some("t0123abc".to_owned()),
2606                            id: "c0123abc".to_owned(),
2607                            thread: None,
2608                        },
2609                        delivery: None,
2610                        trigger,
2611                    };
2612                    let attestation = Attestation::for_chat(
2613                        dekopon_core::AttestedSubject::one(SUBJECT.parse().expect("subject"))
2614                            .expect("subject"),
2615                        "chat-agent".parse().expect("agent"),
2616                        scope,
2617                    );
2618                    let leg = probe_leg(&socket, Some(attestation));
2619                    let broker = tokio::spawn(async move {
2620                        let mut parent = accept(&listener).await;
2621                        let stdout = parent.upcall("probe --uri http://write/", None).await;
2622                        let child = accept(&listener).await;
2623                        let seen = child
2624                            .attestation
2625                            .as_ref()
2626                            .and_then(|claim| claim.scope.as_ref())
2627                            .map(|scope| scope.trigger);
2628                        child.answer(InvocationOutcome::Denied, "").await;
2629                        let (_, status) = parent.child_exit(stdout).await;
2630                        parent.answer(InvocationOutcome::Succeeded, "").await;
2631                        (seen, status)
2632                    });
2633                    assert_eq!(invoke_in(leg).await, CapabilityCallResult::Succeeded);
2634                    assert_eq!(
2635                        broker.await.expect("fake broker"),
2636                        (Some(trigger), ExitCode::DENIED.get())
2637                    );
2638                }
2639            }
2640
2641            #[tokio::test(flavor = "multi_thread")]
2642            async fn inherited_and_reader_stdin_reach_the_child_provider_stage() {
2643                for kind in [UpcallStdin::Inherit, UpcallStdin::Reader] {
2644                    let directory = private_broker_directory();
2645                    let (listener, socket) = listen(directory.path());
2646                    let leg = probe_leg(&socket, None);
2647                    let broker = tokio::spawn(async move {
2648                        let mut parent = accept(&listener).await;
2649                        let (source, mut writer) =
2650                            std::os::unix::net::UnixStream::pair().expect("input");
2651                        writer.write_all(b"child input").expect("input bytes");
2652                        drop(writer);
2653                        let stdout = parent
2654                            .upcall_with_stdin("probe --uri http://stdin/", kind, &source)
2655                            .await;
2656                        let mut child = accept(&listener).await;
2657                        drop(source);
2658                        assert_eq!(child.uri, "http://stdin/");
2659                        assert_eq!(child.descriptors.len(), 2, "child stage has piped stdin");
2660                        let stdin = child.descriptors.remove(0);
2661                        let mut stdin = std::os::unix::net::UnixStream::from(stdin);
2662                        use std::io::Read as _;
2663                        let mut bytes = String::new();
2664                        stdin
2665                            .read_to_string(&mut bytes)
2666                            .expect("child provider stdin");
2667                        drop(stdin);
2668                        child.answer(InvocationOutcome::Succeeded, &bytes).await;
2669                        let exit = parent.child_exit(stdout).await;
2670                        parent.answer(InvocationOutcome::Succeeded, "").await;
2671                        exit
2672                    });
2673                    assert_eq!(invoke_in(leg).await, CapabilityCallResult::Succeeded);
2674                    assert_eq!(
2675                        broker.await.expect("fake broker"),
2676                        ("child input\n".to_owned(), 0)
2677                    );
2678                }
2679            }
2680
2681            struct PanickingJobs;
2682
2683            impl dekopon_shell::JobControl for PanickingJobs {
2684                fn start(
2685                    &self,
2686                    _seed: dekopon_shell::JobSeed,
2687                ) -> Result<dekopon_process::JobId, dekopon_shell::JobRefusal> {
2688                    panic!("child job controller panicked")
2689                }
2690
2691                fn list(&self) -> Vec<dekopon_process::JobSummary> {
2692                    Vec::new()
2693                }
2694
2695                fn wait(
2696                    &self,
2697                    _ids: &[dekopon_process::JobId],
2698                    _keep_waiting: &dyn Fn() -> bool,
2699                ) -> Vec<Result<dekopon_process::JobWait, dekopon_shell::JobRefusal>>
2700                {
2701                    Vec::new()
2702                }
2703
2704                fn kill(
2705                    &self,
2706                    _id: dekopon_process::JobId,
2707                ) -> Result<(), dekopon_shell::JobRefusal> {
2708                    Ok(())
2709                }
2710            }
2711
2712            #[tokio::test(flavor = "multi_thread")]
2713            async fn child_panic_yields_status_70_and_terminal_parent_result() {
2714                let directory = private_broker_directory();
2715                let (listener, socket) = listen(directory.path());
2716                let leg =
2717                    probe_leg(&socket, None).with_job_control(std::sync::Arc::new(PanickingJobs));
2718                let broker = tokio::spawn(async move {
2719                    let mut parent = accept(&listener).await;
2720                    let stdout = parent.upcall("echo hi &", None).await;
2721                    let (output, status) = parent.child_exit(stdout).await;
2722                    parent.answer(InvocationOutcome::Succeeded, "").await;
2723                    (output, status)
2724                });
2725                assert_eq!(invoke_in(leg).await, CapabilityCallResult::Succeeded);
2726                let (output, status) = broker.await.expect("fake broker");
2727                assert_eq!(status, 70);
2728                assert!(output.is_empty(), "panicked child does not claim stdout");
2729            }
2730
2731            #[tokio::test(flavor = "multi_thread")]
2732            async fn idle_child_stdin_and_panicking_job_deliver_status_70() {
2733                let directory = private_broker_directory();
2734                let (listener, socket) = listen(directory.path());
2735                let leg =
2736                    probe_leg(&socket, None).with_job_control(std::sync::Arc::new(PanickingJobs));
2737                let broker = tokio::spawn(async move {
2738                    let mut parent = accept(&listener).await;
2739                    let (source, _idle_writer) =
2740                        std::os::unix::net::UnixStream::pair().expect("idle child stdin");
2741                    let stdout = parent
2742                        .upcall_with_stdin("echo hi &", UpcallStdin::Reader, &source)
2743                        .await;
2744                    let (output, status) = parent.child_exit(stdout).await;
2745                    assert_eq!(status, 70);
2746                    parent.answer(InvocationOutcome::Succeeded, "").await;
2747                    output
2748                });
2749                assert_eq!(
2750                    tokio::time::timeout(Duration::from_secs(4), invoke_in(leg))
2751                        .await
2752                        .expect("parent terminates after child panic"),
2753                    CapabilityCallResult::Succeeded
2754                );
2755                assert!(broker.await.expect("fake broker").is_empty());
2756            }
2757
2758            #[tokio::test(flavor = "multi_thread")]
2759            async fn dropped_child_stdout_still_receives_a_terminal_status() {
2760                let directory = private_broker_directory();
2761                let (listener, socket) = listen(directory.path());
2762                let leg = probe_leg(&socket, None);
2763                let broker = tokio::spawn(async move {
2764                    let mut parent = accept(&listener).await;
2765                    let stdout = parent.upcall("printf child", None).await;
2766                    drop(stdout);
2767                    let (result, descriptors) = parent
2768                        .stream
2769                        .read_frame::<RequestEnvelope>(FrameLimits::default())
2770                        .await
2771                        .expect("child still completes after its reader drops");
2772                    assert!(descriptors.is_empty());
2773                    let BrokerRequest::UpcallResult { status, .. } = result.request else {
2774                        panic!("expected child status");
2775                    };
2776                    parent.answer(InvocationOutcome::Succeeded, "").await;
2777                    status
2778                });
2779                assert_eq!(invoke_in(leg).await, CapabilityCallResult::Succeeded);
2780                assert_eq!(broker.await.expect("fake broker"), 0);
2781            }
2782
2783            #[tokio::test(flavor = "multi_thread")]
2784            async fn child_trace_and_shared_call_budget() {
2785                let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder().build();
2786                let dispatch =
2787                    tracing::Dispatch::new(tracing_subscriber::registry().with(
2788                        tracing_opentelemetry::layer().with_tracer(provider.tracer("nesting")),
2789                    ));
2790                let directory = private_broker_directory();
2791                let (listener, socket) = listen(directory.path());
2792                let leg = probe_leg(&socket, None);
2793                let session = leg.identifiers.parent;
2794                let upcall_parent =
2795                    TraceParent::new(session.trace_id(), [7; 8], 1).expect("trace parent");
2796                let broker = tokio::spawn(async move {
2797                    let mut parent = accept(&listener).await;
2798                    let stdout = parent
2799                        .upcall("probe --uri http://b/", Some(upcall_parent))
2800                        .await;
2801                    let child = accept(&listener).await;
2802                    let child_parent = child.trace_parent;
2803                    child.answer(InvocationOutcome::Succeeded, "").await;
2804                    let (_, status) = parent.child_exit(stdout).await;
2805                    parent.answer(InvocationOutcome::Succeeded, "").await;
2806                    (child_parent, status)
2807                });
2808                let calls = CallBudget::new(1);
2809                let shared = tree(&calls);
2810                let result = tokio::task::spawn_blocking(move || {
2811                    tracing::dispatcher::with_default(&dispatch, || call(&leg, &shared))
2812                })
2813                .await
2814                .expect("blocking dispatch completes");
2815                assert_eq!(result, CapabilityCallResult::Succeeded);
2816                let (child_parent, status) = broker.await.expect("fake broker");
2817                assert_eq!(child_parent.trace(), session.trace());
2818                assert_ne!(child_parent.parent_id(), session.parent_id());
2819                assert_eq!((calls.used(), status), (1, 0));
2820            }
2821        }
2822
2823        #[tokio::test(flavor = "multi_thread")]
2824        async fn a_denied_invocation_stays_denied_all_the_way_to_the_exit_code() {
2825            let directory = private_broker_directory();
2826            let leg = stub_leg(
2827                directory.path(),
2828                vec![ResponseEnvelope::invocation(
2829                    result(InvocationOutcome::Denied, Some("policy-denied")),
2830                    Vec::new(),
2831                    Vec::new(),
2832                    Vec::new(),
2833                )],
2834            )
2835            .await;
2836
2837            assert_eq!(
2838                invoke(leg, CAPABILITY).await,
2839                CapabilityCallResult::Denied {
2840                    reason: "policy-denied".to_owned()
2841                }
2842            );
2843        }
2844
2845        #[tokio::test(flavor = "multi_thread")]
2846        async fn an_unmapped_peer_is_a_denial_rather_than_an_infrastructure_failure() {
2847            let directory = private_broker_directory();
2848            let leg = stub_leg(
2849                directory.path(),
2850                vec![ResponseEnvelope::error(
2851                    ERROR_UNAUTHENTICATED,
2852                    "peer is not mapped by broker policy",
2853                )],
2854            )
2855            .await;
2856
2857            assert!(matches!(
2858                invoke(leg, CAPABILITY).await,
2859                CapabilityCallResult::Denied { .. }
2860            ));
2861        }
2862
2863        #[tokio::test(flavor = "multi_thread")]
2864        async fn an_embedder_without_a_store_reports_received_descriptors_instead_of_silently_discarding_metadata()
2865         {
2866            use dekopon_broker_protocol::{AssetEncoding, NewAsset};
2867            use std::{io::Write, os::fd::AsFd};
2868            let directory = private_broker_directory();
2869            let socket = directory.path().join("broker.sock");
2870            let listener = UnixListener::bind(&socket).unwrap();
2871            std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600)).unwrap();
2872            let blob = dekopon_model::asset::DiskBlob::from_bytes(b"PRIVATE_PAYLOAD").unwrap();
2873            let descriptor = blob.descriptor().unwrap();
2874            drop(blob);
2875            let peer = tokio::spawn(async move {
2876                let (stream, _) = listener.accept().await.unwrap();
2877                let mut stream = DescriptorStream::new(stream);
2878                let (_request, descriptors) = stream
2879                    .read_frame::<RequestEnvelope>(FrameLimits::default())
2880                    .await
2881                    .unwrap();
2882                assert_eq!(
2883                    descriptors.len(),
2884                    1,
2885                    "stdout descriptor accompanies invocation"
2886                );
2887                let mut provider_stdout =
2888                    std::os::unix::net::UnixStream::from(descriptors.into_iter().next().unwrap());
2889                provider_stdout.write_all(b"provider line\n").unwrap();
2890                let reply = ResponseEnvelope::invocation(
2891                    result(InvocationOutcome::Succeeded, None),
2892                    vec![NewAsset {
2893                        descriptor: 0,
2894                        content_type: "text/plain".to_owned(),
2895                        encoding: AssetEncoding::Identity,
2896                        bytes: 15,
2897                        sha256: "0".repeat(64),
2898                    }],
2899                    vec![],
2900                    vec![],
2901                );
2902                stream
2903                    .write_frame(&reply, &[descriptor.as_fd()], FrameLimits::default())
2904                    .await
2905                    .unwrap();
2906            });
2907            let (status, stdout) = invoke_with_stdout(leg_with(&socket, None), CAPABILITY).await;
2908            peer.await.unwrap();
2909            assert_eq!(
2910                status,
2911                CapabilityCallResult::SucceededWithStderr("[gateway: capability executed but this embedder has no asset store; received asset effects could not be retained or delivered; do not repeat the paid call]\n".to_owned()),
2912                "effect already completed"
2913            );
2914            assert_eq!(stdout, "provider line\n");
2915            assert!(!stdout.contains("PRIVATE_PAYLOAD"));
2916            assert!(
2917                !stdout.contains("\"effect\":\"complete\""),
2918                "returned value leaked into stdout"
2919            );
2920        }
2921
2922        #[tokio::test(flavor = "multi_thread")]
2923        async fn a_failed_invocation_carries_the_broker_reason_without_becoming_a_denial() {
2924            let directory = private_broker_directory();
2925            let leg = stub_leg(
2926                directory.path(),
2927                vec![ResponseEnvelope::invocation(
2928                    result(InvocationOutcome::Failed, Some("provider trapped")),
2929                    Vec::new(),
2930                    Vec::new(),
2931                    Vec::new(),
2932                )],
2933            )
2934            .await;
2935
2936            assert_eq!(
2937                invoke(leg, CAPABILITY).await,
2938                CapabilityCallResult::Failed {
2939                    error: "provider trapped".to_owned(),
2940                    detail: None
2941                }
2942            );
2943        }
2944
2945        #[tokio::test(flavor = "multi_thread")]
2946        async fn a_guest_exit_uses_the_typed_status_and_stderr_not_a_parsed_detail_code() {
2947            let directory = private_broker_directory();
2948            let leg = stub_leg(
2949                directory.path(),
2950                vec![ResponseEnvelope::invocation(
2951                    InvocationResult {
2952                        exit_status: std::num::NonZeroU8::new(7),
2953                        detail: Some(ProviderFailureDetail::new(
2954                            "provider-exit",
2955                            "guest failed\n",
2956                        )),
2957                        ..result(InvocationOutcome::Failed, Some("provider-failure"))
2958                    },
2959                    Vec::new(),
2960                    Vec::new(),
2961                    Vec::new(),
2962                )],
2963            )
2964            .await;
2965            assert_eq!(
2966                invoke(leg, CAPABILITY).await,
2967                CapabilityCallResult::Exited {
2968                    status: std::num::NonZeroU8::new(7).unwrap(),
2969                    stderr: "guest failed\n".to_owned(),
2970                }
2971            );
2972        }
2973
2974        #[tokio::test(flavor = "multi_thread")]
2975        async fn a_typed_provider_failure_reaches_the_script_with_its_code_and_message() {
2976            let directory = private_broker_directory();
2977            let detail = ProviderFailureDetail::new(
2978                "upstream-rejected",
2979                "the image route refused the request with HTTP 400 (moderation_blocked)",
2980            );
2981            let leg = stub_leg(
2982                directory.path(),
2983                vec![ResponseEnvelope::invocation(
2984                    InvocationResult {
2985                        detail: Some(detail.clone()),
2986                        ..result(InvocationOutcome::Failed, Some("provider-failure"))
2987                    },
2988                    Vec::new(),
2989                    Vec::new(),
2990                    Vec::new(),
2991                )],
2992            )
2993            .await;
2994
2995            assert_eq!(
2996                invoke(leg, CAPABILITY).await,
2997                CapabilityCallResult::Failed {
2998                    error: "provider-failure".to_owned(),
2999                    detail: Some(detail)
3000                }
3001            );
3002        }
3003
3004        #[tokio::test(flavor = "multi_thread")]
3005        async fn a_successful_invocation_has_no_returned_value() {
3006            let directory = private_broker_directory();
3007            let leg = stub_leg(
3008                directory.path(),
3009                vec![ResponseEnvelope::invocation(
3010                    result(InvocationOutcome::Succeeded, None),
3011                    Vec::new(),
3012                    Vec::new(),
3013                    Vec::new(),
3014                )],
3015            )
3016            .await;
3017
3018            assert_eq!(
3019                invoke(leg, CAPABILITY).await,
3020                CapabilityCallResult::Succeeded
3021            );
3022        }
3023
3024        #[tokio::test(flavor = "multi_thread")]
3025        async fn successful_guest_stderr_reaches_the_gateway_note() {
3026            let directory = private_broker_directory();
3027            let leg = stub_leg(
3028                directory.path(),
3029                vec![ResponseEnvelope::invocation(
3030                    InvocationResult {
3031                        detail: Some(ProviderFailureDetail::new(
3032                            "provider-stderr",
3033                            "guest note\n",
3034                        )),
3035                        ..result(InvocationOutcome::Succeeded, None)
3036                    },
3037                    Vec::new(),
3038                    Vec::new(),
3039                    Vec::new(),
3040                )],
3041            )
3042            .await;
3043            assert_eq!(
3044                invoke(leg, CAPABILITY).await,
3045                CapabilityCallResult::SucceededWithStderr("guest note\n".to_owned())
3046            );
3047        }
3048
3049        #[tokio::test(flavor = "multi_thread")]
3050        async fn an_attested_leg_proposes_on_behalf_of_its_subject() {
3051            let directory = private_broker_directory();
3052            let (leg, mut observed) = stub_leg_observing(
3053                directory.path(),
3054                vec![ResponseEnvelope::invocation(
3055                    result(InvocationOutcome::Succeeded, None),
3056                    Vec::new(),
3057                    Vec::new(),
3058                    Vec::new(),
3059                )],
3060                Some(attestation()),
3061            )
3062            .await;
3063
3064            assert_eq!(
3065                invoke(leg, CAPABILITY).await,
3066                CapabilityCallResult::Succeeded
3067            );
3068
3069            let request = observed.recv().await.expect("stub broker saw one request");
3070            let BrokerRequest::Invoke {
3071                attestation: Some(attestation),
3072                invocation,
3073                ..
3074            } = request.request
3075            else {
3076                panic!("an attested leg must send an attested invoke frame: {request:?}");
3077            };
3078            assert_eq!(attestation.subjects.name().canonical(), SUBJECT);
3079            assert_eq!(attestation.agent.as_str(), "chat-agent");
3080            assert_eq!(attestation.invocation, Some(invocation.id));
3081            assert_eq!(invocation.capability.as_str(), CAPABILITY);
3082        }
3083
3084        #[tokio::test(flavor = "multi_thread")]
3085        async fn a_refused_attestation_is_a_denial_rather_than_an_infrastructure_failure() {
3086            let directory = private_broker_directory();
3087            let (leg, _observed) = stub_leg_observing(
3088                directory.path(),
3089                vec![ResponseEnvelope::error(
3090                    ERROR_UNAUTHENTICATED,
3091                    "attestation refused: no attestor authority for this subject",
3092                )],
3093                Some(attestation()),
3094            )
3095            .await;
3096
3097            assert!(matches!(
3098                invoke(leg, CAPABILITY).await,
3099                CapabilityCallResult::Denied { .. }
3100            ));
3101        }
3102
3103        #[tokio::test(flavor = "multi_thread")]
3104        async fn a_direct_leg_still_proposes_without_any_identity_claim() {
3105            let directory = private_broker_directory();
3106            let (leg, mut observed) = stub_leg_observing(
3107                directory.path(),
3108                vec![ResponseEnvelope::invocation(
3109                    result(InvocationOutcome::Succeeded, None),
3110                    Vec::new(),
3111                    Vec::new(),
3112                    Vec::new(),
3113                )],
3114                None,
3115            )
3116            .await;
3117
3118            assert_eq!(
3119                invoke(leg, CAPABILITY).await,
3120                CapabilityCallResult::Succeeded
3121            );
3122
3123            let request = observed.recv().await.expect("stub broker saw one request");
3124            assert!(
3125                matches!(request.request, BrokerRequest::Invoke { .. }),
3126                "{request:?}"
3127            );
3128        }
3129
3130        #[tokio::test(flavor = "multi_thread")]
3131        async fn capabilities_outside_the_session_never_reach_the_broker() {
3132            let directory = private_broker_directory();
3133            let leg = leg_for(&directory.path().join("absent.sock"));
3134
3135            assert_eq!(
3136                invoke(leg, "totally.unknown").await,
3137                CapabilityCallResult::NotFound
3138            );
3139        }
3140
3141        #[tokio::test(flavor = "multi_thread")]
3142        async fn a_cancelled_session_is_refused_before_a_proposal_is_built() {
3143            let directory = private_broker_directory();
3144            let leg = leg_for(&directory.path().join("absent.sock"));
3145            let (handle, signal) = CancelSignal::pair();
3146            let leg = leg.with_cancel_signal(signal);
3147            handle.cancel();
3148
3149            assert_eq!(
3150                invoke(leg, CAPABILITY).await,
3151                CapabilityCallResult::Denied {
3152                    reason: "session-cancelled".to_owned(),
3153                }
3154            );
3155        }
3156
3157        #[tokio::test(flavor = "multi_thread")]
3158        async fn the_cancellation_check_never_narrows_what_a_proposal_may_carry() {
3159            let directory = private_broker_directory();
3160            let (leg, mut observed) = stub_leg_observing(
3161                directory.path(),
3162                vec![ResponseEnvelope::invocation(
3163                    result(InvocationOutcome::Succeeded, None),
3164                    Vec::new(),
3165                    Vec::new(),
3166                    Vec::new(),
3167                )],
3168                None,
3169            )
3170            .await;
3171            let leg = leg.with_cancel_signal(CancelSignal::pair().1);
3172            let proposal = SecretUseProposal::HttpBearer {
3173                secret: "drn:secret:api/token"
3174                    .parse::<SecretDrn>()
3175                    .expect("canonical DRN fixture"),
3176            };
3177            let submitted = proposal.clone();
3178
3179            assert_eq!(
3180                tokio::task::spawn_blocking(move || {
3181                    leg.invoke(
3182                        CommandProposal::new(
3183                            CAPABILITY,
3184                            json!({"uri": "http://x/"}),
3185                            Some(submitted),
3186                        ),
3187                        streams().0,
3188                        &dekopon_process::TreeContext::new(
3189                            dekopon_process::Limits::default(),
3190                            dekopon_process::CallBudget::new(64),
3191                            dekopon_test_support::shell_threads(),
3192                        ),
3193                    )
3194                })
3195                .await
3196                .expect("blocking dispatch completes"),
3197                CapabilityCallResult::Succeeded
3198            );
3199
3200            let request = observed.recv().await.expect("stub broker saw one request");
3201            let BrokerRequest::Invoke { invocation, .. } = request.request else {
3202                panic!("a capability call sends an invoke frame: {request:?}");
3203            };
3204            assert_eq!(invocation.secret_use, Some(proposal));
3205        }
3206
3207        #[tokio::test(flavor = "multi_thread")]
3208        async fn transport_failures_never_disclose_where_the_broker_lives() {
3209            let directory = private_broker_directory();
3210            let socket = directory.path().join("dekopon-secret-broker.sock");
3211            let leg = leg_for(&socket);
3212
3213            let CapabilityCallResult::Failed { error, .. } = invoke(leg, CAPABILITY).await else {
3214                panic!("a missing broker socket is an infrastructure failure");
3215            };
3216            assert!(!error.contains("dekopon-secret-broker"), "{error}");
3217            assert!(!error.contains(&socket.display().to_string()), "{error}");
3218        }
3219
3220        #[tokio::test]
3221        async fn invocation_identifiers_are_unique_and_extend_the_session_trace() {
3222            let identifiers = IdSequence::for_session();
3223            let first = identifiers.next_invocation();
3224            let second = identifiers.next_invocation();
3225
3226            assert_ne!(first, second);
3227            let trace = identifiers.trace().to_string();
3228            assert!(first.as_str().starts_with(&trace), "{first} vs {trace}");
3229            assert!(second.as_str().starts_with(&trace), "{second} vs {trace}");
3230
3231            let other = IdSequence::for_session();
3232            assert_ne!(identifiers.trace(), other.trace());
3233        }
3234
3235        #[tokio::test]
3236        async fn a_session_that_exports_nothing_still_carries_one_trace() {
3237            let span = tracing::info_span!("gateway.session");
3238            let _entered = span.enter();
3239            assert!(
3240                current_trace_parent().is_none(),
3241                "no exporter is installed in this test process"
3242            );
3243
3244            let identifiers = IdSequence::for_session();
3245            let minted = identifiers.trace_parent();
3246            assert_eq!(minted.trace(), identifiers.trace());
3247            assert_eq!(
3248                minted.to_string(),
3249                format!(
3250                    "00-{}-{:016x}-01",
3251                    minted.trace(),
3252                    u64::from_be_bytes(minted.parent_id())
3253                ),
3254                "the minted context is a well-formed traceparent"
3255            );
3256            assert_eq!(minted.flags(), 1, "a minted parent instructs the receiver");
3257            assert!(
3258                identifiers
3259                    .next_invocation()
3260                    .as_str()
3261                    .starts_with(&identifiers.trace().to_string())
3262            );
3263        }
3264
3265        fn available(id: &str) -> dekopon_broker_protocol::AvailableCapability {
3266            serde_json::from_value(json!({
3267                "provider": "http-probe",
3268                "capability": {
3269                    "id": id,
3270                    "description": "Fetches one broker-authorized URI",
3271                    "effect": "read-only",
3272                    "risk": "Low",
3273                    "inputSchema": {"type": "object"}
3274                }
3275            }))
3276            .expect("capability fixture decodes")
3277        }
3278
3279        #[test]
3280        fn a_duplicated_capability_identifier_is_a_malformed_broker_answer() {
3281            let error = crate::snapshot(vec![
3282                available("http-probe.fetch"),
3283                available("cli-probe.upper"),
3284                available("http-probe.fetch"),
3285                available("cli-probe.upper"),
3286            ])
3287            .expect_err("a duplicate identifier is refused");
3288
3289            assert!(
3290                matches!(
3291                    &error,
3292                    crate::BrokerLegError::DuplicateCapabilities { capabilities }
3293                        if capabilities == "cli-probe.upper, http-probe.fetch"
3294                ),
3295                "{error}"
3296            );
3297        }
3298
3299        #[test]
3300        fn a_distinct_capability_set_indexes_both_views() {
3301            let (descriptions, effective) = crate::snapshot(vec![
3302                available("http-probe.fetch"),
3303                available("cli-probe.upper"),
3304            ])
3305            .expect("a distinct set is accepted");
3306
3307            assert_eq!(descriptions.len(), 2);
3308            assert_eq!(
3309                effective
3310                    .iter()
3311                    .map(|view| view.id.as_str())
3312                    .collect::<Vec<_>>(),
3313                vec!["cli-probe.upper", "http-probe.fetch"]
3314            );
3315        }
3316
3317        #[derive(Default)]
3318        struct RecordingSink {
3319            events: Mutex<Vec<ProgressEvent>>,
3320        }
3321
3322        impl ProgressSink for RecordingSink {
3323            fn emit(&self, event: ProgressEvent) {
3324                self.events.lock().push(event);
3325            }
3326        }
3327
3328        fn recording_sink() -> (Arc<RecordingSink>, Arc<dyn ProgressSink>) {
3329            let recorder = Arc::new(RecordingSink::default());
3330            let installed = Arc::clone(&recorder) as Arc<dyn ProgressSink>;
3331            (recorder, installed)
3332        }
3333
3334        impl RecordingSink {
3335            fn labels(&self) -> Vec<String> {
3336                self.events.lock().iter().map(label).collect()
3337            }
3338        }
3339
3340        #[expect(
3341            clippy::wildcard_enum_match_arm,
3342            reason = "reshaped by the unit that next rewrites this"
3343        )]
3344        fn label(event: &ProgressEvent) -> String {
3345            match event {
3346                ProgressEvent::ToolStarted {
3347                    word,
3348                    argument_count,
3349                    calls_used,
3350                    calls_max,
3351                } => format!(
3352                    "started {} arguments={argument_count} calls={calls_used}/{calls_max}",
3353                    word.as_str()
3354                ),
3355                ProgressEvent::ToolFinished { word, outcome, .. } => {
3356                    format!("finished {} {outcome:?}", word.as_str())
3357                }
3358                ProgressEvent::Attachment {
3359                    index,
3360                    media_type,
3361                    bytes,
3362                } => format!("attachment {index} {media_type} {bytes}"),
3363                ProgressEvent::Note { text, eta } => format!("note {:?} {eta:?}", text.as_str()),
3364                other => format!("unexpected {other:?}"),
3365            }
3366        }
3367
3368        #[tokio::test]
3369        async fn notes_without_the_broker_opt_in_emit_nothing() {
3370            let directory = private_broker_directory();
3371            let (sink, progress) = recording_sink();
3372            let leg = leg_for(&directory.path().join("absent.sock"))
3373                .with_progress(progress, dekopon_process::CallBudget::new(4));
3374            leg.note("not enabled", None);
3375            assert!(sink.labels().is_empty());
3376        }
3377
3378        #[tokio::test]
3379        async fn the_ninth_note_is_dropped_and_the_next_script_starts_fresh() {
3380            let directory = private_broker_directory();
3381            let (sink, progress) = recording_sink();
3382            let leg = leg_for(&directory.path().join("absent.sock"))
3383                .with_progress(progress, dekopon_process::CallBudget::new(4))
3384                .with_progress_notes();
3385            let calls = leg.calls.clone();
3386            let runtime = ShellRuntime {
3387                invoker: crate::SessionInvoker {
3388                    direct: super::FakeLeg::new("cli-probe.upper", "direct"),
3389                    broker: Some(Box::new(leg)),
3390                },
3391                limits: Limits::default(),
3392                calls,
3393                threads: dekopon_test_support::shell_threads(),
3394            };
3395            let script = (1..=9)
3396                .map(|index| format!("progress note-{index}"))
3397                .collect::<Vec<_>>()
3398                .join("; ");
3399            tokio::task::spawn_blocking(move || {
3400                assert_eq!(
3401                    runtime.run_script(&script, None).exit_code,
3402                    ExitCode::SUCCESS
3403                );
3404                assert_eq!(
3405                    runtime.run_script("progress fresh", None).exit_code,
3406                    ExitCode::SUCCESS
3407                );
3408            })
3409            .await
3410            .expect("script thread completes");
3411            let mut expected = (1..=8)
3412                .map(|index| format!("note \"note-{index}\" None"))
3413                .collect::<Vec<_>>();
3414            expected.push("note \"fresh\" None".to_owned());
3415            assert_eq!(sink.labels(), expected);
3416        }
3417
3418        #[tokio::test(flavor = "multi_thread")]
3419        async fn a_capability_call_is_reported_started_and_finished_with_the_brokers_answer() {
3420            let directory = private_broker_directory();
3421            let leg = stub_leg(
3422                directory.path(),
3423                vec![ResponseEnvelope::invocation(
3424                    result(
3425                        InvocationOutcome::Denied,
3426                        Some("authorization refused this invocation"),
3427                    ),
3428                    Vec::new(),
3429                    Vec::new(),
3430                    Vec::new(),
3431                )],
3432            )
3433            .await;
3434            let (sink, progress) = recording_sink();
3435            let leg = leg.with_progress(progress, dekopon_process::CallBudget::new(4));
3436
3437            assert_eq!(
3438                invoke(leg, CAPABILITY).await,
3439                CapabilityCallResult::Denied {
3440                    reason: "authorization refused this invocation".to_owned(),
3441                }
3442            );
3443
3444            assert_eq!(
3445                sink.labels(),
3446                vec![
3447                    format!("started {CAPABILITY} arguments=1 calls=0/4"),
3448                    format!("finished {CAPABILITY} Denied"),
3449                ]
3450            );
3451        }
3452
3453        #[tokio::test(flavor = "multi_thread")]
3454        async fn a_call_proposed_after_a_stop_reads_as_cancelled_rather_than_refused() {
3455            let directory = private_broker_directory();
3456            let leg = leg_for(&directory.path().join("absent.sock"));
3457            let (handle, signal) = CancelSignal::pair();
3458            let (sink, progress) = recording_sink();
3459            let leg = leg
3460                .with_cancel_signal(signal)
3461                .with_progress(progress, dekopon_process::CallBudget::new(4));
3462            handle.cancel();
3463
3464            assert_eq!(
3465                invoke(leg, CAPABILITY).await,
3466                CapabilityCallResult::Denied {
3467                    reason: "session-cancelled".to_owned(),
3468                }
3469            );
3470            assert_eq!(
3471                sink.labels(),
3472                vec![
3473                    format!("started {CAPABILITY} arguments=1 calls=0/4"),
3474                    format!("finished {CAPABILITY} Cancelled"),
3475                ]
3476            );
3477        }
3478
3479        #[tokio::test(flavor = "multi_thread")]
3480        async fn a_broker_stop_interrupts_a_running_shell_loop() {
3481            let directory = private_broker_directory();
3482            let (handle, signal) = CancelSignal::pair();
3483            let leg = leg_for(&directory.path().join("absent.sock")).with_cancel_signal(signal);
3484            let limits = Limits {
3485                max_steps: u64::MAX,
3486                timeout: Duration::from_secs(300),
3487                ..Limits::default()
3488            };
3489            let runtime = ShellRuntime {
3490                invoker: leg,
3491                limits,
3492                calls: dekopon_process::CallBudget::new(4),
3493                threads: dekopon_test_support::shell_threads(),
3494            };
3495            let running = tokio::task::spawn_blocking(move || {
3496                runtime.run_script("while true; do :; done", None)
3497            });
3498            tokio::time::sleep(Duration::from_millis(200)).await;
3499            handle.cancel();
3500            let outcome = tokio::time::timeout(Duration::from_secs(2), running)
3501                .await
3502                .expect("script stopped promptly")
3503                .expect("script worker");
3504            assert_eq!(outcome.exit_code, ExitCode::CANCELLED);
3505            assert!(outcome.steps < u64::MAX);
3506        }
3507
3508        #[tokio::test(flavor = "multi_thread")]
3509        async fn a_broker_stop_interrupts_a_sleeping_shell() {
3510            let directory = private_broker_directory();
3511            let (handle, signal) = CancelSignal::pair();
3512            let leg = leg_for(&directory.path().join("absent.sock")).with_cancel_signal(signal);
3513            let limits = Limits {
3514                timeout: Duration::from_secs(310),
3515                ..Limits::default()
3516            };
3517            let runtime = ShellRuntime {
3518                invoker: leg,
3519                limits,
3520                calls: dekopon_process::CallBudget::new(4),
3521                threads: dekopon_test_support::shell_threads(),
3522            };
3523            let running =
3524                tokio::task::spawn_blocking(move || runtime.run_script("sleep 300", None));
3525            tokio::time::sleep(Duration::from_millis(200)).await;
3526            handle.cancel();
3527            let outcome = tokio::time::timeout(Duration::from_millis(1500), running)
3528                .await
3529                .expect("sleep stopped promptly")
3530                .expect("script worker");
3531            assert_eq!(outcome.exit_code, ExitCode::CANCELLED);
3532        }
3533
3534        async fn reporting_probe_leg(
3535            directory: &Path,
3536            responses: Vec<ResponseEnvelope>,
3537        ) -> (BrokerLeg, Arc<RecordingSink>) {
3538            let (mut leg, _observed) = stub_leg_observing(directory, responses, None).await;
3539            leg.command_words.insert("probe".to_owned());
3540            let (sink, progress) = recording_sink();
3541            (
3542                leg.with_progress(progress, dekopon_process::CallBudget::new(4)),
3543                sink,
3544            )
3545        }
3546
3547        fn proposal_of(capability: &str) -> ResponseEnvelope {
3548            ResponseEnvelope::command_run(dekopon_broker_protocol::CommandRunOutcome::Proposed {
3549                capability: capability.parse().expect("valid capability fixture"),
3550                input: json!({"number": 7}),
3551                secret_use: None,
3552            })
3553        }
3554
3555        #[tokio::test(flavor = "multi_thread")]
3556        async fn progress_reads_the_same_call_count_across_scripts() {
3557            let directory = private_broker_directory();
3558            let denied = || {
3559                ResponseEnvelope::invocation(
3560                    result(InvocationOutcome::Denied, Some("policy-denied")),
3561                    Vec::new(),
3562                    Vec::new(),
3563                    Vec::new(),
3564                )
3565            };
3566            let (leg, sink) = reporting_probe_leg(
3567                directory.path(),
3568                vec![
3569                    proposal_of(CAPABILITY),
3570                    denied(),
3571                    proposal_of(CAPABILITY),
3572                    denied(),
3573                ],
3574            )
3575            .await;
3576            let calls = leg.calls.clone();
3577            let runtime = ShellRuntime {
3578                invoker: leg,
3579                limits: Limits::default(),
3580                calls: calls.clone(),
3581                threads: dekopon_test_support::shell_threads(),
3582            };
3583            let (first, second) = tokio::task::spawn_blocking(move || {
3584                (
3585                    runtime.run_script("probe fetch 7", None),
3586                    runtime.run_script("probe fetch 7", None),
3587                )
3588            })
3589            .await
3590            .expect("scripts finish");
3591            assert_eq!(
3592                (
3593                    first.capability_calls,
3594                    second.capability_calls,
3595                    calls.used()
3596                ),
3597                (1, 1, 2)
3598            );
3599            assert_eq!(
3600                sink.labels(),
3601                vec![
3602                    "started probe arguments=2 calls=1/4".to_owned(),
3603                    "finished probe Denied".to_owned(),
3604                    "started probe arguments=2 calls=2/4".to_owned(),
3605                    "finished probe Denied".to_owned(),
3606                ]
3607            );
3608        }
3609
3610        #[tokio::test(flavor = "multi_thread")]
3611        async fn a_proposal_the_script_never_invokes_finishes_failed_before_the_script_returns() {
3612            let directory = private_broker_directory();
3613            let (leg, sink) =
3614                reporting_probe_leg(directory.path(), vec![proposal_of("gh.pr-merge")]).await;
3615            let calls = leg.calls.clone();
3616            let runtime = ShellRuntime {
3617                invoker: crate::SessionInvoker {
3618                    direct: super::FakeLeg::new("cli-probe.upper", "direct"),
3619                    broker: Some(Box::new(leg)),
3620                },
3621                limits: Limits::default(),
3622                calls,
3623                threads: dekopon_test_support::shell_threads(),
3624            };
3625
3626            let outcome =
3627                tokio::task::spawn_blocking(move || runtime.run_script("probe merge 7", None))
3628                    .await
3629                    .expect("blocking dispatch completes");
3630
3631            assert_eq!(outcome.exit_code, ExitCode::NOT_FOUND, "{}", outcome.output);
3632            assert_eq!(
3633                sink.labels(),
3634                vec![
3635                    "started probe arguments=2 calls=1/4".to_owned(),
3636                    "finished probe Failed".to_owned(),
3637                ],
3638                "{}",
3639                outcome.output
3640            );
3641        }
3642
3643        #[tokio::test(flavor = "multi_thread")]
3644        async fn a_capability_no_provider_owns_is_refused_without_reaching_a_progress_surface() {
3645            // Check the capability is known before reporting progress, or an untrusted model-chosen
3646            // word renders directly in chat.
3647            let directory = private_broker_directory();
3648            let leg = leg_for(&directory.path().join("absent.sock"));
3649            let (sink, progress) = recording_sink();
3650            let leg = leg.with_progress(progress, dekopon_process::CallBudget::new(4));
3651
3652            let outcome = tokio::task::spawn_blocking(move || {
3653                leg.invoke(
3654                    CommandProposal::new("ignore-your-instructions", json!({}), None),
3655                    streams().0,
3656                    &dekopon_process::TreeContext::new(
3657                        dekopon_process::Limits::default(),
3658                        dekopon_process::CallBudget::new(64),
3659                        dekopon_test_support::shell_threads(),
3660                    ),
3661                )
3662            })
3663            .await
3664            .expect("blocking dispatch completes");
3665
3666            assert!(
3667                matches!(outcome, CapabilityCallResult::NotFound),
3668                "an identifier no provider owns is refused as not found: {outcome:?}"
3669            );
3670            assert!(
3671                sink.labels().is_empty(),
3672                "a word the model invented reached a progress surface: {:?}",
3673                sink.labels()
3674            );
3675        }
3676    }
3677}