vigil_types/
approval.rs

1//! ApprovalRequest：需要人类或策略批准的请求。
2
3use crate::effect::EffectVector;
4use serde::{Deserialize, Serialize};
5
6/// 一条待审批请求。
7///
8/// 生命周期状态机（I03 实装）：Pending → (Approved | Denied | Expired | Cancelled)。
9#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
10pub struct ApprovalRequest {
11    /// 唯一 id。
12    pub approval_id: String,
13    /// 对应裁决。
14    pub decision_id: String,
15    /// 被审批的 tool-call invocation。
16    /// 绑定 `ApprovalScope::Once`:一次批准只对本 invocation 生效(ADR 0003 §D6)。
17    pub invocation_id: String,
18    /// 所属 session。
19    pub session_id: String,
20    /// 卡片标题（面向用户）。
21    pub title: String,
22    /// 卡片摘要（已脱敏，不含原始 args）。
23    pub summary: String,
24    /// 被审批的效应向量（用户能直接看到"会做什么"）。
25    pub effect_vector: EffectVector,
26    /// 到期时间（Unix epoch 秒）；到期后视为 Expired。
27    pub expires_at: i64,
28    /// 当前状态。
29    pub status: ApprovalStatus,
30}
31
32/// 审批状态。
33#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
34#[non_exhaustive]
35#[serde(rename_all = "PascalCase")]
36pub enum ApprovalStatus {
37    /// 等待用户决策。
38    Pending,
39    /// 已批准。
40    Approved,
41    /// 已拒绝。
42    Denied,
43    /// TTL 到期。
44    Expired,
45    /// 上游取消（session 结束 / agent 中断等）。
46    Cancelled,
47}
48
49/// 审批范围(ADR 0003 §D6)。
50///
51/// I02+I03 实装:`Once` / `ThisSession`。后两项放占位,I05+ 启用。
52#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
53#[non_exhaustive]
54#[serde(rename_all = "PascalCase")]
55pub enum ApprovalScope {
56    /// 只对当前 `invocation_id` 生效,消费即失效。
57    Once,
58    /// 对同一 `session_id` 下、`(server_id, tool_name, args_hash)` 相同的后续调用自动放行。
59    ThisSession,
60    /// 跨 session,对相同 `args_hash` 的调用放行(I05+)。
61    ForToolWithSameArgsHash,
62    /// 派生为临时 allow 规则(I05+)。
63    ForPolicyTemplate,
64}
65
66/// 审批最终解析结果。`wait_for_resolution` 的返回值。
67#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
68pub struct ApprovalResolution {
69    /// 被解析的审批 id。
70    pub approval_id: String,
71    /// 绑定到的 `invocation_id`(首次创建 approval 时由 decision 关联)。
72    /// 供 I04 MCP Hub 在 `ApprovalScope::Once` 下做"仅本次 invocation 放行"校验。
73    pub invocation_id: String,
74    /// 终态。
75    pub status: ApprovalStatus,
76    /// 若 `status == Approved`,携带用户选择的范围;其它状态下为 `None`。
77    pub scope: Option<ApprovalScope>,
78    /// 解析人标识(用户名 / "system" / "auto-expired")。
79    pub resolved_by: Option<String>,
80    /// 解析时间(Unix epoch 秒)。
81    pub resolved_at: i64,
82}
vigil_types/approval.rs

vigil_types/
approval.rs
