@clearlysh/beehaven 0.8.16

package/dist/daemon-omni-tool-gate.js

@@ -0,0 +1,116 @@
+/**
+ * canUseTool policy framework (#58) — foundation for #59-#63.
+ *
+ * The SDK exposes a `canUseTool: CanUseTool` option on `query()`. Every
+ * tool call passes through it before execution: the function returns
+ * `{behavior:'allow', updatedInput?}` or `{behavior:'deny', message?}`.
+ *
+ * Rather than write one giant function, we compose N small POLICIES
+ * (today: bash-cost-gate, per-tool-quota, tier-restrict).
+ * Each policy is independent + testable. The dispatcher chains them:
+ *
+ *   1. Run policies in registration order.
+ *   2. First DENY wins (short-circuits).
+ *   3. Otherwise, accumulate `updatedInput` from each policy that
+ *      returned `{transformedInput}`. Later transforms see earlier
+ *      results — order matters when policies compose.
+ *   4. If no policy denied, return `{behavior: 'allow', updatedInput}`
+ *      with the accumulated transformations (or unchanged input).
+ *
+ * Why this design:
+ *   - Policies are composable. canUseTool framework + tier policy +
+ *     cost gate + path transform all stack without one fat function.
+ *   - First-deny semantics match security intuition: a single veto
+ *     blocks; transforms layer up.
+ *   - Async-friendly. Policies can hit the DB, call out to the FAB
+ *     for user approval (#59), etc.
+ *
+ * Per-session vs global:
+ *   - Global registry (this file's `policies` Map) is for policies
+ *     that apply to every session — e.g. cost gates, tier checks.
+ *   - Per-session policies could be added later via OmniSession.config
+ *     (e.g. when a composition is tagged "shopify-store", attach an
+ *     extra policy that gates Bash commands hitting the store API).
+ */
+const policies = new Map();
+/** Register a policy. Returns an unregister function. Idempotent on
+ *  id — re-registering replaces. */
+export function registerToolGatePolicy(policy) {
+    policies.set(policy.id, policy);
+    return () => { policies.delete(policy.id); };
+}
+/** For diagnostics / `omni:sessions` UI later. */
+export function listToolGatePolicies() {
+    return [...policies.values()]
+        .map((p) => ({ id: p.id, priority: p.priority ?? 100 }))
+        .sort((a, b) => a.priority - b.priority);
+}
+/** Compose a `CanUseTool` callback bound to a specific session. The
+ *  returned function is what we pass to the SDK's `canUseTool` option.
+ *  Each turn calls this once per tool use; we walk the policy chain
+ *  and produce a PermissionResult.
+ *
+ *  The signature here matches the SDK's CanUseTool type exactly so
+ *  it can be passed directly into `buildSdkOptions().canUseTool`.
+ */
+export function buildToolGate(sessionCtx) {
+    return async (toolName, input, options) => {
+        const sorted = [...policies.values()].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+        let workingInput = input;
+        for (const policy of sorted) {
+            if (policy.appliesTo && !policy.appliesTo(toolName))
+                continue;
+            let decision;
+            try {
+                decision = await policy.decide(toolName, workingInput, {
+                    sessionId: sessionCtx.sessionId,
+                    userId: sessionCtx.userId,
+                    signal: options.signal,
+                });
+            }
+            catch (err) {
+                // FAIL CLOSED. This used to swallow the error and continue
+                // ("better to let through than to block on a buggy policy"),
+                // which inverted the gate: anything that could make a deny
+                // policy throw — an aborted signal, a DB blip, a timed-out FAB
+                // approval round-trip — turned a denial into an ALLOW, silently.
+                // The policies this framework is built for are explicitly async
+                // and I/O-bound (the header advertises DB hits and user-approval
+                // prompts), so throwing is a normal failure mode, not an exotic
+                // one. A policy that genuinely shouldn't block sets failOpen.
+                const msg = err?.message ?? String(err);
+                // eslint-disable-next-line no-console
+                console.warn(`[omni.gate] policy '${policy.id}' threw: ${msg}`);
+                if (policy.failOpen) {
+                    decision = null;
+                }
+                else {
+                    return {
+                        behavior: 'deny',
+                        message: `Blocked '${toolName}': the '${policy.id}' safety check could not complete ` +
+                            `(${msg}). This is a fail-closed refusal, not a policy decision — retry, ` +
+                            `and if it persists the check itself is broken.`,
+                        interrupt: false,
+                    };
+                }
+            }
+            if (!decision)
+                continue;
+            if ('deny' in decision) {
+                return {
+                    behavior: 'deny',
+                    message: decision.message,
+                    interrupt: decision.interrupt ?? false,
+                };
+            }
+            if ('allow' in decision && decision.updatedInput) {
+                workingInput = decision.updatedInput;
+            }
+        }
+        // No policy denied. Allow with whatever accumulated transforms.
+        return {
+            behavior: 'allow',
+            updatedInput: workingInput,
+        };
+    };
+}