@watchlight/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Watchlight AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,117 @@
+# @watchlight/sdk
+
+Govern your Node/TypeScript agent's tools with a **fail-closed, in-process
+policy decision** — zero infrastructure. Declare an intent, wrap a tool, and the
+call is authorized against your Cedar policies before it runs; denied calls throw
+and their body never executes. Every decision lands in a **value-free**
+`.watchlight/audit.jsonl`.
+
+This is the TypeScript counterpart of the Python `watchlight` package. It is thin
+glue over [`@watchlight/engine`](https://www.npmjs.com/package/@watchlight/engine)
+(the real `wl-apdp` Cedar core compiled to WebAssembly) and contains **no
+decision logic** — every ALLOW/DENY comes from the engine.
+
+## Install
+
+```bash
+npm install @watchlight/sdk
+```
+
+## Govern a tool
+
+```ts
+import { govern, Denied } from "@watchlight/sdk";
+
+govern.load("watchlight.policy.json"); // or govern.allow('permit(principal, action == Action::"research", resource);')
+
+const webSearch = govern.tool(async (q: string) => search(q), { intent: "research" });
+const transferFunds = govern.tool(async (amt: number) => bank.send(amt), { intent: "transfer" });
+
+await webSearch("cedar policy");   // ALLOW → runs
+try {
+  await transferFunds(1000);       // no policy permits "transfer" → DENY
+} catch (e) {
+  if (e instanceof Denied) console.error(e.message); // never executed
+}
+```
+
+TypeScript uses a higher-order function (`govern.tool(fn, { intent })`) rather
+than a decorator — it works across every TS build setup with full type
+inference. Governed functions are always async (the engine's authorize path is
+async in WebAssembly).
+
+Fail-closed by default: with no matching policy, every governed call is denied.
+
+## Sub-agent scope attenuation
+
+Derive strictly-narrower child scopes for sub-agents; the real engine enforces
+strict-subset, so a child can never hold a capability its parent lacks.
+
+```ts
+const root = await govern.scope({ tools: ["read", "search"], timeBudgetSeconds: 600 });
+const child = root.attenuate({ tools: ["read"] });        // ⊆ parent → OK
+root.attenuate({ tools: ["read", "write"] });             // escalation → throws AttenuationDenied
+```
+
+The Developer Edition governs the tree up to depth `DE_MAX_DEPTH` (5); beyond it,
+`attenuate` throws `DevEditionCeiling`. Enterprise removes the cap and enforces
+it server-side.
+
+## Claude Agent SDK
+
+Govern an SDK-managed agent's tool calls with a `PreToolUse` gate — no glue in
+your tool bodies. Denied tools are blocked by the SDK before they run.
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { govern, governedHooks } from "@watchlight/sdk";
+
+govern.load("watchlight.policy.json");
+
+// Map Claude tool names → governance intents.
+const TOOL_INTENTS: Record<string, string> = { WebSearch: "research", Bash: "execute" };
+const { hooks } = governedHooks({ intentFor: (t) => TOOL_INTENTS[t] ?? t });
+
+for await (const msg of query({ prompt, options: { hooks } })) {
+  // WebSearch runs if a policy permits "research"; anything unpermitted is
+  // denied before execution.
+}
+```
+
+The hook is fail-closed and never throws back to the SDK — a governance error
+denies the call. Every decision is audited.
+
+## Value-free audit
+
+`.watchlight/audit.jsonl` records **who / what intent / which tool / the
+decision** — never argument values. Same contract as the production audit trail.
+
+```json
+{"ts":"2026-08-29T…Z","agent":"my-agent","intent":"research","resource":"tool/webSearch","decision":"Allow"}
+```
+
+## Graduation to Enterprise
+
+Set `WATCHLIGHT_APDP_URL` and the **same code** authorizes against the networked
+Watchlight control plane (signed lineage, cross-tenant isolation, IdP/mTLS
+attestation) instead of the in-process engine — no policy or code change. The
+authorize request/response shape is identical; only the transport swaps.
+
+```bash
+export WATCHLIGHT_APDP_URL=https://apdp.example.com   # → networked (Enterprise)
+export WATCHLIGHT_PLUGIN_TOKEN=...                     # bearer for the control plane
+export WATCHLIGHT_TENANT_ID=...                        # X-Wl-Tenant-Id
+# unset WATCHLIGHT_APDP_URL → in-process (Developer Edition)
+```
+
+Or per-instance: `new Watchlight({ apdpUrl, token, tenantId })`. Check which is
+live with `governor.mode` (`"in-process"` | `"networked"`). Networked mode is
+fail-closed — an unreachable control plane denies. Sub-agent `attenuate()` runs
+in-process in the DE; under `WATCHLIGHT_APDP_URL` it is enforced server-side, so
+`scope()` defers to the control plane.
+
+## License
+
+Apache-2.0. The compiled engine it depends on (`@watchlight/engine`) is under the
+Watchlight Developer Edition License (free for development, testing, and
+production — including commercially — up to 25 governed agents per organization).

package/dist/attenuation.d.ts

@@ -0,0 +1,63 @@
+import type { Engine } from "@watchlight/engine";
+/** Developer-Edition sub-agent tree depth ceiling. */
+export declare const DE_MAX_DEPTH = 5;
+/** Raised at the Developer-Edition depth ceiling. NOT a policy denial — a
+ *  product boundary. Every attenuation up to the cap was a real, engine-validated
+ *  strict subset. */
+export declare class DevEditionCeiling extends Error {
+    readonly depth: number;
+    readonly cap: number;
+    constructor(depth: number);
+}
+/** Raised when a requested child scope is not a strict subset of its parent. */
+export declare class AttenuationDenied extends Error {
+    readonly violations: string[];
+    readonly reason: string;
+    constructor(violations: string[], reason: string);
+}
+export interface AttenuateOptions {
+    tools?: readonly string[];
+    resources?: readonly string[];
+    intents?: readonly string[];
+    timeBudgetSeconds?: number;
+}
+interface ScopeInit {
+    engine: Engine;
+    auditPath: string;
+    agent: string;
+    allowedTools: string[];
+    allowedResources: string[];
+    allowedIntents: string[];
+    maxDepth: number;
+    timeBudgetSeconds: number;
+    depth: number;
+    parentId?: string;
+}
+/** A capability scope that can spawn strictly-narrower child scopes. Create the
+ *  root with {@link Watchlight.scope}; call {@link attenuate} to derive a
+ *  sub-agent scope. `attenuate` is synchronous (the engine validator is sync). */
+export declare class Scope {
+    readonly agent: string;
+    readonly allowedTools: string[];
+    readonly allowedResources: string[];
+    readonly allowedIntents: string[];
+    readonly maxDepth: number;
+    readonly timeBudgetSeconds: number;
+    readonly depth: number;
+    readonly nodeId: string;
+    readonly parentId?: string;
+    private readonly _engine;
+    private readonly _auditPath;
+    constructor(init: ScopeInit);
+    /**
+     * Derive a sub-agent scope — a strict subset of this one. Any dimension you
+     * omit inherits the parent's (and the engine clamps it regardless). Throws
+     * {@link AttenuationDenied} if the request exceeds the parent, and
+     * {@link DevEditionCeiling} at the Developer-Edition depth ceiling.
+     */
+    attenuate(opts?: AttenuateOptions): Scope;
+    /** Record this scope as the root of an attenuation tree (parent-less). */
+    emitRoot(): void;
+    private _record;
+}
+export {};

package/dist/attenuation.js

@@ -0,0 +1,207 @@
+"use strict";
+// Sub-agent scope attenuation — the TS mirror of Python `watchlight.attenuation`.
+//
+// A Scope is a capability set that can spawn strictly-narrower child scopes. Any
+// dimension a child requests that the parent does not hold is denied by the real
+// engine strict-subset validator (@watchlight/engine), and every attenuation is
+// written to the value-free audit trail. The Developer Edition governs the tree
+// up to DE_MAX_DEPTH; Enterprise removes the cap and enforces it server-side.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scope = exports.AttenuationDenied = exports.DevEditionCeiling = exports.DE_MAX_DEPTH = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+/** Developer-Edition sub-agent tree depth ceiling. */
+exports.DE_MAX_DEPTH = 5;
+const CEILING_NOTICE = (cap, depth) => `Developer Edition governs sub-agent trees up to depth ${cap}; ` +
+    `requested depth ${depth}. Enterprise removes this cap and enforces it server-side.`;
+/** Raised at the Developer-Edition depth ceiling. NOT a policy denial — a
+ *  product boundary. Every attenuation up to the cap was a real, engine-validated
+ *  strict subset. */
+class DevEditionCeiling extends Error {
+    constructor(depth) {
+        super(CEILING_NOTICE(exports.DE_MAX_DEPTH, depth));
+        this.name = "DevEditionCeiling";
+        this.depth = depth;
+        this.cap = exports.DE_MAX_DEPTH;
+    }
+}
+exports.DevEditionCeiling = DevEditionCeiling;
+/** Raised when a requested child scope is not a strict subset of its parent. */
+class AttenuationDenied extends Error {
+    constructor(violations, reason) {
+        super(`sub-agent scope denied: ${reason}`);
+        this.name = "AttenuationDenied";
+        this.violations = violations;
+        this.reason = reason;
+    }
+}
+exports.AttenuationDenied = AttenuationDenied;
+const norm = (x) => (x ? [...x] : []);
+const nodeId = () => crypto.randomBytes(4).toString("hex");
+/** A capability scope that can spawn strictly-narrower child scopes. Create the
+ *  root with {@link Watchlight.scope}; call {@link attenuate} to derive a
+ *  sub-agent scope. `attenuate` is synchronous (the engine validator is sync). */
+class Scope {
+    constructor(init) {
+        this._engine = init.engine;
+        this._auditPath = init.auditPath;
+        this.agent = init.agent;
+        this.allowedTools = norm(init.allowedTools);
+        this.allowedResources = norm(init.allowedResources);
+        this.allowedIntents = norm(init.allowedIntents);
+        this.maxDepth = init.maxDepth;
+        this.timeBudgetSeconds = init.timeBudgetSeconds;
+        this.depth = init.depth;
+        this.nodeId = nodeId();
+        this.parentId = init.parentId;
+    }
+    /**
+     * Derive a sub-agent scope — a strict subset of this one. Any dimension you
+     * omit inherits the parent's (and the engine clamps it regardless). Throws
+     * {@link AttenuationDenied} if the request exceeds the parent, and
+     * {@link DevEditionCeiling} at the Developer-Edition depth ceiling.
+     */
+    attenuate(opts = {}) {
+        const childDepth = this.depth + 1;
+        const requestedTools = opts.tools !== undefined ? norm(opts.tools) : this.allowedTools;
+        // Developer-Edition ceiling — a product boundary, checked before the engine.
+        if (childDepth > exports.DE_MAX_DEPTH) {
+            this._record({
+                nodeId: nodeId(),
+                parentId: this.nodeId,
+                tools: requestedTools,
+                resource: `sub-agent depth ${childDepth}`,
+                decision: "Deny",
+                depth: childDepth,
+                reason: CEILING_NOTICE(exports.DE_MAX_DEPTH, childDepth),
+            });
+            throw new DevEditionCeiling(childDepth);
+        }
+        const parent = {
+            allowed_tools: this.allowedTools,
+            allowed_resources: this.allowedResources.map((matcher) => ({ matcher })),
+            allowed_intents: this.allowedIntents,
+            max_depth: this.maxDepth,
+            time_budget_seconds: this.timeBudgetSeconds,
+            depth: this.depth,
+        };
+        const request = {
+            allowed_tools: requestedTools,
+            allowed_resources: (opts.resources !== undefined ? norm(opts.resources) : this.allowedResources).map((matcher) => ({ matcher })),
+            allowed_intents: opts.intents !== undefined ? norm(opts.intents) : this.allowedIntents,
+            max_depth: Math.max(0, this.maxDepth - 1),
+            time_budget_seconds: opts.timeBudgetSeconds !== undefined ? opts.timeBudgetSeconds : this.timeBudgetSeconds,
+        };
+        const resp = this._engine.attenuateScope(parent, request);
+        if (resp.decision !== "Allow") {
+            const violations = "violations" in resp ? resp.violations : [];
+            const reason = ("reason" in resp && resp.reason) || "requested scope is not a strict subset of the parent";
+            this._record({
+                nodeId: nodeId(),
+                parentId: this.nodeId,
+                tools: requestedTools,
+                resource: `sub-agent depth ${childDepth}`,
+                decision: "Deny",
+                depth: childDepth,
+                reason,
+            });
+            throw new AttenuationDenied(violations, reason);
+        }
+        // The engine returns the CLAMPED grant — never the child's raw request.
+        const granted = resp.granted_scope;
+        const grantedResources = (granted.allowed_resources ?? request.allowed_resources).map((r) => typeof r === "string" ? r : r.matcher);
+        const child = new Scope({
+            engine: this._engine,
+            auditPath: this._auditPath,
+            agent: this.agent,
+            allowedTools: granted.allowed_tools ?? request.allowed_tools,
+            allowedResources: grantedResources,
+            allowedIntents: granted.allowed_intents ?? request.allowed_intents,
+            maxDepth: granted.max_depth ?? request.max_depth,
+            timeBudgetSeconds: granted.time_budget_seconds ?? request.time_budget_seconds,
+            depth: granted.depth ?? childDepth,
+            parentId: this.nodeId,
+        });
+        this._record({
+            nodeId: child.nodeId,
+            parentId: this.nodeId,
+            tools: child.allowedTools,
+            resource: `sub-agent depth ${child.depth}`,
+            decision: "Allow",
+            depth: child.depth,
+        });
+        return child;
+    }
+    /** Record this scope as the root of an attenuation tree (parent-less). */
+    emitRoot() {
+        this._record({
+            nodeId: this.nodeId,
+            parentId: undefined,
+            tools: this.allowedTools,
+            resource: "root scope",
+            decision: "Allow",
+            depth: this.depth,
+        });
+    }
+    _record(r) {
+        // Value-free by construction — a scope's dimensions are capability NAMES,
+        // never argument values. Shape matches Python's audit tree records.
+        const record = {
+            ts: new Date().toISOString(),
+            agent: this.agent,
+            intent: "attenuate",
+            event: "attenuation",
+            node_id: r.nodeId,
+            resource: r.resource,
+            decision: r.decision,
+            depth: r.depth,
+            tools: [...r.tools],
+        };
+        if (r.parentId)
+            record.parent_id = r.parentId;
+        if (r.reason)
+            record.reason = r.reason;
+        try {
+            fs.mkdirSync(path.dirname(this._auditPath), { recursive: true });
+            fs.appendFileSync(this._auditPath, JSON.stringify(record) + "\n", "utf8");
+        }
+        catch {
+            // Best-effort in dev mode.
+        }
+    }
+}
+exports.Scope = Scope;

package/dist/backend.d.ts

@@ -0,0 +1,61 @@
+import { Engine } from "@watchlight/engine";
+export interface AuthorizeRequest {
+    principal: string;
+    action: string;
+    resource: string;
+    context?: Record<string, unknown>;
+}
+export interface Decision {
+    decision: string;
+    reason: string;
+}
+export interface GovernanceBackend {
+    readonly kind: "in-process" | "networked";
+    /** A short human label for the dev announce line. */
+    readonly label: string;
+    /** Register a policy. In-process loads it; networked ignores it (policies are
+     *  managed by the control plane) after warning once. */
+    addPolicy(policy: {
+        name: string;
+        code: string;
+    }): void;
+    /** Authorize a request. Fail-closed. */
+    authorize(req: AuthorizeRequest): Promise<Decision>;
+    /** The in-process engine (for local sub-agent attenuation), or null when
+     *  networked — attenuation is enforced server-side in Enterprise. */
+    engine(): Promise<Engine> | null;
+}
+/** DE default — the compiled engine in-process. */
+export declare class InProcessBackend implements GovernanceBackend {
+    readonly kind: "in-process";
+    readonly label = "dev mode, in-process engine";
+    private _enginePromise?;
+    private _pending;
+    addPolicy(policy: {
+        name: string;
+        code: string;
+    }): void;
+    private _ready;
+    authorize(req: AuthorizeRequest): Promise<Decision>;
+    engine(): Promise<Engine>;
+}
+/** Enterprise — POST /authorize to the networked control plane. */
+export declare class NetworkedBackend implements GovernanceBackend {
+    readonly kind: "networked";
+    readonly label: string;
+    private readonly _base;
+    private readonly _token?;
+    private readonly _tenantId?;
+    private _warnedPolicy;
+    constructor(url: string, token?: string, tenantId?: string);
+    addPolicy(): void;
+    authorize(req: AuthorizeRequest): Promise<Decision>;
+    engine(): null;
+}
+/** Select the backend: networked when a URL is given (option or
+ *  WATCHLIGHT_APDP_URL), in-process otherwise. */
+export declare function selectBackend(opts: {
+    apdpUrl?: string;
+    token?: string;
+    tenantId?: string;
+}): GovernanceBackend;

package/dist/backend.js

@@ -0,0 +1,114 @@
+"use strict";
+// Governance backend seam — the one object that graduation swaps.
+//
+// The authorize request/response shape is IDENTICAL in both editions
+// (`{principal, action, resource, context}` → `{decision, reason}`), so the same
+// govern/tool/hook code works either way:
+//
+//   * Developer Edition (default) — InProcessBackend runs the compiled
+//     @watchlight/engine wasm core in-process. Zero infrastructure.
+//   * Enterprise — set WATCHLIGHT_APDP_URL and NetworkedBackend POSTs the same
+//     request to the control plane's /authorize (signed lineage, cross-tenant
+//     isolation, IdP/mTLS attestation live there). No policy or code change.
+//
+// Fail-closed everywhere: any transport/engine error resolves to Deny.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkedBackend = exports.InProcessBackend = void 0;
+exports.selectBackend = selectBackend;
+const engine_1 = require("@watchlight/engine");
+/** DE default — the compiled engine in-process. */
+class InProcessBackend {
+    constructor() {
+        this.kind = "in-process";
+        this.label = "dev mode, in-process engine";
+        this._pending = [];
+    }
+    addPolicy(policy) {
+        this._pending.push(policy);
+    }
+    async _ready() {
+        if (!this._enginePromise)
+            this._enginePromise = engine_1.Engine.create();
+        const engine = await this._enginePromise;
+        if (this._pending.length) {
+            const batch = this._pending;
+            this._pending = [];
+            for (const p of batch)
+                await engine.addPolicy(p);
+        }
+        return engine;
+    }
+    async authorize(req) {
+        const engine = await this._ready();
+        const resp = await engine.authorize({
+            principal: req.principal,
+            action: req.action,
+            resource: req.resource,
+            context: req.context ?? {},
+        });
+        return { decision: resp.decision ?? "Deny", reason: resp.reason ?? "" };
+    }
+    engine() {
+        return this._ready();
+    }
+}
+exports.InProcessBackend = InProcessBackend;
+/** Enterprise — POST /authorize to the networked control plane. */
+class NetworkedBackend {
+    constructor(url, token, tenantId) {
+        this.kind = "networked";
+        this._warnedPolicy = false;
+        this._base = url.replace(/\/+$/, "");
+        this._token = token;
+        this._tenantId = tenantId;
+        this.label = `control plane: ${this._base}`;
+    }
+    addPolicy() {
+        if (!this._warnedPolicy) {
+            // eslint-disable-next-line no-console
+            console.warn("watchlight: WATCHLIGHT_APDP_URL is set — policies are managed by the " +
+                "control plane; local allow()/load() is ignored.");
+            this._warnedPolicy = true;
+        }
+    }
+    async authorize(req) {
+        const headers = { "content-type": "application/json" };
+        if (this._token)
+            headers["authorization"] = `Bearer ${this._token}`;
+        if (this._tenantId)
+            headers["x-wl-tenant-id"] = this._tenantId;
+        try {
+            const resp = await fetch(`${this._base}/authorize`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    principal: req.principal,
+                    action: req.action,
+                    resource: req.resource,
+                    context: req.context ?? {},
+                }),
+            });
+            if (!resp.ok)
+                return { decision: "Deny", reason: `APDP error: ${resp.status}` };
+            const data = (await resp.json());
+            return { decision: data.decision ?? "Deny", reason: data.reason ?? "" };
+        }
+        catch (e) {
+            // Fail-closed: an unreachable control plane denies.
+            return { decision: "Deny", reason: `APDP unreachable: ${String(e)}` };
+        }
+    }
+    engine() {
+        return null;
+    }
+}
+exports.NetworkedBackend = NetworkedBackend;
+/** Select the backend: networked when a URL is given (option or
+ *  WATCHLIGHT_APDP_URL), in-process otherwise. */
+function selectBackend(opts) {
+    const url = opts.apdpUrl ?? process.env.WATCHLIGHT_APDP_URL;
+    if (url && url.trim()) {
+        return new NetworkedBackend(url.trim(), opts.token ?? process.env.WATCHLIGHT_PLUGIN_TOKEN, opts.tenantId ?? process.env.WATCHLIGHT_TENANT_ID);
+    }
+    return new InProcessBackend();
+}

package/dist/claude-agent-types.d.ts

@@ -0,0 +1,29 @@
+export type HookEventName = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop" | "SessionStart" | "SessionEnd" | "SubagentStart" | "SubagentStop";
+/** Permission verdict the SDK accepts on a PreToolUse hook. */
+export type PermissionDecision = "allow" | "deny" | "ask" | "defer";
+export interface BaseHookInput {
+    hook_event_name: HookEventName;
+    session_id?: string;
+    cwd?: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface PreToolUseHookInput extends BaseHookInput {
+    hook_event_name: "PreToolUse";
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+}
+export interface HookOutput {
+    continue?: boolean;
+    hookSpecificOutput?: {
+        hookEventName: HookEventName;
+        permissionDecision?: PermissionDecision;
+        permissionDecisionReason?: string;
+    };
+}
+export type HookCallback = (input: BaseHookInput) => Promise<HookOutput> | HookOutput;
+export interface HookMatcherEntry {
+    matcher?: string;
+    hooks: HookCallback[];
+}
+export type HooksOption = Partial<Record<HookEventName, HookMatcherEntry[]>>;

package/dist/claude-agent-types.js

@@ -0,0 +1,6 @@
+"use strict";
+// Minimal local type definitions mirroring the Claude Agent SDK's hook contract
+// — just the subset the PreToolUse governance gate needs. Kept local so
+// @watchlight/sdk does not take a hard dependency on the Claude Agent SDK; it is
+// a peer you install alongside. Shapes match the SDK's documented hook I/O.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/claude-agent.d.ts

@@ -0,0 +1,21 @@
+import { Watchlight } from "./index";
+import type { HooksOption } from "./claude-agent-types";
+export type { HookEventName, PermissionDecision, BaseHookInput, PreToolUseHookInput, HookOutput, HookCallback, HookMatcherEntry, HooksOption, } from "./claude-agent-types";
+export interface GovernedHooksOptions {
+    /** The governor to authorize against. Defaults to the shared `govern`. */
+    governor?: Watchlight;
+    /** Map a Claude tool name to a governance intent. Defaults to identity
+     *  (the intent is the tool name). Provide this to bind semantic intents,
+     *  e.g. `(t) => ({ WebSearch: "research", Bash: "execute" }[t] ?? t)`. */
+    intentFor?: (toolName: string) => string;
+}
+export interface GovernedHooksResult {
+    /** Pass directly to the Claude Agent SDK: `query({ options: { hooks } })`. */
+    hooks: HooksOption;
+}
+/**
+ * Build Claude Agent SDK hooks that gate every tool call through the in-process
+ * Watchlight engine. Fail-closed. The hook never throws back to the SDK — a
+ * governance error becomes a `deny`.
+ */
+export declare function governedHooks(options?: GovernedHooksOptions): GovernedHooksResult;

package/dist/claude-agent.js

@@ -0,0 +1,56 @@
+"use strict";
+// Claude Agent SDK integration — govern an SDK-managed agent's tool calls with
+// the in-process engine. The TS counterpart of Python `watchlight.claude_agent`.
+//
+//   import { query } from "@anthropic-ai/claude-agent-sdk";
+//   import { govern, governedHooks } from "@watchlight/sdk";
+//
+//   govern.load("watchlight.policy.json");
+//   const { hooks } = governedHooks({ intentFor: (t) => TOOL_INTENTS[t] ?? t });
+//
+//   for await (const msg of query({ prompt, options: { hooks } })) { … }
+//
+// The returned `hooks` install a PreToolUse gate: before the SDK runs any tool,
+// the in-process engine authorizes (agent, intent, tool/<name>). ALLOW lets the
+// call proceed; anything else returns a `deny` permission decision and the tool
+// never executes — denied before it runs. Fail-closed: a governance error also
+// denies. Every decision lands in the value-free `.watchlight/audit.jsonl`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.governedHooks = governedHooks;
+const index_1 = require("./index");
+/**
+ * Build Claude Agent SDK hooks that gate every tool call through the in-process
+ * Watchlight engine. Fail-closed. The hook never throws back to the SDK — a
+ * governance error becomes a `deny`.
+ */
+function governedHooks(options = {}) {
+    const governor = options.governor ?? index_1.govern;
+    const intentFor = options.intentFor ?? ((t) => t);
+    const preToolUse = async (input) => {
+        const ev = input;
+        const toolName = ev.tool_name ?? "unknown";
+        try {
+            const intent = intentFor(toolName);
+            const { allowed, reason } = await governor.check(intent, toolName);
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: allowed ? "allow" : "deny",
+                    ...(allowed ? {} : { permissionDecisionReason: reason || "no matching policy" }),
+                },
+            };
+        }
+        catch (e) {
+            // Hooks must never throw back to the SDK; a governance error is
+            // fail-closed — deny the tool call rather than let it through.
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: `watchlight governance error (fail-closed): ${String(e)}`,
+                },
+            };
+        }
+    };
+    return { hooks: { PreToolUse: [{ hooks: [preToolUse] }] } };
+}

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { Scope } from "./attenuation";
+export { Scope, DE_MAX_DEPTH, AttenuationDenied, DevEditionCeiling } from "./attenuation";
+export { governedHooks } from "./claude-agent";
+export type { GovernedHooksOptions, GovernedHooksResult } from "./claude-agent";
+export type { GovernanceBackend, Decision, AuthorizeRequest } from "./backend";
+export { InProcessBackend, NetworkedBackend } from "./backend";
+/** Raised when the policy engine refuses a governed tool call (fail-closed). */
+export declare class Denied extends Error {
+    readonly tool: string;
+    readonly intent: string;
+    readonly reason: string;
+    constructor(tool: string, intent: string, reason: string);
+}
+/** A function governed by {@link Watchlight.tool} — always async (the engine's
+ *  authorize path is async in WebAssembly). */
+export type Governed<A extends unknown[], R> = (...args: A) => Promise<Awaited<R>>;
+export interface WatchlightOptions {
+    /** Stable agent identity for the audit trail. Defaults to
+     *  `WATCHLIGHT_AGENT` env or `"my-agent"`. */
+    agent?: string;
+    /** Directory for the audit trail. `audit.jsonl` is written inside it.
+     *  Defaults to `.watchlight`. */
+    auditDir?: string;
+    /** Graduate to the networked control plane: authorize against this APDP URL
+     *  instead of the in-process engine. Defaults to `WATCHLIGHT_APDP_URL`. When
+     *  unset, governance runs fully in-process (Developer Edition). */
+    apdpUrl?: string;
+    /** Bearer token for the networked control plane. Defaults to
+     *  `WATCHLIGHT_PLUGIN_TOKEN`. Ignored in-process. */
+    token?: string;
+    /** Tenant id (`X-Wl-Tenant-Id`) for the networked control plane. Defaults to
+     *  `WATCHLIGHT_TENANT_ID`. Ignored in-process. */
+    tenantId?: string;
+}
+export interface ScopeOptions {
+    tools?: readonly string[];
+    resources?: readonly string[];
+    intents?: readonly string[];
+    maxDepth?: number;
+    timeBudgetSeconds?: number;
+}
+/**
+ * An in-process policy decision point for a single agent. Wraps the
+ * `@watchlight/engine` core; policies are loaded from a file or added inline and
+ * each governed call is authorized against them. Fail-closed: with no matching
+ * policy, every call is denied.
+ */
+export declare class Watchlight {
+    readonly agent: string;
+    private readonly _auditPath;
+    private readonly _backend;
+    private _policyCount;
+    private _announced;
+    constructor(opts?: WatchlightOptions);
+    /** `"in-process"` (Developer Edition) or `"networked"` (graduated to the
+     *  control plane via WATCHLIGHT_APDP_URL). */
+    get mode(): "in-process" | "networked";
+    /** Add one Cedar policy inline. Chainable. (In networked mode policies are
+     *  managed by the control plane and this is ignored, with a one-time warning.) */
+    allow(cedarCode: string, name?: string): this;
+    /** Load policies from a JSON file — a list of `{name, code}` (or
+     *  `{policies:[...]}`). Fail-closed: a missing file loads nothing, so every
+     *  governed call is denied until a policy permits it. Chainable. */
+    load(file: string): this;
+    /** Create a root capability scope for this agent, from which sub-agent scopes
+     *  are attenuated (strict-subset). Async because the engine initializes
+     *  lazily; `attenuate()` on the returned scope is synchronous. The Developer
+     *  Edition governs the tree up to depth {@link DE_MAX_DEPTH}. */
+    scope(opts?: ScopeOptions): Promise<Scope>;
+    /**
+     * Wrap a function as a governed tool with the given `intent`. On every call
+     * the engine authorizes `(agent, intent, tool/<name>)`. On ALLOW the function
+     * runs; on anything else a {@link Denied} is thrown and the body never
+     * executes. The returned function is async.
+     */
+    tool<A extends unknown[], R>(fn: (...args: A) => R, opts: {
+        intent: string;
+    }): Governed<A, R>;
+    /**
+     * Authorize a raw `(intent, tool)` pair, audit the decision, and return it.
+     * Fail-closed. Used by framework adapters (e.g. the Claude Agent SDK hooks)
+     * that gate tool calls themselves rather than wrapping the function — the
+     * decision is identical to {@link tool}, just without running a body.
+     */
+    check(intent: string, toolName: string): Promise<{
+        allowed: boolean;
+        decision: string;
+        reason: string;
+    }>;
+    private _authorize;
+    private _announce;
+    private _audit;
+}
+/** A ready-to-use default governor so `import { govern } from "@watchlight/sdk"`
+ *  just works. Starts with NO policies — fail-closed — until you `govern.load()`
+ *  a file or `govern.allow()` a policy inline. */
+export declare const govern: Watchlight;

package/dist/index.js

@@ -0,0 +1,228 @@
+"use strict";
+// @watchlight/sdk — the Watchlight Developer-Edition govern glue for Node/TS.
+//
+// Thin, dependency-light glue over @watchlight/engine (the compiled wl-apdp
+// core). It contains ZERO decision logic — every ALLOW/DENY comes from the
+// engine. It mirrors the Python `watchlight` package: declare intent, govern a
+// tool, get a fail-closed decision, and a value-free `.watchlight/audit.jsonl`
+// trail.
+//
+//   import { govern, Denied } from "@watchlight/sdk";
+//   govern.load("watchlight.policy.json");            // or govern.allow("permit(...);")
+//   const search = govern.tool(webSearch, { intent: "research" });
+//   await search(query);                              // ALLOW → runs; else throws Denied
+//
+// TypeScript uses a higher-order function (`govern.tool(fn, {intent})`) rather
+// than a decorator — decorators are still awkward across TS build setups, and a
+// HOF works everywhere with full type inference.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.govern = exports.Watchlight = exports.Denied = exports.NetworkedBackend = exports.InProcessBackend = exports.governedHooks = exports.DevEditionCeiling = exports.AttenuationDenied = exports.DE_MAX_DEPTH = exports.Scope = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const attenuation_1 = require("./attenuation");
+const backend_1 = require("./backend");
+var attenuation_2 = require("./attenuation");
+Object.defineProperty(exports, "Scope", { enumerable: true, get: function () { return attenuation_2.Scope; } });
+Object.defineProperty(exports, "DE_MAX_DEPTH", { enumerable: true, get: function () { return attenuation_2.DE_MAX_DEPTH; } });
+Object.defineProperty(exports, "AttenuationDenied", { enumerable: true, get: function () { return attenuation_2.AttenuationDenied; } });
+Object.defineProperty(exports, "DevEditionCeiling", { enumerable: true, get: function () { return attenuation_2.DevEditionCeiling; } });
+var claude_agent_1 = require("./claude-agent");
+Object.defineProperty(exports, "governedHooks", { enumerable: true, get: function () { return claude_agent_1.governedHooks; } });
+var backend_2 = require("./backend");
+Object.defineProperty(exports, "InProcessBackend", { enumerable: true, get: function () { return backend_2.InProcessBackend; } });
+Object.defineProperty(exports, "NetworkedBackend", { enumerable: true, get: function () { return backend_2.NetworkedBackend; } });
+/** Raised when the policy engine refuses a governed tool call (fail-closed). */
+class Denied extends Error {
+    constructor(tool, intent, reason) {
+        super(`watchlight denied intent '${intent}' on tool/${tool}: ${reason}`);
+        this.name = "Denied";
+        this.tool = tool;
+        this.intent = intent;
+        this.reason = reason;
+    }
+}
+exports.Denied = Denied;
+const norm = (x) => (x ? [...x] : []);
+/**
+ * An in-process policy decision point for a single agent. Wraps the
+ * `@watchlight/engine` core; policies are loaded from a file or added inline and
+ * each governed call is authorized against them. Fail-closed: with no matching
+ * policy, every call is denied.
+ */
+class Watchlight {
+    constructor(opts = {}) {
+        this._policyCount = 0;
+        this._announced = false;
+        this.agent = opts.agent ?? process.env.WATCHLIGHT_AGENT ?? "my-agent";
+        this._auditPath = path.join(opts.auditDir ?? ".watchlight", "audit.jsonl");
+        this._backend = (0, backend_1.selectBackend)({
+            apdpUrl: opts.apdpUrl,
+            token: opts.token,
+            tenantId: opts.tenantId,
+        });
+    }
+    /** `"in-process"` (Developer Edition) or `"networked"` (graduated to the
+     *  control plane via WATCHLIGHT_APDP_URL). */
+    get mode() {
+        return this._backend.kind;
+    }
+    // ── policy loading ────────────────────────────────────────────────
+    /** Add one Cedar policy inline. Chainable. (In networked mode policies are
+     *  managed by the control plane and this is ignored, with a one-time warning.) */
+    allow(cedarCode, name) {
+        this._backend.addPolicy({ name: name ?? `policy-${this._policyCount}`, code: cedarCode });
+        this._policyCount += 1;
+        return this;
+    }
+    /** Load policies from a JSON file — a list of `{name, code}` (or
+     *  `{policies:[...]}`). Fail-closed: a missing file loads nothing, so every
+     *  governed call is denied until a policy permits it. Chainable. */
+    load(file) {
+        if (!fs.existsSync(file))
+            return this;
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        const entries = Array.isArray(data)
+            ? data
+            : (data.policies ?? []);
+        for (const e of entries)
+            this.allow(e.code, e.name);
+        return this;
+    }
+    // ── sub-agent scope attenuation ───────────────────────────────────
+    /** Create a root capability scope for this agent, from which sub-agent scopes
+     *  are attenuated (strict-subset). Async because the engine initializes
+     *  lazily; `attenuate()` on the returned scope is synchronous. The Developer
+     *  Edition governs the tree up to depth {@link DE_MAX_DEPTH}. */
+    async scope(opts = {}) {
+        const eng = this._backend.engine();
+        if (!eng) {
+            throw new Error("sub-agent attenuation runs in-process; with WATCHLIGHT_APDP_URL set it is " +
+                "enforced by the control plane server-side. Use the Enterprise API for networked attenuation.");
+        }
+        const engine = await eng;
+        const root = new attenuation_1.Scope({
+            engine,
+            auditPath: this._auditPath,
+            agent: this.agent,
+            allowedTools: norm(opts.tools),
+            allowedResources: norm(opts.resources),
+            allowedIntents: norm(opts.intents),
+            maxDepth: Math.min(opts.maxDepth ?? attenuation_1.DE_MAX_DEPTH, attenuation_1.DE_MAX_DEPTH),
+            timeBudgetSeconds: opts.timeBudgetSeconds ?? 3600,
+            depth: 0,
+        });
+        root.emitRoot();
+        return root;
+    }
+    // ── governing tools ───────────────────────────────────────────────
+    /**
+     * Wrap a function as a governed tool with the given `intent`. On every call
+     * the engine authorizes `(agent, intent, tool/<name>)`. On ALLOW the function
+     * runs; on anything else a {@link Denied} is thrown and the body never
+     * executes. The returned function is async.
+     */
+    tool(fn, opts) {
+        const intent = opts.intent;
+        const name = fn.name || "anonymous";
+        const resource = `tool/${name}`;
+        return async (...args) => {
+            const [decision, reason] = await this._authorize(intent, resource);
+            this._audit(intent, resource, decision, reason);
+            if (decision !== "Allow") {
+                throw new Denied(name, intent, reason || "no matching policy");
+            }
+            return (await fn(...args));
+        };
+    }
+    /**
+     * Authorize a raw `(intent, tool)` pair, audit the decision, and return it.
+     * Fail-closed. Used by framework adapters (e.g. the Claude Agent SDK hooks)
+     * that gate tool calls themselves rather than wrapping the function — the
+     * decision is identical to {@link tool}, just without running a body.
+     */
+    async check(intent, toolName) {
+        const resource = `tool/${toolName}`;
+        const [decision, reason] = await this._authorize(intent, resource);
+        this._audit(intent, resource, decision, reason);
+        return { allowed: decision === "Allow", decision, reason };
+    }
+    // ── internals ─────────────────────────────────────────────────────
+    async _authorize(intent, resource) {
+        const { decision, reason } = await this._backend.authorize({
+            principal: this.agent,
+            action: intent,
+            resource,
+            context: {},
+        });
+        return [decision, reason];
+    }
+    _announce() {
+        if (!this._announced) {
+            // eslint-disable-next-line no-console
+            console.log(`watchlight: governing '${this.agent}' (${this._backend.label})`);
+            this._announced = true;
+        }
+    }
+    _audit(intent, resource, decision, reason) {
+        this._announce();
+        const allowed = decision === "Allow";
+        const tag = allowed ? "ALLOW" : "DENY";
+        const trailer = allowed ? "" : `     ${reason || "no matching policy"}`;
+        // eslint-disable-next-line no-console
+        console.log(`watchlight: ${tag.padEnd(5)} ${intent.padEnd(9)} ${resource}${trailer}`);
+        // Value-free audit: argument VALUES never enter the trail — only the
+        // governance decision. Mirrors the production audit contract.
+        const record = {
+            ts: new Date().toISOString(),
+            agent: this.agent,
+            intent,
+            resource,
+            decision,
+        };
+        try {
+            fs.mkdirSync(path.dirname(this._auditPath), { recursive: true });
+            fs.appendFileSync(this._auditPath, JSON.stringify(record) + "\n", "utf8");
+        }
+        catch {
+            // Audit is best-effort in dev mode; never let it break the app.
+        }
+    }
+}
+exports.Watchlight = Watchlight;
+/** A ready-to-use default governor so `import { govern } from "@watchlight/sdk"`
+ *  just works. Starts with NO policies — fail-closed — until you `govern.load()`
+ *  a file or `govern.allow()` a policy inline. */
+exports.govern = new Watchlight();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@watchlight/sdk",
+  "version": "0.1.0",
+  "description": "Watchlight Developer Edition govern glue for Node/TypeScript — declare intent, govern a tool with a fail-closed in-process policy decision, and get a value-free audit trail. Glue over @watchlight/engine; zero decision logic in JS.",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node test/govern.test.mjs && node test/claude-agent.test.mjs && node test/graduation.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "authorization",
+    "cedar",
+    "policy",
+    "agent",
+    "governance",
+    "watchlight",
+    "ai-agents"
+  ],
+  "dependencies": {
+    "@watchlight/engine": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://www.watchlight.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/watchlight-ai-beacon/watchlight-de.git",
+    "directory": "ts"
+  },
+  "bugs": {
+    "url": "https://github.com/watchlight-ai-beacon/watchlight-de/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}