@clawkeepers/gatekeeper-kit 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ControlStackAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,206 @@
+OpenClaw OS
+Copyright (c) 2026 ControlStackAI
+Original project contributions are licensed under the MIT License; see LICENSE.
+Third-party and adapted material retains its applicable license terms.
+
+OpenClaw (https://github.com/openclaw/openclaw) provides the separately installed,
+unmodified agent runtime, Gateway and public plugin interfaces. Its pinned
+v2026.9.2 license is MIT, copyright (c) 2026 OpenClaw Foundation; its own
+THIRD_PARTY_NOTICES.md applies to incorporated upstream dependencies.
+
+Cloudflare OS (https://github.com/cloudflare/cloudflare-os), by Cloudflare and
+its contributors, provides architectural foundations and adapted material:
+capability introductions, gatekeepers, approval/simulation contracts, observers,
+and kernel review/authoring guidance. OpenClaw OS contributors modified these
+contracts and documents for a self-hosted, single-process, tool-calling plugin
+runtime. Cloudflare OS Starter (https://github.com/cloudflare/cloudflare-os-starter)
+informed wrapper-owned customization and the upgrade discipline.
+
+Cloudflare OS and Cloudflare OS Starter are Apache-2.0 licensed. Their retained
+material is not relicensed by the project's MIT license. The applicable Apache
+License 2.0 text is reproduced below. The original source distribution includes
+further provenance in docs/acknowledgments.md. Other dependencies retain their
+respective licenses and notices, including generated THIRD-PARTY-NOTICES for
+bundled dependencies.
+
+This is an independent project, not an upstream-endorsed product. No affiliation,
+endorsement or rights to upstream trademarks are implied.
+
+--- Apache License 2.0: retained Cloudflare material ---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,10 @@
+# @clawkeepers/gatekeeper-kit
+
+Security-critical helpers for gatekeeper authors. Start with [SKELETON.md](SKELETON.md).
+
+Includes the validated lifecycle builder, two-stage OAuth nonces, encrypted account storage with refresh coalescing,
+persistent simulation stores, action sequencing, a resource-session base class, fixed-message error sanitization, and
+an offline test queue. Kernel authorization and tool registration remain exclusively the kernel's responsibility.
+
+Phase 2 acceptance is library-only: `scripts/vm/test.sh phase-2`. No Gateway, external API, or production state is used.
+See the skeleton's ordering/recovery section for single-writer ownership, uncertain-action handling and sync approval binding.

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import * as openclaw_plugin_sdk_plugin_entry from 'openclaw/plugin-sdk/plugin-entry';
+import * as _clawkeepers_shared from '@clawkeepers/shared';
+import { SupportedResource, GatekeeperToolDef, ActionDescription, GatekeeperVendor, Gatekeeper, ApprovalQueue, GatekeeperSession, ObserverVerifier, ObservationDescription, SessionCallContext } from '@clawkeepers/shared';
+
+/** Gatekeeper declaration: metadata is separate from instance-bound implementations. */
+interface GatekeeperDefinition {
+    vendor: string;
+    apiVersion: 1;
+    id: `gatekeeper-${string}`;
+    name: string;
+    description: string;
+    resources: SupportedResource[];
+    tools: GatekeeperToolDef[];
+    /** Pure descriptions are mandatory for all declared action tools; instance implementations are checked again on calls. */
+    actions?: Record<string, {
+        describe(params: Record<string, unknown>): ActionDescription | Promise<ActionDescription>;
+    }>;
+    createVendor(ctx: VendorContext): GatekeeperVendor;
+}
+/** Lifecycle-owned vendor configuration. No OpenClaw registration API is handed to a driver. */
+interface VendorContext {
+    pluginConfig: Record<string, unknown>;
+    stateDir: string;
+    logger: {
+        debug(message: string): void;
+        info(message: string): void;
+        warn(message: string): void;
+        error(message: string): void;
+    };
+}
+/** Cell/root identity the kernel must compare to its trusted catalog before using a live driver. */
+interface GatekeeperRuntimeIdentity {
+    pluginId: string;
+    vendor: string;
+    apiVersion: 1;
+    stateDir: string;
+    root: string;
+}
+/** Lifecycle slot. Its vendor and every retained account/resource/session fail closed after revocation. */
+interface GatekeeperRuntime extends GatekeeperRuntimeIdentity {
+    getVendor(): GatekeeperVendor;
+    revoke(): void;
+}
+/** Access transport only: the kernel still validates enablement/catalog identity and uses resolveGrant(). */
+declare function gatekeeperRuntimeSlot(pluginId: string): {
+    setRuntime: (next: GatekeeperRuntime) => void;
+    clearRuntime: () => void;
+    tryGetRuntime: () => GatekeeperRuntime | null;
+    getRuntime: () => GatekeeperRuntime;
+};
+/** Validate before loading a vendor; never registers tools or starts services in discovery modes. */
+declare function defineGatekeeper(def: GatekeeperDefinition): Omit<{
+    id: string;
+    name: string;
+    description: string;
+    kind?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["kind"];
+    configSchema?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema | (() => openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema);
+    reload?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["securityAuditCollectors"];
+    register: NonNullable<openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["register"]>;
+}, "configSchema"> & {
+    configSchema: openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema;
+};
+
+/** One pending local effect, identified by the action's durable per-instance id. */
+interface OverlayEntry {
+    actionId: number;
+    kind: string;
+    payload: unknown;
+}
+/** Overlay-at-read effects. File-backed instances survive restart; one cell process owns each file. */
+declare class OverlayStore {
+    private readonly path?;
+    private state;
+    constructor(path?: string | undefined);
+    private load;
+    private save;
+    /** Allocate a negative simulated identifier without colliding with remote positive ids. */
+    nextTempId(): number;
+    /** Add exactly one effect per queued action; duplicate IDs are rejected. */
+    add(entry: OverlayEntry): void;
+    /** Retire a rejected or applied action. Missing ids are harmless. */
+    remove(actionId: number): void;
+    /** Return detached pending entries in action-id order. */
+    list(): OverlayEntry[];
+    /** Merge pending effects without allowing reducers to mutate the authoritative read or stored entries. */
+    applyTo<T>(value: T, mergers: Record<string, (value: T, entry: OverlayEntry) => T>): T;
+}
+
+/** Side-effect-free description, local simulation, and explicit remote application. */
+interface ActionImpl<P = Record<string, unknown>> {
+    describe(params: P): ActionDescription | Promise<ActionDescription>;
+    simulate?(params: P, overlay: OverlayStore, actionId: number): unknown | Promise<unknown>;
+    apply(params: P, actionId: number): Promise<{
+        remoteId?: string;
+        value?: unknown;
+    } | void>;
+    revert?(record: {
+        actionId: number;
+        remoteId?: string;
+        params: P;
+    }): Promise<void>;
+}
+/** Observations describe before reading; the kit owns authorization and never hands them a write queue. */
+interface ObservationImpl<P = Record<string, unknown>> {
+    describe(params: P): _clawkeepers_shared.ObservationDescription | Promise<_clawkeepers_shared.ObservationDescription>;
+    read(params: P): Promise<unknown>;
+}
+/** Base resource driver. Only the kernel may create its sessions through resolveGrant(). */
+declare abstract class KitGatekeeper<State = unknown> implements Gatekeeper {
+    private readonly journalPath?;
+    abstract resource: SupportedResource;
+    observations: Record<string, ObservationImpl>;
+    actions: Record<string, ActionImpl>;
+    protected abstract overlay: OverlayStore;
+    private records;
+    private readonly sequence;
+    constructor(journalPath?: string | undefined);
+    private save;
+    private record;
+    private assertSettled;
+    private recoverOverlay;
+    private impl;
+    describe(): Promise<{
+        resource: SupportedResource;
+        title: string;
+        suggestedName: string;
+    }>;
+    getAutoApprovableActions(): Promise<never[]>;
+    /** Bind a kernel queue; dry passes never read vendors, reserve ids, submit actions or modify overlays. */
+    startSession(queue: ApprovalQueue): Promise<GatekeeperSession>;
+    private applyRecorded;
+    /** Apply once after the kernel's operator decision. Ambiguous remote failures are never blindly retried. */
+    applyAction(actionId: number): Promise<void>;
+    /** Remove a pending effect. An ambiguous submission/application requires operator reconciliation instead. */
+    rejectAction(actionId: number): Promise<void>;
+    /** Revert once using only the recorded remote identifier and original parameters. */
+    revertAction(actionId: number): Promise<void>;
+    /** v1 defaults to private-only; granting observers is never inferred from resource metadata. */
+    addObserver(_id: string, _verifier: ObserverVerifier): Promise<void>;
+    removeObserver(_id: string): Promise<void>;
+}
+
+/** Two-stage, operator-bound OAuth nonces. Advancing never extends the original lifetime. */
+declare class OAuthNonceMachine {
+    private readonly ttlMs;
+    private readonly now;
+    private pending;
+    constructor(ttlMs?: number, now?: () => number);
+    /** Issue the first nonce for a local operator-initiated authorization flow. */
+    issue(operatorId: string): string;
+    /** Consume stage one and mint a distinct callback nonce for stage two. */
+    advance(nonce: string): string | null;
+    /** Rotate stage one while returning its trusted binding to the authorization router. */
+    advanceBound(nonce: string): {
+        nonce: string;
+        operatorId: string;
+    } | null;
+    /** Consume only a stage-two callback, exactly once. Invalid, expired and replayed values deny. */
+    consume(nonce: string): string | null;
+    private take;
+    /** Remove expired records without accepting them. */
+    sweep(): void;
+}
+
+/** AES-256-GCM account storage. Ciphertext is bound to both canonical store and exact operator identity. */
+declare class TokenStore {
+    private readonly key;
+    private readonly dir;
+    private refreshes;
+    private generations;
+    constructor(dir: string, cellKey: Buffer);
+    private path;
+    private aad;
+    /** Encrypt and atomically replace one account record; plaintext is never written. */
+    put(operatorId: string, value: unknown): void;
+    /** Return null only for an absent account. Tampering, wrong keys and corrupt envelopes fail closed. */
+    get<T = unknown>(operatorId: string): T | null;
+    /** Delete an account and invalidate any in-flight refresh so it cannot restore revoked credentials. */
+    remove(operatorId: string): void;
+    /** Share one refresh per account. A concurrent put/remove makes its stale result fail closed. */
+    refresh<T>(operatorId: string, operation: () => Promise<T>): Promise<T>;
+}
+
+/** Mutate-the-cache simulation with an authoritative base retained for rejection and refresh replay. */
+declare class CacheMutationStore<T> {
+    private readonly reducers;
+    private readonly path?;
+    private state;
+    private view;
+    constructor(base: T, reducers: Record<string, (value: T, entry: OverlayEntry) => T>, path?: string | undefined);
+    private replay;
+    private save;
+    /** Return a detached view containing all pending effects. */
+    read(): T;
+    /** Apply one new effect to the cached view after its action was queued. */
+    add(entry: OverlayEntry): void;
+    /** Reject one action and rebuild the view from the authoritative base. */
+    remove(actionId: number): void;
+    /** Refresh authoritative data and replay all pending actions in order. */
+    refresh(base: T): void;
+    /** Retire an applied effect together with the refreshed authoritative data. */
+    commit(actionId: number, base: T): void;
+}
+
+/** Per-instance monotonic action ids and single-flight lifecycle scheduling; file ownership is one cell process. */
+declare class ActionSequencer {
+    private readonly path?;
+    private nextId;
+    private tail;
+    constructor(path?: string | undefined, minimum?: number);
+    private load;
+    /** Reserve an id durably before it can be submitted to the kernel queue. */
+    next(): number;
+    /** Serialize operations and remain usable after a rejected operation. */
+    run<T>(operation: () => Promise<T>): Promise<T>;
+}
+
+/** Emit only a fixed message and a structured numeric HTTP status; never vendor error strings or bodies. */
+declare function sanitizeError(error: unknown): string;
+
+/** Offline unit-test queue; never use it as a production authority or conformance substitute. */
+declare class TestApprovalQueue implements ApprovalQueue {
+    readonly observations: ObservationDescription[];
+    readonly actions: Array<{
+        id: number;
+        description: ActionDescription;
+    }>;
+    denyObservations: boolean;
+    denyActions: boolean;
+    authorizeObservation(description: ObservationDescription): Promise<void>;
+    submitAction(id: number, description: ActionDescription): Promise<void>;
+    /** Construct a deterministic unit-test call context. */
+    context(toolCallId?: string): SessionCallContext;
+}
+
+export { type ActionImpl, ActionSequencer, CacheMutationStore, type GatekeeperDefinition, type GatekeeperRuntime, type GatekeeperRuntimeIdentity, KitGatekeeper, OAuthNonceMachine, type ObservationImpl, type OverlayEntry, OverlayStore, TestApprovalQueue, TokenStore, type VendorContext, defineGatekeeper, gatekeeperRuntimeSlot, sanitizeError };

package/dist/index.js

@@ -0,0 +1,686 @@
+// src/define-gatekeeper.ts
+import { realpathSync } from "fs";
+import { Value } from "typebox/value";
+import { GatekeeperToolDefSchema, SupportedResourceSchema } from "@clawkeepers/shared";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+var forbidden = /approv|oauth|cache|queue|simulat/i;
+function gatekeeperRuntimeSlot(pluginId) {
+  if (!/^gatekeeper-[a-z][a-z0-9_]*$/.test(pluginId)) throw new Error("Invalid gatekeeper id.");
+  return createPluginRuntimeStore({ pluginId, errorMessage: "Gatekeeper unavailable." });
+}
+function defineGatekeeper(def) {
+  if (!/^[a-z][a-z0-9_]*$/.test(def.vendor) || def.id !== `gatekeeper-${def.vendor}` || def.apiVersion !== 1) throw new Error("Invalid gatekeeper identity.");
+  const resources = /* @__PURE__ */ new Map();
+  for (const resource of def.resources) {
+    if (!Value.Check(SupportedResourceSchema, resource) || resources.has(resource.type)) throw new Error("Invalid or duplicate resource.");
+    resources.set(resource.type, resource);
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const tool of def.tools) {
+    if (forbidden.test(tool.description)) throw new Error("Tool description leaks internals.");
+    if (!Value.Check(GatekeeperToolDefSchema, JSON.parse(JSON.stringify(tool))) || !tool.name.startsWith(`gk_${def.vendor}_`) || names.has(tool.name)) throw new Error("Invalid or duplicate tool name/metadata.");
+    const parameters = tool.parameters;
+    const properties = parameters.properties;
+    const required = parameters.required;
+    if (parameters.type !== "object" || !properties || !Object.hasOwn(properties, "grant") || properties.grant?.type !== "string" || !Array.isArray(required) || !required.includes("grant")) throw new Error("Tool requires a string grant parameter.");
+    if (!resources.get(tool.resourceType)?.tools.includes(tool.name)) throw new Error("Tool resource mapping mismatch.");
+    if (tool.kind === "action" && (!def.actions || !Object.hasOwn(def.actions, tool.name) || typeof def.actions[tool.name]?.describe !== "function")) throw new Error("Action tool requires describe().");
+    names.add(tool.name);
+  }
+  for (const resource of resources.values()) for (const name2 of resource.tools) {
+    if (!def.tools.some((tool) => tool.name === name2 && tool.resourceType === resource.type)) throw new Error("Resource tool mapping mismatch.");
+  }
+  for (const name2 of Object.keys(def.actions ?? {})) if (!def.tools.some((tool) => tool.name === name2 && tool.kind === "action")) throw new Error("Undeclared action implementation.");
+  const { id, vendor, apiVersion, name, description, createVendor } = def;
+  return definePluginEntry({ id, name, description, register(api) {
+    if (api.id !== id) throw new Error("Plugin identity mismatch.");
+    if (api.registrationMode !== "full") return;
+    const slot = gatekeeperRuntimeSlot(id);
+    let owned;
+    api.registerService({ id: `${id}-driver`, start(ctx) {
+      if (!api.rootDir) throw new Error("Plugin root unavailable.");
+      const root = realpathSync(api.rootDir), stateDir = realpathSync(ctx.stateDir);
+      const instance = createVendor({ pluginConfig: structuredClone(api.pluginConfig ?? {}), stateDir, logger: { debug: (message) => ctx.logger.debug?.(message), info: (message) => ctx.logger.info(message), warn: (message) => ctx.logger.warn(message), error: (message) => ctx.logger.error(message) } });
+      if (instance.vendor !== vendor || instance.apiVersion !== apiVersion) throw new Error("Vendor identity mismatch.");
+      let active = true;
+      const guard = () => {
+        if (!active || slot.tryGetRuntime() !== owned) throw new Error("Gatekeeper unavailable.");
+      };
+      const wrapped = revocable(instance, guard);
+      const runtime = {
+        pluginId: id,
+        vendor,
+        apiVersion,
+        root,
+        stateDir,
+        getVendor() {
+          guard();
+          return wrapped;
+        },
+        revoke() {
+          active = false;
+        }
+      };
+      slot.tryGetRuntime()?.revoke();
+      owned = runtime;
+      slot.setRuntime(runtime);
+    }, stop() {
+      owned?.revoke();
+      if (owned && slot.tryGetRuntime() === owned) slot.clearRuntime();
+      owned = void 0;
+    } });
+  } });
+}
+function revocable(root, guard) {
+  const cache = /* @__PURE__ */ new WeakMap();
+  function wrap(value) {
+    if (value === null || typeof value !== "object" && typeof value !== "function") return value;
+    const existing = cache.get(value);
+    if (existing) return existing;
+    const proxy = new Proxy(value, {
+      get(target, key) {
+        guard();
+        const member = Reflect.get(target, key, target);
+        if (typeof member !== "function") return wrap(member);
+        return (...args) => {
+          guard();
+          const result2 = Reflect.apply(member, target, args);
+          if (result2 instanceof Promise) return result2.then((resolved) => {
+            guard();
+            return wrap(resolved);
+          });
+          guard();
+          return wrap(result2);
+        };
+      }
+    });
+    cache.set(value, proxy);
+    return proxy;
+  }
+  return wrap(root);
+}
+
+// src/kit-gatekeeper.ts
+import { isDeepStrictEqual } from "util";
+import { Value as Value2 } from "typebox/value";
+import { ActionDescriptionSchema, ObservationDescriptionSchema } from "@clawkeepers/shared";
+
+// src/atomic-json.ts
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { randomBytes } from "crypto";
+function writeJsonAtomic(path, value) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const temp = join(dir, `.clawos-${randomBytes(16).toString("hex")}.tmp`);
+  let fd;
+  try {
+    fd = openSync(temp, "wx", 384);
+    writeFileSync(fd, JSON.stringify(value), "utf8");
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = void 0;
+    renameSync(temp, path);
+    const directory = openSync(dir, "r");
+    try {
+      fsyncSync(directory);
+    } finally {
+      closeSync(directory);
+    }
+  } finally {
+    if (fd !== void 0) closeSync(fd);
+    try {
+      unlinkSync(temp);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw new Error("Invalid persisted state.");
+  }
+}
+
+// src/overlay-store.ts
+function validEntries(value) {
+  return Array.isArray(value) && value.every((e) => e && Number.isSafeInteger(e.actionId) && e.actionId > 0 && typeof e.kind === "string" && e.kind.length > 0 && "payload" in e) && new Set(value.map((e) => e.actionId)).size === value.length;
+}
+var OverlayStore = class {
+  constructor(path) {
+    this.path = path;
+    this.load();
+  }
+  state = { version: 1, tempId: -1, entries: [] };
+  load() {
+    if (!this.path) return;
+    const raw = readJson(this.path);
+    if (raw === void 0) return;
+    const value = raw;
+    if (value.version !== 1 || !Number.isSafeInteger(value.tempId) || value.tempId >= 0 || !validEntries(value.entries)) throw new Error("Invalid overlay state.");
+    this.state = value;
+  }
+  save(next) {
+    if (this.path) writeJsonAtomic(this.path, next);
+    this.state = next;
+  }
+  /** Allocate a negative simulated identifier without colliding with remote positive ids. */
+  nextTempId() {
+    this.load();
+    if (this.state.tempId <= Number.MIN_SAFE_INTEGER) throw new Error("Temporary id space exhausted.");
+    const id = this.state.tempId;
+    this.save({ ...this.state, tempId: id - 1 });
+    return id;
+  }
+  /** Add exactly one effect per queued action; duplicate IDs are rejected. */
+  add(entry) {
+    this.load();
+    const entries = [...this.state.entries, structuredClone(entry)].sort((a, b) => a.actionId - b.actionId);
+    if (!validEntries(entries)) throw new Error("Invalid or duplicate overlay action.");
+    this.save({ ...this.state, entries });
+  }
+  /** Retire a rejected or applied action. Missing ids are harmless. */
+  remove(actionId) {
+    this.load();
+    this.save({ ...this.state, entries: this.state.entries.filter((e) => e.actionId !== actionId) });
+  }
+  /** Return detached pending entries in action-id order. */
+  list() {
+    this.load();
+    return structuredClone(this.state.entries);
+  }
+  /** Merge pending effects without allowing reducers to mutate the authoritative read or stored entries. */
+  applyTo(value, mergers) {
+    return this.list().reduce((result2, entry) => {
+      const merge = Object.hasOwn(mergers, entry.kind) ? mergers[entry.kind] : void 0;
+      if (!merge) throw new Error("Unknown simulation action kind.");
+      return merge(result2, entry);
+    }, structuredClone(value));
+  }
+};
+
+// src/action-sequencer.ts
+var ActionSequencer = class {
+  constructor(path, minimum = 1) {
+    this.path = path;
+    if (!Number.isSafeInteger(minimum) || minimum < 1) throw new Error("Invalid action sequence minimum.");
+    this.nextId = minimum;
+    this.load();
+  }
+  nextId = 1;
+  tail = Promise.resolve();
+  load() {
+    if (!this.path) return;
+    const raw = readJson(this.path);
+    if (raw === void 0) return;
+    const state = raw;
+    if (state.version !== 1 || !Number.isSafeInteger(state.next) || state.next < 1) throw new Error("Invalid action sequence.");
+    this.nextId = Math.max(this.nextId, state.next);
+  }
+  /** Reserve an id durably before it can be submitted to the kernel queue. */
+  next() {
+    this.load();
+    if (this.nextId >= Number.MAX_SAFE_INTEGER) throw new Error("Action id space exhausted.");
+    const id = this.nextId;
+    if (this.path) writeJsonAtomic(this.path, { version: 1, next: id + 1 });
+    this.nextId = id + 1;
+    return id;
+  }
+  /** Serialize operations and remain usable after a rejected operation. */
+  run(operation) {
+    const result2 = this.tail.then(operation);
+    this.tail = result2.then(() => {
+    }, () => {
+    });
+    return result2;
+  }
+};
+
+// src/sanitize.ts
+function sanitizeError(error) {
+  let status;
+  try {
+    if (error !== null && typeof error === "object" && "status" in error) status = error.status;
+  } catch {
+  }
+  return typeof status === "number" && Number.isInteger(status) && status >= 400 && status <= 599 ? `The operation failed. (status ${status})` : "The operation failed.";
+}
+
+// src/kit-gatekeeper.ts
+var KitGatekeeper = class {
+  constructor(journalPath) {
+    this.journalPath = journalPath;
+    if (journalPath) {
+      const raw = readJson(journalPath);
+      if (raw !== void 0) {
+        const value = raw;
+        if (value.version !== 1 || !Array.isArray(value.records)) throw new Error("Invalid action journal.");
+        for (const record of value.records) {
+          if (!Number.isSafeInteger(record.id) || record.id < 1 || this.records.has(record.id) || typeof record.tool !== "string" || !record.params || typeof record.params !== "object" || !Value2.Check(ActionDescriptionSchema, record.description) || !["submitting", "pending", "applying", "applied", "rejected", "reverting", "reverted", "uncertain"].includes(record.status)) throw new Error("Invalid action journal.");
+          this.records.set(record.id, record);
+        }
+      }
+    }
+    this.sequence = new ActionSequencer(journalPath ? `${journalPath}.sequence` : void 0, [...this.records.keys()].reduce((max, id) => Math.max(max, id), 0) + 1);
+  }
+  observations = {};
+  actions = {};
+  records = /* @__PURE__ */ new Map();
+  sequence;
+  save(record) {
+    const records = new Map(this.records);
+    records.set(record.id, structuredClone(record));
+    if (this.journalPath) writeJsonAtomic(this.journalPath, { version: 1, records: [...records.values()] });
+    this.records = records;
+  }
+  record(id) {
+    const record = this.records.get(id);
+    if (!record) throw new Error("Unknown action.");
+    return structuredClone(record);
+  }
+  assertSettled() {
+    if ([...this.records.values()].some((record) => ["submitting", "applying", "reverting", "uncertain"].includes(record.status))) throw new Error("Action outcome requires reconciliation.");
+  }
+  async recoverOverlay() {
+    this.assertSettled();
+    for (const entry of this.overlay.list()) {
+      if (this.records.get(entry.actionId)?.status !== "pending") this.overlay.remove(entry.actionId);
+    }
+    for (const record of this.records.values()) {
+      if (record.status === "pending" && !record.description.awaitDecision && !this.overlay.list().some((entry) => entry.actionId === record.id)) {
+        const impl = this.impl(record.tool);
+        if (!impl.simulate) throw new Error("Simulation implementation missing.");
+        await impl.simulate(structuredClone(record.params), this.overlay, record.id);
+      }
+    }
+  }
+  impl(tool) {
+    const impl = Object.hasOwn(this.actions, tool) ? this.actions[tool] : void 0;
+    if (!impl || typeof impl.describe !== "function" || typeof impl.apply !== "function") throw new Error("Action implementation missing.");
+    return impl;
+  }
+  async describe() {
+    return { resource: this.resource, title: this.resource.title, suggestedName: this.resource.type.toUpperCase() };
+  }
+  async getAutoApprovableActions() {
+    return [];
+  }
+  /** Bind a kernel queue; dry passes never read vendors, reserve ids, submit actions or modify overlays. */
+  async startSession(queue) {
+    await this.sequence.run(() => this.recoverOverlay());
+    let closed = false;
+    const live = () => {
+      if (closed) throw new Error("Session closed.");
+      this.assertSettled();
+    };
+    return {
+      close: async () => {
+        closed = true;
+      },
+      call: async (tool, input, ctx) => {
+        try {
+          live();
+          this.assertSettled();
+          if (ctx.queue !== queue || !ctx.agentId || !ctx.sessionKey || (ctx.observers?.length ?? 0) > 0) throw new Error("Session authority unavailable.");
+          const params = structuredClone(input);
+          if (!this.resource.tools.includes(tool)) throw new Error("Tool outside resource.");
+          const observation = Object.hasOwn(this.observations, tool) ? this.observations[tool] : void 0;
+          if (observation) {
+            const description2 = await observation.describe(structuredClone(params));
+            if (!Value2.Check(ObservationDescriptionSchema, description2)) throw new Error("Invalid observation description.");
+            live();
+            if (ctx.dryRun) return { kind: "observation", description: description2 };
+            await queue.authorizeObservation(description2);
+            live();
+            const value = await observation.read(params);
+            live();
+            return result(value);
+          }
+          const impl = this.impl(tool), description = await impl.describe(structuredClone(params));
+          if (!Value2.Check(ActionDescriptionSchema, description) || description.implementsRevert && !impl.revert) throw new Error("Invalid action description.");
+          if (!description.awaitDecision && !impl.simulate) throw new Error("Action simulation missing.");
+          live();
+          if (ctx.dryRun) return { kind: "action", description };
+          if (description.awaitDecision && !approved(tool, params, ctx)) throw new Error("Action approval missing.");
+          return await this.sequence.run(async () => {
+            live();
+            this.assertSettled();
+            const callKey = ctx.toolCallId ? JSON.stringify([ctx.agentId, ctx.sessionKey, ctx.toolCallId]) : void 0;
+            if (callKey && [...this.records.values()].some((record2) => record2.callKey === callKey)) throw new Error("Action call already submitted.");
+            const id = this.sequence.next();
+            const record = { id, tool, params, description, status: "submitting", ...callKey ? { callKey } : {} };
+            this.save(record);
+            try {
+              await queue.submitAction(id, description);
+            } catch {
+              this.save({ ...record, status: "uncertain" });
+              throw new Error("Action submission failed.");
+            }
+            this.save({ ...record, status: "pending" });
+            try {
+              live();
+              if (description.awaitDecision) {
+                const value2 = await this.applyRecorded(id);
+                live();
+                return result(value2);
+              }
+              const value = await impl.simulate(structuredClone(params), this.overlay, id);
+              live();
+              if (!this.overlay.list().some((entry) => entry.actionId === id)) throw new Error("Simulation effect missing.");
+              return result(value);
+            } catch {
+              this.overlay.remove(id);
+              const current = this.record(id);
+              if (current.status === "pending") this.save({ ...current, status: "uncertain" });
+              throw new Error("Action did not complete.");
+            }
+          });
+        } catch (error) {
+          throw new Error(sanitizeError(error));
+        }
+      }
+    };
+  }
+  async applyRecorded(id) {
+    const record = this.record(id);
+    if (record.status === "applied") {
+      this.overlay.remove(id);
+      return void 0;
+    }
+    if (record.status !== "pending") throw new Error("Action is not pending.");
+    if ([...this.records.values()].some((other) => other.id < id && !["applied", "rejected", "reverted"].includes(other.status))) throw new Error("Earlier action must be decided first.");
+    this.save({ ...record, status: "applying" });
+    let applied;
+    try {
+      applied = await this.impl(record.tool).apply(structuredClone(record.params), id);
+    } catch {
+      this.save({ ...record, status: "uncertain" });
+      throw new Error("Application outcome uncertain.");
+    }
+    this.save({ ...record, status: "applied", ...applied?.remoteId ? { remoteId: applied.remoteId } : {} });
+    this.overlay.remove(id);
+    return applied?.value;
+  }
+  /** Apply once after the kernel's operator decision. Ambiguous remote failures are never blindly retried. */
+  async applyAction(actionId) {
+    try {
+      await this.sequence.run(async () => {
+        await this.applyRecorded(actionId);
+      });
+    } catch (error) {
+      throw new Error(sanitizeError(error));
+    }
+  }
+  /** Remove a pending effect. An ambiguous submission/application requires operator reconciliation instead. */
+  async rejectAction(actionId) {
+    await this.sequence.run(async () => {
+      const record = this.record(actionId);
+      if (record.status === "rejected") {
+        this.overlay.remove(actionId);
+        return;
+      }
+      if (record.status !== "pending") throw new Error("Action is not pending.");
+      this.save({ ...record, status: "rejected" });
+      this.overlay.remove(actionId);
+    });
+  }
+  /** Revert once using only the recorded remote identifier and original parameters. */
+  async revertAction(actionId) {
+    try {
+      await this.sequence.run(async () => {
+        const record = this.record(actionId);
+        if (record.status === "reverted") return;
+        const impl = this.impl(record.tool);
+        if (record.status !== "applied" || !record.description.implementsRevert || !impl.revert) throw new Error("Action cannot be reverted.");
+        this.save({ ...record, status: "reverting" });
+        try {
+          await impl.revert({ actionId, params: structuredClone(record.params), ...record.remoteId ? { remoteId: record.remoteId } : {} });
+        } catch {
+          this.save({ ...record, status: "uncertain" });
+          throw new Error("Revert outcome uncertain.");
+        }
+        this.save({ ...record, status: "reverted" });
+      });
+    } catch (error) {
+      throw new Error(sanitizeError(error));
+    }
+  }
+  /** v1 defaults to private-only; granting observers is never inferred from resource metadata. */
+  async addObserver(_id, _verifier) {
+    throw new Error("Shared access is unavailable.");
+  }
+  async removeObserver(_id) {
+  }
+};
+function result(value) {
+  const encoded = JSON.stringify(value ?? { ok: true });
+  if (encoded === void 0) throw new Error("Invalid tool result.");
+  return { content: [{ type: "text", text: encoded }], details: JSON.parse(encoded) };
+}
+function approved(tool, params, ctx) {
+  const approval = ctx.actionApproval;
+  return !!ctx.toolCallId && approval?.toolCallId === ctx.toolCallId && approval.tool === tool && isDeepStrictEqual(approval.params, params);
+}
+
+// src/oauth-nonce.ts
+import { randomBytes as randomBytes2, timingSafeEqual } from "crypto";
+var OAuthNonceMachine = class {
+  constructor(ttlMs = 10 * 6e4, now = Date.now) {
+    this.ttlMs = ttlMs;
+    this.now = now;
+  }
+  pending = /* @__PURE__ */ new Map();
+  /** Issue the first nonce for a local operator-initiated authorization flow. */
+  issue(operatorId) {
+    if (!operatorId) throw new Error("Operator required.");
+    this.sweep();
+    const nonce = randomBytes2(24).toString("base64url");
+    this.pending.set(nonce, { operatorId, expiresAt: this.now() + this.ttlMs, stage: 1 });
+    return nonce;
+  }
+  /** Consume stage one and mint a distinct callback nonce for stage two. */
+  advance(nonce) {
+    return this.advanceBound(nonce)?.nonce ?? null;
+  }
+  /** Rotate stage one while returning its trusted binding to the authorization router. */
+  advanceBound(nonce) {
+    const record = this.take(nonce, 1);
+    if (!record) return null;
+    const next = randomBytes2(24).toString("base64url");
+    this.pending.set(next, { ...record, stage: 2 });
+    return { nonce: next, operatorId: record.operatorId };
+  }
+  /** Consume only a stage-two callback, exactly once. Invalid, expired and replayed values deny. */
+  consume(nonce) {
+    return this.take(nonce, 2)?.operatorId ?? null;
+  }
+  take(nonce, stage) {
+    if (!/^[A-Za-z0-9_-]{32}$/.test(nonce)) return null;
+    for (const [key, record] of this.pending) {
+      if (timingSafeEqual(Buffer.from(key), Buffer.from(nonce))) {
+        this.pending.delete(key);
+        return record.stage === stage && record.expiresAt > this.now() ? record : null;
+      }
+    }
+    return null;
+  }
+  /** Remove expired records without accepting them. */
+  sweep() {
+    for (const [key, record] of this.pending) if (record.expiresAt <= this.now()) this.pending.delete(key);
+  }
+};
+
+// src/token-store.ts
+import { createCipheriv, createDecipheriv, createHash, randomBytes as randomBytes3 } from "crypto";
+import { chmodSync, mkdirSync as mkdirSync2, realpathSync as realpathSync2, unlinkSync as unlinkSync2 } from "fs";
+import { join as join2 } from "path";
+var TokenStore = class {
+  key;
+  dir;
+  refreshes = /* @__PURE__ */ new Map();
+  generations = /* @__PURE__ */ new Map();
+  constructor(dir, cellKey) {
+    if (cellKey.length !== 32) throw new Error("A 32-byte cell key is required.");
+    mkdirSync2(dir, { recursive: true, mode: 448 });
+    chmodSync(dir, 448);
+    this.dir = realpathSync2(dir);
+    this.key = Buffer.from(cellKey);
+  }
+  path(id) {
+    if (!id) throw new Error("Operator required.");
+    return join2(this.dir, `${createHash("sha256").update(id).digest("hex")}.json`);
+  }
+  aad(id) {
+    return Buffer.from(JSON.stringify(["clawos-token-v1", this.dir, id]));
+  }
+  /** Encrypt and atomically replace one account record; plaintext is never written. */
+  put(operatorId, value) {
+    const path = this.path(operatorId);
+    const plaintext = JSON.stringify(value);
+    if (plaintext === void 0) throw new Error("Token record must be JSON.");
+    const iv = randomBytes3(12), cipher = createCipheriv("aes-256-gcm", this.key, iv);
+    cipher.setAAD(this.aad(operatorId));
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    writeJsonAtomic(path, { v: 1, iv: iv.toString("base64"), tag: cipher.getAuthTag().toString("base64"), ct: ct.toString("base64") });
+    this.generations.set(operatorId, (this.generations.get(operatorId) ?? 0) + 1);
+  }
+  /** Return null only for an absent account. Tampering, wrong keys and corrupt envelopes fail closed. */
+  get(operatorId) {
+    const path = this.path(operatorId);
+    try {
+      const data = readJson(path);
+      if (data === void 0) return null;
+      const j = data;
+      if (j.v !== 1 || typeof j.iv !== "string" || typeof j.tag !== "string" || typeof j.ct !== "string") throw new Error();
+      const iv = Buffer.from(j.iv, "base64"), tag = Buffer.from(j.tag, "base64");
+      if (iv.length !== 12 || tag.length !== 16) throw new Error();
+      const decipher = createDecipheriv("aes-256-gcm", this.key, iv);
+      decipher.setAAD(this.aad(operatorId));
+      decipher.setAuthTag(tag);
+      return JSON.parse(Buffer.concat([decipher.update(Buffer.from(j.ct, "base64")), decipher.final()]).toString("utf8"));
+    } catch {
+      throw new Error("Credential record could not be decrypted.");
+    }
+  }
+  /** Delete an account and invalidate any in-flight refresh so it cannot restore revoked credentials. */
+  remove(operatorId) {
+    const path = this.path(operatorId);
+    try {
+      unlinkSync2(path);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw new Error("Credential removal failed.");
+    }
+    this.generations.set(operatorId, (this.generations.get(operatorId) ?? 0) + 1);
+  }
+  /** Share one refresh per account. A concurrent put/remove makes its stale result fail closed. */
+  refresh(operatorId, operation) {
+    this.path(operatorId);
+    const existing = this.refreshes.get(operatorId);
+    if (existing) return existing;
+    const generation = this.generations.get(operatorId) ?? 0;
+    const pending = Promise.resolve().then(operation).then((value) => {
+      if ((this.generations.get(operatorId) ?? 0) !== generation) throw new Error("Credential refresh superseded.");
+      this.put(operatorId, value);
+      return value;
+    }).catch(() => {
+      throw new Error("Credential refresh failed.");
+    });
+    this.refreshes.set(operatorId, pending);
+    void pending.finally(() => {
+      if (this.refreshes.get(operatorId) === pending) this.refreshes.delete(operatorId);
+    }).catch(() => {
+    });
+    return pending;
+  }
+};
+
+// src/cache-mutation-store.ts
+var CacheMutationStore = class {
+  constructor(base, reducers, path) {
+    this.reducers = reducers;
+    this.path = path;
+    this.state = { version: 1, base: structuredClone(base), pending: [] };
+    if (path) {
+      const raw = readJson(path);
+      if (raw !== void 0) {
+        if (raw.version !== 1 || !validEntries(raw.pending) || !("base" in raw)) throw new Error("Invalid cache state.");
+        this.state = raw;
+      }
+    }
+    this.view = this.replay(this.state);
+  }
+  state;
+  view;
+  replay(state) {
+    return structuredClone(state.pending).reduce((value, entry) => {
+      const reduce = Object.hasOwn(this.reducers, entry.kind) ? this.reducers[entry.kind] : void 0;
+      if (!reduce) throw new Error("Unknown simulation action kind.");
+      return reduce(value, entry);
+    }, structuredClone(state.base));
+  }
+  save(next) {
+    const view = this.replay(next);
+    if (this.path) writeJsonAtomic(this.path, next);
+    this.state = next;
+    this.view = view;
+  }
+  /** Return a detached view containing all pending effects. */
+  read() {
+    return structuredClone(this.view);
+  }
+  /** Apply one new effect to the cached view after its action was queued. */
+  add(entry) {
+    const pending = [...this.state.pending, structuredClone(entry)].sort((a, b) => a.actionId - b.actionId);
+    if (!validEntries(pending)) throw new Error("Invalid or duplicate cache action.");
+    this.save({ ...this.state, pending });
+  }
+  /** Reject one action and rebuild the view from the authoritative base. */
+  remove(actionId) {
+    this.save({ ...this.state, pending: this.state.pending.filter((e) => e.actionId !== actionId) });
+  }
+  /** Refresh authoritative data and replay all pending actions in order. */
+  refresh(base) {
+    this.save({ ...this.state, base: structuredClone(base) });
+  }
+  /** Retire an applied effect together with the refreshed authoritative data. */
+  commit(actionId, base) {
+    this.save({ version: 1, base: structuredClone(base), pending: this.state.pending.filter((e) => e.actionId !== actionId) });
+  }
+};
+
+// src/testing.ts
+var TestApprovalQueue = class {
+  observations = [];
+  actions = [];
+  denyObservations = false;
+  denyActions = false;
+  async authorizeObservation(description) {
+    if (this.denyObservations) throw new Error("Observation denied.");
+    this.observations.push(structuredClone(description));
+  }
+  async submitAction(id, description) {
+    if (this.denyActions) throw new Error("Action denied.");
+    if (this.actions.some((action) => action.id === id)) throw new Error("Duplicate action.");
+    this.actions.push({ id, description: structuredClone(description) });
+  }
+  /** Construct a deterministic unit-test call context. */
+  context(toolCallId = "test-call") {
+    return { agentId: "test-agent", sessionKey: "test-session", toolCallId, queue: this };
+  }
+};
+export {
+  ActionSequencer,
+  CacheMutationStore,
+  KitGatekeeper,
+  OAuthNonceMachine,
+  OverlayStore,
+  TestApprovalQueue,
+  TokenStore,
+  defineGatekeeper,
+  gatekeeperRuntimeSlot,
+  sanitizeError
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@clawkeepers/gatekeeper-kit",
+  "version": "0.1.0-beta.1",
+  "description": "Builder and security-critical helpers for OpenClaw OS gatekeepers.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "dependencies": {
+    "typebox": "1.1.39",
+    "@clawkeepers/shared": "0.1.0-beta.1"
+  },
+  "devDependencies": {
+    "tsup": "8.5.0",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4",
+    "@types/node": "22.18.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.9.2 <2026.11.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawkeeper/openclaw-os.git",
+    "directory": "packages/gatekeeper-kit"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}