@gfrmin/credence-pi-openclaw 0.1.0

package/src/daemon-client.ts

@@ -0,0 +1,204 @@
+// 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().
+
+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>;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_INITIAL_BACKOFF_MS = 500;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+
+export function createDaemonClient(opts: ClientOptions): DaemonClient {
+  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: Logger =
+    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: string,
+  event: object,
+  timeoutMs: number,
+  log: Logger,
+): Promise<PostResult> {
+  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: string,
+  onSignal: (sig: SignalEnvelope) => void,
+  initialBackoff: number,
+  maxBackoff: number,
+  log: Logger,
+): SignalsConnection {
+  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<void>((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: string,
+  onSignal: (sig: SignalEnvelope) => void,
+  signal: AbortSignal,
+  log: Logger,
+): Promise<void> {
+  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: number;
+      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: string,
+  onSignal: (sig: SignalEnvelope) => void,
+  log: Logger,
+): void {
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("data: ")) {
+      const payload = line.slice(6);
+      try {
+        onSignal(JSON.parse(payload) as SignalEnvelope);
+      } catch (err) {
+        log("credence-pi: /signals dispatch dropped malformed frame", err);
+      }
+    }
+  }
+}

package/src/features.ts

@@ -0,0 +1,152 @@
+// 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).
+
+import type { BeforeToolCallEvent, ToolContext } from "./openclaw-types.js";
+
+export type Features = Record<string, string>;
+
+const KNOWN_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "bash",
+  "exec",
+  "process",
+  "apply_patch",
+  "grep",
+  "find",
+  "ls",
+]);
+
+const HISTORY_CAP = 50;
+const REPETITION_WINDOW = 5;
+
+interface Entry {
+  tool: string;
+  ts: number;
+}
+
+interface RunState {
+  history: Entry[];
+  lastUserTs?: number;
+}
+
+function bucketTool(name: string | undefined): string {
+  if (!name) return "other";
+  const t = name.toLowerCase();
+  return KNOWN_TOOLS.has(t) ? t : "other";
+}
+
+function runKey(ctx: ToolContext): string {
+  return ctx.runId ?? ctx.sessionKey ?? ctx.sessionId ?? "default";
+}
+
+function timeSinceUserBucket(elapsedMs: number | undefined): string {
+  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: ToolContext,
+  event: BeforeToolCallEvent,
+): string {
+  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: string) => 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 {
+  private runs = new Map<string, RunState>();
+
+  /** 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 {
+    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: BeforeToolCallEvent,
+    ctx: ToolContext,
+    now: number = Date.now(),
+  ): Features {
+    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: 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: ToolContext): void {
+    this.runs.delete(runKey(ctx));
+  }
+
+  /** Test/inspection accessor. */
+  runCount(): number {
+    return this.runs.size;
+  }
+}

package/src/index.ts

@@ -0,0 +1,342 @@
+// 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,
+  type DaemonClient,
+  type SignalEnvelope,
+  type Logger,
+} from "./daemon-client.js";
+import { FeatureTracker } from "./features.js";
+import { buildPriceTable, computeTurnCost, type PriceTable } from "./cost.js";
+import type {
+  PluginEntry,
+  BeforeToolCallEvent,
+  BeforeToolCallResult,
+  AfterToolCallEvent,
+  LlmOutputEvent,
+  ToolContext,
+  RequireApprovalPayload,
+} from "./openclaw-types.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(): string {
+  return `evt_${randomUUID().slice(0, 12)}`;
+}
+
+export function mapSignal(
+  sig: SignalEnvelope | undefined,
+  originatingEventId: string,
+  client: DaemonClient,
+  approvalTimeoutMs: number,
+): BeforeToolCallResult | undefined {
+  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: RequireApprovalPayload = {
+        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
+  }
+}
+
+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;
+}
+
+// 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: DaemonClient,
+  opts: GovernorOpts,
+): Governor {
+  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<string, (sig: SignalEnvelope | undefined) => void>();
+
+  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: BeforeToolCallEvent,
+    ctx: ToolContext,
+  ): Promise<BeforeToolCallResult | undefined> {
+    const eventId = newEventId();
+    const signalPromise = new Promise<SignalEnvelope | undefined>((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: AfterToolCallEvent,
+    _ctx: ToolContext,
+  ): Promise<void> {
+    // 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: LlmOutputEvent,
+    ctx: ToolContext,
+  ): Promise<void> {
+    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(): void {
+    sse.close();
+    for (const resolve of awaiters.values()) resolve(undefined);
+    awaiters.clear();
+  }
+
+  return {
+    beforeToolCall,
+    afterToolCall,
+    llmOutput,
+    cleanup,
+    pendingCount: () => awaiters.size,
+  };
+}
+
+const plugin: PluginEntry = {
+  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: Logger = (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;