@gfrmin/credence-pi-openclaw 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# credence-pi — OpenClaw plugin body
+
+The **body** that lets the credence-pi Bayesian brain govern a real
+pi/OpenClaw agent. It registers an OpenClaw `before_tool_call` hook,
+forwards each proposed tool call to the credence-pi daemon (the opaque
+brain), and maps the brain's decision back to OpenClaw:
+
+| brain effector | OpenClaw result |
+|---|---|
+| `proceed` | allow |
+| `block`   | `{ block: true, blockReason }` |
+| `ask`     | `{ requireApproval }` — OpenClaw's native approval dialog; the user's choice is posted back so the brain learns |
+
+It also logs tool **outcomes** (`after_tool_call`) and reconstructs
+**per-turn cost** (`llm_output` token counts × a price table) so the
+observation log accumulates the data the dollars-saved surface needs.
+
+**Fail-open:** if the daemon is unreachable or slow, the tool proceeds
+(one warning per outage). Governance never blocks the agent on
+infrastructure failure.
+
+This is one of two bodies over the same brain; the other,
+`apps/credence-pi/extension/`, targets the pi coding agent directly.
+Brain + wire (POST `/sensor`, SSE `/signals`) are shared and unchanged.
+
+## Why a plugin (not a pi extension)
+
+Current OpenClaw vendors pi's coding-agent and runs its gateway agent with
+`noExtensions: true`, so a pi `ExtensionFactory` never loads. The supported
+interception point is an OpenClaw **plugin** `before_tool_call` hook. See
+`docs/credence-pi-pass-2/move-1-design.md`.
+
+## Install (operator)
+
+1. Start the brain daemon — it listens on `http://127.0.0.1:8787`. Either run
+   the published image
+   (`docker run -p 8787:8787 -v ~/.credence-pi:/root/.credence-pi ghcr.io/gfrmin/credence-pi-daemon`)
+   or run it from source
+   (`julia --project=<repo-root> apps/credence-pi/daemon/main.jl`).
+   See `apps/credence-pi/daemon/README.md`.
+2. Build the plugin: `cd apps/credence-pi/openclaw-plugin && npm install && npm run build`.
+3. Install it into OpenClaw. From a published registry:
+   `openclaw plugins install @gfrmin/credence-pi-openclaw`; or link a local
+   checkout for development: `openclaw plugins install -l apps/credence-pi/openclaw-plugin`.
+   Then `openclaw plugins enable credence-pi`.
+4. **Per-turn cost signal.** On current OpenClaw (≥ 2026.6.2) the `llm_output`
+   cost hook is active out of the box — no extra config. (Older builds gated it
+   behind a since-removed `plugins.entries.credence-pi.hooks.allowConversationAccess`
+   flag; that key is now rejected by the config schema.) Governance —
+   allow/block/ask — never depended on it.
+5. Restart the gateway so it picks up the plugin.
+6. Verify it loaded: `openclaw plugins list` shows `credence-pi` as `loaded`.
+
+## Config (`openclaw.plugin.json` → `configSchema`)
+
+| key | default | meaning |
+|---|---|---|
+| `daemonUrl` | `http://127.0.0.1:8787` | credence-pi daemon base URL |
+| `hookTimeoutMs` | `3000` | max wait for the daemon decision before failing open |
+| `approvalTimeoutMs` | `120000` | how long OpenClaw waits for the user on an `ask` before denying |
+| `redactToolInputs` | `false` | omit tool-call inputs from sensor events (they can carry secrets); ask-preview becomes generic |
+| `silent` | `false` | suppress info/warn logs |
+| `pricing` | — | per-model USD/Mtok overrides: `{ "<model>": { "input": n, "output": n, "cacheRead": n, "cacheWrite": n } }` |
+
+**Privacy:** by default the daemon logs `proposed_call.input` (commands, paths) to
+`~/.credence-pi/observations.jsonl`. Set `redactToolInputs: true` to keep inputs out of the log.
+Fail-open warnings are emitted once per outage (re-armed when the daemon recovers).
+
+The built-in price table is approximate; set `pricing` for an exact
+dollars-saved figure for your providers. Unknown/unpriced models log
+`usd: null` (token counts still recorded; the Move-2 surface applies a
+token×price fallback).
+
+## Develop
+
+```
+npm install
+npm run build      # tsc → dist/
+npm run typecheck  # tsc --noEmit
+npm test           # node --test (tsx) over tests/*.test.ts
+```
+
+## Known limitations (Move 1 / MVP-0)
+
+- `working-directory-relative` and `time-since-last-user-message` features
+  are best-effort (OpenClaw doesn't put cwd or message timestamps on the
+  tool ctx); the loop-relevant features (tool-name, parent, repetition)
+  are exact. In Move 1 the brain does not condition on features at decision
+  time, so this only affects future feature-conditioned learning.
+- Cost USD is reconstructed from a local price table (no host
+  `calculateCost` dependency); override via `pricing`.
+- The per-run feature buffer is bounded per run but the run map is not
+  evicted on a long-lived gateway — a PASS-2 cleanup item.

package/dist/cost.d.ts

@@ -0,0 +1,21 @@
+import type { LlmOutputEvent } from "./openclaw-types.js";
+export interface ModelPrice {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+export type PriceTable = Record<string, ModelPrice>;
+export declare const DEFAULT_PRICES: PriceTable;
+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;
+}
+/** Merge operator `pricing` config over the built-in table. */
+export declare function buildPriceTable(overrides: unknown): PriceTable;
+export declare function computeTurnCost(event: LlmOutputEvent, table: PriceTable): TurnCost;

package/dist/cost.js

@@ -0,0 +1,97 @@
+// 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.
+// 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 = {
+    "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 },
+};
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function resolvePrice(model, table) {
+    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;
+    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) {
+    const table = { ...DEFAULT_PRICES };
+    if (overrides && typeof overrides === "object") {
+        for (const [k, v] of Object.entries(overrides)) {
+            if (v && typeof v === "object") {
+                const o = v;
+                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, table) {
+    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 = 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,
+    };
+}

package/dist/daemon-client.d.ts

@@ -0,0 +1,27 @@
+export interface SignalEnvelope {
+    signal_type: string;
+    signal_id: string;
+    in_response_to: string;
+    effector: string;
+    parameters: Record<string, unknown>;
+}
+export type Logger = (msg: string, err?: unknown) => void;
+export interface ClientOptions {
+    baseUrl: string;
+    timeoutMs?: number;
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    logger?: Logger;
+}
+export interface PostResult {
+    ok: boolean;
+}
+export interface DaemonClient {
+    postSensor: (event: object) => Promise<PostResult>;
+    connectSignalsStream: (onSignal: (sig: SignalEnvelope) => void) => SignalsConnection;
+}
+export interface SignalsConnection {
+    close: () => void;
+    done: Promise<void>;
+}
+export declare function createDaemonClient(opts: ClientOptions): DaemonClient;

package/dist/daemon-client.js

@@ -0,0 +1,145 @@
+// daemon-client.ts — body-side HTTP client for the credence-pi daemon.
+//
+// shared-source: apps/credence-pi/extension/src/client.ts
+//   This is a vendored copy (verbatim behaviour) so the OpenClaw plugin
+//   is a self-contained, installable package. The pi-extension body and
+//   this OpenClaw body MUST keep the same daemon wire (POST /sensor,
+//   GET /signals SSE). If you change one, change the other; client.test.ts
+//   in the extension covers the reference behaviour.
+//
+// Two responsibilities, both fail-open:
+//   postSensor(event)              — POST /sensor with a timeout; never
+//                                    throws, never hangs; logs once on
+//                                    failure and returns {ok:false}.
+//   connectSignalsStream(onSignal) — streaming GET /signals consumer;
+//                                    parses `data:` SSE frames; auto-
+//                                    reconnects with exponential backoff
+//                                    until close().
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_INITIAL_BACKOFF_MS = 500;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+export function createDaemonClient(opts) {
+    const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const initialBackoff = opts.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
+    const maxBackoff = opts.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+    const log = opts.logger ??
+        ((m, e) => (e === undefined ? console.warn(m) : console.warn(m, e)));
+    return {
+        postSensor: (event) => postSensor(baseUrl, event, timeoutMs, log),
+        connectSignalsStream: (onSignal) => connectSignalsStream(baseUrl, onSignal, initialBackoff, maxBackoff, log),
+    };
+}
+async function postSensor(baseUrl, event, timeoutMs, log) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const resp = await fetch(`${baseUrl}/sensor`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(event),
+            signal: ctrl.signal,
+        });
+        try {
+            await resp.text();
+        }
+        catch {
+            /* noop */
+        }
+        if (!resp.ok) {
+            log(`credence-pi: daemon /sensor returned status ${resp.status}; failing open`);
+            return { ok: false };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        log("credence-pi: daemon unreachable on /sensor; failing open", err);
+        return { ok: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function connectSignalsStream(baseUrl, onSignal, initialBackoff, maxBackoff, log) {
+    const ctrl = new AbortController();
+    let closed = false;
+    const done = (async () => {
+        let backoff = initialBackoff;
+        while (!closed) {
+            try {
+                await consumeOnce(baseUrl, onSignal, ctrl.signal, log);
+                if (closed)
+                    break;
+                log("credence-pi: /signals stream ended; reconnecting");
+            }
+            catch (err) {
+                if (closed)
+                    break;
+                log("credence-pi: /signals stream error; reconnecting", err);
+            }
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, backoff);
+                ctrl.signal.addEventListener("abort", () => {
+                    clearTimeout(t);
+                    resolve();
+                }, { once: true });
+            });
+            backoff = Math.min(backoff * 2, maxBackoff);
+        }
+    })();
+    return {
+        close: () => {
+            closed = true;
+            ctrl.abort();
+        },
+        done,
+    };
+}
+async function consumeOnce(baseUrl, onSignal, signal, log) {
+    const resp = await fetch(`${baseUrl}/signals`, {
+        method: "GET",
+        headers: { Accept: "text/event-stream" },
+        signal,
+    });
+    if (!resp.ok || !resp.body) {
+        throw new Error(`/signals returned ${resp.status}`);
+    }
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buffer.indexOf("\n\n")) >= 0) {
+                const frame = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                dispatchFrame(frame, onSignal, log);
+            }
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* noop */
+        }
+    }
+}
+function dispatchFrame(frame, onSignal, log) {
+    for (const line of frame.split("\n")) {
+        if (line.startsWith("data: ")) {
+            const payload = line.slice(6);
+            try {
+                onSignal(JSON.parse(payload));
+            }
+            catch (err) {
+                log("credence-pi: /signals dispatch dropped malformed frame", err);
+            }
+        }
+    }
+}

package/dist/features.d.ts

@@ -0,0 +1,15 @@
+import type { BeforeToolCallEvent, ToolContext } from "./openclaw-types.js";
+export type Features = Record<string, string>;
+export declare class FeatureTracker {
+    private runs;
+    /** Stamp the most recent user message for a run (best-effort; wired
+     *  from a message hook if one is available). */
+    markUserMessage(ctx: ToolContext, ts: number): void;
+    /** Compute features from the run's history BEFORE this call, then record
+     *  the current call. `now` is injectable for deterministic tests. */
+    extractAndRecord(event: BeforeToolCallEvent, ctx: ToolContext, now?: number): Features;
+    /** Drop a run's buffer (call on agent_end to bound memory). */
+    clearRun(ctx: ToolContext): void;
+    /** Test/inspection accessor. */
+    runCount(): number;
+}

package/dist/features.js

@@ -0,0 +1,122 @@
+// features.ts — the body's sensory periphery for the OpenClaw plugin.
+//
+// Produces the brain's declared kebab-case feature vocabulary
+// (apps/credence-pi/bdsl/features.bdsl) from the before_tool_call event +
+// a small per-run history buffer. In Move 1 the brain does NOT condition
+// on features at decision time (global Beta), so these are logged for the
+// dollars-saved surface and future feature-conditioned learning; the
+// loop-relevant ones (tool-name, parent, repetition) are exact, while
+// working-directory-relative and time-since-last-user-message are
+// best-effort (OpenClaw does not put cwd or message timestamps on the
+// tool ctx — see move-1-design.md OQ-d).
+const KNOWN_TOOLS = new Set([
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "exec",
+    "process",
+    "apply_patch",
+    "grep",
+    "find",
+    "ls",
+]);
+const HISTORY_CAP = 50;
+const REPETITION_WINDOW = 5;
+function bucketTool(name) {
+    if (!name)
+        return "other";
+    const t = name.toLowerCase();
+    return KNOWN_TOOLS.has(t) ? t : "other";
+}
+function runKey(ctx) {
+    return ctx.runId ?? ctx.sessionKey ?? ctx.sessionId ?? "default";
+}
+function timeSinceUserBucket(elapsedMs) {
+    if (elapsedMs === undefined)
+        return "gt-10m";
+    const s = elapsedMs / 1000;
+    if (s < 30)
+        return "lt-30s";
+    if (s < 120)
+        return "lt-2m";
+    if (s < 600)
+        return "lt-10m";
+    return "gt-10m";
+}
+function workingDirRelative(ctx, event) {
+    const root = ctx.workspaceDir;
+    const paths = event.derivedPaths ?? [];
+    if (paths.length === 0) {
+        // No path-bearing tool (e.g. a bare bash with no file args we can see).
+        return "no-path";
+    }
+    if (!root)
+        return "no-path";
+    const norm = (p) => p.replace(/\/+$/, "");
+    const r = norm(root);
+    let sawOutside = false;
+    let sawRootExact = false;
+    let sawSub = false;
+    for (const raw of paths) {
+        const p = norm(raw);
+        if (p === r) {
+            sawRootExact = true;
+        }
+        else if (p.startsWith(r + "/")) {
+            sawSub = true;
+        }
+        else {
+            sawOutside = true;
+        }
+    }
+    if (sawOutside)
+        return "outside-project";
+    if (sawRootExact && !sawSub)
+        return "project-root";
+    return "subdirectory";
+}
+export class FeatureTracker {
+    runs = new Map();
+    /** Stamp the most recent user message for a run (best-effort; wired
+     *  from a message hook if one is available). */
+    markUserMessage(ctx, ts) {
+        const k = runKey(ctx);
+        const st = this.runs.get(k) ?? { history: [] };
+        st.lastUserTs = ts;
+        this.runs.set(k, st);
+    }
+    /** Compute features from the run's history BEFORE this call, then record
+     *  the current call. `now` is injectable for deterministic tests. */
+    extractAndRecord(event, ctx, now = Date.now()) {
+        const k = runKey(ctx);
+        const st = this.runs.get(k) ?? { history: [] };
+        const tool = bucketTool(event.toolName);
+        const parent = st.history.length > 0 ? st.history[st.history.length - 1].tool : "none";
+        const recent = st.history.slice(-REPETITION_WINDOW);
+        const reps = recent.filter((e) => e.tool === tool).length;
+        const repBucket = reps === 0 ? "rep-0" : reps === 1 ? "rep-1" : reps === 2 ? "rep-2" : "rep-3plus";
+        const elapsed = st.lastUserTs === undefined ? undefined : now - st.lastUserTs;
+        const features = {
+            "tool-name": tool,
+            "working-directory-relative": workingDirRelative(ctx, event),
+            "parent-tool-call-name": parent,
+            "recent-repetition-count": repBucket,
+            "time-since-last-user-message": timeSinceUserBucket(elapsed),
+        };
+        // Record current call.
+        st.history.push({ tool, ts: now });
+        if (st.history.length > HISTORY_CAP)
+            st.history.shift();
+        this.runs.set(k, st);
+        return features;
+    }
+    /** Drop a run's buffer (call on agent_end to bound memory). */
+    clearRun(ctx) {
+        this.runs.delete(runKey(ctx));
+    }
+    /** Test/inspection accessor. */
+    runCount() {
+        return this.runs.size;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { type DaemonClient, type SignalEnvelope, type Logger } from "./daemon-client.js";
+import { type PriceTable } from "./cost.js";
+import type { PluginEntry, BeforeToolCallEvent, BeforeToolCallResult, AfterToolCallEvent, LlmOutputEvent, ToolContext } from "./openclaw-types.js";
+export declare function mapSignal(sig: SignalEnvelope | undefined, originatingEventId: string, client: DaemonClient, approvalTimeoutMs: number): BeforeToolCallResult | undefined;
+export interface GovernorOpts {
+    hookTimeoutMs: number;
+    approvalTimeoutMs: number;
+    priceTable: PriceTable;
+    redactToolInputs: boolean;
+    log: Logger;
+}
+export interface Governor {
+    beforeToolCall: (event: BeforeToolCallEvent, ctx: ToolContext) => Promise<BeforeToolCallResult | undefined>;
+    afterToolCall: (event: AfterToolCallEvent, ctx: ToolContext) => Promise<void>;
+    llmOutput: (event: LlmOutputEvent, ctx: ToolContext) => Promise<void>;
+    cleanup: () => void;
+    /** Test/inspection accessor: in-flight tool_call awaiters. */
+    pendingCount: () => number;
+}
+export declare function createGovernor(client: DaemonClient, opts: GovernorOpts): Governor;
+declare const plugin: PluginEntry;
+export default plugin;