@gfrmin/credence-pi-openclaw 0.1.0

package/dist/index.js

@@ -0,0 +1,258 @@
+// index.ts — credence-pi OpenClaw-plugin body.
+//
+// Governs the pi/OpenClaw agent loop by intercepting tool calls and
+// routing the decision to the credence-pi Julia daemon (the opaque
+// brain). Reuses credence-pi's async wire UNCHANGED: POST /sensor (a
+// tool-proposed sensor event) then await the correlated effector signal
+// off the SSE /signals stream; map it to OpenClaw's before_tool_call
+// result. Also logs tool outcomes and reconstructed per-turn cost so the
+// observation log accumulates the data the dollars-saved surface (Move 2)
+// needs.
+//
+// Discipline (matches the pi-extension body):
+//   - The BRAIN decides; the body only translates. ask -> requireApproval
+//     (OpenClaw enforces the user's choice natively); the body posts
+//     user-responded via onResolution so the brain learns, but does not
+//     itself decide proceed/block on the reply.
+//   - Fail-open everywhere: daemon unreachable / slow ⇒ the tool proceeds,
+//     with one warning per outage.
+//
+// The orchestration lives in `createGovernor`, separated from `register`
+// so it can be unit-tested with an injected DaemonClient (see
+// tests/index.test.ts).
+import { randomUUID } from "node:crypto";
+import { createDaemonClient, } from "./daemon-client.js";
+import { FeatureTracker } from "./features.js";
+import { buildPriceTable, computeTurnCost } from "./cost.js";
+const DEFAULT_DAEMON_URL = "http://127.0.0.1:8787";
+const DEFAULT_HOOK_TIMEOUT_MS = 3_000;
+// How long OpenClaw waits for the human on an `ask` (requireApproval).
+// Distinct from the daemon-decision timeout above.
+const DEFAULT_APPROVAL_TIMEOUT_MS = 120_000;
+function newEventId() {
+    return `evt_${randomUUID().slice(0, 12)}`;
+}
+export function mapSignal(sig, originatingEventId, client, approvalTimeoutMs) {
+    if (!sig)
+        return undefined; // timeout / fail-open ⇒ proceed
+    const p = sig.parameters ?? {};
+    switch (sig.effector) {
+        case "proceed":
+            return undefined;
+        case "block":
+            return {
+                block: true,
+                blockReason: `credence-pi: ${typeof p.reason === "string"
+                    ? p.reason
+                    : "tool call vetoed by expected-utility calculation"}`,
+            };
+        case "ask": {
+            const description = typeof p.text === "string" ? p.text : "Confirm this tool call?";
+            const requireApproval = {
+                title: "credence-pi governance",
+                description,
+                severity: "warning",
+                timeoutMs: approvalTimeoutMs,
+                timeoutBehavior: "deny",
+                allowedDecisions: ["allow-once", "allow-always", "deny"],
+                onResolution: async (decision) => {
+                    const response = decision === "allow-once" || decision === "allow-always"
+                        ? "yes"
+                        : decision === "deny"
+                            ? "no"
+                            : "timeout";
+                    // Fire-and-forget: the brain conditions on the reply; OpenClaw
+                    // has already enforced the decision. The daemon's follow-up
+                    // proceed/block signal is unneeded here and harmlessly dropped
+                    // (no awaiter).
+                    await client.postSensor({
+                        event_type: "user-responded",
+                        event_id: newEventId(),
+                        in_response_to: originatingEventId,
+                        timestamp: new Date().toISOString(),
+                        response,
+                    });
+                },
+            };
+            return { requireApproval };
+        }
+        default:
+            return undefined; // unknown effector ⇒ fail open
+    }
+}
+// The governance orchestration over an injected DaemonClient. register()
+// wires this to the OpenClaw hook API; tests drive it with a fake client.
+export function createGovernor(client, opts) {
+    const { hookTimeoutMs, approvalTimeoutMs, priceTable, redactToolInputs, log } = opts;
+    const tracker = new FeatureTracker();
+    // event_id -> resolver for the awaited effector signal. The single SSE
+    // consumer dispatches signals here by in_response_to. Unmatched signals
+    // (e.g. an ask-followup after the hook already resolved) find no resolver
+    // and are dropped.
+    const awaiters = new Map();
+    const sse = client.connectSignalsStream((sig) => {
+        const resolve = awaiters.get(sig.in_response_to);
+        if (resolve)
+            resolve(sig);
+    });
+    let warnedDown = false;
+    let announcedUp = false;
+    let down = false;
+    async function beforeToolCall(event, ctx) {
+        const eventId = newEventId();
+        const signalPromise = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                awaiters.delete(eventId);
+                resolve(undefined);
+            }, hookTimeoutMs);
+            awaiters.set(eventId, (sig) => {
+                clearTimeout(timer);
+                awaiters.delete(eventId);
+                resolve(sig);
+            });
+        });
+        const features = tracker.extractAndRecord(event, ctx);
+        const post = await client.postSensor({
+            event_type: "tool-proposed",
+            event_id: eventId,
+            session_id: ctx.sessionId ?? ctx.sessionKey ?? "",
+            timestamp: new Date().toISOString(),
+            features,
+            // Tool inputs can carry secrets (commands, tokens). Operators may
+            // redact them; the brain does not condition on input (Move 1), only
+            // the daemon's ask-text preview uses it.
+            proposed_call: {
+                tool_name: event.toolName,
+                input: redactToolInputs ? null : event.params,
+            },
+        });
+        if (!post.ok) {
+            const r = awaiters.get(eventId);
+            if (r)
+                r(undefined); // clean up timer + awaiter
+            if (!warnedDown) {
+                log(`credence-pi: daemon unreachable at the configured URL; proceeding without governance`);
+                warnedDown = true;
+            }
+            down = true;
+            announcedUp = false;
+            return undefined; // fail open
+        }
+        if (down && !announcedUp) {
+            log("credence-pi: daemon reachable again; governance resumed");
+            announcedUp = true;
+            down = false;
+            warnedDown = false; // re-arm the unreachable warning for the next outage
+        }
+        const sig = await signalPromise;
+        return mapSignal(sig, eventId, client, approvalTimeoutMs);
+    }
+    async function afterToolCall(event, _ctx) {
+        // Correlate by the stable toolCallId (tools run in parallel).
+        await client.postSensor({
+            event_type: "tool-completed",
+            event_id: newEventId(),
+            in_response_to: event.toolCallId ?? "",
+            timestamp: new Date().toISOString(),
+            outcome: {
+                success: event.error == null,
+                duration_ms: event.durationMs ?? null,
+                result_summary: null,
+                error: event.error ?? null,
+            },
+        });
+    }
+    async function llmOutput(event, ctx) {
+        const tc = computeTurnCost(event, priceTable);
+        await client.postSensor({
+            event_type: "turn-cost",
+            event_id: newEventId(),
+            session_id: ctx.sessionId ?? event.sessionId ?? "",
+            timestamp: new Date().toISOString(),
+            usd: tc.usd,
+            total_tokens: tc.total_tokens,
+            input_tokens: tc.input_tokens,
+            output_tokens: tc.output_tokens,
+            cache_read: tc.cache_read,
+            cache_write: tc.cache_write,
+            model: tc.model,
+        });
+    }
+    function cleanup() {
+        sse.close();
+        for (const resolve of awaiters.values())
+            resolve(undefined);
+        awaiters.clear();
+    }
+    return {
+        beforeToolCall,
+        afterToolCall,
+        llmOutput,
+        cleanup,
+        pendingCount: () => awaiters.size,
+    };
+}
+const plugin = {
+    id: "credence-pi",
+    name: "credence-pi governance",
+    description: "Bayesian in-loop governance for the pi/OpenClaw agent — intercepts tool calls (allow/block/ask) via the credence-pi brain and logs outcomes + per-turn cost.",
+    register(api) {
+        const cfg = api.pluginConfig ?? {};
+        const daemonUrl = typeof cfg.daemonUrl === "string" ? cfg.daemonUrl : DEFAULT_DAEMON_URL;
+        const hookTimeoutMs = typeof cfg.hookTimeoutMs === "number"
+            ? cfg.hookTimeoutMs
+            : DEFAULT_HOOK_TIMEOUT_MS;
+        const approvalTimeoutMs = typeof cfg.approvalTimeoutMs === "number"
+            ? cfg.approvalTimeoutMs
+            : DEFAULT_APPROVAL_TIMEOUT_MS;
+        const silent = cfg.silent === true;
+        const redactToolInputs = cfg.redactToolInputs === true;
+        const priceTable = buildPriceTable(cfg.pricing);
+        const log = (m, e) => {
+            if (silent)
+                return;
+            const msg = e === undefined ? m : `${m} ${String(e)}`;
+            api.logger?.warn?.(msg);
+        };
+        const client = createDaemonClient({
+            baseUrl: daemonUrl,
+            timeoutMs: hookTimeoutMs,
+            logger: log,
+        });
+        const gov = createGovernor(client, {
+            hookTimeoutMs,
+            approvalTimeoutMs,
+            priceTable,
+            redactToolInputs,
+            log,
+        });
+        api.on("before_tool_call", gov.beforeToolCall, {
+            priority: 100,
+            timeoutMs: hookTimeoutMs + 1_000,
+        });
+        api.on("after_tool_call", gov.afterToolCall);
+        // Per-turn cost REQUIRES plugins.entries.credence-pi.hooks
+        // .allowConversationAccess: true. Wrapped so a blocked registration
+        // never breaks governance — cost is just absent.
+        try {
+            api.on("llm_output", gov.llmOutput);
+        }
+        catch (err) {
+            log("credence-pi: llm_output hook unavailable (set hooks.allowConversationAccess:true for the cost signal)", err);
+        }
+        // Close the SSE stream + drain awaiters on reset/delete/reload so a
+        // hot-reload does not accumulate daemon connections. Optional-chained
+        // for hosts predating the lifecycle API.
+        try {
+            api.lifecycle?.registerRuntimeLifecycle?.({
+                id: "credence-pi-governor",
+                description: "Close the credence-pi daemon SSE stream and drain pending tool-call awaiters.",
+                cleanup: () => gov.cleanup(),
+            });
+        }
+        catch (err) {
+            log("credence-pi: could not register lifecycle cleanup", err);
+        }
+    },
+};
+export default plugin;

package/dist/openclaw-types.d.ts

@@ -0,0 +1,96 @@
+export type PluginApprovalResolution = "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled";
+export interface RequireApprovalPayload {
+    title: string;
+    description: string;
+    severity?: "info" | "warning" | "critical";
+    timeoutMs?: number;
+    timeoutBehavior?: "allow" | "deny";
+    allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
+    pluginId?: string;
+    onResolution?: (decision: PluginApprovalResolution) => Promise<void> | void;
+}
+export interface BeforeToolCallEvent {
+    toolName: string;
+    params: Record<string, unknown>;
+    toolKind?: string;
+    toolInputKind?: string;
+    runId?: string;
+    toolCallId?: string;
+    derivedPaths?: readonly string[];
+}
+export interface BeforeToolCallResult {
+    params?: Record<string, unknown>;
+    block?: boolean;
+    blockReason?: string;
+    requireApproval?: RequireApprovalPayload;
+}
+export interface AfterToolCallEvent {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+}
+export interface LlmUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+}
+export interface LlmOutputEvent {
+    runId?: string;
+    sessionId?: string;
+    provider?: string;
+    model?: string;
+    resolvedRef?: string;
+    usage?: LlmUsage;
+}
+export interface ToolContext {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    toolName?: string;
+    toolCallId?: string;
+    channelId?: string;
+    workspaceDir?: string;
+}
+export interface PluginLogger {
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
+}
+export type HookHandler<E, R = void> = (event: E, ctx: ToolContext) => Promise<R | void> | R | void;
+export interface HookOpts {
+    priority?: number;
+    timeoutMs?: number;
+}
+export interface OpenClawPluginApi {
+    id?: string;
+    logger?: PluginLogger;
+    pluginConfig?: Record<string, unknown>;
+    lifecycle?: {
+        registerRuntimeLifecycle: (registration: {
+            id: string;
+            description?: string;
+            cleanup?: (ctx: {
+                reason?: string;
+                sessionKey?: string;
+                runId?: string;
+            }) => void | Promise<void>;
+        }) => void;
+    };
+    on(hook: "before_tool_call", handler: HookHandler<BeforeToolCallEvent, BeforeToolCallResult>, opts?: HookOpts): void;
+    on(hook: "after_tool_call", handler: HookHandler<AfterToolCallEvent, void>, opts?: HookOpts): void;
+    on(hook: "llm_output", handler: HookHandler<LlmOutputEvent, void>, opts?: HookOpts): void;
+    on(hook: string, handler: (...args: unknown[]) => unknown, opts?: HookOpts): void;
+}
+export interface PluginEntry {
+    id: string;
+    name: string;
+    description?: string;
+    register: (api: OpenClawPluginApi) => void | Promise<void>;
+}

package/dist/openclaw-types.js

@@ -0,0 +1,15 @@
+// openclaw-types.ts — minimal local declarations of the OpenClaw plugin
+// API surface this body consumes.
+//
+// Sourced from OpenClaw (HEAD 36a596aa9f, 2026-06-02):
+//   - src/plugins/types.ts          (OpenClawPluginApi, api.on)
+//   - src/plugins/hook-types.ts     (before_tool_call / after_tool_call /
+//                                     llm_output events + results)
+//
+// We declare ONLY what we consume so the plugin builds standalone with no
+// @openclaw/openclaw dependency — mirroring the dependency-free pattern of
+// apps/openclaw-plugin/ (which used `api: any`). At runtime OpenClaw calls
+// register(api) with the real, fully-typed api; these declarations are our
+// compile-time view. If the host surface drifts, the runtime still works;
+// only this file needs occasional resync. Keep it narrow.
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,45 @@
+{
+  "id": "credence-pi",
+  "version": "0.1.0",
+  "name": "credence-pi governance",
+  "description": "Bayesian in-loop governance for the pi/OpenClaw agent — intercepts tool calls and halts/asks on low expected-value spend; logs outcomes and per-turn cost for the dollars-saved surface.",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "daemonUrl": {
+        "type": "string",
+        "description": "Base URL of the credence-pi Julia daemon (POST /sensor, GET /signals).",
+        "default": "http://127.0.0.1:8787"
+      },
+      "hookTimeoutMs": {
+        "type": "number",
+        "description": "Max time to await the daemon's decision before failing open (proceeding without governance).",
+        "default": 3000
+      },
+      "approvalTimeoutMs": {
+        "type": "number",
+        "description": "How long OpenClaw waits for the user on an `ask` (requireApproval) before applying timeoutBehavior=deny.",
+        "default": 120000
+      },
+      "redactToolInputs": {
+        "type": "boolean",
+        "description": "Omit tool-call inputs from sensor events sent to the daemon (they can carry secrets/commands). Governance still works; the ask-dialog preview becomes generic.",
+        "default": false
+      },
+      "silent": {
+        "type": "boolean",
+        "description": "Suppress info/warn logging.",
+        "default": false
+      },
+      "pricing": {
+        "type": "object",
+        "description": "Optional per-model USD price overrides in $/million tokens: { \"<model-id>\": { \"input\": <num>, \"output\": <num>, \"cacheRead\": <num>, \"cacheWrite\": <num> } }. Merged over the built-in table.",
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@gfrmin/credence-pi-openclaw",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "credence-pi body: OpenClaw plugin that governs tool calls via the credence-pi Bayesian brain (before_tool_call -> allow/block/ask) and logs outcomes + per-turn cost.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "AGPL-3.0-or-later",
+  "author": "Guy Freeman",
+  "homepage": "https://github.com/gfrmin/credence/tree/master/apps/credence-pi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gfrmin/credence.git",
+    "directory": "apps/credence-pi/openclaw-plugin"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "ai-agent",
+    "governance",
+    "bayesian",
+    "tool-call",
+    "llm-cost",
+    "expected-utility"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": ["./src/index.ts"],
+    "runtimeExtensions": ["./dist/index.js"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.6.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/cost.ts

@@ -0,0 +1,130 @@
+// cost.ts — reconstruct per-turn USD from llm_output token counts.
+//
+// OpenClaw does not hand plugins a dollar figure (only token counts +
+// model id on llm_output). The host computes USD internally via
+// calculateCost(model, usage), but does not expose it to plugins, and we
+// stay dependency-free (no `openclaw` runtime import). So we reconstruct
+// USD from a small, CONFIG-OVERRIDABLE price table (USD per million
+// tokens). The built-in numbers are approximate defaults — the operator
+// should verify/override via the plugin's `pricing` config for an exact
+// dollars-saved figure. When a model can't be priced, usd is null and the
+// Move-2 surface falls back to token counts.
+
+import type { LlmOutputEvent } from "./openclaw-types.js";
+
+export interface ModelPrice {
+  input: number; // USD / million input tokens
+  output: number; // USD / million output tokens
+  cacheRead?: number; // USD / million cache-read tokens
+  cacheWrite?: number; // USD / million cache-write tokens
+}
+
+export type PriceTable = Record<string, ModelPrice>;
+
+// Built-in defaults, keyed by a lowercase family substring matched against
+// the model id. Approximate; override via config `pricing`. Ordered by
+// specificity is not required — we pick the longest matching key.
+export const DEFAULT_PRICES: PriceTable = {
+  "claude-opus": { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+  "claude-sonnet": { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+  "claude-haiku": { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4o": { input: 2.5, output: 10 },
+  "gpt-4.1": { input: 2, output: 8 },
+  "o3": { input: 2, output: 8 },
+  "gemini-2.5-pro": { input: 1.25, output: 10 },
+  "gemini-2.5-flash": { input: 0.3, output: 2.5 },
+};
+
+export interface TurnCost {
+  usd: number | null;
+  total_tokens: number | null;
+  input_tokens: number | null;
+  output_tokens: number | null;
+  cache_read: number | null;
+  cache_write: number | null;
+  model: string | null;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function resolvePrice(
+  model: string | undefined,
+  table: PriceTable,
+): ModelPrice | undefined {
+  if (!model) return undefined;
+  const m = model.toLowerCase();
+  // Exact match first.
+  if (table[m]) return table[m];
+  // Longest key that appears as a SEGMENT of the id — anchored at the
+  // start or after a non-alphanumeric separator. So "o3" matches
+  // "o3-mini" and "openai/o3" but NOT "foo3"; longest match wins.
+  let best: { key: string; price: ModelPrice } | undefined;
+  for (const [key, price] of Object.entries(table)) {
+    const re = new RegExp(`(^|[^a-z0-9])${escapeRegExp(key)}`);
+    if (re.test(m) && (best === undefined || key.length > best.key.length)) {
+      best = { key, price };
+    }
+  }
+  return best?.price;
+}
+
+/** Merge operator `pricing` config over the built-in table. */
+export function buildPriceTable(overrides: unknown): PriceTable {
+  const table: PriceTable = { ...DEFAULT_PRICES };
+  if (overrides && typeof overrides === "object") {
+    for (const [k, v] of Object.entries(overrides as Record<string, unknown>)) {
+      if (v && typeof v === "object") {
+        const o = v as Record<string, unknown>;
+        const input = typeof o.input === "number" ? o.input : undefined;
+        const output = typeof o.output === "number" ? o.output : undefined;
+        if (input !== undefined && output !== undefined) {
+          table[k.toLowerCase()] = {
+            input,
+            output,
+            cacheRead: typeof o.cacheRead === "number" ? o.cacheRead : undefined,
+            cacheWrite:
+              typeof o.cacheWrite === "number" ? o.cacheWrite : undefined,
+          };
+        }
+      }
+    }
+  }
+  return table;
+}
+
+export function computeTurnCost(
+  event: LlmOutputEvent,
+  table: PriceTable,
+): TurnCost {
+  const u = event.usage ?? {};
+  const input = u.input ?? 0;
+  const output = u.output ?? 0;
+  const cacheRead = u.cacheRead ?? 0;
+  const cacheWrite = u.cacheWrite ?? 0;
+  const total = u.total ?? input + output + cacheRead + cacheWrite;
+  const model = event.model ?? null;
+
+  const price = resolvePrice(event.model, table);
+  let usd: number | null = null;
+  if (price) {
+    usd =
+      (input * price.input +
+        output * price.output +
+        cacheRead * (price.cacheRead ?? price.input) +
+        cacheWrite * (price.cacheWrite ?? price.input)) /
+      1_000_000;
+  }
+
+  return {
+    usd,
+    total_tokens: total,
+    input_tokens: input,
+    output_tokens: output,
+    cache_read: cacheRead,
+    cache_write: cacheWrite,
+    model,
+  };
+}