@carfiedli/runtime-guardrail 0.1.19

package/dist/openclaw/skills-availability.d.ts

@@ -0,0 +1,10 @@
+import type { OpenClawApi } from "../contracts";
+export type SkillsAvailabilityOptions = {
+    /** 是否启用 skills 可用性治理（默认开启；可显式设为 false 关闭） */
+    enabled?: boolean;
+    /** 预留：后端校验接口地址（当前仅记录 TODO，不发起调用） */
+    verificationEndpoint?: string;
+    /** 模拟返回需禁用的 skills（用于联调验证） */
+    simulatedDisabledSkills?: string[];
+};
+export declare const registerSkillsAvailabilityService: (api: OpenClawApi, options?: SkillsAvailabilityOptions) => void;

package/dist/openclaw/skills-upload.d.ts

@@ -0,0 +1,17 @@
+import type { OpenClawApi } from "../contracts";
+import { type RemoteGuardConfig } from "../runtime-core";
+export type SkillsUploadOptions = {
+    /** 是否启用自动上传（默认启用） */
+    enabled?: boolean;
+    /** 上传超时毫秒数（默认使用 remote-guard-config.options.timeoutMs） */
+    timeoutMs?: number;
+    /** 是否忽略幂等缓存强制上传 */
+    force?: boolean;
+    /** 申请预签名 URL 时使用的 content_type */
+    contentType?: string;
+    /** 指向用户侧下发的 remote-guard-config.json */
+    remoteGuardConfigPath?: string;
+    /** 直接注入远端配置（优先于 remoteGuardConfigPath） */
+    remoteGuardConfig?: RemoteGuardConfig;
+};
+export declare const registerSkillsUploadService: (api: OpenClawApi, options?: SkillsUploadOptions) => void;

package/dist/openclaw/testing/index.d.ts

@@ -0,0 +1 @@
+export * from "./mock-openclaw-api";

package/dist/openclaw/testing/mock-openclaw-api.d.ts

@@ -0,0 +1,74 @@
+import type { CliCommandHandler, GatewayRequestHandlerOptions, OpenClawApi, OpenClawCliRegistrarContext, OpenClawHookName, PluginHookContextMap, PluginHookEventMap, PluginHookHandler } from "../../contracts";
+/**
+ * Mock OpenClaw API
+ * 模拟宿主平台的完整能力：钩子注册、网关方法、CLI 命令、日志
+ * 用于独立测试和集成测试
+ */
+export declare class MockOpenClawApi implements OpenClawApi {
+    /** 已注册的钩子处理器 */
+    private readonly hookHandlers;
+    /** 已注册的网关方法 */
+    private readonly gatewayMethods;
+    /** 已注册的 CLI 命令 */
+    private readonly cliCommands;
+    /** 日志记录 */
+    private readonly logEntries;
+    /** 是否静默模式（不输出日志到控制台） */
+    private silent;
+    constructor(options?: {
+        silent?: boolean;
+    });
+    on<H extends OpenClawHookName>(hookName: H, handler: PluginHookHandler<H>): void;
+    registerGatewayMethod(method: string, handler: (options: GatewayRequestHandlerOptions) => Promise<void> | void): void;
+    registerCli(nameOrRegistrar: string | ((ctx: OpenClawCliRegistrarContext) => void | Promise<void>), handlerOrOptions?: CliCommandHandler | {
+        commands?: string[];
+    }): void;
+    log: {
+        info: (message: string) => void;
+        warn: (message: string) => void;
+        error: (message: string) => void;
+        debug: (message: string) => void;
+    };
+    /**
+     * 模拟触发一个钩子事件
+     * @returns 所有处理器的返回结果数组
+     */
+    triggerHook<H extends OpenClawHookName>(hookName: H, event: PluginHookEventMap[H], ctx?: PluginHookContextMap[H]): Promise<unknown[]>;
+    /**
+     * 模拟调用 RPC 方法
+     * @returns 处理器的响应结果
+     */
+    callRpc(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 模拟执行 CLI 命令
+     */
+    executeCli(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** 获取已注册的钩子名称列表 */
+    getRegisteredHooks(): string[];
+    /** 获取已注册的网关方法列表 */
+    getRegisteredGatewayMethods(): string[];
+    /** 获取已注册的 CLI 命令列表 */
+    getRegisteredCliCommands(): string[];
+    /** 获取日志记录 */
+    getLogs(): ReadonlyArray<{
+        level: string;
+        message: string;
+        timestamp: number;
+    }>;
+    /** 获取指定级别的日志 */
+    getLogsByLevel(level: string): Array<{
+        level: string;
+        message: string;
+        timestamp: number;
+    }>;
+    /** 清空日志 */
+    clearLogs(): void;
+    /** 设置是否静默 */
+    setSilent(silent: boolean): void;
+}
+/**
+ * 工厂函数：创建 Mock OpenClaw API 实例
+ */
+export declare const createMockOpenClawApi: (options?: {
+    silent?: boolean;
+}) => MockOpenClawApi;

package/dist/operator/cli/register-cli.d.ts

@@ -0,0 +1,4 @@
+import type { OpenClawApi } from "../../contracts";
+import type { OperatorCommandService } from "../command-service";
+import type { OperatorQueryService } from "../query-service";
+export declare const registerShieldCli: (api: OpenClawApi, queryService: OperatorQueryService, commandService: OperatorCommandService) => void;

package/dist/operator/command-service.d.ts

@@ -0,0 +1,15 @@
+import type { CancelRunHoldCommand, ResolveApprovalCommand, ResumeRunHoldCommand } from "../contracts";
+import type { ApprovalService, RunHoldService } from "../approval";
+export interface OperatorCommandService {
+    resolveApproval(command: ResolveApprovalCommand): Promise<unknown>;
+    resumeRunHold(command: ResumeRunHoldCommand): Promise<unknown>;
+    cancelRunHold(command: CancelRunHoldCommand): Promise<unknown>;
+}
+export declare class DefaultOperatorCommandService implements OperatorCommandService {
+    private readonly approvalService;
+    private readonly runHoldService;
+    constructor(approvalService: ApprovalService, runHoldService: RunHoldService);
+    resolveApproval(command: ResolveApprovalCommand): Promise<unknown>;
+    resumeRunHold(command: ResumeRunHoldCommand): Promise<unknown>;
+    cancelRunHold(command: CancelRunHoldCommand): Promise<unknown>;
+}

package/dist/operator/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./query-service";
+export * from "./command-service";
+export * from "./rpc/register-rpc";
+export * from "./cli/register-cli";
+export * from "./reporting/report-service";

package/dist/operator/query-service.d.ts

@@ -0,0 +1,21 @@
+import type { ApprovalListQuery, ApprovalListResult, IncidentListQuery, IncidentListResult, RunHoldListQuery, RunHoldListResult, StatusQueryResult } from "../contracts";
+import type { ApprovalService, RunHoldService } from "../approval";
+import type { AuditReadModelBuilder } from "../audit";
+import type { ShieldRuntimeConfig } from "../runtime-core";
+export interface OperatorQueryService {
+    getStatus(): Promise<StatusQueryResult>;
+    listIncidents(query?: IncidentListQuery): Promise<IncidentListResult>;
+    listApprovals(query?: ApprovalListQuery): Promise<ApprovalListResult>;
+    listRunHolds(query?: RunHoldListQuery): Promise<RunHoldListResult>;
+}
+export declare class DefaultOperatorQueryService implements OperatorQueryService {
+    private readonly runtimeConfig;
+    private readonly auditReadModelBuilder;
+    private readonly approvalService;
+    private readonly runHoldService;
+    constructor(runtimeConfig: ShieldRuntimeConfig, auditReadModelBuilder: AuditReadModelBuilder, approvalService: ApprovalService, runHoldService: RunHoldService);
+    getStatus(): Promise<StatusQueryResult>;
+    listIncidents(query?: IncidentListQuery): Promise<IncidentListResult>;
+    listApprovals(query?: ApprovalListQuery): Promise<ApprovalListResult>;
+    listRunHolds(query?: RunHoldListQuery): Promise<RunHoldListResult>;
+}

package/dist/operator/reporting/report-service.d.ts

@@ -0,0 +1,9 @@
+import type { OperatorQueryService } from "../query-service";
+export interface ReportService {
+    generateSummary(): Promise<Record<string, unknown>>;
+}
+export declare class DefaultReportService implements ReportService {
+    private readonly queryService;
+    constructor(queryService: OperatorQueryService);
+    generateSummary(): Promise<Record<string, unknown>>;
+}

package/dist/operator/rpc/register-rpc.d.ts

@@ -0,0 +1,5 @@
+import type { OpenClawApi } from "../../contracts";
+import type { OperatorCommandService } from "../command-service";
+import type { OperatorQueryService } from "../query-service";
+import type { ReportService } from "../reporting/report-service";
+export declare const registerShieldRpc: (api: OpenClawApi, queryService: OperatorQueryService, commandService: OperatorCommandService, reportService: ReportService) => void;

package/dist/policy/detectors/detector-port.d.ts

@@ -0,0 +1,23 @@
+import type { ReasonCode } from "../../contracts";
+import type { ShieldPolicyInput, ShieldRedaction, ShieldSeverity, ShieldStage, ShieldRuleAction } from "../../types";
+export type DetectorContext = {
+    stage: ShieldStage;
+    now: number;
+};
+export type DetectorSignal = {
+    detector: string;
+    reasonCode: ReasonCode | string;
+    severity: ShieldSeverity;
+    summary: string;
+    tags: string[];
+    evidence?: Record<string, unknown>;
+    matchedRuleIds?: string[];
+    suggestedAction?: Exclude<ShieldRuleAction, "allow">;
+    redactions?: ShieldRedaction[];
+};
+export interface PolicyDetector {
+    detect(input: ShieldPolicyInput, context: DetectorContext): Promise<DetectorSignal[]>;
+}
+export declare class NoopPolicyDetector implements PolicyDetector {
+    detect(): Promise<DetectorSignal[]>;
+}

package/dist/policy/finding-normalizer.d.ts

@@ -0,0 +1,3 @@
+import type { NormalizedFinding } from "../contracts";
+import type { DetectorSignal } from "./detectors/detector-port";
+export declare const normalizeSignals: (decisionId: string, signals: DetectorSignal[]) => NormalizedFinding[];

package/dist/policy/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./policy-engine";
+export * from "./stage-resolver";
+export * from "./finding-normalizer";
+export * from "./detectors/detector-port";

package/dist/policy/policy-engine.d.ts

@@ -0,0 +1,8 @@
+import type { PolicyEvaluator } from "../runtime-core";
+import type { ShieldPolicyInput, ShieldPolicyResult, ShieldStage } from "../types";
+import type { PolicyDetector } from "./detectors/detector-port";
+export declare class PolicyEngine implements PolicyEvaluator {
+    private readonly detectors;
+    constructor(detectors?: PolicyDetector[]);
+    evaluate(input: ShieldPolicyInput, stage: ShieldStage): Promise<ShieldPolicyResult>;
+}

package/dist/policy/stage-resolver.d.ts

@@ -0,0 +1,7 @@
+import type { ShieldRuleAction, ShieldSeverity, ShieldStage } from "../types";
+export type StageResolution = {
+    effectiveAction: ShieldRuleAction;
+    simulatedBlock: boolean;
+    simulatedRedaction: boolean;
+};
+export declare const resolveStageAction: (stage: ShieldStage, rawAction: ShieldRuleAction, severity: ShieldSeverity) => StageResolution;

package/dist/runtime-core/device-id.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 设备 ID 自动获取工具
+ * 基于操作系统信息自动生成设备标识，用于心跳上报、数据上报和安全检测请求
+ */
+/**
+ * 获取设备 ID
+ * 格式: {platform}-{release}
+ * 例如: linux-5.15.0-86-generic
+ * 获取失败时返回 "Unknown"
+ */
+export declare const getDeviceId: () => string;
+/**
+ * 清除缓存的设备 ID（仅用于测试）
+ */
+export declare const clearDeviceIdCache: () => void;

package/dist/runtime-core/evaluate-service.d.ts

@@ -0,0 +1,91 @@
+import type { GuardrailDecision, HookEnvelope } from "../contracts";
+import type { ShieldFailMode, ShieldPolicyInput, ShieldPolicyResult } from "../types";
+import type { ShieldStage } from "../types";
+/**
+ * 策略评估器接口
+ * 负责根据输入和当前阶段执行策略评估，返回评估结果
+ */
+export interface PolicyEvaluator {
+    evaluate(input: ShieldPolicyInput, stage: ShieldStage): Promise<ShieldPolicyResult>;
+    evaluateSync?(input: ShieldPolicyInput, stage: ShieldStage): ShieldPolicyResult;
+}
+/**
+ * 审计日志器接口
+ * 负责记录每次护栏决策的审计日志
+ */
+export interface AuditLogger {
+    logDecision(decision: GuardrailDecision): Promise<void>;
+    logDecisionSync?(decision: GuardrailDecision): void;
+}
+/** 护盾运行时配置 */
+export interface ShieldRuntimeConfig {
+    /** 是否为模拟模式（仅记录不实际执行） */
+    simulated: boolean;
+    /** 失败模式（评估异常时的行为） */
+    failMode: ShieldFailMode;
+}
+/**
+ * 评估服务接口
+ * 接收钩子信封，返回护栏决策
+ */
+export interface EvaluateService {
+    evaluate(envelope: HookEnvelope): Promise<GuardrailDecision>;
+    evaluateSync?(envelope: HookEnvelope): GuardrailDecision | undefined;
+}
+/**
+ * 创建空操作（Noop）策略评估器
+ * 始终返回"放行"结果，用于未配置策略评估器时的默认行为
+ */
+export declare const createNoopPolicyEvaluator: () => PolicyEvaluator;
+/**
+ * 创建空操作（Noop）审计日志器
+ * 不做任何记录，用于未配置审计日志器时的默认行为
+ */
+export declare const createNoopAuditLogger: () => AuditLogger;
+/**
+ * 评估服务实现类（核心引擎）
+ * 整个护栏系统的核心处理流程：
+ * 信封(Envelope) → 策略输入 → 策略评估 → 决策映射 → 审计日志
+ */
+export declare class EvaluateServiceImpl implements EvaluateService {
+    private readonly config;
+    private readonly policyEvaluator;
+    private readonly auditLogger;
+    constructor(config: ShieldRuntimeConfig, policyEvaluator: PolicyEvaluator, auditLogger: AuditLogger);
+    /**
+     * 执行完整的安全评估流程（异步主路径）
+     */
+    evaluate(envelope: HookEnvelope): Promise<GuardrailDecision>;
+    /**
+     * 同步评估路径：仅当策略评估器支持 evaluateSync 时可用。
+     * 主要用于 OpenClaw 的同步 persist hooks。
+     */
+    evaluateSync(envelope: HookEnvelope): GuardrailDecision | undefined;
+    /**
+     * 生成唯一的决策 ID
+     * 格式：decision_{时间戳}_{随机字符串}
+     */
+    private createDecisionId;
+    /**
+     * 将钩子信封转换为策略评估输入
+     * 根据不同的钩子类型，提取对应的字段组合成 ShieldPolicyInput
+     */
+    private mapEnvelopeToPolicyInput;
+    /**
+     * 将策略评估结果映射为护栏决策
+     */
+    private mapPolicyResultToDecision;
+    /**
+     * 将策略评估结果映射为决策效果列表
+     */
+    private mapPolicyResultToEffects;
+    /**
+     * 标准化原因代码
+     */
+    private normalizeReasonCode;
+    /**
+     * 构建 failMode 降级决策
+     * failMode="open" → 放行（allow），failMode="closed" → 拦截（block）
+     */
+    private buildFailModeDecision;
+}

package/dist/runtime-core/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./evaluate-service";
+export * from "./remote-policy-evaluator";
+export * from "./memory-audit-logger";
+export * from "./memory-store";
+export * from "./remote-guard-types";
+export * from "./remote-guard-request-builder";
+export * from "./remote-guard-transport";
+export * from "./sync-remote-evaluate";
+export * from "./telemetry-types";
+export * from "./telemetry-service";

package/dist/runtime-core/memory-audit-logger.d.ts

@@ -0,0 +1,55 @@
+import type { AuditEvent, GuardrailDecision } from "../contracts";
+import type { AuditLogger } from "./evaluate-service";
+/** 审计日志级别 */
+export type AuditLogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** 内存审计日志器配置 */
+export type MemoryAuditLoggerConfig = {
+    /** 日志级别（控制控制台输出的详细程度） */
+    logLevel?: AuditLogLevel;
+    /** 最大存储事件数（超过后自动清理最早的事件） */
+    maxEvents?: number;
+    /** 自定义日志前缀 */
+    prefix?: string;
+};
+/**
+ * 内存审计日志器
+ * 将审计事件存储在内存中，并可选输出到控制台
+ * 支持查询历史事件、按类型过滤、清空等操作
+ */
+export declare class MemoryAuditLogger implements AuditLogger {
+    private readonly events;
+    private readonly config;
+    constructor(config?: MemoryAuditLoggerConfig);
+    /**
+     * 记录护栏决策（实现 AuditLogger 接口）
+     */
+    logDecision(decision: GuardrailDecision): Promise<void>;
+    /**
+     * 同步记录护栏决策，供 OpenClaw 的同步 persist hook 使用。
+     */
+    logDecisionSync(decision: GuardrailDecision): void;
+    /**
+     * 直接记录一个审计事件（用于 RPC 操作等非决策场景）
+     */
+    logEvent(event: AuditEvent): void;
+    /** 获取所有审计事件 */
+    getEvents(): ReadonlyArray<AuditEvent>;
+    /** 按事件类型查询 */
+    getEventsByType(eventType: AuditEvent["eventType"]): AuditEvent[];
+    /** 按决策 ID 查询 */
+    getEventsByDecisionId(decisionId: string): AuditEvent[];
+    /** 获取事件总数 */
+    getEventCount(): number;
+    /** 清空所有事件 */
+    clear(): void;
+    /** 存储事件到内存 */
+    private storeEvent;
+    /** 输出审计事件到控制台 */
+    private printEvent;
+    /** 检查是否应该输出指定级别的日志 */
+    private shouldLog;
+}
+/**
+ * 工厂函数：创建内存审计日志器
+ */
+export declare const createMemoryAuditLogger: (config?: MemoryAuditLoggerConfig) => MemoryAuditLogger;

package/dist/runtime-core/memory-store.d.ts

@@ -0,0 +1,141 @@
+import type { ApprovalTicket, ApprovalTicketDraft, GuardrailDecision, RunHoldDraft, RunHoldTicket } from "../contracts";
+import type { ShieldIncident } from "../types";
+/**
+ * 内存存储：安全事件(Incident)
+ * 记录每次安全检查产生的事件
+ *
+ * 淘汰策略：写入时若总量超过阈值，自动清理已上报的旧记录；
+ * 未上报的记录永远不会被淘汰，确保审计链完整。
+ */
+export declare class IncidentStore {
+    private readonly incidents;
+    private readonly gcThreshold;
+    /** 已上报的记录 ID 集合 */
+    private readonly reportedIds;
+    constructor(gcThreshold?: number);
+    /** 从护栏决策创建安全事件 */
+    createFromDecision(decision: GuardrailDecision): ShieldIncident;
+    /** 获取所有事件 */
+    list(query?: {
+        agentId?: string;
+        runId?: string;
+        limit?: number;
+        offset?: number;
+    }): {
+        total: number;
+        items: ShieldIncident[];
+    };
+    /** 根据 ID 获取事件 */
+    get(id: string): ShieldIncident | undefined;
+    /** 获取事件总数 */
+    count(): number;
+    /** 标记事件为已上报，后续 GC 时可被清理 */
+    markReported(ids: string[]): void;
+    /** 清空所有事件 */
+    clear(): void;
+    /** 超过阈值时清理已上报的记录 */
+    private maybeGc;
+}
+/**
+ * 内存存储：审批工单(Approval)
+ *
+ * 淘汰策略：写入时若总量超过阈值，自动清理已终态（approved/rejected）的旧记录；
+ * pending 状态的工单永远不会被淘汰，避免 agent 永久卡住。
+ */
+export declare class ApprovalStore {
+    private readonly approvals;
+    private readonly gcThreshold;
+    constructor(gcThreshold?: number);
+    /** 从草案创建审批工单 */
+    create(draft: ApprovalTicketDraft, incidentId?: string): ApprovalTicket;
+    /** 解决审批 */
+    resolve(approvalId: string, decision: "approved" | "rejected", resolvedBy?: string, note?: string): ApprovalTicket | undefined;
+    /** 列出审批 */
+    list(query?: {
+        status?: string[];
+        category?: string[];
+        limit?: number;
+        offset?: number;
+    }): {
+        total: number;
+        items: ApprovalTicket[];
+    };
+    /** 根据 ID 获取审批 */
+    get(approvalId: string): ApprovalTicket | undefined;
+    /** 获取待审批数量 */
+    pendingCount(): number;
+    /** 获取总数 */
+    count(): number;
+    /** 清空 */
+    clear(): void;
+    /** 已终态的审批状态 */
+    private static readonly TERMINAL_STATUSES;
+    /** 超过阈值时清理已终态的记录 */
+    private maybeGc;
+}
+/**
+ * 内存存储：运行暂停(RunHold)
+ *
+ * 淘汰策略：写入时若总量超过阈值，自动清理已终态（resumed/cancelled）的旧记录；
+ * pending 和 approved_waiting_resume 状态的不会被淘汰。
+ */
+export declare class RunHoldStore {
+    private readonly holds;
+    private readonly gcThreshold;
+    constructor(gcThreshold?: number);
+    /** 从草案创建运行暂停 */
+    create(draft: RunHoldDraft, approvalId: string): RunHoldTicket;
+    /** 恢复运行 */
+    resume(holdId: string): RunHoldTicket | undefined;
+    /** 取消暂停 */
+    cancel(holdId: string): RunHoldTicket | undefined;
+    /** 列出暂停 */
+    list(query?: {
+        agentId?: string;
+        status?: string[];
+        limit?: number;
+        offset?: number;
+    }): {
+        total: number;
+        items: RunHoldTicket[];
+    };
+    /** 根据 ID 获取暂停 */
+    get(holdId: string): RunHoldTicket | undefined;
+    /** 获取待处理数量 */
+    pendingCount(): number;
+    /** 获取总数 */
+    count(): number;
+    /** 清空 */
+    clear(): void;
+    /** 已终态的 hold 状态 */
+    private static readonly TERMINAL_STATUSES;
+    /** 超过阈值时清理已终态的记录 */
+    private maybeGc;
+}
+/**
+ * 聚合存储：统一管理所有内存存储
+ */
+export declare class MemoryStore {
+    readonly incidents: IncidentStore;
+    readonly approvals: ApprovalStore;
+    readonly runHolds: RunHoldStore;
+    /** 获取统计摘要 */
+    getStats(): {
+        incidents: number;
+        approvals: number;
+        pendingApprovals: number;
+        runHolds: number;
+        pendingRunHolds: number;
+    };
+    /** 清空所有存储 */
+    clearAll(): void;
+    /**
+     * 处理护栏决策产生的副作用
+     * 根据决策效果自动创建 Incident、Approval、RunHold
+     */
+    processDecisionEffects(decision: GuardrailDecision): {
+        incident?: ShieldIncident;
+        approval?: ApprovalTicket;
+        runHold?: RunHoldTicket;
+    };
+}

package/dist/runtime-core/remote-guard-request-builder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 远端安全检测请求构建器
+ * 将内部 ShieldPolicyInput 数据转换为远端服务需要的统一格式
+ */
+import type { ShieldPolicyInput, ShieldStage } from "../types";
+import type { RemoteGuardConfig, RemoteGuardRequest } from "./remote-guard-types";
+/**
+ * 构建远端安全检测请求
+ */
+export declare const buildRemoteGuardRequest: (input: ShieldPolicyInput, stage: ShieldStage, config: RemoteGuardConfig) => Promise<RemoteGuardRequest>;
+/**
+ * 同步版本：构建远端安全检测请求
+ * 用于同步 hook（before_message_write / tool_result_persist）中构建请求体
+ */
+export declare const buildRemoteGuardRequestSync: (input: ShieldPolicyInput, stage: ShieldStage, config: RemoteGuardConfig) => RemoteGuardRequest;

package/dist/runtime-core/remote-guard-transport.d.ts

@@ -0,0 +1,79 @@
+type PathModule = {
+    resolve: (...parts: string[]) => string;
+    join: (...parts: string[]) => string;
+};
+type OsModule = {
+    homedir: () => string;
+};
+/**
+ * 远端安全检测 HTTP Transport 实现
+ * 负责调用远端服务并处理响应
+ */
+import type { RemotePolicyResponse, RemotePolicyTransport } from "./remote-policy-evaluator";
+import type { RemoteGuardConfig, RemoteGuardResponse } from "./remote-guard-types";
+/**
+ * 清除配置缓存，强制下次重新加载配置文件
+ */
+export declare const clearRemoteGuardConfigCache: () => void;
+export declare const getDefaultRemoteGuardConfigPath: (params?: {
+    env?: Record<string, string | undefined>;
+    path?: PathModule;
+    os?: OsModule;
+}) => string;
+export declare const getDefaultRemoteGuardAuthConfigPath: (params?: {
+    env?: Record<string, string | undefined>;
+    path?: PathModule;
+    os?: OsModule;
+}) => string;
+export declare const resolveRuntimeRemoteGuardConfigPath: (configPath?: string) => string;
+/**
+ * 加载远端配置文件
+ * 注意：此函数只在 Node.js 环境下工作
+ */
+export declare const loadRemoteGuardConfig: (configPath?: string) => Promise<RemoteGuardConfig | null>;
+/**
+ * 同步加载配置（用于启动时）
+ *
+ * @param configPath 配置文件路径
+ * @param forceReload 是否强制重新读取文件（跳过缓存）
+ */
+export declare const loadRemoteGuardConfigSync: (configPath?: string, forceReload?: boolean) => RemoteGuardConfig | null;
+/**
+ * 获取已加载的配置
+ */
+export declare const getRemoteGuardConfig: () => RemoteGuardConfig | null;
+/**
+ * 设置配置（用于测试或手动注入）
+ */
+export declare const setRemoteGuardConfig: (config: RemoteGuardConfig | null) => void;
+/**
+ * 将远端响应转换为内部策略响应格式
+ *
+ * 处理逻辑：
+ * - deny: 阻断，设置 block 动作，创建 finding 用于 Incident 记录
+ * - approval: 需要审批，设置 block 动作（暂停会话），创建 approvalRequest 和 runHold
+ * - redact: 脱敏
+ * - allow/其他: 放行
+ */
+export declare const mapRemoteGuardResponseToPolicyResponse: (response: RemoteGuardResponse, requestContext?: {
+    toolName?: string;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+}) => RemotePolicyResponse;
+/**
+ * 创建 HTTP Transport 实现
+ *
+ * 配置在创建 transport 时传入，后续使用该配置。
+ * 如需更新本地配置或 API Key，可修改文件后执行 `shield.config.refresh` 或重启 gateway。
+ */
+export declare const createRemoteGuardHttpTransport: (config: RemoteGuardConfig) => RemotePolicyTransport;
+/**
+ * 创建带自动配置加载的 HTTP Transport
+ */
+export declare const createAutoConfigRemoteGuardTransport: (configPath?: string) => Promise<RemotePolicyTransport | undefined>;
+/**
+ * 创建带自动配置加载的 HTTP Transport（同步版本）
+ */
+export declare const createAutoConfigRemoteGuardTransportSync: (configPath?: string) => RemotePolicyTransport | undefined;
+export {};