@carfiedli/runtime-guardrail 0.1.19

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

@@ -0,0 +1,183 @@
+/**
+ * 远端安全检测服务请求/响应类型定义
+ * 基于 iwiki 文档：https://iwiki.woa.com/p/4018637975
+ */
+/** Hook 类型枚举 */
+export type RemoteGuardHookType = "message_received" | "before_prompt_build" | "llm_input" | "before_tool_call" | "tool_result_persist" | "before_message_write" | "message_sending";
+/** message_received 事件数据 */
+export type MessageReceivedEvents = {
+    from?: string;
+    content: string;
+    metadata: {
+        provider: string;
+        surface: string;
+        originatingChannel: string;
+        messageId: string;
+        senderId: string;
+    };
+};
+/** before_prompt_build 事件数据 */
+export type BeforePromptBuildEvents = {
+    prompt: string;
+};
+/** llm_input 事件数据 */
+export type LlmInputEvents = {
+    runId: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    prompt: string;
+    imagesCount: number;
+};
+/** before_tool_call 事件数据 */
+export type BeforeToolCallEvents = {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId: string;
+    toolCallId: string;
+    /** Skill 名称（当检测到读取 SKILL.md 时填充，否则为空字符串） */
+    skillName: string;
+};
+/** tool_result_persist 事件数据 */
+export type ToolResultPersistEvents = {
+    toolName: string;
+    toolCallId: string;
+    content: string;
+    isError: boolean;
+    isSynthetic: boolean;
+};
+/** Token 使用统计 */
+export type UsageInfo = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+};
+/** before_message_write 事件数据 */
+export type BeforeMessageWriteEvents = {
+    role: "user" | "assistant" | "toolResult";
+    content: string;
+    stopReason?: string;
+    usage?: UsageInfo;
+    toolName?: string;
+    isError?: boolean;
+};
+/** message_sending 事件数据 */
+export type MessageSendingEvents = {
+    to: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+};
+/** 事件数据按 hook 类型分组 */
+export type RemoteGuardEventsData = {
+    message_received: MessageReceivedEvents | Record<string, never>;
+    before_prompt_build: BeforePromptBuildEvents | Record<string, never>;
+    llm_input: LlmInputEvents | Record<string, never>;
+    before_tool_call: BeforeToolCallEvents | Record<string, never>;
+    tool_result_persist: ToolResultPersistEvents | Record<string, never>;
+    before_message_write: BeforeMessageWriteEvents | Record<string, never>;
+    message_sending: MessageSendingEvents | Record<string, never>;
+};
+/** 上下文数据 */
+export type RemoteGuardContextData = {
+    agentId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    channelId?: string;
+    runId?: string;
+    workspaceDir?: string;
+    messageProvider?: string;
+    trigger?: string;
+    toolName?: string;
+    toolCallId?: string;
+};
+/** 安全检测数据（Data 字段内容） */
+export type RemoteGuardSecurityCheckData = {
+    hook: RemoteGuardHookType;
+    timestamp: number;
+    events: RemoteGuardEventsData;
+    ctx: RemoteGuardContextData;
+};
+/** 远端安全检测请求体（最外层） */
+export type RemoteGuardRequest = {
+    Type: number;
+    AgentId: string;
+    DeviceId: string;
+    Data: RemoteGuardSecurityCheckData;
+};
+/** 远端安全检测响应体 */
+export type RemoteGuardResponse = {
+    RequestId?: string;
+    /**
+     * 响应动作：
+     * - allow: 放行
+     * - deny: 阻断，停止当前会话
+     * - approval: 需要审批，暂停当前会话等待审批
+     * - redact: 脱敏
+     * - permit: 放行（与 allow 等效，不做任何处理，不记录 incident）
+     * - log: 记录日志后放行（不做任何处理，不记录 incident，正常继续）
+     */
+    Action: "allow" | "deny" | "approval" | "redact" | "permit" | "log";
+    RuleId?: string;
+    Message?: string;
+    RedactedContent?: string;
+};
+/** 远端服务配置 */
+export type RemoteGuardServerConfig = {
+    ip: string;
+    port: number;
+    path: string;
+    corPresignPath?: string;
+    /** skills 上传完成后提交检测任务的接口路径 */
+    detectPath?: string;
+};
+/** WebSocket 配置 */
+export type RemoteGuardWebSocketConfig = {
+    /** WebSocket 端口（默认 8081） */
+    port?: number;
+    /** 连接协议（ws 或 wss，默认 ws） */
+    protocol?: "ws" | "wss";
+};
+/** 远端认证配置 */
+export type RemoteGuardAuthConfig = {
+    key: string;
+};
+/** 远端身份配置 */
+export type RemoteGuardIdentityConfig = {
+    agentId: string;
+};
+/** 遥测上报配置 */
+export type RemoteGuardTelemetryConfig = {
+    /** 是否启用遥测上报 */
+    enabled?: boolean;
+    /** 心跳间隔（毫秒），默认 30000 */
+    heartbeatIntervalMs?: number;
+    /** 数据上报间隔（毫秒），默认 600000（10分钟） */
+    dataReportIntervalMs?: number;
+};
+/** 远端选项配置 */
+export type RemoteGuardOptionsConfig = {
+    timeoutMs: number;
+    /** 同步 hook（before_message_write / tool_result_persist）远端调用超时（毫秒），默认 500 */
+    syncHookTimeoutMs?: number;
+    /** skills 上传产物落盘目录（支持绝对路径或相对 workspace 的路径） */
+    skillsStateDir?: string;
+};
+/** 完整的远端配置 */
+export type RemoteGuardConfig = {
+    enabled: boolean;
+    server: RemoteGuardServerConfig;
+    websocket?: RemoteGuardWebSocketConfig;
+    auth: RemoteGuardAuthConfig;
+    identity: RemoteGuardIdentityConfig;
+    telemetry?: RemoteGuardTelemetryConfig;
+    options: RemoteGuardOptionsConfig;
+};

package/dist/runtime-core/remote-policy-evaluator.d.ts

@@ -0,0 +1,51 @@
+import type { PolicyEvaluator } from "./evaluate-service";
+import type { CompiledShieldRule, ShieldApprovalRequest, ShieldHookModification, ShieldMatch, ShieldPolicyFinding, ShieldPolicyInput, ShieldPolicyResult, ShieldRedaction, ShieldRuleAction, ShieldRunHold, ShieldSeverity, ShieldStage } from "../types";
+/** 远端评估请求体（可直接对接安全服务） */
+export type RemotePolicyRequest = {
+    input: ShieldPolicyInput;
+    stage: ShieldStage;
+};
+/** 远端评估响应体（允许部分字段，骨架会补齐默认值） */
+export type RemotePolicyResponse = Partial<ShieldPolicyResult> & {
+    rawAction?: ShieldRuleAction;
+    effectiveAction?: ShieldRuleAction;
+    severity?: ShieldSeverity;
+    blockReason?: string;
+    redactions?: ShieldRedaction[];
+    redactedTexts?: Record<string, string>;
+    matched?: ShieldMatch[];
+    appliedExceptions?: string[];
+    redactionRules?: CompiledShieldRule[];
+    tags?: string[];
+    durationMs?: number;
+    findings?: ShieldPolicyFinding[];
+    modifications?: ShieldHookModification[];
+    approvalRequest?: ShieldApprovalRequest;
+    runHold?: ShieldRunHold;
+};
+/** 远端调用函数签名：由接入方注入（HTTP/gRPC/SDK 均可） */
+export type RemotePolicyTransport = (request: RemotePolicyRequest) => Promise<RemotePolicyResponse | undefined>;
+/** 远端评估器配置 */
+export type RemotePolicyEvaluatorConfig = {
+    /** 真实对接时由业务方注入远端调用逻辑 */
+    transport?: RemotePolicyTransport;
+    /** 远端失败时是否打印日志（默认 true） */
+    enableWarnLog?: boolean;
+    /** 远端失败时回退动作（默认 allow） */
+    fallbackAction?: ShieldRuleAction;
+};
+/**
+ * 远端策略评估器骨架：
+ * - 未配置 transport 时，默认返回 allow（确保内置 demo 策略不生效）
+ * - 配置 transport 后，可直接对接安全团队远端接口
+ */
+export declare class RemotePolicyEvaluator implements PolicyEvaluator {
+    private readonly transport?;
+    private readonly enableWarnLog;
+    private readonly fallbackAction;
+    constructor(config?: RemotePolicyEvaluatorConfig);
+    evaluate(input: ShieldPolicyInput, stage: ShieldStage): Promise<ShieldPolicyResult>;
+    evaluateSync(_input: ShieldPolicyInput, _stage: ShieldStage): ShieldPolicyResult;
+}
+/** 工厂函数：创建远端策略评估器骨架 */
+export declare const createRemotePolicyEvaluator: (config?: RemotePolicyEvaluatorConfig) => PolicyEvaluator;

package/dist/runtime-core/skill-name-resolver.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Skill 名称解析器
+ * 用于从 SKILL.md 文件路径中识别和提取 skill 名称
+ */
+/** Skill 名称解析结果 */
+export type SkillNameResolveResult = {
+    /** 是否检测到 SKILL.md 读取操作 */
+    isSkillRead: boolean;
+    /** Skill 名称（如果识别到） */
+    skillName: string;
+    /** 解析来源：'frontmatter' 表示从文件内容解析，'path' 表示从路径提取 */
+    source: "frontmatter" | "path" | "none";
+};
+/**
+ * 解析 skill 名称
+ * 优先从 SKILL.md 文件内容的 frontmatter 中解析，解析失败则从路径中提取
+ *
+ * @param toolName 工具名称
+ * @param params 工具参数
+ * @returns 解析结果
+ */
+export declare const resolveSkillName: (toolName: string, params: Record<string, unknown>) => Promise<SkillNameResolveResult>;
+/**
+ * 同步版本：仅从路径提取 skill 名称（不读取文件）
+ * 用于无法执行异步操作的场景
+ *
+ * @param toolName 工具名称
+ * @param params 工具参数
+ * @returns 解析结果
+ */
+export declare const resolveSkillNameSync: (toolName: string, params: Record<string, unknown>) => SkillNameResolveResult;

package/dist/runtime-core/sync-remote-evaluate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 同步远端安全评估模块
+ *
+ * 通过 SharedArrayBuffer + Atomics.wait + Worker 线程实现：
+ * 在同步 hook（before_message_write / tool_result_persist）中
+ * 同步等待远端 HTTP 安全检测结果，根据返回做阻断/脱敏决策。
+ *
+ * 超时后 fallback allow，避免冻结 openclaw 进程。
+ */
+import type { GuardrailDecision, HookEnvelope } from "../contracts";
+import type { RemoteGuardConfig } from "./remote-guard-types";
+/**
+ * 同步执行远端安全检测
+ *
+ * 在同步 hook 中调用，通过 Worker + SharedArrayBuffer + Atomics.wait
+ * 同步等待远端 HTTP 检测结果并返回 GuardrailDecision。
+ *
+ * @param envelope 钩子信封
+ * @param config 远端配置
+ * @returns 护栏决策（超时/错误时返回 fallback allow 决策）
+ */
+export declare const syncRemoteEvaluate: (envelope: HookEnvelope, config: RemoteGuardConfig) => GuardrailDecision;
+/**
+ * 创建绑定了配置的同步远端评估函数
+ *
+ * @param config 远端配置（为 null 时返回 undefined，表示远端不可用）
+ * @returns 同步评估函数，或 undefined（远端不可用）
+ */
+export declare const createSyncRemoteEvaluateFn: (config: RemoteGuardConfig | null | undefined) => ((envelope: HookEnvelope) => GuardrailDecision) | undefined;

package/dist/runtime-core/sync-remote-worker.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Worker 线程脚本：执行同步远端 HTTP 调用
+ *
+ * 通过 SharedArrayBuffer + Atomics 与主线程通信：
+ * - 主线程通过 workerData 传入 SAB 和请求参数
+ * - Worker 异步执行 fetch，将结果写入 SAB
+ * - 完成后 Atomics.notify 通知主线程
+ *
+ * SharedArrayBuffer 布局：
+ *   [0..3]  Int32 — status (0=pending, 1=success, 2=http_error, 3=network_error)
+ *   [4..7]  Int32 — result length in bytes
+ *   [8..]   Uint8Array — result data (response body or error message, UTF-8)
+ */
+export {};

package/dist/runtime-core/sync-remote-worker.js

@@ -0,0 +1,2 @@
+/* @tencent/runtime-guardrail worker - UNLICENSED */
+"use strict";var c=require("worker_threads"),{sab:i,url:m,method:d,headers:l,body:g,timeoutMs:u}=c.workerData,o=new Int32Array(i,0,2),s=new Uint8Array(i,8),a=(t,r)=>{let e=new TextEncoder().encode(r),n=Math.min(e.length,s.length);s.set(e.subarray(0,n)),Atomics.store(o,1,n),Atomics.store(o,0,t),Atomics.notify(o,0)};(async()=>{try{let t=new AbortController,r=setTimeout(()=>t.abort(),u),e=await fetch(m,{method:d,headers:l,body:g,signal:t.signal});clearTimeout(r);let n=await e.text();a(e.ok?1:2,n)}catch(t){let r=t instanceof Error?t.message:String(t);a(3,r)}})();

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

@@ -0,0 +1,94 @@
+/**
+ * 遥测上报后台服务
+ * 实现心跳上报（30秒一次）和数据上报（10分钟一次）
+ * 基于 iwiki 文档：https://iwiki.woa.com/p/4018670075
+ */
+import type { OpenClawApi } from "../contracts";
+import type { MemoryStore } from "./memory-store";
+import type { TelemetryServiceConfig, TelemetryServiceStatus } from "./telemetry-types";
+import type { RemoteGuardConfig } from "./remote-guard-types";
+/** 遥测服务实例 */
+export declare class TelemetryService {
+    private config;
+    private readonly store;
+    private readonly logger?;
+    private ws;
+    private heartbeatInterval;
+    private dataReportInterval;
+    private reconnectTimeout;
+    private authTimeout;
+    private authRetryInterval;
+    private isRunning;
+    private isAuthenticated;
+    private pendingAuthRequestId;
+    private status;
+    /** 已发送但未收到 ACK 的数据上报，key 为 request_id，value 为 incident IDs */
+    private readonly pendingReports;
+    constructor(config: TelemetryServiceConfig, store: MemoryStore, logger?: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    } | undefined);
+    /** 获取当前状态 */
+    getStatus(): TelemetryServiceStatus;
+    /** 启动遥测服务 */
+    start(): Promise<void>;
+    /** 停止遥测服务 */
+    stop(): Promise<void>;
+    /** 使用新配置重新加载遥测服务 */
+    reload(config: TelemetryServiceConfig | undefined): Promise<void>;
+    /** 建立 WebSocket 连接 */
+    private connect;
+    /** 创建 WebSocket 连接 */
+    private createWebSocketConnection;
+    /** WebSocket 连接成功 */
+    private handleOpen;
+    /** 发送认证消息 */
+    private sendAuth;
+    /** 安排认证重试 */
+    private scheduleAuthRetry;
+    /** 停止认证重试 */
+    private stopAuthRetry;
+    /** 启动心跳和数据上报定时器 */
+    private startHeartbeatAndDataReport;
+    /** 认证成功后的处理 */
+    private onAuthenticationSuccess;
+    /** WebSocket 接收消息 */
+    private handleMessage;
+    /** 处理消息数据 */
+    private processMessageData;
+    /** WebSocket 连接关闭 */
+    private handleClose;
+    /** WebSocket 错误 */
+    private handleError;
+    /** 计划重连 */
+    private scheduleReconnect;
+    /** 发送心跳 */
+    private sendHeartbeat;
+    /** 发送数据上报 */
+    private sendDataReport;
+    /** 日志输出 */
+    private log;
+}
+/** 从 RemoteGuardConfig 构建 TelemetryServiceConfig */
+export declare const buildTelemetryConfigFromRemoteGuard: (remoteConfig: RemoteGuardConfig) => TelemetryServiceConfig;
+/** 遥测服务注册选项 */
+export type TelemetryServiceOptions = {
+    /** 是否启用遥测上报 */
+    enabled?: boolean;
+    /** 自定义配置（优先于从 remote-guard-config.json 加载） */
+    config?: Partial<TelemetryServiceConfig>;
+    /** 心跳间隔（毫秒），默认 30000 */
+    heartbeatIntervalMs?: number;
+    /** 数据上报间隔（毫秒），默认 600000 */
+    dataReportIntervalMs?: number;
+    /** 指向用户侧下发的 remote-guard-config.json */
+    remoteGuardConfigPath?: string;
+    /** 直接注入远端配置（优先于 remoteGuardConfigPath） */
+    remoteGuardConfig?: RemoteGuardConfig;
+};
+export declare const resolveTelemetryServiceConfig: (options?: TelemetryServiceOptions) => TelemetryServiceConfig | undefined;
+/**
+ * 注册遥测服务到 OpenClaw 插件
+ */
+export declare const registerTelemetryService: (api: OpenClawApi, store: MemoryStore, options?: TelemetryServiceOptions) => TelemetryService | undefined;

package/dist/runtime-core/telemetry-types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 遥测上报服务类型定义
+ * 基于 iwiki 文档：https://iwiki.woa.com/p/4018670075
+ */
+/** WebSocket 消息基础结构 */
+export type TelemetryMessageBase = {
+    /** 消息类型 */
+    type: "heartbeat" | "data_report" | "config_push" | "device_push" | "error" | "auth" | "auth_ack";
+    /** 请求唯一标识 */
+    request_id: string;
+    /** Unix 时间戳（秒） */
+    timestamp: number;
+    /** 消息体 */
+    payload?: unknown;
+};
+/** WebSocket 发送消息基础结构（客户端 → 服务端，已认证连接无需 api_key） */
+export type TelemetrySendMessageBase = TelemetryMessageBase;
+/** 心跳消息 Payload（客户端 → 服务端） */
+export type HeartbeatPayload = {
+    /** 插件 ID（同时作为 appid 使用） */
+    plugin_id: string;
+    /** 设备唯一标识 */
+    device_id: string;
+    /** Agent 标识（当前使用 deviceId 值） */
+    agent_id?: string;
+    /** 插件版本号 */
+    plugin_version: string;
+    /** 运行状态 */
+    running_status: "healthy" | "warning" | "error" | "offline";
+};
+/** 心跳消息（客户端 → 服务端） */
+export type HeartbeatMessage = TelemetryMessageBase & {
+    type: "heartbeat";
+    payload: HeartbeatPayload;
+};
+/** 心跳发送消息（客户端 → 服务端，已认证连接无需 api_key） */
+export type HeartbeatSendMessage = TelemetrySendMessageBase & {
+    type: "heartbeat";
+    payload: HeartbeatPayload;
+};
+/** 心跳响应 Payload（服务端 → 客户端） */
+export type HeartbeatAckPayload = {
+    server_time: number;
+};
+/** 心跳响应消息 */
+export type HeartbeatAckMessage = TelemetryMessageBase & {
+    type: "heartbeat";
+    payload: HeartbeatAckPayload;
+};
+/** 数据上报 Payload */
+export type DataReportPayload = {
+    /** 插件 ID */
+    plugin_id: string;
+    /** 上报数据类型 */
+    report_type: string;
+    /** 上报数据体 */
+    data: unknown;
+};
+/** 数据上报消息（客户端 → 服务端） */
+export type DataReportMessage = TelemetryMessageBase & {
+    type: "data_report";
+    payload: DataReportPayload;
+};
+/** 数据上报发送消息（客户端 → 服务端，已认证连接无需 api_key） */
+export type DataReportSendMessage = TelemetrySendMessageBase & {
+    type: "data_report";
+    payload: DataReportPayload;
+};
+/** 数据上报响应 Payload */
+export type DataReportAckPayload = {
+    accepted: boolean;
+    message: string;
+};
+/** 数据上报响应消息 */
+export type DataReportAckMessage = TelemetryMessageBase & {
+    type: "data_report";
+    payload: DataReportAckPayload;
+};
+/** 配置推送 Payload（服务端 → 客户端） */
+export type ConfigPushPayload = {
+    config_version: string;
+    config_type: string;
+    config: Record<string, unknown>;
+};
+/** 配置推送消息 */
+export type ConfigPushMessage = TelemetryMessageBase & {
+    type: "config_push";
+    payload: ConfigPushPayload;
+};
+/** 设备推送 Payload */
+export type DevicePushPayload = {
+    message_type: string;
+    data: unknown;
+};
+/** 设备推送消息 */
+export type DevicePushMessage = TelemetryMessageBase & {
+    type: "device_push";
+    payload: DevicePushPayload;
+};
+/** 错误消息 Payload */
+export type ErrorPayload = {
+    message: string;
+};
+/** 错误消息 */
+export type ErrorMessage = TelemetryMessageBase & {
+    type: "error";
+    payload: ErrorPayload;
+};
+/** 认证消息（客户端 → 服务端） */
+export type AuthSendMessage = {
+    type: "auth";
+    request_id: string;
+    timestamp: number;
+    api_key: string;
+};
+/** 认证响应 Payload（服务端 → 客户端） */
+export type AuthAckPayload = {
+    success: boolean;
+    message: string;
+};
+/** 认证响应消息（服务端 → 客户端） */
+export type AuthAckMessage = TelemetryMessageBase & {
+    type: "auth_ack";
+    payload: AuthAckPayload;
+};
+/** 所有消息类型的联合类型 */
+export type TelemetryMessage = HeartbeatMessage | HeartbeatAckMessage | DataReportMessage | DataReportAckMessage | ConfigPushMessage | DevicePushMessage | ErrorMessage | AuthAckMessage;
+/** 遥测服务配置 */
+export type TelemetryServiceConfig = {
+    /** 是否启用遥测上报 */
+    enabled: boolean;
+    /** WebSocket 服务器配置 */
+    websocket: {
+        /** 服务器 IP */
+        ip: string;
+        /** WebSocket 端口（默认 8081） */
+        port: number;
+        /** 连接协议（ws 或 wss） */
+        protocol?: "ws" | "wss";
+    };
+    /** 身份配置 */
+    identity: {
+        agentId: string;
+    };
+    /** 认证配置 */
+    auth: {
+        /** API 密钥 */
+        apiKey: string;
+    };
+    /** 上报间隔配置 */
+    intervals: {
+        /** 心跳间隔（毫秒），默认 30000 */
+        heartbeatMs: number;
+        /** 数据上报间隔（毫秒），默认 600000（10分钟） */
+        dataReportMs: number;
+    };
+    /** 重连配置 */
+    reconnect: {
+        /** 最大重连次数 */
+        maxAttempts: number;
+        /** 基础重连延迟（毫秒） */
+        baseDelayMs: number;
+        /** 最大重连延迟（毫秒） */
+        maxDelayMs: number;
+    };
+};
+/** 遥测服务状态 */
+export type TelemetryServiceStatus = {
+    /** 是否已连接 */
+    connected: boolean;
+    /** 最后心跳时间 */
+    lastHeartbeatAt?: number;
+    /** 最后数据上报时间 */
+    lastDataReportAt?: number;
+    /** 重连次数 */
+    reconnectAttempts: number;
+    /** 最后错误信息 */
+    lastError?: string;
+    /** 服务启动时间 */
+    startedAt?: number;
+};