Skip to main content

acosmi/agent_runs/
client.rs

1//! SDK-facing Agent Run Gateway 客户端。端口自 `agent-runs/client.ts`
2//! (getter 子客户端 + 自有 requestRaw/requestAPI,不复用 chat 路由)。
3
4use crate::agent_runs::remote_control::{
5    is_terminal_remote_event, parse_remote_control_event, PermissionPolicy, RemoteControlEvent,
6    RemotePermissionResultRequest, RemoteSessionTokenGrant, RemoteUserMessageAck,
7    RemoteUserMessageRequest, WorkspacePolicy,
8};
9use crate::agent_runs::types::{
10    AgentRun, AgentRunArtifact, AgentRunCreateRequest, AgentRunCreateResponse, AgentRunDownload,
11    AgentRunErrorPayload, AgentRunListOptions, AgentRunListResult, AgentRunLocalToolResult,
12    AgentRunRunOptions, AgentRunSettlement, AgentRunStatus, AgentRunStreamEvent,
13    AgentRunStreamOptions, AgentRunUsage, AgentRunWithLocalToolsOptions,
14    AGENT_RUN_RUNTIME_CRABCODE_REMOTE,
15};
16use crate::billing::entitlements::urlencoding;
17use crate::core::client::Client;
18use crate::core::http::{
19    iter_sse_lines_result as iter_sse_lines, parse_http_error_with_retry_after,
20    read_limited_result as read_limited, read_limited_text_result as read_limited_text,
21    DEFAULT_JSON_TIMEOUT_MS, MAX_DOWNLOAD_SIZE, MAX_ERROR_BODY_SIZE,
22};
23use crate::shared::{ApiResponse, Error, Result};
24use futures::{Stream, StreamExt};
25use serde::de::DeserializeOwned;
26use serde_json::{json, Value};
27use std::collections::HashMap;
28use std::future::Future;
29use std::pin::Pin;
30use tokio_util::sync::CancellationToken;
31
32/// SDK-facing cloud agent run gateway 子客户端。对应 TS `AgentRunsClient`。
33///
34/// 经 [`Client::agent_runs`] getter 获取(无状态,持 [`Client`] clone)。
35pub struct AgentRunsClient {
36    client: Client,
37}
38
39impl AgentRunsClient {
40    pub(crate) fn new(client: Client) -> Self {
41        Self { client }
42    }
43
44    /// 创建 agent run。对应 TS `create`(POST /agent-runs,retryOn401=false)。
45    pub async fn create(
46        &self,
47        req: &AgentRunCreateRequest,
48        signal: Option<CancellationToken>,
49    ) -> Result<AgentRunCreateResponse> {
50        let body = to_wire_create_request(req).to_string();
51        let env: ApiResponse<WireAgentRunCreateResponse> = self
52            .client
53            .agent_runs_request_api("POST", "/agent-runs", Some(&body), signal, false)
54            .await?;
55        Ok(from_wire_create_response(env.data))
56    }
57
58    /// 列出调用者自己的 agent run(GET /agent-runs,Phase 5C 控制台;retryOn401=true)。对应 TS `list`。
59    pub async fn list(
60        &self,
61        opts: &AgentRunListOptions,
62        signal: Option<CancellationToken>,
63    ) -> Result<AgentRunListResult> {
64        let mut params: Vec<(String, String)> = Vec::new();
65        if let Some(r) = &opts.runtime {
66            params.push(("runtime".into(), r.clone()));
67        }
68        if let Some(s) = &opts.status {
69            params.push(("status".into(), s.clone()));
70        }
71        if let Some(p) = opts.page {
72            params.push(("page".into(), p.to_string()));
73        }
74        if let Some(ps) = opts.page_size {
75            params.push(("page_size".into(), ps.to_string()));
76        }
77        let qs = params
78            .iter()
79            .map(|(k, v)| format!("{}={}", k, urlencoding(v)))
80            .collect::<Vec<_>>()
81            .join("&");
82        let path = if qs.is_empty() {
83            "/agent-runs".to_string()
84        } else {
85            format!("/agent-runs?{qs}")
86        };
87        let env: ApiResponse<WireAgentRunListResult> = self
88            .client
89            .agent_runs_request_api("GET", &path, None, signal, true)
90            .await?;
91        let resp = env.data;
92        Ok(AgentRunListResult {
93            records: resp
94                .records
95                .unwrap_or_default()
96                .into_iter()
97                .map(from_wire_run)
98                .collect(),
99            total: resp.total.unwrap_or(0),
100            page: resp.page.unwrap_or(1),
101            page_size: resp.page_size.unwrap_or(20),
102        })
103    }
104
105    /// 查询单个 agent run(GET /agent-runs/:id;retryOn401=true)。对应 TS `get`。
106    pub async fn get(&self, run_id: &str, signal: Option<CancellationToken>) -> Result<AgentRun> {
107        let path = format!("/agent-runs/{}", urlencoding(run_id));
108        let env: ApiResponse<WireAgentRun> = self
109            .client
110            .agent_runs_request_api("GET", &path, None, signal, true)
111            .await?;
112        Ok(from_wire_run(env.data))
113    }
114
115    /// 取消 agent run(POST /agent-runs/:id/cancel;retryOn401=false)。对应 TS `cancel`。
116    pub async fn cancel(
117        &self,
118        run_id: &str,
119        signal: Option<CancellationToken>,
120    ) -> Result<AgentRun> {
121        let path = format!("/agent-runs/{}/cancel", urlencoding(run_id));
122        let env: ApiResponse<WireAgentRun> = self
123            .client
124            .agent_runs_request_api("POST", &path, Some("{}"), signal, false)
125            .await?;
126        Ok(from_wire_run(env.data))
127    }
128
129    /// 创建 CrabCode 远控 agent run(契约 §3,ADR-2 + ADR-5)。对应 TS `createRemoteRun`。
130    ///
131    /// 等价 `create()` 但 runtime 固定 `crabcode_remote` 且 runner + adapter 必填。
132    /// 对应 stream 用 [`Self::stream_remote_control`](事件 union 不同,契约 §4)。
133    pub async fn create_remote_run(
134        &self,
135        req: &AgentRunCreateRequest,
136        signal: Option<CancellationToken>,
137    ) -> Result<AgentRunCreateResponse> {
138        if req.runtime.as_deref() != Some(AGENT_RUN_RUNTIME_CRABCODE_REMOTE) {
139            return Err(Error::other(
140                "create_remote_run: runtime must be \"crabcode_remote\"",
141            ));
142        }
143        if req.runner.is_none() {
144            return Err(Error::other("create_remote_run: runner is required"));
145        }
146        if req.adapter.is_none() {
147            return Err(Error::other("create_remote_run: adapter is required"));
148        }
149        self.create(req, signal).await
150    }
151
152    /// 提交 permission 决策(POST /agent-runs/:id/permission-results;契约 §4/§9/§14)。对应 TS `submitPermissionResult`。
153    ///
154    /// 仅 `approved` | `rejected` 可由客户端提交。需 remote_control scope(或 web JWT)。
155    pub async fn submit_permission_result(
156        &self,
157        run_id: &str,
158        result: &RemotePermissionResultRequest,
159        signal: Option<CancellationToken>,
160    ) -> Result<()> {
161        let path = format!("/agent-runs/{}/permission-results", urlencoding(run_id));
162        let body = json!({
163            "request_id": result.request_id,
164            "decision": result.decision,
165            "reason": result.reason,
166        })
167        .to_string();
168        // 返回 `{ok?}`,调用方不关心 → 解析后丢弃(空体亦容忍)。
169        let _: Option<ApiResponse<Value>> = self
170            .client
171            .agent_runs_request_api_opt("POST", &path, Some(&body), signal, false)
172            .await?;
173        Ok(())
174    }
175
176    /// 会话中途追加用户消息(POST /agent-runs/:id/messages,Phase 5C)。对应 TS `submitUserMessage`。
177    ///
178    /// Role 由服务端硬编码 'user'(契约 §6 #5 防注入); content ≤ 64KB。需 remote_control scope。
179    pub async fn submit_user_message(
180        &self,
181        run_id: &str,
182        message: &RemoteUserMessageRequest,
183        signal: Option<CancellationToken>,
184    ) -> Result<RemoteUserMessageAck> {
185        let path = format!("/agent-runs/{}/messages", urlencoding(run_id));
186        let body = json!({
187            "request_id": message.request_id,
188            "content": message.content,
189        })
190        .to_string();
191        let env: Option<ApiResponse<WireUserMessageAck>> = self
192            .client
193            .agent_runs_request_api_opt("POST", &path, Some(&body), signal, false)
194            .await?;
195        let data = env.map(|e| e.data).unwrap_or_default();
196        Ok(RemoteUserMessageAck {
197            ok: data.ok.unwrap_or(false),
198            request_id: data
199                .request_id
200                .filter(|s| !s.is_empty())
201                .or_else(|| message.request_id.clone())
202                .unwrap_or_default(),
203        })
204    }
205
206    /// 揭示 desktop-runner run 的一次性 session token(POST /agent-runs/:id/remote-token,Phase 5B;契约 §18.1)。对应 TS `revealRemoteToken`。
207    ///
208    /// 仅 desktop launcher: token 一次性消费(第二次 409),永不落浏览器存储。需 remote_control scope。
209    pub async fn reveal_remote_token(
210        &self,
211        run_id: &str,
212        signal: Option<CancellationToken>,
213    ) -> Result<RemoteSessionTokenGrant> {
214        let path = format!("/agent-runs/{}/remote-token", urlencoding(run_id));
215        let env: ApiResponse<WireRemoteSessionTokenGrant> = self
216            .client
217            .agent_runs_request_api("POST", &path, Some("{}"), signal, false)
218            .await?;
219        let data = env.data;
220        Ok(RemoteSessionTokenGrant {
221            access_token: data.access_token.unwrap_or_default(),
222            session_url: data.session_url.unwrap_or_default(),
223            tenant_id: data.tenant_id.unwrap_or_default(),
224            workspace: data.workspace.filter(|s| !s.is_empty()),
225        })
226    }
227
228    /// 列出 run 的产物(GET /agent-runs/:id/artifacts;retryOn401=true)。对应 TS `listArtifacts`。
229    pub async fn list_artifacts(
230        &self,
231        run_id: &str,
232        signal: Option<CancellationToken>,
233    ) -> Result<Vec<AgentRunArtifact>> {
234        let path = format!("/agent-runs/{}/artifacts", urlencoding(run_id));
235        let env: ApiResponse<WireAgentRunArtifactList> = self
236            .client
237            .agent_runs_request_api("GET", &path, None, signal, true)
238            .await?;
239        Ok(env
240            .data
241            .artifacts
242            .unwrap_or_default()
243            .into_iter()
244            .map(from_wire_artifact)
245            .collect())
246    }
247
248    /// 提交本地工具结果(POST /agent-runs/:id/local-tool-results;retryOn401=false)。对应 TS `submitLocalToolResult`。
249    pub async fn submit_local_tool_result(
250        &self,
251        run_id: &str,
252        result: &AgentRunLocalToolResult,
253        signal: Option<CancellationToken>,
254    ) -> Result<AgentRun> {
255        let path = format!("/agent-runs/{}/local-tool-results", urlencoding(run_id));
256        let body = json!({
257            "request_id": result.request_id,
258            "ok": result.ok,
259            "content": result.content,
260            "error": result.error,
261        })
262        .to_string();
263        let env: ApiResponse<WireAgentRun> = self
264            .client
265            .agent_runs_request_api("POST", &path, Some(&body), signal, false)
266            .await?;
267        Ok(from_wire_run(env.data))
268    }
269
270    /// 下载产物(GET /agent-runs/:id/artifacts/:artifactId;retryOn401=true)。对应 TS `downloadArtifact`。
271    ///
272    /// 🔴 v2.5.0:多读 1 字节探测超限 —— 超过 [`MAX_DOWNLOAD_SIZE`] **抛错**,
273    /// 绝不静默截断(否则下游拿到被砍断的不完整产物却毫无感知)。
274    pub async fn download_artifact(
275        &self,
276        run_id: &str,
277        artifact_id: &str,
278        signal: Option<CancellationToken>,
279    ) -> Result<AgentRunDownload> {
280        let path = format!(
281            "/agent-runs/{}/artifacts/{}",
282            urlencoding(run_id),
283            urlencoding(artifact_id)
284        );
285        let resp = self
286            .client
287            .agent_runs_request_raw(
288                "GET",
289                &path,
290                None,
291                signal.as_ref(),
292                true,
293                "application/json",
294            )
295            .await?;
296        let content_type = resp
297            .headers()
298            .get(http::header::CONTENT_TYPE)
299            .and_then(|v| v.to_str().ok())
300            .map(|s| s.to_string());
301        let filename = filename_from_content_disposition(
302            resp.headers()
303                .get(http::header::CONTENT_DISPOSITION)
304                .and_then(|v| v.to_str().ok()),
305        )
306        .unwrap_or_else(|| artifact_id.to_string());
307
308        // 多读 1 字节探测超限(与 download_skill 一致),超限抛错不截断。
309        let data = read_limited(resp.bytes_stream(), MAX_DOWNLOAD_SIZE + 1).await?;
310        if data.len() > MAX_DOWNLOAD_SIZE {
311            return Err(Error::other(format!(
312                "download artifact: response exceeds {}MB limit",
313                MAX_DOWNLOAD_SIZE >> 20
314            )));
315        }
316        Ok(AgentRunDownload {
317            data,
318            filename,
319            content_type,
320        })
321    }
322
323    /// 流式 agent run 事件(GET /agent-runs/:id/stream)。对应 TS `stream`。
324    ///
325    /// 🔴 计费安全:流式只走单次 `do_request`,**绝不重试**(仅 401 单次 force_refresh)。
326    /// `error` 事件在 `throw_on_error`(默认 true)时转 [`Error::AgentRunStream`] 抛出。
327    pub fn stream(
328        &self,
329        run_id: &str,
330        opts: AgentRunStreamOptions,
331        signal: Option<CancellationToken>,
332    ) -> impl Stream<Item = Result<AgentRunStreamEvent>> + '_ {
333        let run_id = run_id.to_string();
334        async_stream::try_stream! {
335            let inner = self.stream_gen(&run_id, signal);
336            futures::pin_mut!(inner);
337            while let Some(ev) = inner.next().await {
338                let ev = ev?;
339                if matches!(ev, AgentRunStreamEvent::Error { .. }) && opts.throw_on_error {
340                    if let AgentRunStreamEvent::Error { error } = &ev {
341                        Err(Error::AgentRunStream {
342                            code: error.code.clone().unwrap_or_default(),
343                            stage: error.stage.clone(),
344                            message: error.message.clone(),
345                            retryable: error.retryable.unwrap_or(false),
346                        })?;
347                    }
348                }
349                yield ev;
350            }
351        }
352    }
353
354    /// 流式 CrabCode 远控事件(契约 §4,11-event union)。对应 TS `streamRemoteControl`。
355    ///
356    /// 🔴 未知 event type / 畸形帧 **静默丢弃**(对齐 `parse_remote_control_event` 的 None 契约;
357    /// 与 [`Self::stream`] 的未知→Error 注入流**相反**)。`done`/`settle` 终结事件后自然结束,从不抛异常。
358    pub fn stream_remote_control(
359        &self,
360        run_id: &str,
361        signal: Option<CancellationToken>,
362    ) -> impl Stream<Item = Result<RemoteControlEvent>> + '_ {
363        let run_id = run_id.to_string();
364        async_stream::try_stream! {
365            let frames = self.remote_sse_frames(&run_id, signal);
366            futures::pin_mut!(frames);
367            while let Some(frame) = frames.next().await {
368                let frame = frame?;
369                // 🔴 未知 type / 缺字段 → None 静默丢弃。
370                if let Some(ev) = parse_remote_control_event(&frame) {
371                    let terminal = is_terminal_remote_event(&ev);
372                    yield ev;
373                    if terminal {
374                        return;
375                    }
376                }
377            }
378        }
379    }
380
381    /// create + stream 一气呵成。对应 TS `run`。
382    pub fn run(
383        &self,
384        req: &AgentRunCreateRequest,
385        opts: AgentRunRunOptions,
386        signal: Option<CancellationToken>,
387    ) -> impl Stream<Item = Result<AgentRunStreamEvent>> + '_ {
388        let req = req.clone();
389        async_stream::try_stream! {
390            let created = self.create(&req, signal.clone()).await?;
391            let inner = self.stream(&created.run_id, opts, signal);
392            futures::pin_mut!(inner);
393            while let Some(ev) = inner.next().await {
394                yield ev?;
395            }
396        }
397    }
398
399    /// run + 本地工具回调编排(local_tool_request → handler → submit_local_tool_result)。对应 TS `runWithLocalTools`。
400    ///
401    /// 🔴 v2.5.0 本地工具回调硬超时:即便 handler 完全忽略 signal(不响应协作式取消),
402    /// `timeout_ms` 后也会胜出返回稳定失败结果,不会永挂(`tokio::select!` 双臂)。
403    pub fn run_with_local_tools<H, Fut>(
404        &self,
405        req: &AgentRunCreateRequest,
406        handlers: HashMap<String, H>,
407        opts: AgentRunWithLocalToolsOptions,
408        signal: Option<CancellationToken>,
409    ) -> impl Stream<Item = Result<AgentRunStreamEvent>> + '_
410    where
411        H: Fn(Value, LocalToolContext) -> Fut + Send + Sync + 'static,
412        Fut: Future<Output = Result<Value>> + Send + 'static,
413    {
414        let req = req.clone();
415        let stream_opts = AgentRunStreamOptions {
416            throw_on_error: opts.throw_on_error,
417        };
418        async_stream::try_stream! {
419            let mut current_run_id = String::new();
420            let run = self.run(&req, stream_opts, signal.clone());
421            futures::pin_mut!(run);
422            while let Some(ev) = run.next().await {
423                let ev = ev?;
424                if let AgentRunStreamEvent::RunStarted { run_id, .. } = &ev {
425                    current_run_id = run_id.clone();
426                }
427
428                if let AgentRunStreamEvent::LocalToolRequest { request_id, name, input } = &ev {
429                    if current_run_id.is_empty() {
430                        Err(Error::other("local tool request arrived before run_started"))?;
431                    }
432                    let result = invoke_local_tool(
433                        &current_run_id,
434                        request_id,
435                        name,
436                        input.clone(),
437                        &handlers,
438                        opts.timeout_ms,
439                        signal.as_ref(),
440                    )
441                    .await;
442                    // 先 yield 事件再回写(对齐 TS yield 顺序)。
443                    let run_id_for_submit = current_run_id.clone();
444                    yield ev;
445                    self.submit_local_tool_result(&run_id_for_submit, &result, signal.clone()).await?;
446                    continue;
447                }
448
449                yield ev;
450            }
451        }
452    }
453
454    // ===========================================================================
455    // 内部:SSE 解析(agent run events / remote control frames)
456    // ===========================================================================
457
458    /// agent run SSE 流的真实实现(401 单次 force_refresh 重试经 [`Client::agent_runs_request_raw`])。
459    fn stream_gen<'a>(
460        &'a self,
461        run_id: &'a str,
462        signal: Option<CancellationToken>,
463    ) -> Pin<Box<dyn Stream<Item = Result<AgentRunStreamEvent>> + Send + 'a>> {
464        Box::pin(async_stream::try_stream! {
465            let path = format!("/agent-runs/{}/stream", urlencoding(run_id));
466            let resp = self
467                .client
468                .agent_runs_request_raw("GET", &path, None, signal.as_ref(), true, "text/event-stream")
469                .await?;
470
471            let lines = iter_sse_lines(resp.bytes_stream());
472            futures::pin_mut!(lines);
473            let mut event_name = String::new();
474            let mut data_lines: Vec<String> = Vec::new();
475            loop {
476                let next: Option<Result<String>> = match &signal {
477                    Some(cancel) => tokio::select! {
478                        l = lines.next() => l,
479                        _ = cancel.cancelled() => Some(Err(Error::other("agent run stream: aborted"))),
480                    },
481                    None => lines.next().await,
482                };
483                let line = match next {
484                    Some(l) => l?,
485                    None => break,
486                };
487                if line.is_empty() {
488                    if let Some(ev) = flush_agent_run_event(&event_name, &mut data_lines) {
489                        event_name.clear();
490                        yield ev;
491                    } else {
492                        event_name.clear();
493                    }
494                    continue;
495                }
496                if line.starts_with(':') {
497                    continue;
498                }
499                if let Some(rest) = line.strip_prefix("event:") {
500                    event_name = rest.trim().to_string();
501                } else if let Some(rest) = line.strip_prefix("data:") {
502                    data_lines.push(rest.trim_start().to_string());
503                }
504            }
505            if let Some(ev) = flush_agent_run_event(&event_name, &mut data_lines) {
506                yield ev;
507            }
508        })
509    }
510
511    /// remote-control SSE 帧流(产出原始 JSON 对象,注入 `__event__`/`type` 名)。对应 TS `readAgentRunSSEFrames`。
512    fn remote_sse_frames<'a>(
513        &'a self,
514        run_id: &'a str,
515        signal: Option<CancellationToken>,
516    ) -> Pin<Box<dyn Stream<Item = Result<Value>> + Send + 'a>> {
517        Box::pin(async_stream::try_stream! {
518            let path = format!("/agent-runs/{}/stream", urlencoding(run_id));
519            let resp = self
520                .client
521                .agent_runs_request_raw("GET", &path, None, signal.as_ref(), true, "text/event-stream")
522                .await?;
523
524            let lines = iter_sse_lines(resp.bytes_stream());
525            futures::pin_mut!(lines);
526            let mut event_name = String::new();
527            let mut data_lines: Vec<String> = Vec::new();
528            loop {
529                let next: Option<Result<String>> = match &signal {
530                    Some(cancel) => tokio::select! {
531                        l = lines.next() => l,
532                        _ = cancel.cancelled() => Some(Err(Error::other("remote-control stream: aborted"))),
533                    },
534                    None => lines.next().await,
535                };
536                let line = match next {
537                    Some(l) => l?,
538                    None => break,
539                };
540                if line.is_empty() {
541                    if let Some(frame) = flush_remote_frame(&event_name, &mut data_lines) {
542                        event_name.clear();
543                        yield frame;
544                    } else {
545                        event_name.clear();
546                    }
547                    continue;
548                }
549                if line.starts_with(':') {
550                    continue;
551                }
552                if let Some(rest) = line.strip_prefix("event:") {
553                    event_name = rest.trim().to_string();
554                } else if let Some(rest) = line.strip_prefix("data:") {
555                    data_lines.push(rest.trim_start().to_string());
556                }
557            }
558            if let Some(frame) = flush_remote_frame(&event_name, &mut data_lines) {
559                yield frame;
560            }
561        })
562    }
563}
564
565impl Client {
566    /// SDK-facing cloud agent run gateway。对应 TS `client.agentRuns` getter。
567    ///
568    /// # Examples
569    ///
570    /// ```no_run
571    /// # use acosmi::Client;
572    /// # use acosmi::agent_runs::AgentRunCreateRequest;
573    /// # async fn demo(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
574    /// let runs = client.agent_runs();
575    /// let run = runs
576    ///     .create(
577    ///         &AgentRunCreateRequest {
578    ///             app_id: "crabdesign".into(),
579    ///             input: "Create a landing page mockup".into(),
580    ///             ..Default::default()
581    ///         },
582    ///         None,
583    ///     )
584    ///     .await?;
585    /// println!("run_id = {}", run.run_id);
586    /// # Ok(()) }
587    /// ```
588    pub fn agent_runs(&self) -> AgentRunsClient {
589        AgentRunsClient::new(self.clone())
590    }
591
592    /// agent-runs/byok 域内部:非流式 JSON 请求 → `ApiResponse<T>`(业务码检查在调用方读 .data 前自动)。
593    /// 对应 TS `AgentRunsClient.requestAPI`(空体 → 强 Err;调用方要容忍空体用 `_opt`)。
594    pub(crate) async fn agent_runs_request_api<T: DeserializeOwned>(
595        &self,
596        method: &str,
597        path: &str,
598        body: Option<&str>,
599        signal: Option<CancellationToken>,
600        retry_on_401: bool,
601    ) -> Result<T> {
602        let opt = self
603            .agent_runs_request_api_opt::<T>(method, path, body, signal, retry_on_401)
604            .await?;
605        opt.ok_or_else(|| Error::other(format!("{path}: empty response body")))
606    }
607
608    /// 同 [`Self::agent_runs_request_api`] 但空体返回 `Ok(None)`(对齐 TS `requestAPI` 空体→undefined)。
609    pub(crate) async fn agent_runs_request_api_opt<T: DeserializeOwned>(
610        &self,
611        method: &str,
612        path: &str,
613        body: Option<&str>,
614        signal: Option<CancellationToken>,
615        retry_on_401: bool,
616    ) -> Result<Option<T>> {
617        // 非流式 JSON 套默认超时(对应 TS requestAPI timeoutMs ?? DEFAULT_API_TIMEOUT_MS)。
618        let ctl = self.derive_timeout_token(DEFAULT_JSON_TIMEOUT_MS, signal);
619        let resp = self
620            .agent_runs_request_raw(
621                method,
622                path,
623                body,
624                ctl.as_ref(),
625                retry_on_401,
626                "application/json",
627            )
628            .await?;
629        let bytes = resp
630            .bytes()
631            .await
632            .map_err(|e| Error::other(format!("{path}: read body: {e}")))?;
633        if bytes.is_empty() {
634            return Ok(None);
635        }
636        let v: T = serde_json::from_slice(&bytes)
637            .map_err(|e| Error::other(format!("{path}: decode: {e}")))?;
638        Ok(Some(v))
639    }
640
641    /// agent-runs 域自有 raw 请求(对应 TS `AgentRunsClient.requestRaw` → `requestRawInner`)。
642    ///
643    /// ensure_token → Bearer + Accept → **单次 [`Client::do_request`](绝不重试,流式安全)** →
644    /// 401(且 `retry_on_401`)单次 force_refresh 重试(`retried` guard 防递归)→ 非 2xx 抛 [`Error::Http`]。
645    /// 返回 raw `reqwest::Response`(供 SSE / 下载流式读 body)。
646    pub(crate) fn agent_runs_request_raw<'a>(
647        &'a self,
648        method: &'a str,
649        path: &'a str,
650        body: Option<&'a str>,
651        signal: Option<&'a CancellationToken>,
652        retry_on_401: bool,
653        accept: &'a str,
654    ) -> Pin<Box<dyn Future<Output = Result<crate::core::transport::Response>> + Send + 'a>> {
655        Box::pin(self.agent_runs_request_raw_inner(
656            method,
657            path,
658            body,
659            signal,
660            retry_on_401,
661            accept,
662            false,
663        ))
664    }
665
666    #[allow(clippy::too_many_arguments)]
667    async fn agent_runs_request_raw_inner(
668        &self,
669        method: &str,
670        path: &str,
671        body: Option<&str>,
672        signal: Option<&CancellationToken>,
673        retry_on_401: bool,
674        accept: &str,
675        retried: bool,
676    ) -> Result<crate::core::transport::Response> {
677        let token = self.ensure_token(signal.cloned()).await?;
678        let url = self.api_url(path);
679        let m = http::Method::from_bytes(method.as_bytes())
680            .map_err(|e| Error::other(format!("invalid method {method}: {e}")))?;
681
682        let mut headers: Vec<(http::header::HeaderName, String)> = vec![
683            (http::header::AUTHORIZATION, format!("Bearer {token}")),
684            (http::header::ACCEPT, accept.to_string()),
685        ];
686        if body.is_some() {
687            headers.push((http::header::CONTENT_TYPE, "application/json".to_string()));
688        }
689
690        // 🔴 流式安全:只走单次 do_request(绝不 do_request_with_retry)。
691        let resp = self
692            .do_request(
693                m.clone(),
694                &url,
695                &headers,
696                body,
697                signal,
698                if accept == "text/event-stream" {
699                    crate::core::transport::HttpContext::streaming(
700                        crate::core::transport::HttpPurpose::Api,
701                        crate::core::http::DEFAULT_JSON_TIMEOUT_MS,
702                    )
703                } else {
704                    crate::core::transport::HttpContext::default()
705                },
706            )
707            .await?;
708
709        if resp.status().as_u16() == 401 && retry_on_401 && !retried {
710            drop(resp);
711            self.force_refresh(signal.cloned())
712                .await
713                .map_err(|e| Error::other(format!("unauthorized and refresh failed: {e}")))?;
714            return Box::pin(self.agent_runs_request_raw_inner(
715                method,
716                path,
717                body,
718                signal,
719                retry_on_401,
720                accept,
721                true,
722            ))
723            .await;
724        }
725
726        if !resp.status().is_success() {
727            let status = resp.status().as_u16();
728            let retry_after = parse_retry_after_secs(resp.headers());
729            let text = read_limited_text(resp.bytes_stream(), MAX_ERROR_BODY_SIZE).await?;
730            return Err(Error::Http(parse_http_error_with_retry_after(
731                status,
732                &text,
733                retry_after,
734            )));
735        }
736        Ok(resp)
737    }
738}
739
740/// 本地工具 handler 上下文。对应 TS `AgentRunLocalToolHandlerContext`。
741#[derive(Debug, Clone)]
742pub struct LocalToolContext {
743    pub run_id: String,
744    pub request_id: String,
745    pub name: String,
746    /// 协作式取消信号;硬超时触发时 cancel(handler 可监听尽早退出)。
747    pub signal: CancellationToken,
748}
749
750/// 调用本地工具 handler,带硬超时(对应 TS `invokeLocalTool`)。
751///
752/// 无 handler → 立即返回 rejected;有 handler → `tokio::select!` 双臂:handler vs 超时定时器,
753/// **超时方胜出立即返回稳定失败结果**(即便 handler 永挂也不阻塞)。
754#[allow(clippy::too_many_arguments)]
755async fn invoke_local_tool<H, Fut>(
756    run_id: &str,
757    request_id: &str,
758    name: &str,
759    input: Value,
760    handlers: &HashMap<String, H>,
761    timeout_ms: u64,
762    parent: Option<&CancellationToken>,
763) -> AgentRunLocalToolResult
764where
765    H: Fn(Value, LocalToolContext) -> Fut,
766    Fut: Future<Output = Result<Value>>,
767{
768    let handler = match handlers.get(name) {
769        Some(h) => h,
770        None => {
771            return AgentRunLocalToolResult {
772                request_id: request_id.to_string(),
773                ok: false,
774                content: None,
775                error: Some(format!("local tool rejected: no handler for {name}")),
776            };
777        }
778    };
779
780    let ctl = CancellationToken::new();
781    // parent 取消 → 联动 ctl(协作式取消提示)。
782    if let Some(p) = parent {
783        if p.is_cancelled() {
784            ctl.cancel();
785        } else {
786            let child = ctl.clone();
787            let parent = p.clone();
788            tokio::spawn(async move {
789                parent.cancelled().await;
790                child.cancel();
791            });
792        }
793    }
794
795    let ctx = LocalToolContext {
796        run_id: run_id.to_string(),
797        request_id: request_id.to_string(),
798        name: name.to_string(),
799        signal: ctl.clone(),
800    };
801    let handler_fut = handler(input, ctx);
802    let timeout = tokio::time::sleep(std::time::Duration::from_millis(timeout_ms));
803
804    tokio::select! {
805        biased;
806        // handler 先完成。
807        out = handler_fut => match out {
808            Ok(content) => AgentRunLocalToolResult {
809                request_id: request_id.to_string(),
810                ok: true,
811                content: Some(content),
812                error: None,
813            },
814            Err(e) => {
815                // parent 取消时直接传播失败原因;否则当作 handler 失败。
816                let timed_out = ctl.is_cancelled() && parent.map(|p| !p.is_cancelled()).unwrap_or(true);
817                AgentRunLocalToolResult {
818                    request_id: request_id.to_string(),
819                    ok: false,
820                    content: None,
821                    error: Some(if timed_out {
822                        format!("local tool timed out after {timeout_ms}ms")
823                    } else {
824                        e.to_string()
825                    }),
826                }
827            }
828        },
829        // 超时胜出:cancel ctl(协作式提示)并返回稳定失败结果。
830        _ = timeout => {
831            ctl.cancel();
832            AgentRunLocalToolResult {
833                request_id: request_id.to_string(),
834                ok: false,
835                content: None,
836                error: Some(format!("local tool timed out after {timeout_ms}ms")),
837            }
838        }
839    }
840}
841
842// =============================================================================
843// SSE flush helpers
844// =============================================================================
845
846/// flush 累积的 agent-run SSE 数据行为一个事件(`[DONE]` → None)。对应 TS `readAgentRunEvents` flush。
847fn flush_agent_run_event(
848    event_name: &str,
849    data_lines: &mut Vec<String>,
850) -> Option<AgentRunStreamEvent> {
851    if data_lines.is_empty() {
852        return None;
853    }
854    let data = data_lines.join("\n");
855    data_lines.clear();
856    if data == "[DONE]" {
857        return None;
858    }
859    Some(parse_agent_run_event(event_name, &data))
860}
861
862/// flush 累积的 remote-control SSE 数据行为一个原始 JSON 帧(注入 type=event_name)。对应 TS `readAgentRunSSEFrames` flush。
863fn flush_remote_frame(event_name: &str, data_lines: &mut Vec<String>) -> Option<Value> {
864    if data_lines.is_empty() {
865        return None;
866    }
867    let data = data_lines.join("\n");
868    data_lines.clear();
869    if data == "[DONE]" {
870        return None;
871    }
872    let parsed: Value = serde_json::from_str(&data).ok()?;
873    let mut obj = match parsed {
874        Value::Object(m) => m,
875        _ => return None,
876    };
877    if !obj.contains_key("type") && !event_name.is_empty() {
878        obj.insert("type".to_string(), Value::String(event_name.to_string()));
879    }
880    Some(Value::Object(obj))
881}
882
883/// 解析单个 agent-run SSE 事件。对应 TS `parseAgentRunEvent`。
884///
885/// 🔴 **未知 type → [`AgentRunStreamEvent::Error`](code=`unknown_event`)注入流**(不丢;
886/// 与 `parse_remote_control_event` 未知→None 相反)。JSON 解析失败 → 同样兜底为 unknown error。
887fn parse_agent_run_event(event_name: &str, data: &str) -> AgentRunStreamEvent {
888    let payload: Value = match serde_json::from_str(data) {
889        Ok(v) => v,
890        Err(_) => {
891            // 非 JSON:当作 {type: eventName, data: 原文} 处理 → 走未知分支兜底 error。
892            return unknown_event(event_name, &json!({ "type": event_name, "data": data }));
893        }
894    };
895    let obj: serde_json::Map<String, Value> = match &payload {
896        Value::Object(m) => m.clone(),
897        other => {
898            let mut m = serde_json::Map::new();
899            m.insert("type".to_string(), Value::String(event_name.to_string()));
900            m.insert("data".to_string(), other.clone());
901            m
902        }
903    };
904    let type_ = sf(&obj, &["type"]);
905    let type_ = if type_.is_empty() {
906        event_name.to_string()
907    } else {
908        type_
909    };
910
911    match type_.as_str() {
912        "run_started" => AgentRunStreamEvent::RunStarted {
913            run_id: sf(&obj, &["run_id", "runId"]),
914            session_id: sf(&obj, &["session_id", "sessionId"]),
915        },
916        "status" => AgentRunStreamEvent::Status {
917            status: sf(&obj, &["status"]),
918            message: osf(&obj, &["message"]),
919        },
920        "text_delta" => AgentRunStreamEvent::TextDelta {
921            text: sf(&obj, &["text"]),
922        },
923        "reasoning_delta" => AgentRunStreamEvent::ReasoningDelta {
924            text: sf(&obj, &["text"]),
925        },
926        "tool_call" => AgentRunStreamEvent::ToolCall {
927            id: sf(&obj, &["id"]),
928            name: sf(&obj, &["name"]),
929            input: obj.get("input").cloned(),
930        },
931        "tool_result" => AgentRunStreamEvent::ToolResult {
932            id: sf(&obj, &["id"]),
933            name: osf(&obj, &["name"]),
934            result: obj.get("result").cloned(),
935            error: osf(&obj, &["error"]),
936        },
937        "local_tool_request" => AgentRunStreamEvent::LocalToolRequest {
938            request_id: sf(&obj, &["request_id", "requestId"]),
939            name: sf(&obj, &["name"]),
940            input: obj.get("input").cloned().unwrap_or(Value::Null),
941        },
942        "artifact" => {
943            let art_val = obj
944                .get("artifact")
945                .filter(|v| v.is_object())
946                .cloned()
947                .unwrap_or_else(|| Value::Object(obj.clone()));
948            AgentRunStreamEvent::Artifact {
949                artifact: from_wire_artifact_value(&art_val),
950            }
951        }
952        "sources" => AgentRunStreamEvent::Sources {
953            sources: obj.get("sources").cloned().unwrap_or(Value::Null),
954        },
955        "usage" => {
956            let src = obj
957                .get("usage")
958                .filter(|v| v.is_object())
959                .cloned()
960                .unwrap_or_else(|| Value::Object(obj.clone()));
961            AgentRunStreamEvent::Usage {
962                usage: normalize_usage(&src),
963            }
964        }
965        "settle" => {
966            let src = obj
967                .get("settlement")
968                .filter(|v| v.is_object())
969                .cloned()
970                .unwrap_or_else(|| Value::Object(obj.clone()));
971            AgentRunStreamEvent::Settle {
972                settlement: normalize_settlement(&src),
973            }
974        }
975        "error" => {
976            let err = normalize_error(obj.get("error"))
977                .or_else(|| normalize_error(Some(&Value::Object(obj.clone()))))
978                .unwrap_or_else(|| AgentRunErrorPayload {
979                    message: "agent run failed".to_string(),
980                    ..Default::default()
981                });
982            AgentRunStreamEvent::Error { error: err }
983        }
984        "done" => AgentRunStreamEvent::Done {
985            run_id: sf(&obj, &["run_id", "runId"]),
986            status: sf(&obj, &["status"]),
987        },
988        // 🔴 未知 type → Error 注入流(不丢)。
989        _ => unknown_event(&type_, &Value::Object(obj)),
990    }
991}
992
993fn unknown_event(type_: &str, raw: &Value) -> AgentRunStreamEvent {
994    AgentRunStreamEvent::Error {
995        error: AgentRunErrorPayload {
996            code: Some("unknown_event".to_string()),
997            message: format!("unknown agent run event: {type_}"),
998            stage: None,
999            retryable: None,
1000            raw: Some(raw.clone()),
1001        },
1002    }
1003}
1004
1005// =============================================================================
1006// usage / settlement / error 归一化
1007// =============================================================================
1008
1009fn normalize_usage(value: &Value) -> AgentRunUsage {
1010    let obj = value.as_object().cloned().unwrap_or_default();
1011    AgentRunUsage {
1012        input_tokens: nf(&obj, &["input_tokens", "inputTokens"]),
1013        output_tokens: nf(&obj, &["output_tokens", "outputTokens"]),
1014        total_tokens: nf(&obj, &["total_tokens", "totalTokens"]),
1015        cache_read_tokens: nf(&obj, &["cache_read_tokens", "cacheReadTokens"]),
1016        cache_create_tokens: nf(&obj, &["cache_create_tokens", "cacheCreateTokens"]),
1017        exact: bf(&obj, &["exact"]),
1018        source: osf(&obj, &["source"]),
1019        raw: value.clone(),
1020    }
1021}
1022
1023fn normalize_settlement(value: &Value) -> AgentRunSettlement {
1024    let obj = value.as_object().cloned().unwrap_or_default();
1025    AgentRunSettlement {
1026        request_id: osf(&obj, &["request_id", "requestId"]),
1027        status: osf(&obj, &["status"]),
1028        consume_status: osf(&obj, &["consume_status", "consumeStatus"]),
1029        input_tokens: nf(&obj, &["input_tokens", "inputTokens"]),
1030        output_tokens: nf(&obj, &["output_tokens", "outputTokens"]),
1031        total_tokens: nf(&obj, &["total_tokens", "totalTokens"]),
1032        cache_read_tokens: nf(&obj, &["cache_read_tokens", "cacheReadTokens"]),
1033        cache_create_tokens: nf(&obj, &["cache_create_tokens", "cacheCreateTokens"]),
1034        token_remaining: nf(&obj, &["token_remaining", "tokenRemaining"]),
1035        call_remaining: nf(&obj, &["call_remaining", "callRemaining"]),
1036        retry_queued: bf(&obj, &["retry_queued", "retryQueued"]),
1037        exact: bf(&obj, &["exact"]),
1038        raw: value.clone(),
1039    }
1040}
1041
1042fn normalize_error(value: Option<&Value>) -> Option<AgentRunErrorPayload> {
1043    let value = value?;
1044    match value {
1045        Value::Null => None,
1046        Value::String(s) => Some(AgentRunErrorPayload {
1047            message: s.clone(),
1048            raw: Some(value.clone()),
1049            ..Default::default()
1050        }),
1051        Value::Object(obj) => {
1052            let message = {
1053                let m = sf(obj, &["message", "error"]);
1054                if m.is_empty() {
1055                    "agent run failed".to_string()
1056                } else {
1057                    m
1058                }
1059            };
1060            Some(AgentRunErrorPayload {
1061                code: osf(obj, &["code", "error_code", "errorCode"]),
1062                message,
1063                stage: osf(obj, &["stage"]),
1064                retryable: obj.get("retryable").and_then(|v| v.as_bool()),
1065                raw: Some(value.clone()),
1066            })
1067        }
1068        other => Some(AgentRunErrorPayload {
1069            message: other.to_string(),
1070            raw: Some(value.clone()),
1071            ..Default::default()
1072        }),
1073    }
1074}
1075
1076// =============================================================================
1077// field 提取 helpers(对齐 TS stringField/optionalStringField/numberField/booleanField)
1078// =============================================================================
1079
1080fn sf(obj: &serde_json::Map<String, Value>, keys: &[&str]) -> String {
1081    for k in keys {
1082        if let Some(s) = obj.get(*k).and_then(|v| v.as_str()) {
1083            return s.to_string();
1084        }
1085    }
1086    String::new()
1087}
1088
1089fn osf(obj: &serde_json::Map<String, Value>, keys: &[&str]) -> Option<String> {
1090    let s = sf(obj, keys);
1091    if s.is_empty() {
1092        None
1093    } else {
1094        Some(s)
1095    }
1096}
1097
1098fn nf(obj: &serde_json::Map<String, Value>, keys: &[&str]) -> Option<i64> {
1099    for k in keys {
1100        if let Some(v) = obj.get(*k) {
1101            if let Some(i) = v.as_i64() {
1102                return Some(i);
1103            }
1104            if let Some(f) = v.as_f64().filter(|f| f.is_finite()) {
1105                return Some(f as i64);
1106            }
1107        }
1108    }
1109    None
1110}
1111
1112fn bf(obj: &serde_json::Map<String, Value>, keys: &[&str]) -> Option<bool> {
1113    for k in keys {
1114        if let Some(b) = obj.get(*k).and_then(|v| v.as_bool()) {
1115            return Some(b);
1116        }
1117    }
1118    None
1119}
1120
1121// =============================================================================
1122// wire DTO(JSON 反序列化) + 转换
1123// =============================================================================
1124
1125#[derive(serde::Deserialize, Default)]
1126struct WireAgentRunCreateResponse {
1127    #[serde(default)]
1128    run_id: Option<String>,
1129    #[serde(default)]
1130    session_id: Option<String>,
1131    #[serde(default)]
1132    status: Option<String>,
1133}
1134
1135#[derive(serde::Deserialize, Default)]
1136struct WireAgentRun {
1137    #[serde(default)]
1138    run_id: Option<String>,
1139    #[serde(default)]
1140    session_id: Option<String>,
1141    #[serde(default)]
1142    app_id: Option<String>,
1143    #[serde(default)]
1144    mode: Option<String>,
1145    #[serde(default)]
1146    status: Option<String>,
1147    #[serde(default)]
1148    created_at: Option<String>,
1149    #[serde(default)]
1150    started_at: Option<String>,
1151    #[serde(default)]
1152    completed_at: Option<String>,
1153    #[serde(default)]
1154    error: Option<Value>,
1155    #[serde(default)]
1156    metadata: Option<HashMap<String, String>>,
1157    #[serde(default)]
1158    runtime: Option<String>,
1159    #[serde(default)]
1160    runner: Option<String>,
1161    #[serde(default)]
1162    adapter: Option<String>,
1163}
1164
1165#[derive(serde::Deserialize, Default)]
1166struct WireAgentRunListResult {
1167    #[serde(default)]
1168    records: Option<Vec<WireAgentRun>>,
1169    #[serde(default)]
1170    total: Option<i64>,
1171    #[serde(default)]
1172    page: Option<i64>,
1173    // 注: 外层 pageSize 是 camelCase(对齐 listConsumeRecords 信封)。
1174    #[serde(default, rename = "pageSize")]
1175    page_size: Option<i64>,
1176}
1177
1178#[derive(serde::Deserialize, Default)]
1179struct WireRemoteSessionTokenGrant {
1180    #[serde(default)]
1181    access_token: Option<String>,
1182    #[serde(default)]
1183    session_url: Option<String>,
1184    #[serde(default)]
1185    tenant_id: Option<String>,
1186    #[serde(default)]
1187    workspace: Option<String>,
1188}
1189
1190#[derive(serde::Deserialize, Default)]
1191struct WireUserMessageAck {
1192    #[serde(default)]
1193    ok: Option<bool>,
1194    #[serde(default)]
1195    request_id: Option<String>,
1196}
1197
1198#[derive(serde::Deserialize, Default)]
1199struct WireAgentRunArtifactList {
1200    #[serde(default)]
1201    artifacts: Option<Vec<Value>>,
1202}
1203
1204fn to_wire_create_request(req: &AgentRunCreateRequest) -> Value {
1205    let mut m = serde_json::Map::new();
1206    m.insert("app_id".into(), json!(req.app_id));
1207    insert_opt(&mut m, "mode", req.mode.as_ref());
1208    insert_opt(&mut m, "session_id", req.session_id.as_ref());
1209    m.insert("input".into(), json!(req.input));
1210    if let Some(msgs) = &req.messages {
1211        m.insert("messages".into(), json!(msgs));
1212    }
1213    insert_opt(&mut m, "model", req.model.as_ref());
1214    if let Some(v) = &req.active_skill_ids {
1215        m.insert("active_skill_ids".into(), json!(v));
1216    }
1217    if let Some(v) = &req.knowledge_base_ids {
1218        m.insert("knowledge_base_ids".into(), json!(v));
1219    }
1220    if let Some(md) = &req.metadata {
1221        m.insert("metadata".into(), json!(md));
1222    }
1223    if let Some(p) = &req.local_context_policy {
1224        m.insert(
1225            "local_context_policy".into(),
1226            json!({
1227                "enabled": p.enabled,
1228                "readonly": p.readonly,
1229                "max_bytes": p.max_bytes,
1230                "allowed_tools": p.allowed_tools,
1231            }),
1232        );
1233    }
1234    insert_opt(&mut m, "runtime", req.runtime.as_ref());
1235    if let Some(r) = &req.runner {
1236        m.insert("runner".into(), json!(r.as_str()));
1237    }
1238    if let Some(a) = &req.adapter {
1239        m.insert("adapter".into(), json!(a.as_str()));
1240    }
1241    if let Some(p) = &req.permission_policy {
1242        m.insert("permission_policy".into(), to_wire_permission_policy(p));
1243    }
1244    if let Some(p) = &req.workspace_policy {
1245        m.insert("workspace_policy".into(), to_wire_workspace_policy(p));
1246    }
1247    insert_opt(
1248        &mut m,
1249        "byok_credential_ref",
1250        req.byok_credential_ref.as_ref(),
1251    );
1252    if let Some(p) = &req.artifact_policy {
1253        m.insert(
1254            "artifact_policy".into(),
1255            json!({ "enabled": p.enabled, "max_files": p.max_files }),
1256        );
1257    }
1258    Value::Object(m)
1259}
1260
1261fn to_wire_permission_policy(p: &PermissionPolicy) -> Value {
1262    json!({
1263        "shell_allowed": p.shell_allowed,
1264        "shell_deny_list": p.shell_deny_list,
1265        "network_allowed": p.network_allowed,
1266        "write_allowed": p.write_allowed,
1267        "approval_timeout_ms": p.approval_timeout_ms,
1268        "required_actors": p.required_actors,
1269    })
1270}
1271
1272fn to_wire_workspace_policy(p: &WorkspacePolicy) -> Value {
1273    json!({
1274        "read_only": p.read_only,
1275        "allowed_paths": p.allowed_paths,
1276        "denied_paths": p.denied_paths,
1277        "max_bytes": p.max_bytes,
1278    })
1279}
1280
1281fn insert_opt(m: &mut serde_json::Map<String, Value>, key: &str, v: Option<&String>) {
1282    if let Some(v) = v {
1283        m.insert(key.into(), json!(v));
1284    }
1285}
1286
1287fn from_wire_create_response(resp: WireAgentRunCreateResponse) -> AgentRunCreateResponse {
1288    AgentRunCreateResponse {
1289        run_id: resp.run_id.unwrap_or_default(),
1290        session_id: resp.session_id.unwrap_or_default(),
1291        status: AgentRunStatus::from_wire(resp.status.as_deref()),
1292    }
1293}
1294
1295fn from_wire_run(resp: WireAgentRun) -> AgentRun {
1296    AgentRun {
1297        run_id: resp.run_id.unwrap_or_default(),
1298        session_id: resp.session_id.unwrap_or_default(),
1299        app_id: resp.app_id,
1300        mode: resp.mode,
1301        status: Some(AgentRunStatus::from_wire(resp.status.as_deref())),
1302        created_at: resp.created_at,
1303        started_at: resp.started_at,
1304        completed_at: resp.completed_at,
1305        error: normalize_error(resp.error.as_ref()),
1306        metadata: resp.metadata,
1307        runtime: resp.runtime,
1308        runner: resp.runner,
1309        adapter: resp.adapter,
1310    }
1311}
1312
1313/// 从 wire artifact Value(列表/事件共用,宽容多字段)构建 [`AgentRunArtifact`]。对应 TS `fromWireArtifact`。
1314fn from_wire_artifact_value(v: &Value) -> AgentRunArtifact {
1315    let obj = v.as_object().cloned().unwrap_or_default();
1316    let id = sf(&obj, &["id", "artifact_id"]);
1317    let filename = {
1318        let f = sf(&obj, &["filename", "name", "id", "artifact_id"]);
1319        if f.is_empty() {
1320            "artifact".to_string()
1321        } else {
1322            f
1323        }
1324    };
1325    AgentRunArtifact {
1326        id,
1327        filename,
1328        content_type: osf(&obj, &["content_type", "mime_type"]),
1329        size: nf(&obj, &["size"]),
1330        r#type: osf(&obj, &["type"]),
1331        metadata: obj
1332            .get("metadata")
1333            .and_then(|m| serde_json::from_value::<HashMap<String, String>>(m.clone()).ok()),
1334    }
1335}
1336
1337fn from_wire_artifact(v: Value) -> AgentRunArtifact {
1338    from_wire_artifact_value(&v)
1339}
1340
1341/// 从 Content-Disposition 解析 filename(UTF-8'' 优先,回退 plain)。对应 TS `filenameFromContentDisposition`。
1342fn filename_from_content_disposition(value: Option<&str>) -> Option<String> {
1343    let value = value?;
1344    // filename*=UTF-8''<encoded>
1345    if let Some(idx) = value.to_lowercase().find("filename*=utf-8''") {
1346        let start = idx + "filename*=utf-8''".len();
1347        let rest = &value[start..];
1348        let encoded = rest.split(';').next().unwrap_or("").trim();
1349        if !encoded.is_empty() {
1350            return Some(percent_decode(encoded));
1351        }
1352    }
1353    // filename="..." / filename=...
1354    let lower = value.to_lowercase();
1355    if let Some(idx) = lower.find("filename=") {
1356        let start = idx + "filename=".len();
1357        let rest = &value[start..];
1358        let raw = rest.split(';').next().unwrap_or("").trim();
1359        let raw = raw.trim_matches('"');
1360        if !raw.is_empty() {
1361            return Some(raw.to_string());
1362        }
1363    }
1364    None
1365}
1366
1367/// 最小 percent-decode(用于 Content-Disposition filename* 的 UTF-8'' 段)。
1368fn percent_decode(s: &str) -> String {
1369    let bytes = s.as_bytes();
1370    let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
1371    let mut i = 0;
1372    while i < bytes.len() {
1373        if bytes[i] == b'%' && i + 2 < bytes.len() {
1374            let hi = (bytes[i + 1] as char).to_digit(16);
1375            let lo = (bytes[i + 2] as char).to_digit(16);
1376            if let (Some(hi), Some(lo)) = (hi, lo) {
1377                out.push((hi * 16 + lo) as u8);
1378                i += 3;
1379                continue;
1380            }
1381        }
1382        out.push(bytes[i]);
1383        i += 1;
1384    }
1385    String::from_utf8_lossy(&out).into_owned()
1386}
1387
1388// `parse_retry_after_secs` 仅 client.rs 内私有;这里复刻最小版(agent-runs 自有 raw 路径用)。
1389fn parse_retry_after_secs(headers: &http::header::HeaderMap) -> i64 {
1390    headers
1391        .get(http::header::RETRY_AFTER)
1392        .and_then(|v| v.to_str().ok())
1393        .and_then(|s| s.trim().parse::<i64>().ok())
1394        .filter(|&s| s > 0)
1395        .unwrap_or(0)
1396}
1397
1398#[cfg(test)]
1399mod tests {
1400    use super::*;
1401    use crate::agent_runs::remote_control::{
1402        is_terminal_remote_event, parse_remote_control_event, RemoteControlEvent,
1403    };
1404
1405    // === 🔴 红线 1a: AgentRunStreamEvent 未知 type → Error 注入流(不丢)===
1406    #[test]
1407    fn agent_run_unknown_event_becomes_error() {
1408        let ev = parse_agent_run_event("", r#"{"type":"totally_new_event","foo":1}"#);
1409        match ev {
1410            AgentRunStreamEvent::Error { error } => {
1411                assert_eq!(error.code.as_deref(), Some("unknown_event"));
1412                assert!(error.message.contains("totally_new_event"));
1413                assert!(error.raw.is_some());
1414            }
1415            other => panic!("expected Error, got {}", other.type_str()),
1416        }
1417    }
1418
1419    #[test]
1420    fn agent_run_unknown_event_from_event_name_fallback() {
1421        // payload 无 type,靠 SSE event: 名兜底;event 名也未知 → Error。
1422        let ev = parse_agent_run_event("mystery", r#"{"foo":1}"#);
1423        assert!(matches!(ev, AgentRunStreamEvent::Error { .. }));
1424        if let AgentRunStreamEvent::Error { error } = ev {
1425            assert!(error.message.contains("mystery"));
1426        }
1427    }
1428
1429    #[test]
1430    fn agent_run_malformed_json_becomes_error() {
1431        let ev = parse_agent_run_event("text_delta", "not json {{{");
1432        assert!(matches!(ev, AgentRunStreamEvent::Error { .. }));
1433    }
1434
1435    #[test]
1436    fn agent_run_known_events_parse() {
1437        let rs = parse_agent_run_event(
1438            "",
1439            r#"{"type":"run_started","run_id":"r1","session_id":"s1"}"#,
1440        );
1441        assert!(matches!(rs, AgentRunStreamEvent::RunStarted { .. }));
1442        let td = parse_agent_run_event("", r#"{"type":"text_delta","text":"hi"}"#);
1443        match td {
1444            AgentRunStreamEvent::TextDelta { text } => assert_eq!(text, "hi"),
1445            _ => panic!("expected text_delta"),
1446        }
1447        let ltr = parse_agent_run_event(
1448            "",
1449            r#"{"type":"local_tool_request","request_id":"q1","name":"shell","input":{"cmd":"ls"}}"#,
1450        );
1451        match ltr {
1452            AgentRunStreamEvent::LocalToolRequest {
1453                request_id, name, ..
1454            } => {
1455                assert_eq!(request_id, "q1");
1456                assert_eq!(name, "shell");
1457            }
1458            _ => panic!("expected local_tool_request"),
1459        }
1460        let usage = parse_agent_run_event(
1461            "",
1462            r#"{"type":"usage","input_tokens":10,"output_tokens":5,"exact":true}"#,
1463        );
1464        match usage {
1465            AgentRunStreamEvent::Usage { usage } => {
1466                assert_eq!(usage.input_tokens, Some(10));
1467                assert_eq!(usage.output_tokens, Some(5));
1468                assert_eq!(usage.exact, Some(true));
1469            }
1470            _ => panic!("expected usage"),
1471        }
1472        let done =
1473            parse_agent_run_event("", r#"{"type":"done","run_id":"r1","status":"completed"}"#);
1474        match done {
1475            AgentRunStreamEvent::Done { run_id, status } => {
1476                assert_eq!(run_id, "r1");
1477                assert_eq!(status, "completed");
1478            }
1479            _ => panic!("expected done"),
1480        }
1481    }
1482
1483    #[test]
1484    fn agent_run_error_event_parses_payload() {
1485        let ev = parse_agent_run_event(
1486            "",
1487            r#"{"type":"error","error":{"code":"E1","message":"boom","stage":"plan","retryable":true}}"#,
1488        );
1489        match ev {
1490            AgentRunStreamEvent::Error { error } => {
1491                assert_eq!(error.code.as_deref(), Some("E1"));
1492                assert_eq!(error.message, "boom");
1493                assert_eq!(error.stage.as_deref(), Some("plan"));
1494                assert_eq!(error.retryable, Some(true));
1495            }
1496            _ => panic!("expected error"),
1497        }
1498    }
1499
1500    // === 🔴 红线 1b: RemoteControlEvent 未知 type → None 静默丢弃(与上相反)===
1501    #[test]
1502    fn remote_control_unknown_event_is_none() {
1503        let v: Value = serde_json::from_str(r#"{"type":"totally_new_event","foo":1}"#).unwrap();
1504        assert!(parse_remote_control_event(&v).is_none());
1505    }
1506
1507    #[test]
1508    fn remote_control_missing_field_is_none() {
1509        // text_delta 缺 index → None。
1510        let v: Value = serde_json::from_str(r#"{"type":"text_delta","text":"hi"}"#).unwrap();
1511        assert!(parse_remote_control_event(&v).is_none());
1512        // 无 type → None。
1513        let v2: Value = serde_json::from_str(r#"{"foo":1}"#).unwrap();
1514        assert!(parse_remote_control_event(&v2).is_none());
1515    }
1516
1517    // === 红线: 11 事件解析 ===
1518    #[test]
1519    fn remote_control_all_eleven_events_parse() {
1520        let cases: &[(&str, &str)] = &[
1521            (
1522                "text_delta",
1523                r#"{"type":"text_delta","index":0,"text":"a"}"#,
1524            ),
1525            (
1526                "reasoning_delta",
1527                r#"{"type":"reasoning_delta","index":1,"text":"b"}"#,
1528            ),
1529            (
1530                "tool_call",
1531                r#"{"type":"tool_call","tool_call_id":"t1","name":"sh"}"#,
1532            ),
1533            (
1534                "tool_result",
1535                r#"{"type":"tool_result","tool_call_id":"t1","ok":true}"#,
1536            ),
1537            (
1538                "permission_request",
1539                r#"{"type":"permission_request","request_id":"p1","kind":"shell"}"#,
1540            ),
1541            (
1542                "permission_result",
1543                r#"{"type":"permission_result","request_id":"p1","decision":"allow"}"#,
1544            ),
1545            ("usage", r#"{"type":"usage","input_tokens":3}"#),
1546            (
1547                "settle",
1548                r#"{"type":"settle","status":"settled","billed":true}"#,
1549            ),
1550            ("status", r#"{"type":"status","phase":"running"}"#),
1551            ("error", r#"{"type":"error","code":"E","message":"m"}"#),
1552            (
1553                "done",
1554                r#"{"type":"done","reason":"ok","run_id":"r1","final_status":"completed"}"#,
1555            ),
1556        ];
1557        for (name, payload) in cases {
1558            let v: Value = serde_json::from_str(payload).unwrap();
1559            let ev = parse_remote_control_event(&v)
1560                .unwrap_or_else(|| panic!("event {name} should parse"));
1561            assert_eq!(ev.type_str(), *name);
1562        }
1563    }
1564
1565    #[test]
1566    fn remote_control_terminal_only_done_and_settle() {
1567        let done = RemoteControlEvent::Done {
1568            reason: "ok".into(),
1569            run_id: "r".into(),
1570            final_status: "completed".into(),
1571        };
1572        let settle = RemoteControlEvent::Settle {
1573            status: "settled".into(),
1574            billed: Some(true),
1575        };
1576        let err = RemoteControlEvent::Error {
1577            code: "E".into(),
1578            message: "m".into(),
1579            retryable: None,
1580            kind: None,
1581        };
1582        assert!(is_terminal_remote_event(&done));
1583        assert!(is_terminal_remote_event(&settle));
1584        // error 非终结(契约 §4)。
1585        assert!(!is_terminal_remote_event(&err));
1586    }
1587
1588    #[test]
1589    fn remote_control_camel_snake_aliases() {
1590        let v: Value =
1591            serde_json::from_str(r#"{"type":"tool_call","toolCallId":"t9","name":"x"}"#).unwrap();
1592        match parse_remote_control_event(&v).unwrap() {
1593            RemoteControlEvent::ToolCall { tool_call_id, .. } => assert_eq!(tool_call_id, "t9"),
1594            _ => panic!("expected tool_call"),
1595        }
1596    }
1597
1598    // === 红线: 本地工具回调硬超时(忽略 signal 的 handler 也不永挂)===
1599    #[tokio::test(start_paused = true)]
1600    async fn local_tool_timeout_when_handler_ignores_signal() {
1601        let mut handlers: HashMap<String, _> = HashMap::new();
1602        handlers.insert(
1603            "slow".to_string(),
1604            |_input: Value, _ctx: LocalToolContext| async move {
1605                // 完全忽略取消信号,睡很久。
1606                tokio::time::sleep(std::time::Duration::from_secs(3600)).await;
1607                Ok(Value::Null)
1608            },
1609        );
1610        let result =
1611            invoke_local_tool("run1", "req1", "slow", Value::Null, &handlers, 50, None).await;
1612        assert!(!result.ok);
1613        assert_eq!(result.request_id, "req1");
1614        assert!(result.error.unwrap().contains("timed out"));
1615    }
1616
1617    #[tokio::test]
1618    async fn local_tool_no_handler_rejected() {
1619        // 含一个无关 handler(同型 map),探测 missing 名应被拒。
1620        let mut handlers: HashMap<String, _> = HashMap::new();
1621        handlers.insert(
1622            "present".to_string(),
1623            |input: Value, _ctx: LocalToolContext| async move { Ok(input) },
1624        );
1625        let result = invoke_local_tool(
1626            "run1",
1627            "req1",
1628            "missing",
1629            Value::Null,
1630            &handlers,
1631            1000,
1632            None,
1633        )
1634        .await;
1635        assert!(!result.ok);
1636        assert!(result.error.unwrap().contains("no handler"));
1637    }
1638
1639    #[tokio::test]
1640    async fn local_tool_success_returns_content() {
1641        let mut handlers: HashMap<String, _> = HashMap::new();
1642        handlers.insert(
1643            "echo".to_string(),
1644            |input: Value, _ctx: LocalToolContext| async move { Ok(input) },
1645        );
1646        let result = invoke_local_tool(
1647            "run1",
1648            "req1",
1649            "echo",
1650            json!({"a":1}),
1651            &handlers,
1652            1000,
1653            None,
1654        )
1655        .await;
1656        assert!(result.ok);
1657        assert_eq!(result.content, Some(json!({"a":1})));
1658    }
1659
1660    // === create_remote_run 校验 ===
1661    #[test]
1662    fn to_wire_create_request_remote_fields() {
1663        let req = AgentRunCreateRequest {
1664            app_id: "app".into(),
1665            input: "hi".into(),
1666            runtime: Some("crabcode_remote".into()),
1667            runner: Some(crate::agent_runs::RunnerKind::from("cloud")),
1668            adapter: Some(crate::agent_runs::AdapterKind::from("remote_io")),
1669            byok_credential_ref: Some("cred-ref-1".into()),
1670            ..Default::default()
1671        };
1672        let wire = to_wire_create_request(&req);
1673        assert_eq!(wire["app_id"], "app");
1674        assert_eq!(wire["runtime"], "crabcode_remote");
1675        assert_eq!(wire["runner"], "cloud");
1676        assert_eq!(wire["adapter"], "remote_io");
1677        assert_eq!(wire["byok_credential_ref"], "cred-ref-1");
1678    }
1679
1680    #[test]
1681    fn content_disposition_filename_parsing() {
1682        assert_eq!(
1683            filename_from_content_disposition(Some("attachment; filename=\"report.zip\"")),
1684            Some("report.zip".to_string())
1685        );
1686        assert_eq!(
1687            filename_from_content_disposition(Some("attachment; filename*=UTF-8''a%20b.txt")),
1688            Some("a b.txt".to_string())
1689        );
1690        assert_eq!(filename_from_content_disposition(None), None);
1691    }
1692}