@carfiedli/runtime-guardrail 0.1.19

package/dist/adapters/index.d.ts

@@ -0,0 +1 @@
+export * from "./persistence";

package/dist/adapters/persistence/file-store.d.ts

@@ -0,0 +1,18 @@
+export type FileStoreEntry = {
+    key: string;
+    content: string;
+    updatedAt: number;
+};
+export interface FileStore {
+    read(key: string): Promise<string | undefined>;
+    write(key: string, content: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<FileStoreEntry[]>;
+}
+export declare class InMemoryFileStore implements FileStore {
+    private readonly files;
+    read(key: string): Promise<string | undefined>;
+    write(key: string, content: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<FileStoreEntry[]>;
+}

package/dist/adapters/persistence/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./file-store";
+export * from "./json-event-log";
+export * from "./snapshot-store";
+export * from "./queue-store";

package/dist/adapters/persistence/json-event-log.d.ts

@@ -0,0 +1,31 @@
+import type { FileStore } from "./file-store";
+export type EventLogCorruptionRecord = {
+    key: string;
+    detectedAt: number;
+    reason: string;
+    rawContent?: string;
+};
+export interface EventLogCorruptionSink {
+    record(record: EventLogCorruptionRecord): Promise<void>;
+    list(): Promise<EventLogCorruptionRecord[]>;
+}
+export declare class InMemoryEventLogCorruptionSink implements EventLogCorruptionSink {
+    private readonly records;
+    record(record: EventLogCorruptionRecord): Promise<void>;
+    list(): Promise<EventLogCorruptionRecord[]>;
+}
+export interface EventLog<T> {
+    append(entry: T): Promise<void>;
+    list(): Promise<T[]>;
+    replace(entries: T[]): Promise<void>;
+}
+export declare class JsonEventLog<T> implements EventLog<T> {
+    private readonly fileStore;
+    private readonly key;
+    private readonly corruptionSink;
+    constructor(fileStore: FileStore, key: string, corruptionSink?: EventLogCorruptionSink);
+    append(entry: T): Promise<void>;
+    list(): Promise<T[]>;
+    replace(entries: T[]): Promise<void>;
+    private readEntries;
+}

package/dist/adapters/persistence/queue-store.d.ts

@@ -0,0 +1,19 @@
+import type { FileStore } from "./file-store";
+export type PersistedQueueItem<T> = {
+    id: string;
+    createdAt: number;
+    payload: T;
+};
+export interface QueueStore<T> {
+    enqueue(payload: T): Promise<PersistedQueueItem<T>>;
+    list(): Promise<Array<PersistedQueueItem<T>>>;
+    remove(id: string): Promise<void>;
+}
+export declare class JsonQueueStore<T> implements QueueStore<T> {
+    private readonly fileStore;
+    private readonly key;
+    constructor(fileStore: FileStore, key: string);
+    enqueue(payload: T): Promise<PersistedQueueItem<T>>;
+    list(): Promise<Array<PersistedQueueItem<T>>>;
+    remove(id: string): Promise<void>;
+}

package/dist/adapters/persistence/snapshot-store.d.ts

@@ -0,0 +1,14 @@
+import type { FileStore } from "./file-store";
+export interface SnapshotStore<T> {
+    load(): Promise<T | undefined>;
+    save(snapshot: T): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class JsonSnapshotStore<T> implements SnapshotStore<T> {
+    private readonly fileStore;
+    private readonly key;
+    constructor(fileStore: FileStore, key: string);
+    load(): Promise<T | undefined>;
+    save(snapshot: T): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/approval/approval-service.d.ts

@@ -0,0 +1,27 @@
+import type { ApprovalListQuery, ApprovalTicket, GuardrailDecision } from "../contracts";
+import { ApprovalStateMachine } from "./approval-state-machine";
+import type { HitlConnector } from "./hitl/hitl-connector";
+export type ResolveApprovalInput = {
+    approvalId: string;
+    decision: "approved" | "rejected";
+    resolvedBy?: string;
+    note?: string;
+    source?: string;
+    externalApprovalId?: string;
+};
+export interface ApprovalService {
+    createFromDecision(decision: GuardrailDecision): Promise<ApprovalTicket[]>;
+    getById(approvalId: string): Promise<ApprovalTicket | undefined>;
+    list(query?: ApprovalListQuery): Promise<ApprovalTicket[]>;
+    resolve(input: ResolveApprovalInput): Promise<ApprovalTicket>;
+}
+export declare class InMemoryApprovalService implements ApprovalService {
+    private readonly stateMachine;
+    private readonly hitlConnector;
+    private readonly approvals;
+    constructor(stateMachine: ApprovalStateMachine, hitlConnector: HitlConnector);
+    createFromDecision(decision: GuardrailDecision): Promise<ApprovalTicket[]>;
+    getById(approvalId: string): Promise<ApprovalTicket | undefined>;
+    list(query?: ApprovalListQuery): Promise<ApprovalTicket[]>;
+    resolve(input: ResolveApprovalInput): Promise<ApprovalTicket>;
+}

package/dist/approval/approval-state-machine.d.ts

@@ -0,0 +1,5 @@
+import type { ApprovalStatus } from "../contracts";
+export declare class ApprovalStateMachine {
+    canTransition(from: ApprovalStatus, to: ApprovalStatus): boolean;
+    transition(from: ApprovalStatus, to: ApprovalStatus): ApprovalStatus;
+}

package/dist/approval/hitl/hitl-connector.d.ts

@@ -0,0 +1,9 @@
+import type { ApprovalTicket } from "../../contracts";
+export interface HitlConnector {
+    enqueueApproval(ticket: ApprovalTicket): Promise<void>;
+    notifyResolution(ticket: ApprovalTicket): Promise<void>;
+}
+export declare class NoopHitlConnector implements HitlConnector {
+    enqueueApproval(): Promise<void>;
+    notifyResolution(): Promise<void>;
+}

package/dist/approval/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./approval-state-machine";
+export * from "./approval-service";
+export * from "./run-hold-service";
+export * from "./hitl/hitl-connector";

package/dist/approval/run-hold-service.d.ts

@@ -0,0 +1,16 @@
+import type { GuardrailDecision, RunHoldListQuery, RunHoldTicket } from "../contracts";
+export interface RunHoldService {
+    createFromDecision(decision: GuardrailDecision, approvalIds?: string[]): Promise<RunHoldTicket[]>;
+    getById(holdId: string): Promise<RunHoldTicket | undefined>;
+    list(query?: RunHoldListQuery): Promise<RunHoldTicket[]>;
+    resume(holdId: string): Promise<RunHoldTicket>;
+    cancel(holdId: string): Promise<RunHoldTicket>;
+}
+export declare class InMemoryRunHoldService implements RunHoldService {
+    private readonly holds;
+    createFromDecision(decision: GuardrailDecision, approvalIds?: string[]): Promise<RunHoldTicket[]>;
+    getById(holdId: string): Promise<RunHoldTicket | undefined>;
+    list(query?: RunHoldListQuery): Promise<RunHoldTicket[]>;
+    resume(holdId: string): Promise<RunHoldTicket>;
+    cancel(holdId: string): Promise<RunHoldTicket>;
+}

package/dist/audit/audit-event-store.d.ts

@@ -0,0 +1,12 @@
+import type { EventLog } from "../adapters";
+import type { AuditEvent } from "../contracts";
+export interface AuditEventStore {
+    append(event: AuditEvent): Promise<void>;
+    list(): Promise<AuditEvent[]>;
+}
+export declare class JsonAuditEventStore implements AuditEventStore {
+    private readonly eventLog;
+    constructor(eventLog: EventLog<AuditEvent>);
+    append(event: AuditEvent): Promise<void>;
+    list(): Promise<AuditEvent[]>;
+}

package/dist/audit/audit-read-model-builder.d.ts

@@ -0,0 +1,17 @@
+import type { SnapshotStore } from "../adapters";
+import type { ShieldIncident } from "../types";
+import type { AuditEventStore } from "./audit-event-store";
+import { type MetricsProjection } from "./metrics-projection";
+export type AuditReadModel = {
+    schemaVersion: 1;
+    generatedAt: number;
+    incidents: ShieldIncident[];
+    metrics: MetricsProjection;
+};
+export declare class AuditReadModelBuilder {
+    private readonly auditEventStore;
+    private readonly snapshotStore;
+    constructor(auditEventStore: AuditEventStore, snapshotStore: SnapshotStore<AuditReadModel>);
+    getCurrent(): Promise<AuditReadModel>;
+    refresh(): Promise<AuditReadModel>;
+}

package/dist/audit/audit-service.d.ts

@@ -0,0 +1,18 @@
+import type { AuditEvent, GuardrailDecision } from "../contracts";
+import type { AuditLogger } from "../runtime-core";
+import type { AuditReadModelBuilder } from "./audit-read-model-builder";
+import type { AuditEventStore } from "./audit-event-store";
+export interface AuditService extends AuditLogger {
+    append(event: AuditEvent): Promise<void>;
+    appendDecision(decision: GuardrailDecision): Promise<void>;
+    listEvents(): Promise<AuditEvent[]>;
+}
+export declare class DefaultAuditService implements AuditService {
+    private readonly eventStore;
+    private readonly readModelBuilder?;
+    constructor(eventStore: AuditEventStore, readModelBuilder?: AuditReadModelBuilder | undefined);
+    append(event: AuditEvent): Promise<void>;
+    appendDecision(decision: GuardrailDecision): Promise<void>;
+    logDecision(decision: GuardrailDecision): Promise<void>;
+    listEvents(): Promise<AuditEvent[]>;
+}

package/dist/audit/incident-query-service.d.ts

@@ -0,0 +1,7 @@
+import type { ShieldIncident } from "../types";
+import type { AuditReadModelBuilder } from "./audit-read-model-builder";
+export declare class IncidentQueryService {
+    private readonly readModelBuilder;
+    constructor(readModelBuilder: AuditReadModelBuilder);
+    listIncidents(): Promise<ShieldIncident[]>;
+}

package/dist/audit/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./audit-event-store";
+export * from "./audit-service";
+export * from "./incident-query-service";
+export * from "./metrics-projection";
+export * from "./audit-read-model-builder";

package/dist/audit/metrics-projection.d.ts

@@ -0,0 +1,10 @@
+import type { AuditEvent } from "../contracts";
+import type { ShieldSeverity } from "../types";
+export type MetricsProjection = {
+    totalEvents: number;
+    eventTypeCounts: Record<string, number>;
+    blockedDecisionCount: number;
+    decisionCount: number;
+    severityCounts: Record<ShieldSeverity, number>;
+};
+export declare const buildMetricsProjection: (events: AuditEvent[]) => MetricsProjection;

package/dist/bootstrap/create-runtime-guardrail-plugin.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawApi } from "../contracts";
+import { PluginRuntime, type PluginRuntimeOptions } from "../openclaw/plugin-runtime";
+export declare const createRuntimeGuardrailPlugin: (api: OpenClawApi, options?: PluginRuntimeOptions) => Promise<PluginRuntime>;

package/dist/bootstrap/dependency-container.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeBootstrapOptions, RuntimeFacade } from "./runtime-facade";
+export declare const createRuntimeFacade: (options?: RuntimeBootstrapOptions) => RuntimeFacade;

package/dist/bootstrap/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./runtime-facade";
+export * from "./dependency-container";
+export * from "./create-runtime-guardrail-plugin";

package/dist/bootstrap/runtime-facade.d.ts

@@ -0,0 +1,31 @@
+import type { FileStore } from "../adapters";
+import type { ApprovalService, RunHoldService } from "../approval";
+import type { AuditEventStore, AuditReadModelBuilder, AuditService, IncidentQueryService } from "../audit";
+import type { EgressMediator, ExecutionBroker, ExecutionPlanBuilder, ModelGovernanceService } from "../execution";
+import type { OperatorCommandService, OperatorQueryService, ReportService } from "../operator";
+import type { AuditLogger, EvaluateService, PolicyEvaluator, ShieldRuntimeConfig } from "../runtime-core";
+export type RuntimeBootstrapOptions = {
+    config?: Partial<ShieldRuntimeConfig>;
+    policyEvaluator?: PolicyEvaluator;
+    auditLogger?: AuditLogger;
+};
+export interface RuntimeFacade {
+    runtimeConfig: ShieldRuntimeConfig;
+    fileStore: FileStore;
+    policyEvaluator: PolicyEvaluator;
+    auditLogger: AuditLogger;
+    evaluateService: EvaluateService;
+    auditEventStore: AuditEventStore;
+    auditReadModelBuilder: AuditReadModelBuilder;
+    auditService: AuditService;
+    incidentQueryService: IncidentQueryService;
+    approvalService: ApprovalService;
+    runHoldService: RunHoldService;
+    modelGovernanceService: ModelGovernanceService;
+    egressMediator: EgressMediator;
+    executionPlanBuilder: ExecutionPlanBuilder;
+    executionBroker: ExecutionBroker;
+    operatorQueryService: OperatorQueryService;
+    operatorCommandService: OperatorCommandService;
+    reportService: ReportService;
+}

package/dist/compat/index.d.ts

@@ -0,0 +1 @@
+export * from "./legacy-types";

package/dist/compat/legacy-types.d.ts

@@ -0,0 +1,29 @@
+import type { ApprovalTicket, AuditEvent, GuardrailDecision, RunHoldTicket } from "../contracts";
+import type { ShieldApprovalRequest, ShieldPolicyResult, ShieldRunHold, ShieldStage } from "../types";
+/**
+ * 【兼容层】将旧版策略评估结果映射为新版护栏决策
+ * 用于在旧的 ShieldPolicyResult 格式和新的 GuardrailDecision 格式之间做转换
+ * 处理流程：
+ * 1. 生成决策 ID
+ * 2. 标准化发现列表(findings)
+ * 3. 根据 effectiveAction、审批请求、运行暂停等生成效果(effects)列表
+ * 4. 组装完整决策对象
+ */
+export declare const mapPolicyResultToDecision: (policyResult: ShieldPolicyResult, envelopeRef: GuardrailDecision["envelopeRef"], stage: ShieldStage, simulated: boolean) => GuardrailDecision;
+/**
+ * 【兼容层】将旧版审批请求映射为新版审批工单
+ * ShieldApprovalRequest → ApprovalTicket 的格式转换
+ */
+export declare const mapApprovalRequestToTicket: (request: ShieldApprovalRequest) => ApprovalTicket;
+/**
+ * 【兼容层】将旧版运行暂停记录映射为新版暂停工单
+ * ShieldRunHold → RunHoldTicket 的格式转换
+ */
+export declare const mapRunHoldToTicket: (hold: ShieldRunHold) => RunHoldTicket;
+/**
+ * 构建决策审计事件
+ * 将护栏决策转换为审计事件格式，用于审计日志记录
+ * 如果决策中包含 block 效果，事件类型为 "decision.blocked"
+ * 否则为 "decision.made"
+ */
+export declare const buildDecisionAuditEvent: (decision: GuardrailDecision) => AuditEvent;

package/dist/contracts/core.d.ts

@@ -0,0 +1,277 @@
+import type { ShieldApprovalCategory, ShieldFailMode, ShieldSeverity, ShieldStage, ShieldSurface } from "../types";
+/** 统一钩子名称枚举：对应 Agent 生命周期中的各个检测点 */
+export type ShieldCanonicalHookName = "message_received" | "before_llm_request" | "before_tool_call" | "message_sending" | "before_message_write" | "tool_result_persist";
+/**
+ * 兼容别名：历史代码使用 ShieldHookName，等价于统一钩子名
+ * 后续建议优先使用 ShieldCanonicalHookName
+ */
+export type ShieldHookName = ShieldCanonicalHookName;
+/** 宿主类型 */
+export type HostType = "openclaw" | "langchain" | "custom";
+/** 宿主信息（用于跨宿主接入时标识来源） */
+export type HostInfo = {
+    hostType: HostType;
+    hostVersion?: string;
+};
+/** 钩子信封基础类型：所有钩子事件的公共字段 */
+export type HookEnvelopeBase = {
+    /** 统一钩子名：评估引擎优先依赖该字段 */
+    canonicalHook: ShieldCanonicalHookName;
+    /** 宿主原始钩子名（不同宿主可不一致） */
+    hostHookName: string;
+    surface: ShieldSurface;
+    timestamp: number;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    hostInfo?: HostInfo;
+    /** 宿主平台传递的上下文信息 */
+    hostContext: Record<string, unknown>;
+};
+/** 入口钩子信封：用户消息到达时触发 */
+export type IngressEnvelope = HookEnvelopeBase & {
+    canonicalHook: "message_received";
+    hostHookName: "message_received" | "before_prompt_build";
+    surface: "ingress";
+    payload: {
+        message: unknown;
+    };
+};
+/** LLM 请求钩子信封：向大模型发送请求前触发 */
+export type LlmRequestEnvelope = HookEnvelopeBase & {
+    canonicalHook: "before_llm_request";
+    hostHookName: "llm_input";
+    surface: "llm";
+    payload: {
+        provider: string;
+        model: string;
+        prompt: string;
+        systemPrompt?: string;
+        historyMessages: unknown[];
+        skillNames?: string[];
+    };
+};
+/** 工具调用钩子信封：执行工具调用前触发 */
+export type ToolCallEnvelope = HookEnvelopeBase & {
+    canonicalHook: "before_tool_call";
+    hostHookName: "before_tool_call";
+    surface: "tool";
+    payload: {
+        toolName: string;
+        toolParams: Record<string, unknown>;
+    };
+};
+/** 出口钩子信封：向用户发送消息前触发 */
+export type EgressEnvelope = HookEnvelopeBase & {
+    canonicalHook: "message_sending";
+    hostHookName: "message_sending";
+    surface: "egress";
+    payload: {
+        message: unknown;
+        channel?: string;
+    };
+};
+/** 持久化钩子信封：写入消息或工具结果前触发 */
+export type PersistEnvelope = HookEnvelopeBase & {
+    canonicalHook: "before_message_write" | "tool_result_persist";
+    hostHookName: "before_message_write" | "tool_result_persist";
+    surface: "persist";
+    payload: {
+        message?: unknown;
+        toolName?: string;
+        toolResult?: unknown;
+    };
+};
+/** 钩子信封联合类型：所有钩子信封的联合 */
+export type HookEnvelope = IngressEnvelope | LlmRequestEnvelope | ToolCallEnvelope | EgressEnvelope | PersistEnvelope;
+/** 原因代码：标识安全问题的分类 */
+export type ReasonCode = "prompt_injection" | "retrieval_poisoning" | "sensitive_action" | "egress_exfiltration" | "mcp_allowlist_violation" | "model_governance_violation" | "approval_required" | "unknown";
+/** 标准化的检测发现：将各种来源的发现统一为标准格式 */
+export type NormalizedFinding = {
+    findingId: string;
+    detector: string;
+    reasonCode: ReasonCode;
+    severity: ShieldSeverity;
+    summary: string;
+    tags: string[];
+    evidence?: Record<string, unknown>;
+    matchedRuleIds?: string[];
+};
+/** 审批工单草案：创建审批请求时的初始数据 */
+export type ApprovalTicketDraft = {
+    category: ShieldApprovalCategory;
+    reason: string;
+    severity: ShieldSeverity;
+    tags?: string[];
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    toolName?: string;
+    /** 审批来源绑定（关联外部审批系统） */
+    sourceBinding?: {
+        source: string;
+        externalApprovalId?: string;
+    };
+    /** 相关资源信息 */
+    resource?: {
+        toolName?: string;
+        provider?: string;
+        model?: string;
+    };
+};
+/** 运行暂停草案：创建运行暂停时的初始数据 */
+export type RunHoldDraft = {
+    toolName: string;
+    toolParams?: Record<string, unknown>;
+    /** 暂停时所处的护盾阶段 */
+    stageAtHold: ShieldStage;
+    /** 暂停时的失败模式 */
+    failModeAtHold: ShieldFailMode;
+    category?: ShieldApprovalCategory;
+    severity?: ShieldSeverity;
+    reason?: string;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+};
+/** 执行计划草案：描述即将执行的操作类型和要求 */
+export type ExecutionPlanDraft = {
+    /** 操作类型：llm_request=LLM请求 | tool_call=工具调用 | message_send=消息发送 */
+    actionType: "llm_request" | "tool_call" | "message_send";
+    /** 要求的后端环境 */
+    requiredBackend?: "local" | "sandbox" | "remote_controlled";
+    /** 沙箱配置 */
+    sandboxProfile?: string;
+    /** 审批模式 */
+    approvalMode?: "none" | "required" | "already_bound";
+    /** 预算配置 */
+    budgetProfile?: string;
+};
+/**
+ * 决策效果联合类型：描述护栏决策产生的各种效果
+ * - allow: 放行
+ * - redact: 脱敏（指定字段和替换值）
+ * - block: 拦截（附带原因）
+ * - queue_approval: 排队等待审批
+ * - create_run_hold: 暂停运行
+ * - require_model_profile: 要求使用指定模型配置
+ * - restrict_model: 限制可用的模型/提供商
+ * - route_execution: 路由到指定执行计划
+ * - emit_audit: 发出审计事件
+ */
+export type DecisionEffect = {
+    type: "allow";
+} | {
+    type: "redact";
+    targets: Array<{
+        field: string;
+        replacement: string;
+        ruleId?: string;
+        value?: unknown;
+    }>;
+} | {
+    type: "block";
+    reason: string;
+} | {
+    type: "queue_approval";
+    ticket: ApprovalTicketDraft;
+} | {
+    type: "create_run_hold";
+    hold: RunHoldDraft;
+} | {
+    type: "require_model_profile";
+    profileId: string;
+} | {
+    type: "restrict_model";
+    allowedProviderIds?: string[];
+    allowedModelIds?: string[];
+} | {
+    type: "route_execution";
+    plan: ExecutionPlanDraft;
+} | {
+    type: "emit_audit";
+    eventType: string;
+};
+/** 护栏决策：一次完整的安全评估决策结果 */
+export type GuardrailDecision = {
+    decisionId: string;
+    /** 触发决策的钩子信封引用 */
+    envelopeRef: {
+        /** 统一钩子名 */
+        canonicalHook: ShieldCanonicalHookName;
+        /** 宿主原始钩子名（可选，跨宿主时可能与 canonicalHook 不同） */
+        hostHookName?: string;
+        surface: ShieldSurface;
+        agentId?: string;
+        runId?: string;
+        sessionId?: string;
+    };
+    /** 当前护盾阶段 */
+    stage: ShieldStage;
+    severity: ShieldSeverity;
+    /** 标准化检测发现列表 */
+    findings: NormalizedFinding[];
+    /** 决策产生的效果列表 */
+    effects: DecisionEffect[];
+    /** 原因代码列表 */
+    reasonCodes: ReasonCode[];
+    tags: string[];
+    /** 是否为模拟模式 */
+    simulated: boolean;
+    /** 评估耗时（毫秒） */
+    durationMs: number;
+};
+/** 审批状态 */
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
+/** 审批工单（完整版）：在草案基础上增加了 ID、状态和时间戳等运行时字段 */
+export type ApprovalTicket = ApprovalTicketDraft & {
+    approvalId: string;
+    incidentId?: string;
+    status: ApprovalStatus;
+    createdAt: number;
+    resolvedAt?: number;
+    resolvedBy?: string;
+    note?: string;
+};
+/** 运行暂停状态 */
+export type RunHoldStatus = "pending" | "approved_waiting_resume" | "resumed" | "rejected" | "expired" | "cancelled";
+/** 运行暂停工单（完整版）：在草案基础上增加了 ID、状态和时间戳 */
+export type RunHoldTicket = RunHoldDraft & {
+    holdId: string;
+    approvalId: string;
+    status: RunHoldStatus;
+    createdAt: number;
+    resumedAt?: number;
+    cancelledAt?: number;
+};
+/** 执行计划（完整版）：在草案基础上增加了模型限制和出口策略等 */
+export type ExecutionPlan = ExecutionPlanDraft & {
+    planId: string;
+    allowedProviderIds?: string[];
+    allowedModelIds?: string[];
+    requiredModelProfile?: string;
+    /** 出口策略：限制目标地址和渠道 */
+    egressPolicy?: {
+        destinationAllowlist?: string[];
+        channelAllowlist?: string[];
+    };
+};
+/** 审计事件类型枚举 */
+export type AuditEventType = "decision.made" | "decision.blocked" | "approval.queued" | "approval.resolved" | "run_hold.created" | "run_hold.resumed" | "hitl.deadletter.queued" | "hitl.deadletter.resolved";
+/** 审计事件：记录系统中发生的每一个重要安全事件 */
+export type AuditEvent = {
+    eventId: string;
+    eventType: AuditEventType;
+    timestamp: number;
+    decisionId?: string;
+    approvalId?: string;
+    holdId?: string;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    /** 事件的详细数据 */
+    payload: Record<string, unknown>;
+    /** Schema 版本号 */
+    schemaVersion: 1;
+};

package/dist/contracts/events.d.ts

@@ -0,0 +1,35 @@
+/** 护盾网关事件常量：定义所有可以通过网关发布的事件名称 */
+export declare const SHIELD_GATEWAY_EVENTS: {
+    readonly decision: "shield.decision";
+    readonly blocked: "shield.blocked";
+    readonly stageChanged: "shield.stage.changed";
+    readonly approvalQueued: "shield.approval.queued";
+    readonly approvalResolved: "shield.approval.resolved";
+    readonly hitlDeadLetterQueued: "shield.hitl.deadletter.queued";
+    readonly hitlDeadLetterResolved: "shield.hitl.deadletter.resolved";
+};
+/** 网关事件的通用包装类型 */
+export type GatewayEvent<T = unknown> = {
+    eventName: string;
+    data: T;
+};
+/** 决策事件数据：决策做出时附带的信息 */
+export type DecisionEventData = {
+    decisionId: string;
+    hook: string;
+    surface: string;
+    stage: string;
+    severity: string;
+    effects: unknown[];
+    reasonCodes: string[];
+    simulated: boolean;
+    durationMs: number;
+};
+/** 拦截事件数据：请求被拦截时附带的信息 */
+export type BlockedEventData = {
+    decisionId: string;
+    hook: string;
+    surface: string;
+    reason: string;
+    findings: unknown[];
+};