@intutic/gate 1.10.1

package/dist/eve.js

@@ -0,0 +1,378 @@
+/**
+ * eve adapter: `intuticApproval()`, `intuticConnectionApproval()`,
+ * `intuticAuditHooks()`.
+ *
+ * `@intutic/gate/eve` — a framework-specific specialization of the same idea
+ * `wrapTools.ts` implements generically (see that file's module doc): wrap the
+ * framework's own veto point around this package's `Gate.guard()`.
+ *
+ * eve (npm `eve`, github.com/vercel/eve) is Vercel's filesystem-first
+ * framework for durable backend AI agents: an agent is a directory (`agent/`
+ * with `instructions.md`, `agent/tools/*.ts`, `agent/connections/*.ts`,
+ * `agent/hooks/*.ts`, ...) that eve builds by walking the tree. It is a
+ * pre-1.0 PREVIEW product (0.39.1 at the time of writing, very active) —
+ * see docs/TECH_DEBT.md TD-410 for the churn shield this adapter carries,
+ * the same posture the dsh integration established.
+ *
+ * ## The veto mechanism — CONFIRMED against a real install, not assumed
+ *
+ * `eve@0.39.1` is installed as a devDependency of this package and its
+ * shipped `.d.ts` files were read directly (not inferred from docs alone).
+ * eve's per-tool veto point is the `approval` property on a tool definition
+ * (`dist/src/public/definitions/tool.d.ts`), and the same `Approval` type is
+ * accepted per-connection by `defineMcpClientConnection` /
+ * `defineOpenAPIConnection` (`dist/src/public/definitions/connections/
+ * {mcp,openapi}.d.ts`), gating ALL of that connection's tools. There is NO
+ * agent-level default approval field (`agent.d.ts` carries zero approval
+ * fields — verified) — attaching a shared policy per tool/connection is
+ * eve's own documented multi-tenant pattern
+ * (`docs/patterns/multi-tenant-approvals.md`), and exactly the shape this
+ * adapter exports.
+ *
+ * The confirmed policy contract (`dist/src/public/definitions/approval.d.ts`):
+ *
+ * ```ts
+ * export interface ApprovalContext<TInput = Record<string, unknown>> extends SessionContext {
+ *   readonly approvedTools: ReadonlySet<string>
+ *   readonly callId: string
+ *   readonly toolInput?: ApprovalToolInput<TInput>   // Readonly<TInput> | TInput; CAN be undefined
+ *   readonly toolName: string
+ * }
+ * export type ApprovalStatus = undefined | boolean
+ *   | 'not-applicable' | 'approved' | 'denied' | 'user-approval'
+ *   | { readonly type: 'not-applicable'; readonly reason?: never }
+ *   | { readonly type: 'approved'; readonly reason?: string }
+ *   | { readonly type: 'denied'; readonly reason?: string }
+ *   | { readonly type: 'user-approval'; readonly reason?: never }
+ * export type ApprovalPolicy<TInput = Record<string, unknown>> =
+ *   (ctx: ApprovalContext<TInput>) => ApprovalStatus | Promise<ApprovalStatus>
+ * ```
+ *
+ * These are AI SDK 7 approval statuses (eve is built on `ai` v7 — the same
+ * family `vercel.ts` documents). `'denied'` / `{ type: 'denied', reason }`
+ * vetoes the call before execution; `reason` reaches the model in place of a
+ * tool result. `'not-applicable'` (and `undefined`) means "continue without a
+ * prompt"; `'user-approval'` parks the run durably for a human. The boolean
+ * forms are back-compat for eve's earlier predicate shape: `true` is treated
+ * as `'user-approval'` and `false` as `'not-applicable'` (confirmed in
+ * `docs/tools/human-in-the-loop.md`) — this adapter never RETURNS booleans,
+ * but its structural {@link EveApprovalStatus} copy includes them so the type
+ * stays field-for-field faithful to the real union.
+ *
+ * ## Allow-shape: why `'not-applicable'` and not `'approved'`
+ *
+ * Unlike the Vercel AI SDK's `toolApproval` (a separate, whole-run config
+ * that coexists with per-tool mechanisms), eve's `approval` IS the tool's one
+ * approval policy — whatever this function returns is the whole decision for
+ * that call. On allow this adapter returns `'not-applicable'` by default:
+ * eve's own "no prompt needed, continue" value, matching the semantics of an
+ * omitted `approval` (`never()`). It deliberately does NOT return
+ * `'approved'`: that value asserts an affirmative approval decision this gate
+ * did not make (Intutic's allow is "no objection", not "signed off"), and its
+ * interaction with eve's `approvedTools` bookkeeping (`once()` keys off that
+ * set) is not something this adapter verified. Callers who want eve's human
+ * flow ON TOP of the governance gate set `{ onAllow: 'user-approval' }` —
+ * "governance has no objection; still ask a person" — or compose manually
+ * (see {@link intuticApproval}).
+ *
+ * ## Audit hooks — observe-only, and honestly scoped
+ *
+ * eve's hook surface (`agent/hooks/*.ts`, `dist/src/public/definitions/
+ * hook.d.ts`) exposes `approval.candidate` / `approval.settled` stream
+ * events. Handlers are OBSERVE-ONLY by eve's own contract ("fire after eve
+ * has accepted and durably recorded each event ... cannot inject model
+ * context") — {@link intuticAuditHooks} is telemetry, not enforcement; the
+ * enforcement surface is {@link intuticApproval}. LOAD-BEARING caveat,
+ * verified against `dist/src/protocol/message.d.ts`: these two events carry
+ * `requestId`/`responderPrincipalId`/`turnId`/`stepIndex` but NOT the tool
+ * name or input.
+ *
+ * TD-411 half 2, revisited: `intuticApproval()` and `intuticAuditHooks()` are
+ * both plain functions exported from this one module and cannot be assumed to
+ * run in the same process at settlement time — eve's own docs state a parked
+ * approval survives a process restart verbatim ("the process can restart and
+ * the parked turn survives", `docs/tools/human-in-the-loop.md`), so a
+ * `requestId -> toolName` map populated at approval-decision time and read
+ * back later inside the hook would silently degrade for exactly the durable,
+ * long-parked approvals this mechanism exists for — the worst kind of fix,
+ * correct in local testing and quietly wrong in the deployments that matter
+ * most. That map was NOT built.
+ *
+ * What WAS found and built instead needs no cross-call memory at all: eve
+ * ships a THIRD hookable event, `input.requested` (confirmed in the same
+ * `HookEventMap`, `dist/src/public/definitions/hook.d.ts`), fired once when a
+ * batch of human-input requests is created — including every `kind:
+ * 'tool-approval'` request `intuticApproval()`'s `'user-approval'` return
+ * value produces. Each request in that ONE event already carries
+ * `requestId` AND `action.toolName` TOGETHER (`InputRequest`,
+ * `dist/src/runtime/input/types.d.ts`'s `inputRequestSchema` — confirmed by
+ * the shipped zod schema, not just prose; corroborated by
+ * `docs/tools/human-in-the-loop.md`'s explicit statement that "`toolName` and
+ * `requestId` identify the action and request"). {@link intuticAuditHooks}
+ * now subscribes to it too: it emits a real, tool-identified `tool_flagged`
+ * event at REQUEST time (closing the "no tool identity" gap unconditionally,
+ * with no process-boundary risk — the whole payload arrives in one event),
+ * and best-effort caches `requestId -> toolName` in memory so the LATER
+ * `approval.candidate`/`approval.settled` events attribute to the real tool
+ * name too WHEN this cache is still warm (same-process, or a short-lived
+ * pause). When it is not — a genuinely long-parked, cross-restart approval —
+ * settlement still falls back to the synthetic {@link EVE_APPROVAL_TOOL_NAME},
+ * exactly the pre-existing behaviour, never worse. See TD-411 for the full
+ * reasoning and what a persistent (non-memory) correlation store would take
+ * to close that residual gap.
+ *
+ * ## LLM egress — documented honestly, not oversold
+ *
+ * eve routes models through the Vercel AI Gateway by default (a gateway model
+ * id string in `agent.ts`'s `defineAgent({ model })`, `AI_GATEWAY_API_KEY` /
+ * `VERCEL_OIDC_TOKEN` credentials — confirmed in `docs/agent-config.md` and
+ * `docs/getting-started.mdx`). The AI Gateway wire protocol is NOT something
+ * the Intutic proxy parses, so gateway-routed egress is ungoverned by the
+ * proxy — full stop, and TD-412 tracks it. The governable path is eve's
+ * other documented option: passing a provider-authored `LanguageModel`
+ * (`createOpenAI(...)` etc.) to `defineAgent({ model })`, where the
+ * `withIntuticProxy()` helper — implemented once in `vercel.ts` and
+ * re-exported here — applies exactly as it does for the plain Vercel AI SDK.
+ * As with that framework, there is no env-var base-URL override: routing is
+ * in-code, per provider-construction call site.
+ *
+ * @module
+ */
+import { active as activeGate } from './gate.js';
+import { GateClient } from './client.js';
+import { IntuticGateRefusal } from './errors.js';
+// One routing story, one implementation: eve's direct-provider path is the
+// Vercel AI SDK's (eve is built on `ai` v7), so the helper is re-exported
+// rather than duplicated. See vercel.ts for the full module doc.
+export { intuticProxyUrl, withIntuticProxy } from './vercel.js';
+/** Synthetic tool name used by {@link intuticAuditHooks} — eve's
+ *  `approval.candidate`/`approval.settled` events do not carry the real tool
+ *  name (verified against `dist/src/protocol/message.d.ts`; see module doc). */
+export const EVE_APPROVAL_TOOL_NAME = 'eve:approval';
+/**
+ * Render an eve `toolInput` as the `tool_input` object {@link Gate.guard}
+ * evaluates.
+ *
+ * Mirrors dsh.ts's `renderDshToolInput` (same reasoning as its own mirror of
+ * `wrapTools.ts`'s non-exported `renderToolInput`): a plain object passes
+ * through as-is; `undefined` (which eve documents as possible — "toolInput
+ * can be undefined, so guard the access") becomes `{}`; any other non-object
+ * value falls back to `{ args: [...] }` so the gate still has something to
+ * evaluate.
+ */
+function renderEveToolInput(input) {
+    if (input === undefined)
+        return {};
+    if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+        return input;
+    }
+    return { args: [input] };
+}
+/**
+ * Builds an approval policy matching eve's `ApprovalPolicy` signature, for
+ * direct use as a tool definition's `approval` field:
+ *
+ * ```ts
+ * // agent/tools/refund_charge.ts
+ * import { defineTool } from 'eve/tools'
+ * import { z } from 'zod'
+ * import { intuticApproval } from '@intutic/gate/eve'
+ *
+ * export default defineTool({
+ *   description: 'Refund a charge.',
+ *   inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
+ *   approval: intuticApproval(),
+ *   async execute(input) {
+ *     return refund(input)
+ *   },
+ * })
+ * ```
+ *
+ * (Install the gate once, process-wide, e.g. in `agent.ts`:
+ * `install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))`.)
+ *
+ * Resolves to `'not-applicable'` on allow (or `opts.onAllow` — see
+ * {@link IntuticApprovalOptions.onAllow}) and to `{ type: 'denied', reason }`
+ * on refusal — `reason` is the `[Intutic Governance] BLOCKED: ...` message,
+ * handed back to the model in place of a tool result; the tool's `execute`
+ * never runs.
+ *
+ * Requires a `Gate` — either passed via `{ gate }` here, or installed
+ * process-wide with `install(new Gate(...))`. A call with neither throws,
+ * refusing to run the tool unguarded rather than silently skipping
+ * enforcement — same posture as `wrapTool`/`intuticHooks`/
+ * `intuticToolApproval`. A non-refusal crash inside the gate is re-thrown
+ * rather than mapped to a denial — eve's own approval docs direct policies to
+ * "throw or deny, never silently allow", and a thrown policy fails the turn
+ * (fail closed), matching vercel.ts's posture for the same status family.
+ */
+export function intuticApproval(opts = {}) {
+    return async (ctx) => {
+        const g = opts.gate ?? activeGate();
+        if (g === null) {
+            throw new Error('No gate configured: call install(new Gate(...)) from @intutic/gate, or pass ' +
+                '{ gate } to intuticApproval(). Refusing to run the tool unguarded.');
+        }
+        try {
+            await g.guard(ctx.toolName, renderEveToolInput(ctx.toolInput));
+            return opts.onAllow ?? 'not-applicable';
+        }
+        catch (exc) {
+            if (exc instanceof IntuticGateRefusal) {
+                return { type: 'denied', reason: exc.message };
+            }
+            throw exc;
+        }
+    };
+}
+/**
+ * The same policy, shaped for a CONNECTION's `approval` field — eve's MCP and
+ * OpenAPI connections accept one `approval` gating ALL of that connection's
+ * tools (`defineMcpClientConnection`/`defineOpenAPIConnection`, confirmed at
+ * `dist/src/public/definitions/connections/{mcp,openapi}.d.ts` — an omitted
+ * `approval` means every connection tool executes without approval):
+ *
+ * ```ts
+ * // agent/connections/support.ts
+ * import { defineMcpClientConnection } from 'eve/connections'
+ * import { intuticConnectionApproval } from '@intutic/gate/eve'
+ *
+ * export default defineMcpClientConnection({
+ *   url: 'https://support.example.com/mcp',
+ *   description: 'Support tickets.',
+ *   approval: intuticConnectionApproval(),
+ * })
+ * ```
+ *
+ * Implemented AS {@link intuticApproval} (one enforcement path, not two) —
+ * the separate export exists because the surface differs in one way worth
+ * knowing: `ctx.toolName` for a connection tool is the QUALIFIED name
+ * (`support__add_internal_note`, connection slug + `__` + remote tool name —
+ * eve's own convention, per `docs/patterns/multi-tenant-approvals.md`), and
+ * that qualified name is what `Gate.guard()` evaluates and what SOP rules /
+ * snapshot `tool:` subjects must match. This adapter deliberately does not
+ * strip the prefix: the qualified name is the call's real identity inside
+ * this eve app, and un-prefixing would let two connections' same-named remote
+ * tools collapse into one rule target.
+ */
+export function intuticConnectionApproval(opts = {}) {
+    return intuticApproval(opts);
+}
+/**
+ * Observe-only audit emitter for eve's human-approval lifecycle, shaped for
+ * `agent/hooks/`:
+ *
+ * ```ts
+ * // agent/hooks/intutic-audit.ts
+ * import { defineHook } from 'eve/hooks'
+ * import { intuticAuditHooks } from '@intutic/gate/eve'
+ *
+ * export default defineHook(intuticAuditHooks())
+ * ```
+ *
+ * Maps eve's approval stream events onto Intutic's gate event vocabulary
+ * (the same `tool_allowed`/`tool_blocked`/`tool_flagged` names `gate.ts`
+ * emits, so the dashboard renders both sources on one timeline):
+ *
+ * - `input.requested`, one `kind: 'tool-approval'` request → `tool_flagged`,
+ *   under the REAL tool name (`request.action.toolName`) — a genuinely new
+ *   signal this adapter did not emit before: a call is now pending human
+ *   approval. See the module doc (TD-411) for why this event, not a
+ *   process-memory map, is what closes "no tool identity" here.
+ * - `approval.settled` `outcome: 'approved'` → `tool_allowed` — a human
+ *   explicitly approved the parked call.
+ * - `approval.settled` `outcome: 'cancelled'` → `tool_blocked` — the request
+ *   was settled without approval; the call never ran. This is a HUMAN veto
+ *   recorded for audit, not an Intutic-gate refusal (the reason string says
+ *   so), and like every `tool_blocked` it creates an incident row.
+ * - `approval.candidate` non-`'pending'` outcomes (`rejected`/`failed`/
+ *   `timed-out`/`stale`) → `tool_flagged` — a responder's attempt to answer
+ *   went somewhere worth an operator's attention. `'pending'` (a candidate
+ *   simply being created) is routine lifecycle and deliberately NOT emitted.
+ *
+ * `approval.candidate`/`approval.settled` attribute to the REAL tool name
+ * when this instance's in-memory `requestId -> toolName` cache (populated
+ * by `input.requested`) is still warm, and fall back to the synthetic
+ * {@link EVE_APPROVAL_TOOL_NAME} otherwise — see the module doc for why that
+ * fallback exists and is not itself a bug.
+ *
+ * These hooks are TELEMETRY, not enforcement: eve runs hook handlers after
+ * events are durably recorded, and they cannot veto anything (eve's own
+ * "observe-only" hook contract). The enforcement surface is
+ * {@link intuticApproval}. Handlers never throw — a telemetry failure must
+ * not break the run (`GateClient.emit`'s own never-throws contract).
+ */
+export function intuticAuditHooks(opts = {}) {
+    const perSession = new Map();
+    // Best-effort, same-process-only. Populated by `input.requested` (which
+    // carries requestId and toolName together already — no correlation is
+    // needed to populate it) and consulted by `approval.candidate`/
+    // `approval.settled` (which do not carry toolName at all). Evicted on
+    // `approval.settled` — the terminal event for a requestId, after which it
+    // is never looked up again. A process that restarts between request and
+    // settlement (eve's own docs say this is expected and safe for eve itself
+    // — "the process can restart and the parked turn survives") simply finds
+    // this map empty and falls back to EVE_APPROVAL_TOOL_NAME, exactly this
+    // function's behaviour before this cache existed. See TD-411.
+    const requestIdToToolName = new Map();
+    function clientFor(sessionId) {
+        if (opts.client !== undefined)
+            return opts.client;
+        let client = perSession.get(sessionId);
+        if (client === undefined) {
+            try {
+                client = GateClient.fromEnv({ harness: 'eve', sessionId });
+            }
+            catch {
+                // fromEnv only throws on a missing session id, which we always
+                // supply — but a telemetry hook must never take the run down over a
+                // client it could not build.
+                client = null;
+            }
+            perSession.set(sessionId, client);
+        }
+        return client;
+    }
+    return {
+        events: {
+            'input.requested': async (event, ctx) => {
+                const client = clientFor(ctx.session.id);
+                for (const request of event.data.requests) {
+                    if (request.kind !== 'tool-approval' || request.action === undefined)
+                        continue;
+                    requestIdToToolName.set(request.requestId, request.action.toolName);
+                    if (client === null)
+                        continue;
+                    await client.emit('tool_flagged', request.action.toolName, `eve requested human approval before running this tool (request ${request.requestId})`, request.action.input);
+                }
+            },
+            'approval.candidate': async (event, ctx) => {
+                if (event.data.outcome === 'pending')
+                    return;
+                const client = clientFor(ctx.session.id);
+                if (client === null)
+                    return;
+                const toolName = requestIdToToolName.get(event.data.requestId) ?? EVE_APPROVAL_TOOL_NAME;
+                const suffix = event.data.reason ? `: ${event.data.reason}` : '';
+                await client.emit('tool_flagged', toolName, `eve approval candidate ${event.data.outcome} (request ${event.data.requestId}, ` +
+                    `responder ${event.data.responderPrincipalId})${suffix}`, event.data);
+            },
+            'approval.settled': async (event, ctx) => {
+                const client = clientFor(ctx.session.id);
+                const toolName = requestIdToToolName.get(event.data.requestId) ?? EVE_APPROVAL_TOOL_NAME;
+                requestIdToToolName.delete(event.data.requestId);
+                if (client === null)
+                    return;
+                if (event.data.outcome === 'approved') {
+                    await client.emit('tool_allowed', toolName, `eve approval settled: approved by ${event.data.responderPrincipalId} ` +
+                        `(request ${event.data.requestId})`, event.data);
+                    return;
+                }
+                await client.emit('tool_blocked', toolName, `eve approval settled: cancelled — the parked tool call never ran ` +
+                    `(request ${event.data.requestId}, responder ${event.data.responderPrincipalId}). ` +
+                    `Human veto recorded by the observe-only audit hook, not an Intutic gate refusal.`, event.data);
+            },
+        },
+    };
+}
+//# sourceMappingURL=eve.js.map

package/dist/eve.js.map

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

package/dist/gate.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The enforcement point.
+ *
+ * Port of `packages/intutic-clawde/intutic_clawde/gate/gate.py`.
+ *
+ * Intutic ships PreToolUse hooks for the harnesses it has a native adapter
+ * for; frameworks outside that list (Mastra, the Vercel AI SDK, LangChain.js,
+ * a hand-rolled loop) have no adapter, and the sync-daemon writes no
+ * PreToolUse hook for them. This package is that enforcement point: the
+ * missing adapter, written against Intutic's own published gate contract.
+ *
+ * Four tiers, in order — identical precedence to the Python SDK:
+ *
+ *   A1  policy snapshot   port of intuticGate()          fails CLOSED
+ *   A3  SOP rules         authored in the product        fails OPEN (A2 covers it)
+ *   A2  image integrity   local check                    fails CLOSED
+ *   B   POST /hook-gate   control-plane check             fail posture set by GateClient
+ *
+ * A1 and A2 are load-bearing and local. Tier B contributes the DLP regexes
+ * and workspace policy from the control plane; whether an unreachable control
+ * plane blocks is the client's `failClosed` setting (default true).
+ *
+ * Tier A3 applies rules written in the SOP register rather than in code. It
+ * runs BEFORE A2 so that a block, when both would fire, is attributed to the
+ * authored policy rather than to the hardcoded one. It fails open because A2
+ * covers the identical case and fails closed: A3 moves where the policy is
+ * *written*, and is not what makes the run safe. See soprules.ts.
+ *
+ * ## Naming note for callers porting from other Intutic SDKs
+ *
+ * This is NOT the "static floor" tier the compiled shell/JS gate emitters
+ * carry (`staticFloorPatterns()` in
+ * `services/sync-daemon/src/harness/protectedPaths.ts`, concatenated ahead of
+ * the snapshot's own rules in `gateBody.ts`'s `intuticGate()`). Like the
+ * Python SDK it ports, this package's Tier A1 reads ONLY
+ * `~/.intutic/hooks/policy-snapshot.rules` — the compiled-in bypass/secret/
+ * skill-surface patterns never reach that file (only SOP-authored rules, the
+ * destructive-command tier, and the tier-promoted skill-surface rules do, via
+ * `buildSnapshotRules` in `services/sync-daemon/src/lib/policySnapshot.ts`).
+ * A workspace relying on this SDK for governance therefore gets a strict
+ * SUBSET of what a shipped shell/JS harness gate enforces. That gap already
+ * exists in the Python SDK this package ports; it is not introduced here. See
+ * `src/__tests__/fidelity.test.ts` for the parts of the shipped contract this
+ * package's Tier A1 DOES reproduce exactly (the destructive-command and
+ * skill-surface pattern tables, as they would arrive via a real snapshot).
+ */
+import { GateClient } from './client.js';
+import * as imagecheck from './imagecheck.js';
+import * as snapshot from './snapshot.js';
+import * as soprules from './soprules.js';
+/** Tools that cannot change anything. They still get the local snapshot check
+ *  (Tier A1), but skip the remote gate call (Tier B). */
+export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
+export interface GateConfig {
+    repoRoot?: string;
+    workspaceId?: string;
+    allowlistPath?: string;
+    enforce?: boolean;
+    useHookGate?: boolean;
+    useSopRules?: boolean;
+}
+interface ResolvedConfig {
+    repoRoot: string;
+    workspaceId: string;
+    allowlistPath: string;
+    enforce: boolean;
+    useHookGate: boolean;
+    useSopRules: boolean;
+}
+export type ToolInput = Record<string, unknown>;
+export declare class Gate {
+    readonly cfg: ResolvedConfig;
+    readonly client: GateClient | null;
+    private _snapshot;
+    private _snapshotReported;
+    private _policy;
+    /** `null` = not fetched yet. A failed fetch caches `[]` so one unreachable
+     *  control plane does not add a timeout to every subsequent tool call. */
+    private _sopRules;
+    constructor(cfg?: GateConfig, client?: GateClient | null);
+    private allowlistAbs;
+    getSnapshot(): snapshot.Snapshot;
+    /**
+     * Load the image allowlist.
+     *
+     * A missing or malformed allowlist is NOT treated as "allow everything".
+     * An empty policy with `require_digest` still refuses every unpinned
+     * image, which is the safe direction; a policy we cannot read at all
+     * throws, and the caller turns that into a block.
+     */
+    getPolicy(): imagecheck.ImagePolicy;
+    /**
+     * Active SOP rules, fetched once per process.
+     *
+     * Deliberately not refreshed on a timer: a rule set that changes mid-run
+     * makes a verdict depend on when the fetch landed. Construct a new `Gate`
+     * (or clear the cache) to refresh.
+     */
+    getSopRules(): Promise<soprules.SopRule[]>;
+    private emit;
+    /**
+     * Report snapshot condition exactly once per process — otherwise these
+     * states are computed and never read, and an operator cannot distinguish
+     * "snapshot missing on 400 machines" from "snapshot healthy".
+     */
+    private reportSnapshotHealthOnce;
+    /** Throws {@link IntuticGateRefusal} if this call must not run. Resolves to allow. */
+    guard(toolName: string, toolInput: ToolInput): Promise<void>;
+}
+export declare function install(gate: Gate | null): void;
+export declare function active(): Gate | null;
+export {};
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;yDACyD;AACzD,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAM9C,CAAA;AAEF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,OAAO,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB;AAaD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE/C,qBAAa,IAAI;IACf,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IAClC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,OAAO,CAAsC;IACrD;8EAC0E;IAC1E,OAAO,CAAC,SAAS,CAAkC;gBAEvC,GAAG,GAAE,UAAe,EAAE,MAAM,GAAE,UAAU,GAAG,IAAW;IAKlE,OAAO,CAAC,YAAY;IAOpB,WAAW,IAAI,QAAQ,CAAC,QAAQ;IAOhC;;;;;;;OAOG;IACH,SAAS,IAAI,UAAU,CAAC,WAAW;IAwBnC;;;;;;OAMG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAwBlC,IAAI;IAalB;;;;OAIG;YACW,wBAAwB;IAWtC,sFAAsF;IAChF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAqGnE;AA0BD,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAE/C;AAED,wBAAgB,MAAM,IAAI,IAAI,GAAG,IAAI,CAEpC"}