@carfiedli/runtime-guardrail 0.1.19

package/dist/contracts/host.d.ts

@@ -0,0 +1,239 @@
+import type { ShieldCanonicalHookName } from "./core";
+/** OpenClaw 真实可注册的 hook 名称（当前插件实际依赖的子集） */
+export type OpenClawHookName = "message_received" | "before_prompt_build" | "llm_input" | "before_tool_call" | "message_sending" | "before_message_write" | "tool_result_persist";
+/** 插件钩子事件：收到用户消息时触发 */
+export type PluginHookMessageReceivedEvent = {
+    from: string;
+    content: string;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+};
+/** 插件钩子事件：提示词构建前触发 */
+export type PluginHookBeforePromptBuildEvent = {
+    prompt: string;
+    messages: unknown[];
+};
+/** 插件钩子事件：LLM 输入已组装完成时触发（OpenClaw 真实 hook 名为 llm_input） */
+export type PluginHookLlmInputEvent = {
+    runId: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    systemPrompt?: string;
+    prompt: string;
+    historyMessages: unknown[];
+    imagesCount?: number;
+    skillNames?: string[];
+};
+/** @deprecated 仅保留内部 canonical 语义别名，宿主真实 hook 名为 llm_input */
+export type PluginHookBeforeLlmRequestEvent = PluginHookLlmInputEvent;
+/** 插件钩子事件：执行工具调用前触发 */
+export type PluginHookBeforeToolCallEvent = {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+};
+/** 插件钩子事件：发送消息前触发 */
+export type PluginHookMessageSendingEvent = {
+    to: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+};
+/** 插件钩子事件：写入消息前触发 */
+export type PluginHookBeforeMessageWriteEvent = {
+    message: unknown;
+    sessionKey?: string;
+    agentId?: string;
+};
+/** 插件钩子事件：工具结果持久化前触发 */
+export type PluginHookToolResultPersistEvent = {
+    toolName?: string;
+    toolCallId?: string;
+    message: unknown;
+    isSynthetic?: boolean;
+};
+/** Message 类 hook 上下文 */
+export type PluginHookMessageContext = {
+    channelId?: string;
+    accountId?: string;
+    conversationId?: string;
+};
+/** Agent 类 hook 上下文 */
+export type PluginHookAgentContext = {
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    workspaceDir?: string;
+    messageProvider?: string;
+    trigger?: string;
+    channelId?: string;
+};
+/** Tool 类 hook 上下文 */
+export type PluginHookToolContext = {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    toolName?: string;
+    toolCallId?: string;
+};
+/** 工具结果持久化 hook 上下文 */
+export type PluginHookToolResultPersistContext = {
+    agentId?: string;
+    sessionKey?: string;
+    toolName?: string;
+    toolCallId?: string;
+};
+/** 钩子名称到对应事件类型的映射表 */
+export type PluginHookEventMap = {
+    message_received: PluginHookMessageReceivedEvent;
+    before_prompt_build: PluginHookBeforePromptBuildEvent;
+    llm_input: PluginHookLlmInputEvent;
+    before_tool_call: PluginHookBeforeToolCallEvent;
+    message_sending: PluginHookMessageSendingEvent;
+    before_message_write: PluginHookBeforeMessageWriteEvent;
+    tool_result_persist: PluginHookToolResultPersistEvent;
+};
+/** 钩子名称到上下文类型的映射表 */
+export type PluginHookContextMap = {
+    message_received: PluginHookMessageContext;
+    before_prompt_build: PluginHookAgentContext;
+    llm_input: PluginHookAgentContext;
+    before_tool_call: PluginHookToolContext;
+    message_sending: PluginHookMessageContext;
+    before_message_write: {
+        agentId?: string;
+        sessionKey?: string;
+    };
+    tool_result_persist: PluginHookToolResultPersistContext;
+};
+/** 钩子名称到返回值类型的映射表 */
+export type PluginHookResultMap = {
+    message_received: void;
+    before_prompt_build: {
+        systemPrompt?: string;
+        prependContext?: string;
+        prependSystemContext?: string;
+        appendSystemContext?: string;
+    } | void;
+    llm_input: void;
+    before_tool_call: {
+        params?: Record<string, unknown>;
+        block?: boolean;
+        blockReason?: string;
+    } | void;
+    message_sending: {
+        content?: string;
+        cancel?: boolean;
+    } | void;
+    before_message_write: {
+        block?: boolean;
+        message?: unknown;
+    } | void;
+    tool_result_persist: {
+        message?: unknown;
+    } | void;
+};
+type SyncHookName = "before_message_write" | "tool_result_persist";
+/** 插件钩子处理器：接收钩子事件和上下文，返回宿主能理解的结果 */
+export type PluginHookHandler<H extends OpenClawHookName> = (event: PluginHookEventMap[H], ctx: PluginHookContextMap[H]) => H extends SyncHookName ? PluginHookResultMap[H] : PluginHookResultMap[H] | Promise<PluginHookResultMap[H]>;
+/** 网关请求处理器选项（兼容旧/新 OpenClaw 形态） */
+export type GatewayRequestHandlerOptions = {
+    eventName?: string;
+    data?: unknown;
+    params?: unknown;
+    respond?: (ok: boolean, payload: unknown) => void;
+};
+/** CLI 上下文：命令行命令执行时的上下文信息（旧签名） */
+export type CliContext = {
+    projectPath: string;
+    api: unknown;
+};
+/** CLI 命令处理器：接收参数和上下文，执行命令逻辑（旧签名） */
+export type CliCommandHandler = (args: Record<string, unknown>, context: CliContext) => unknown | Promise<unknown>;
+/** OpenClaw 新版 CLI 注册器上下文 */
+export type OpenClawCliRegistrarContext = {
+    program: unknown;
+    config: unknown;
+    workspaceDir?: string;
+    logger?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+};
+/** 宿主钩子注册表：提供注册钩子、网关方法和 CLI 命令的接口 */
+export type HostHookRegistry = {
+    /** 注册指定钩子名称的处理器 */
+    on<H extends OpenClawHookName>(hookName: H, handler: PluginHookHandler<H>): void;
+    /** 注册网关方法（RPC 风格的远程调用） */
+    registerGatewayMethod(method: string, handler: (options: GatewayRequestHandlerOptions) => Promise<void> | void): void;
+    /** 注册 CLI（兼容旧签名与 OpenClaw 新签名） */
+    registerCli(nameOrRegistrar: string | ((ctx: OpenClawCliRegistrarContext) => void | Promise<void>), handlerOrOptions?: CliCommandHandler | {
+        commands?: string[];
+    }): void;
+};
+export type OpenClawPluginServiceContext = {
+    config?: {
+        skills?: {
+            load?: {
+                extraDirs?: string[];
+            };
+        };
+    };
+    workspaceDir?: string;
+    stateDir: string;
+    logger: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+};
+export type OpenClawPluginService = {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+};
+/** OpenClaw 宿主 API：兼容 log/logger 两种日志能力 */
+export type OpenClawApi = HostHookRegistry & {
+    config?: {
+        skills?: {
+            load?: {
+                extraDirs?: string[];
+            };
+        };
+    };
+    runtime?: {
+        config?: {
+            loadConfig?: () => unknown | Promise<unknown>;
+            writeConfigFile?: (config: unknown) => void | Promise<void>;
+        };
+        system?: {
+            requestHeartbeatNow?: (opts?: {
+                reason?: string;
+                coalesceMs?: number;
+                sessionKey?: string;
+            }) => void;
+        };
+    };
+    resolvePath?: (input: string) => string;
+    registerService?: (service: OpenClawPluginService) => void;
+    log?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+    logger?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+};
+/** internal canonical hook 到 OpenClaw 宿主 hook 的语义映射说明 */
+export type CanonicalToHostHookMap = Partial<Record<ShieldCanonicalHookName, OpenClawHookName | OpenClawHookName[]>>;
+export {};

package/dist/contracts/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./core";
+export * from "./host";
+export * from "./operator";
+export * from "./events";
+export { SHIELD_RPC_METHODS, SHIELD_CLI_COMMANDS } from "./operator";
+export { SHIELD_GATEWAY_EVENTS } from "./events";

package/dist/contracts/operator.d.ts

@@ -0,0 +1,110 @@
+/** 护盾 RPC 方法常量：定义所有可通过网关调用的远程方法名 */
+export declare const SHIELD_RPC_METHODS: {
+    readonly status: "shield.status";
+    readonly releaseInfo: "shield.release.info";
+    readonly rulePacksList: "shield.rulepacks.list";
+    readonly policyValidate: "shield.policy.validate";
+    readonly policyTest: "shield.policy.test";
+    readonly metrics: "shield.metrics";
+    readonly rolloutSummary: "shield.rollout.summary";
+    readonly reportGenerate: "shield.report.generate";
+    readonly reportGet: "shield.report.get";
+    readonly incidentList: "shield.incident.list";
+    readonly incidentGet: "shield.incident.get";
+    readonly incidentResolve: "shield.incident.resolve";
+    readonly approvalList: "shield.approval.list";
+    readonly approvalResolve: "shield.approval.resolve";
+    readonly runHoldList: "shield.runhold.list";
+    readonly runHoldResume: "shield.runhold.resume";
+    readonly runHoldCancel: "shield.runhold.cancel";
+    readonly configRefresh: "shield.config.refresh";
+};
+/** 护盾 CLI 命令常量：定义所有可用的命令行命令名 */
+export declare const SHIELD_CLI_COMMANDS: {
+    readonly status: "shield-status";
+    readonly validate: "shield-validate";
+    readonly report: "shield-report";
+    readonly incidents: "shield-incidents";
+    readonly approvals: "shield-approvals";
+    readonly runHolds: "shield-runholds";
+    readonly configRefresh: "shield-config-refresh";
+};
+/** RPC 请求格式 */
+export type RpcRequest = {
+    method: string;
+    params?: Record<string, unknown>;
+};
+/** RPC 响应格式 */
+export type RpcResponse<T = unknown> = {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+/** 状态查询结果 */
+export type StatusQueryResult = {
+    version: string;
+    config: Record<string, unknown>;
+    stats: {
+        incidents: number;
+        approvals: number;
+        runHolds: number;
+    };
+};
+/** 安全事件列表查询参数 */
+export type IncidentListQuery = {
+    agentId?: string;
+    runId?: string;
+    status?: string[];
+    limit?: number;
+    offset?: number;
+};
+/** 安全事件列表查询结果 */
+export type IncidentListResult = {
+    total: number;
+    items: Array<Record<string, unknown>>;
+};
+/** 审批列表查询参数 */
+export type ApprovalListQuery = {
+    status?: string[];
+    category?: string[];
+    limit?: number;
+    offset?: number;
+};
+/** 审批列表查询结果 */
+export type ApprovalListResult = {
+    total: number;
+    items: Array<Record<string, unknown>>;
+};
+/** 运行暂停列表查询参数 */
+export type RunHoldListQuery = {
+    agentId?: string;
+    status?: string[];
+    limit?: number;
+    offset?: number;
+};
+/** 运行暂停列表查询结果 */
+export type RunHoldListResult = {
+    total: number;
+    items: Array<Record<string, unknown>>;
+};
+/** 解决审批命令 */
+export type ResolveApprovalCommand = {
+    approvalId: string;
+    decision: "approved" | "rejected";
+    resolvedBy?: string;
+    note?: string;
+    source?: string;
+    externalApprovalId?: string;
+};
+/** 恢复运行暂停命令 */
+export type ResumeRunHoldCommand = {
+    holdId: string;
+};
+/** 取消运行暂停命令 */
+export type CancelRunHoldCommand = {
+    holdId: string;
+};

package/dist/execution/egress-mediator.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutionPlan, HookEnvelope } from "../contracts";
+export interface EgressMediator {
+    apply(plan: ExecutionPlan, envelope: HookEnvelope): Promise<ExecutionPlan>;
+}
+export declare class DefaultEgressMediator implements EgressMediator {
+    apply(plan: ExecutionPlan, envelope: HookEnvelope): Promise<ExecutionPlan>;
+}

package/dist/execution/execution-broker.d.ts

@@ -0,0 +1,13 @@
+import type { ExecutionPlan, GuardrailDecision, HookEnvelope } from "../contracts";
+import type { ApprovalService, RunHoldService } from "../approval";
+import type { ExecutionPlanBuilder } from "./execution-plan-builder";
+export interface ExecutionBroker {
+    prepare(envelope: HookEnvelope, decision: GuardrailDecision): Promise<ExecutionPlan | undefined>;
+}
+export declare class DefaultExecutionBroker implements ExecutionBroker {
+    private readonly planBuilder;
+    private readonly approvalService;
+    private readonly runHoldService;
+    constructor(planBuilder: ExecutionPlanBuilder, approvalService: ApprovalService, runHoldService: RunHoldService);
+    prepare(envelope: HookEnvelope, decision: GuardrailDecision): Promise<ExecutionPlan | undefined>;
+}

package/dist/execution/execution-plan-builder.d.ts

@@ -0,0 +1,12 @@
+import type { ExecutionPlan, GuardrailDecision, HookEnvelope } from "../contracts";
+import type { ModelGovernanceService } from "./model-governance-service";
+import type { EgressMediator } from "./egress-mediator";
+export interface ExecutionPlanBuilder {
+    build(envelope: HookEnvelope, decision: GuardrailDecision): Promise<ExecutionPlan | undefined>;
+}
+export declare class DefaultExecutionPlanBuilder implements ExecutionPlanBuilder {
+    private readonly modelGovernanceService;
+    private readonly egressMediator;
+    constructor(modelGovernanceService: ModelGovernanceService, egressMediator: EgressMediator);
+    build(envelope: HookEnvelope, decision: GuardrailDecision): Promise<ExecutionPlan | undefined>;
+}

package/dist/execution/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./model-governance-service";
+export * from "./egress-mediator";
+export * from "./execution-plan-builder";
+export * from "./execution-broker";

package/dist/execution/model-governance-service.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutionPlan, GuardrailDecision, HookEnvelope } from "../contracts";
+export interface ModelGovernanceService {
+    apply(plan: ExecutionPlan, envelope: HookEnvelope, decision: GuardrailDecision): Promise<ExecutionPlan>;
+}
+export declare class DefaultModelGovernanceService implements ModelGovernanceService {
+    apply(plan: ExecutionPlan, envelope: HookEnvelope, decision: GuardrailDecision): Promise<ExecutionPlan>;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import type { OpenClawApi } from "./contracts";
+import { PluginRuntime, type PluginRuntimeOptions } from "./openclaw/plugin-runtime";
+/**
+ * 创建运行时护栏插件的工厂函数（整个库的主入口）
+ * 接收宿主平台 API 和可选配置，实例化并初始化插件运行时后返回
+ * @param api - 宿主平台（OpenClaw）提供的 API 接口，用于注册钩子、日志等
+ * @param options - 可选的运行时配置，包括策略评估器、审计日志器、阶段/模式配置等
+ * @returns 初始化完成的 PluginRuntime 实例
+ */
+export declare const createRuntimeGuardrailPlugin: (api: OpenClawApi, options?: PluginRuntimeOptions) => Promise<PluginRuntime>;
+/**
+ * OpenClaw 插件入口（官方插件加载器优先识别 register/activate 导出）
+ */
+export declare const register: (api: OpenClawApi) => void;
+/** OpenClaw 插件入口别名 */
+export declare const activate: (api: OpenClawApi) => void;
+export default register;
+export * from "./types";
+export * from "./contracts";
+export * from "./adapters";
+export * from "./runtime-core";
+export * from "./compat";
+export * from "./policy";
+export * from "./approval";
+export * from "./execution";
+export * from "./audit";
+export * from "./operator";
+export * from "./bootstrap";
+export * from "./openclaw";