usertrust-openclaw 1.1.1

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import type { Governor } from "usertrust";
+import type { OpenClawPluginApi, StreamFn, UsertrustPluginConfig } from "./types.js";
+export { wrapStreamWithGovernance, wrapCompleteWithGovernance } from "./stream-governor.js";
+export { createAccumulator, extractUsageFromEvent } from "./token-extractor.js";
+export type { StreamEvent, StreamFn, StreamContext, StreamUsage, UsertrustPluginConfig, GovernedStreamMeta, } from "./types.js";
+/**
+ * OpenClaw plugin entry point.
+ *
+ * Called by OpenClaw's plugin loader. Initializes the usertrust
+ * governance engine and registers the stream wrapper.
+ */
+export default function register(api: OpenClawPluginApi): void;
+/**
+ * Programmatic API for non-OpenClaw usage.
+ *
+ * Use this when integrating usertrust governance into a custom
+ * pi-ai setup without the full OpenClaw plugin system.
+ *
+ * ```ts
+ * import { createGovernedStreamFn } from "@usertrust/openclaw";
+ *
+ * const governed = await createGovernedStreamFn(myStreamFn, {
+ *   budget: 100_000,
+ *   dryRun: true,
+ * });
+ *
+ * for await (const event of governed("claude-sonnet-4-6", context)) {
+ *   // events flow through with governance applied
+ * }
+ * ```
+ */
+export declare function createGovernedStreamFn(streamFn: StreamFn, config: UsertrustPluginConfig): Promise<{
+    governedStreamFn: StreamFn;
+    governor: Governor;
+}>;
+/**
+ * Get the active governor instance.
+ * Returns null if the plugin hasn't been initialized yet.
+ */
+export declare function getGovernor(): Governor | null;
+/**
+ * Graceful shutdown — call this when OpenClaw exits.
+ * Voids all pending holds and flushes the audit chain.
+ */
+export declare function shutdown(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,KAAK,EACX,iBAAiB,EAGjB,QAAQ,EACR,qBAAqB,EACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAChF,YAAY,EACX,WAAW,EACX,QAAQ,EACR,aAAa,EACb,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GAClB,MAAM,YAAY,CAAC;AAKpB;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CA0B7D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC3C,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,qBAAqB,GAC3B,OAAO,CAAC;IAAE,gBAAgB,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAI7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,QAAQ,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9C"}

package/dist/index.js

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Usertools, Inc.
+/**
+ * @usertrust/openclaw — usertrust governance plugin for OpenClaw
+ *
+ * Adds budget enforcement, policy gates, and hash-chained audit trails
+ * to every LLM call in OpenClaw. Zero code changes required — install
+ * the plugin and every call is governed.
+ *
+ * Installation:
+ *   openclaw plugins install @usertrust/openclaw
+ *
+ * Or manual setup in openclaw.json:
+ *   {
+ *     "plugins": {
+ *       "entries": {
+ *         "usertrust": {
+ *           "enabled": true,
+ *           "config": { "budget": 100000, "dryRun": true }
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * How it works:
+ *   User's LLM call → OpenClaw → wrapStreamFn (usertrust) →
+ *     1. Check budget (PENDING hold)
+ *     2. Forward to real stream
+ *     3. Accumulate token usage from stream
+ *     4. POST settle with actual cost
+ *     5. Return governed stream to OpenClaw
+ */
+import { createGovernor } from "usertrust";
+import { wrapStreamWithGovernance } from "./stream-governor.js";
+// Re-export for consumers
+export { wrapStreamWithGovernance, wrapCompleteWithGovernance } from "./stream-governor.js";
+export { createAccumulator, extractUsageFromEvent } from "./token-extractor.js";
+/** Active governor instance — singleton per plugin lifecycle. */
+let governor = null;
+/**
+ * OpenClaw plugin entry point.
+ *
+ * Called by OpenClaw's plugin loader. Initializes the usertrust
+ * governance engine and registers the stream wrapper.
+ */
+export default function register(api) {
+    // Config is injected by OpenClaw from openclaw.json → plugins.entries.usertrust.config
+    // We register a hook that initializes on first use (lazy)
+    // since config isn't available at register time in all OpenClaw versions.
+    const plugin = {
+        id: "usertrust",
+        label: "usertrust Governance",
+        /**
+         * wrapStreamFn — the core integration point.
+         *
+         * OpenClaw calls this with the existing stream function.
+         * We return a wrapped version that adds governance.
+         */
+        wrapStreamFn(originalStreamFn, config) {
+            // Lazy-initialize governor on first call
+            const getGovernor = lazyGovernor(config);
+            return (model, context, options) => {
+                return governedStreamLazy(getGovernor, originalStreamFn, model, context, options);
+            };
+        },
+    };
+    api.registerProvider(plugin);
+}
+/**
+ * Programmatic API for non-OpenClaw usage.
+ *
+ * Use this when integrating usertrust governance into a custom
+ * pi-ai setup without the full OpenClaw plugin system.
+ *
+ * ```ts
+ * import { createGovernedStreamFn } from "@usertrust/openclaw";
+ *
+ * const governed = await createGovernedStreamFn(myStreamFn, {
+ *   budget: 100_000,
+ *   dryRun: true,
+ * });
+ *
+ * for await (const event of governed("claude-sonnet-4-6", context)) {
+ *   // events flow through with governance applied
+ * }
+ * ```
+ */
+export async function createGovernedStreamFn(streamFn, config) {
+    const gov = await initGovernor(config);
+    const governedStreamFn = wrapStreamWithGovernance(streamFn, gov);
+    return { governedStreamFn, governor: gov };
+}
+/**
+ * Get the active governor instance.
+ * Returns null if the plugin hasn't been initialized yet.
+ */
+export function getGovernor() {
+    return governor;
+}
+/**
+ * Graceful shutdown — call this when OpenClaw exits.
+ * Voids all pending holds and flushes the audit chain.
+ */
+export async function shutdown() {
+    if (governor != null) {
+        await governor.destroy();
+        governor = null;
+        initPromise = null;
+    }
+}
+// ── Internal ──
+/** Module-level promise to prevent concurrent initialization race. */
+let initPromise = null;
+function initGovernor(config) {
+    if (governor != null) {
+        return Promise.resolve(governor);
+    }
+    // Memoize the init promise to prevent TOCTOU race — two concurrent
+    // callers both see governor == null but only one createGovernor runs.
+    if (initPromise == null) {
+        initPromise = createGovernor({
+            budget: config.budget,
+            ...(config.dryRun != null ? { dryRun: config.dryRun } : {}),
+            ...(config.configPath != null ? { configPath: config.configPath } : {}),
+            ...(config.proxy != null ? { proxy: config.proxy } : {}),
+            ...(config.proxyKey != null ? { key: config.proxyKey } : {}),
+        }).then((gov) => {
+            governor = gov;
+            return gov;
+        });
+    }
+    return initPromise;
+}
+function lazyGovernor(config) {
+    let promise = null;
+    return () => {
+        if (promise == null) {
+            promise = initGovernor(config);
+        }
+        return promise;
+    };
+}
+async function* governedStreamLazy(getGovernor, streamFn, model, context, options) {
+    const gov = await getGovernor();
+    const governed = wrapStreamWithGovernance(streamFn, gov);
+    yield* governed(model, context, options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/stream-governor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * stream-governor.ts — Governed Stream Wrapper for pi-ai
+ *
+ * Wraps a pi-ai stream function with usertrust governance:
+ *   1. Before stream: authorize (budget check, PENDING hold)
+ *   2. During stream: forward events, accumulate token usage
+ *   3. After stream: settle with actual cost
+ *   4. On error: abort (VOID the hold)
+ *
+ * The wrapped function has the same signature as the original —
+ * it's a transparent middleware layer.
+ */
+import type { Governor } from "usertrust";
+import type { StreamContext, StreamFn } from "./types.js";
+/**
+ * Wrap a pi-ai stream function with usertrust governance.
+ *
+ * Returns a new stream function with the same signature. Every call:
+ *   - Checks budget and creates a PENDING hold
+ *   - Forwards all stream events unchanged
+ *   - Settles with actual token usage on completion
+ *   - Voids the hold on error
+ *
+ * The governance receipt is emitted as a custom `usertrust:receipt`
+ * property on the `done` event for consumers that want it.
+ */
+export declare function wrapStreamWithGovernance(streamFn: StreamFn, governor: Governor): StreamFn;
+/**
+ * Wrap a non-streaming completion function with governance.
+ *
+ * For pi-ai's `completeSimple()` / `complete()` functions that
+ * return a Promise instead of an async iterable.
+ */
+export declare function wrapCompleteWithGovernance<T extends {
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}>(completeFn: (model: string, context: StreamContext, options?: Record<string, unknown>) => Promise<T>, governor: Governor): (model: string, context: StreamContext, options?: Record<string, unknown>) => Promise<T>;
+//# sourceMappingURL=stream-governor.d.ts.map

package/dist/stream-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-governor.d.ts","sourceRoot":"","sources":["../src/stream-governor.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAe,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAQzF;AA+CD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACzC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAEnE,UAAU,EAAE,CACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,CAAC,CAAC,EACf,QAAQ,EAAE,QAAQ,GAChB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAsC1F"}

package/dist/stream-governor.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Usertools, Inc.
+import { createAccumulator } from "./token-extractor.js";
+/**
+ * Wrap a pi-ai stream function with usertrust governance.
+ *
+ * Returns a new stream function with the same signature. Every call:
+ *   - Checks budget and creates a PENDING hold
+ *   - Forwards all stream events unchanged
+ *   - Settles with actual token usage on completion
+ *   - Voids the hold on error
+ *
+ * The governance receipt is emitted as a custom `usertrust:receipt`
+ * property on the `done` event for consumers that want it.
+ */
+export function wrapStreamWithGovernance(streamFn, governor) {
+    return (model, context, options) => {
+        return governedStream(streamFn, governor, model, context, options);
+    };
+}
+async function* governedStream(streamFn, governor, model, context, options) {
+    // 1. Authorize — budget check, policy gate, PENDING hold
+    const auth = await governor.authorize({
+        model,
+        messages: context.messages,
+        ...(context.maxTokens != null ? { maxOutputTokens: context.maxTokens } : {}),
+        params: {
+            ...(context.temperature != null ? { temperature: context.temperature } : {}),
+        },
+    });
+    // 2. Stream with token accumulation
+    const accumulator = createAccumulator();
+    try {
+        const stream = streamFn(model, context, options);
+        for await (const event of stream) {
+            accumulator.update(event);
+            yield event;
+        }
+        // 3. Settle — POST actual cost
+        const usage = accumulator.result();
+        await governor.settle(auth, {
+            ...(usage.usageReported
+                ? { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens }
+                : {}),
+            chunksDelivered: usage.chunksDelivered,
+            usageSource: usage.usageReported ? "provider" : "estimated",
+        });
+    }
+    catch (err) {
+        // 4. Abort — VOID the hold (catch abort errors to preserve original)
+        await governor.abort(auth, err).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Wrap a non-streaming completion function with governance.
+ *
+ * For pi-ai's `completeSimple()` / `complete()` functions that
+ * return a Promise instead of an async iterable.
+ */
+export function wrapCompleteWithGovernance(completeFn, governor) {
+    return async (model, context, options) => {
+        // 1. Authorize
+        const auth = await governor.authorize({
+            model,
+            messages: context.messages,
+            ...(context.maxTokens != null ? { maxOutputTokens: context.maxTokens } : {}),
+            params: {
+                ...(context.temperature != null ? { temperature: context.temperature } : {}),
+            },
+        });
+        try {
+            // 2. Execute
+            const result = await completeFn(model, context, options);
+            // 3. Settle with actual usage if available
+            await governor.settle(auth, {
+                ...(result.usage != null
+                    ? {
+                        inputTokens: result.usage.inputTokens,
+                        outputTokens: result.usage.outputTokens,
+                        usageSource: "provider",
+                    }
+                    : { usageSource: "estimated" }),
+            });
+            return result;
+        }
+        catch (err) {
+            // 4. Abort (catch abort errors to preserve original)
+            await governor.abort(auth, err).catch(() => { });
+            throw err;
+        }
+    };
+}
+//# sourceMappingURL=stream-governor.js.map

package/dist/stream-governor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-governor.js","sourceRoot":"","sources":["../src/stream-governor.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAgBjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAkB,EAAE,QAAkB;IAC9E,OAAO,CACN,KAAa,EACb,OAAsB,EACtB,OAAiC,EACJ,EAAE;QAC/B,OAAO,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC,CAAC;AACH,CAAC;AAED,KAAK,SAAS,CAAC,CAAC,cAAc,CAC7B,QAAkB,EAClB,QAAkB,EAClB,KAAa,EACb,OAAsB,EACtB,OAAiC;IAEjC,yDAAyD;IACzD,MAAM,IAAI,GAAkB,MAAM,QAAQ,CAAC,SAAS,CAAC;QACpD,KAAK;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,EAAE;YACP,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E;KACD,CAAC,CAAC;IAEH,oCAAoC;IACpC,MAAM,WAAW,GAAG,iBAAiB,EAAE,CAAC;IAExC,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAEjD,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAClC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1B,MAAM,KAAK,CAAC;QACb,CAAC;QAED,+BAA+B;QAC/B,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC;QAEnC,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;YAC3B,GAAG,CAAC,KAAK,CAAC,aAAa;gBACtB,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE;gBACtE,CAAC,CAAC,EAAE,CAAC;YACN,eAAe,EAAE,KAAK,CAAC,eAAe;YACtC,WAAW,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW;SAC3D,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,qEAAqE;QACrE,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAChD,MAAM,GAAG,CAAC;IACX,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAGzC,UAIe,EACf,QAAkB;IAElB,OAAO,KAAK,EACX,KAAa,EACb,OAAsB,EACtB,OAAiC,EACpB,EAAE;QACf,eAAe;QACf,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC;YACrC,KAAK;YACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,MAAM,EAAE;gBACP,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5E;SACD,CAAC,CAAC;QAEH,IAAI,CAAC;YACJ,aAAa;YACb,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YAEzD,2CAA2C;YAC3C,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;gBAC3B,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI;oBACvB,CAAC,CAAC;wBACA,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW;wBACrC,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY;wBACvC,WAAW,EAAE,UAAmB;qBAChC;oBACF,CAAC,CAAC,EAAE,WAAW,EAAE,WAAoB,EAAE,CAAC;aACzC,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QACf,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,qDAAqD;YACrD,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAChD,MAAM,GAAG,CAAC;QACX,CAAC;IACF,CAAC,CAAC;AACH,CAAC"}

package/dist/token-extractor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * token-extractor.ts — pi-ai Stream Token Extraction
+ *
+ * Extracts token usage from pi-ai's normalized stream events.
+ * pi-ai reports usage on `done` and `error` events, unlike provider
+ * SDKs which scatter it across multiple event types.
+ */
+import type { StreamEvent, StreamUsage } from "./types.js";
+/** Accumulated usage from a pi-ai stream. */
+export interface AccumulatedUsage {
+    inputTokens: number;
+    outputTokens: number;
+    chunksDelivered: number;
+    usageReported: boolean;
+}
+export declare function extractUsageFromEvent(event: StreamEvent): StreamUsage | null;
+/**
+ * Creates a token accumulator for tracking usage across a stream.
+ * Call `update()` for each event and `result()` when done.
+ */
+export declare function createAccumulator(): {
+    update(event: StreamEvent): void;
+    result(): AccumulatedUsage;
+};
+//# sourceMappingURL=token-extractor.d.ts.map

package/dist/token-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-extractor.d.ts","sourceRoot":"","sources":["../src/token-extractor.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3D,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACvB;AAaD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAgB5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI;IACpC,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,MAAM,IAAI,gBAAgB,CAAC;CAC3B,CAsBA"}

package/dist/token-extractor.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Usertools, Inc.
+/**
+ * Extract token usage from a pi-ai stream event.
+ * Returns non-zero usage only for `done` and `error` events.
+ */
+/** Max tokens to accept from a provider (prevents Infinity/overflow in cost math). */
+const MAX_TOKENS = 2_000_000;
+function clampTokens(n) {
+    return Math.min(Math.max(0, n), MAX_TOKENS);
+}
+export function extractUsageFromEvent(event) {
+    if (event.type === "done" && event.usage != null) {
+        return {
+            ...event.usage,
+            inputTokens: clampTokens(event.usage.inputTokens),
+            outputTokens: clampTokens(event.usage.outputTokens),
+        };
+    }
+    if (event.type === "error" && event.usage != null) {
+        return {
+            ...event.usage,
+            inputTokens: clampTokens(event.usage.inputTokens),
+            outputTokens: clampTokens(event.usage.outputTokens),
+        };
+    }
+    return null;
+}
+/**
+ * Creates a token accumulator for tracking usage across a stream.
+ * Call `update()` for each event and `result()` when done.
+ */
+export function createAccumulator() {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let chunksDelivered = 0;
+    let usageReported = false;
+    return {
+        update(event) {
+            chunksDelivered++;
+            const usage = extractUsageFromEvent(event);
+            if (usage != null) {
+                inputTokens = usage.inputTokens;
+                outputTokens = usage.outputTokens;
+                usageReported = true;
+            }
+        },
+        result() {
+            return { inputTokens, outputTokens, chunksDelivered, usageReported };
+        },
+    };
+}
+//# sourceMappingURL=token-extractor.js.map

package/dist/token-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-extractor.js","sourceRoot":"","sources":["../src/token-extractor.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAoBjC;;;GAGG;AACH,sFAAsF;AACtF,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B,SAAS,WAAW,CAAC,CAAS;IAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAkB;IACvD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QAClD,OAAO;YACN,GAAG,KAAK,CAAC,KAAK;YACd,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;YACjD,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC;SACnD,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QACnD,OAAO;YACN,GAAG,KAAK,CAAC,KAAK;YACd,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC;YACjD,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC;SACnD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAIhC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,aAAa,GAAG,KAAK,CAAC;IAE1B,OAAO;QACN,MAAM,CAAC,KAAkB;YACxB,eAAe,EAAE,CAAC;YAElB,MAAM,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;gBACnB,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;gBAChC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;gBAClC,aAAa,GAAG,IAAI,CAAC;YACtB,CAAC;QACF,CAAC;QAED,MAAM;YACL,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;QACtE,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * types.ts — OpenClaw Plugin API Types
+ *
+ * Type definitions for the OpenClaw plugin system and pi-ai streaming
+ * events. These mirror the OpenClaw/pi-ai interfaces without requiring
+ * the packages at compile time.
+ */
+export interface StreamUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export interface TextDeltaEvent {
+    type: "text_delta";
+    text: string;
+}
+export interface TextStartEvent {
+    type: "text_start";
+}
+export interface TextEndEvent {
+    type: "text_end";
+}
+export interface ThinkingDeltaEvent {
+    type: "thinking_delta";
+    text: string;
+}
+export interface ThinkingStartEvent {
+    type: "thinking_start";
+}
+export interface ThinkingEndEvent {
+    type: "thinking_end";
+}
+export interface ToolCallStartEvent {
+    type: "toolcall_start";
+    name: string;
+    id: string;
+}
+export interface ToolCallDeltaEvent {
+    type: "toolcall_delta";
+    args: string;
+}
+export interface ToolCallEndEvent {
+    type: "toolcall_end";
+}
+export interface StartEvent {
+    type: "start";
+}
+export interface DoneEvent {
+    type: "done";
+    stopReason: "stop" | "toolUse" | "length" | "error" | "aborted";
+    usage: StreamUsage;
+}
+export interface ErrorEvent {
+    type: "error";
+    error: unknown;
+    usage?: StreamUsage;
+}
+export type StreamEvent = StartEvent | TextStartEvent | TextDeltaEvent | TextEndEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | DoneEvent | ErrorEvent;
+export interface OpenClawPluginApi {
+    registerTool(tool: unknown): void;
+    registerProvider(provider: unknown): void;
+    registerChannel(channel: unknown): void;
+    registerHttpRoute(route: unknown): void;
+}
+/** Configuration passed to the plugin from openclaw.json. */
+export interface UsertrustPluginConfig {
+    budget: number;
+    tier?: "free" | "mini" | "pro" | "mega" | "ultra";
+    dryRun?: boolean;
+    configPath?: string;
+    proxy?: string;
+    proxyKey?: string;
+}
+export interface StreamContext {
+    messages: unknown[];
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+    [key: string]: unknown;
+}
+export type StreamFn = (model: string, context: StreamContext, options?: Record<string, unknown>) => AsyncIterable<StreamEvent>;
+/** Receipt attached to governed stream events. */
+export interface GovernedStreamMeta {
+    transferId: string;
+    estimatedCost: number;
+    model: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Usertools, Inc.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/openclaw.plugin.json

@@ -0,0 +1,59 @@
+{
+	"id": "usertrust",
+	"name": "usertrust",
+	"description": "Financial governance for AI agents. Every LLM call becomes an immutable, auditable transaction with budget enforcement, policy gates, and hash-chained audit trails.",
+	"kind": "provider",
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"budget": {
+				"type": "number",
+				"description": "Token budget in usertokens. 1 usertoken = $0.0001."
+			},
+			"tier": {
+				"type": "string",
+				"enum": ["free", "mini", "pro", "mega", "ultra"],
+				"description": "Budget tier for policy evaluation."
+			},
+			"dryRun": {
+				"type": "boolean",
+				"description": "Skip TigerBeetle ledger — audit-chain-only mode."
+			},
+			"configPath": {
+				"type": "string",
+				"description": "Path to usertrust.config.json. Defaults to .usertrust/usertrust.config.json."
+			},
+			"proxy": {
+				"type": "string",
+				"description": "Remote governance proxy URL."
+			},
+			"proxyKey": {
+				"type": "string",
+				"description": "API key for the governance proxy."
+			}
+		},
+		"required": ["budget"]
+	},
+	"uiHints": {
+		"budget": {
+			"label": "Token Budget",
+			"placeholder": "100000"
+		},
+		"tier": {
+			"label": "Budget Tier",
+			"placeholder": "pro"
+		},
+		"dryRun": {
+			"label": "Dry Run Mode"
+		},
+		"proxy": {
+			"label": "Proxy URL",
+			"placeholder": "https://proxy.usertools.ai"
+		},
+		"proxyKey": {
+			"label": "Proxy API Key",
+			"sensitive": true
+		}
+	}
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "usertrust-openclaw",
+	"version": "1.1.1",
+	"description": "usertrust governance plugin for OpenClaw. Budget enforcement, audit trails, and policy gates for every LLM call — zero code changes.",
+	"license": "Apache-2.0",
+	"author": "Usertools, Inc. <hello@usertools.ai> (https://usertrust.ai)",
+	"homepage": "https://usertrust.ai",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/usertools-ai/usertrust.git",
+		"directory": "packages/openclaw"
+	},
+	"bugs": "https://github.com/usertools-ai/usertrust/issues",
+	"keywords": [
+		"openclaw",
+		"usertrust",
+		"ai",
+		"governance",
+		"budget",
+		"audit",
+		"llm",
+		"plugin"
+	],
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"prepublishOnly": "tsc"
+	},
+	"files": [
+		"dist",
+		"openclaw.plugin.json"
+	],
+	"dependencies": {
+		"usertrust": "*"
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-ai": ">=0.1.0"
+	},
+	"peerDependenciesMeta": {
+		"@mariozechner/pi-ai": {
+			"optional": true
+		}
+	}
+}