@intutic/gate 1.10.1

package/dist/dsh.js

@@ -0,0 +1,189 @@
+/**
+ * dsh.ts — Cordis plugin adapter for DeepSeek's "dsh" harness.
+ *
+ * Published as the `@intutic/gate/dsh` subpath (see README.md's "Subpath
+ * convention for later phases"). `services/sync-daemon/src/harness/dshHooks.ts`
+ * merge-writes a row naming this module (`name: '@intutic/gate/dsh'`) into a
+ * dsh profile's `cordis.patch.yml`; dsh's own Cordis loader resolves that name
+ * with a plain dynamic `import()` and mounts the exported plugin
+ * (`{ name, inject, apply }`) the same way it mounts every other bundle row.
+ *
+ * ## The veto mechanism — CONFIRMED against a real install, not assumed
+ *
+ * dsh is a developer preview (`@deepseek-ai/dsh`, first published 2026-08-13)
+ * built on DeepSeek's own "Cordis" plugin framework (`@deepseek-ai/cordis`,
+ * `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-app-boot`, ...). Both are public
+ * on the npm registry, and this module was authored against a real
+ * `npm pack`/inspection of them (see the TD entry this phase filed for exactly
+ * what was checked and what still had to be assumed) — NOT solely from the
+ * phase brief's prior guess, which named a different event (`agent/pre-step`)
+ * and a different decision shape (`{kind:'reject',...}`). Both turned out to
+ * be close but not exact:
+ *
+ *   - The real per-tool veto point is `tools/pre-execute` (declared by
+ *     `@deepseek-ai/dsh-tools`), not `agent/pre-step` (`@deepseek-ai/dsh-agent`'s
+ *     per-turn/step event — a coarser boundary that batches a driver step
+ *     rather than one tool call, and the wrong extension point for a
+ *     per-tool-call gate).
+ *   - It is a genuine Cordis `waterfall`: `(exec: ToolExecution, next: () =>
+ *     Promise<PreToolDecision>) => Promise<PreToolDecision>`. Cordis's own
+ *     waterfall contract (confirmed by reading `@deepseek-ai/cordis`'s
+ *     `events.d.ts`) composes listeners around a `next()` continuation —
+ *     "a listener that does not call next() vetoes the rest of the chain,
+ *     including the built-in behavior" — so this listener calls `next()` on
+ *     ALLOW (to preserve whatever later listener or built-in behaviour — e.g.
+ *     dsh's own `ask`/approval flow — would otherwise run) and returns its own
+ *     `{kind:'deny',...}` WITHOUT calling `next()` to veto.
+ *   - The decision shape is `PreToolDecision = {kind:'allow'} | {kind:'deny',
+ *     reason} | {kind:'ask', reason?}` (confirmed from
+ *     `@deepseek-ai/dsh-tools`'s shipped `.d.ts`) — `'deny'`, not the phase
+ *     brief's guessed `'reject'`.
+ *
+ * `ctx.tools.guard()` (a separate, monotonic, explicitly SYNCHRONOUS
+ * mechanism dsh also exposes) was considered and rejected: `@intutic/gate`'s
+ * `Gate.guard()` is async (network-backed SOP-rule fetch and `/hook-gate`
+ * POST — see gate.ts's module doc), and a synchronous `ToolGuard` cannot
+ * `await` it. `tools/pre-execute` is the only one of dsh's two extension
+ * points this package's async contract fits.
+ *
+ * ## What this module does NOT import
+ *
+ * Deliberately no dependency on `@deepseek-ai/cordis` or `@deepseek-ai/dsh-tools`
+ * at runtime — `CordisLikeContext`/`DshToolExecution`/`DshPreToolDecision`
+ * below are narrow structural types capturing only the shape this plugin
+ * actually touches, matching Cordis's own duck-typed plugin contract (a
+ * plain `{ name?, inject?, apply(ctx, config) }` object — confirmed against
+ * both `@deepseek-ai/cordis`'s README quick-start and dsh's own in-product
+ * "cordis-plugin-development" skill doc, which returns `{ apply(ctx) {...} }`
+ * with no import of anything). Adding a hard dependency on a fast-moving
+ * preview product's framework package to `@intutic/gate`'s dsh subpath would
+ * make every OTHER subpath's install pull it in too (or need a peerDependency
+ * carve-out) for a shape simple enough to describe locally. The real
+ * `@deepseek-ai/cordis` package is used only as a devDependency, in this
+ * module's own test file, to exercise the real waterfall dispatch mechanics
+ * against the genuine `Context` class rather than a hand-rolled stand-in.
+ *
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { Gate, install } from './gate.js';
+import { GateClient } from './client.js';
+import { IntuticGateRefusal } from './errors.js';
+/** The Cordis Plugin id this module registers as. Shown in dsh's own plugin
+ *  diagnostics/`--dump-config` output. */
+export const PLUGIN_NAME = 'intutic-governance';
+/** Cordis Plugins declare their hard dependencies here; the loader defers
+ *  activation until every named service exists and reactivates on restart.
+ *  `tools` is `@deepseek-ai/dsh-tools`'s `ToolRegistry` service — the thing
+ *  that actually dispatches `tools/pre-execute`. */
+export const inject = ['tools'];
+/**
+ * Render a `tools/pre-execute` call's `arguments` as the `tool_input` object
+ * {@link Gate.guard} evaluates.
+ *
+ * Mirrors `wrapTools.ts`'s `renderToolInput` (not exported from there, so
+ * reimplemented rather than reached into a sibling module's internals): a
+ * plain object passes through as-is; anything else (a scalar, an array, or
+ * — per dsh's own doc — a value that failed to serialize) falls back to
+ * `{ args: [...] }` so the gate still has something to evaluate.
+ */
+function renderDshToolInput(args) {
+    if (args !== null && typeof args === 'object' && !Array.isArray(args)) {
+        return args;
+    }
+    return { args: [args] };
+}
+/**
+ * One session id per dsh PROCESS, not per dsh conversation.
+ *
+ * `GateClient.fromEnv` throws without a session id (see client.ts — an unset
+ * `x-session-id` collapses every run onto one dashboard row at the proxy, so
+ * the client refuses to construct with none at all). dsh has no single
+ * "current session" this plugin can read at plugin-mount time — sessions are
+ * created and disposed while the process runs (`agent/session-start` et al.,
+ * per `@deepseek-ai/dsh-goal`'s shipped types) — so rather than leave Tier B
+ * (the control-plane `/hook-gate` call) and Tier A3 (SOP-rule fetch)
+ * permanently inactive for the whole process when `INTUTIC_SESSION_ID` is
+ * unset, this generates one random id at plugin-mount time and reuses it for
+ * every session the process handles for its lifetime. Coarser attribution
+ * than per-conversation, but strictly better than "those two tiers never run
+ * under dsh at all" — and Tier A1 (the local policy snapshot, the
+ * load-bearing tier) is unaffected either way; it needs no session id.
+ */
+function resolveSessionId(config) {
+    return config.sessionId || process.env.INTUTIC_SESSION_ID || randomUUID();
+}
+/**
+ * Build the `tools/pre-execute` listener for a given {@link Gate}.
+ *
+ * Factored out of {@link apply} so a test can exercise the exact listener
+ * `apply()` registers — event extraction, the refusal-to-decision mapping,
+ * the fail-closed default, and the waterfall `next()`-calling on allow —
+ * against a controllable fake `Gate`, without needing a real dsh install or
+ * network access to construct a `GateClient`.
+ *
+ * Never throws: every path returns a {@link DshPreToolDecision}. A crash
+ * inside `gate.guard()` that is not an {@link IntuticGateRefusal} — a bug in
+ * this gate, or an unexpected throw from a tier it calls into — is treated
+ * as "cannot evaluate" and denied rather than allowed to escape the
+ * waterfall or fall through to an allow; see gate.ts's own module doc for why
+ * every tier in this package takes that direction on failure.
+ */
+export function createPreExecuteListener(gate) {
+    return async (exec, next) => {
+        try {
+            await gate.guard(exec.name, renderDshToolInput(exec.arguments));
+        }
+        catch (err) {
+            if (err instanceof IntuticGateRefusal) {
+                return { kind: 'deny', reason: err.message };
+            }
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                kind: 'deny',
+                reason: `[Intutic Governance] BLOCKED: gate crashed (${detail}) — failing closed rather than allowing an unevaluated call.`,
+            };
+        }
+        // Allow: call next() rather than returning {kind:'allow'} directly, so a
+        // later listener in the waterfall (including dsh's own built-in
+        // ask/approval behaviour) still runs — see the module doc's note on
+        // Cordis's waterfall semantics.
+        return next();
+    };
+}
+/**
+ * Mount the Intutic governance gate on a dsh profile.
+ *
+ * Builds one {@link Gate} for the lifetime of this plugin instance (not per
+ * call — Tier A1/A2/A3 all cache within a `Gate`, see gate.ts) and installs it
+ * as the process-wide default too (`install()`), so a hand-authored
+ * `wrapTool`/`wrapTools` call elsewhere in the same dsh process picks up the
+ * identical instance rather than constructing a second one with independent
+ * caches.
+ *
+ * Never throws out of `apply()` itself: a `GateClient.fromEnv` failure (e.g.
+ * credentials genuinely unreadable) degrades to a client-less `Gate` — Tier B
+ * and Tier A3 inactive, Tier A1/A2 (local, load-bearing) unaffected — rather
+ * than taking down the whole dsh profile boot over a governance layer that is
+ * additive by design.
+ */
+export function apply(ctx, config = {}) {
+    let client;
+    try {
+        client = GateClient.fromEnv({ harness: 'dsh', sessionId: resolveSessionId(config) });
+    }
+    catch {
+        client = null;
+    }
+    const gate = new Gate(config, client);
+    install(gate);
+    ctx.on('tools/pre-execute', createPreExecuteListener(gate));
+}
+/** Default export — the whole Plugin object, for `name: '@intutic/gate/dsh'`
+ *  cordis.patch.yml rows that resolve this module and pass it directly to
+ *  `ctx.plugin()` (dsh's loader unwraps a default export the same way it
+ *  unwraps a named one — see `dsh-app-boot`'s `unwrapExports`). Named exports
+ *  (`apply`, `inject`, `PLUGIN_NAME`) are also available for a caller that
+ *  imports this subpath directly rather than through the loader. */
+export default { name: PLUGIN_NAME, inject, apply };
+//# sourceMappingURL=dsh.js.map

package/dist/dsh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh.js","sourceRoot":"","sources":["../src/dsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD;0CAC0C;AAC1C,MAAM,CAAC,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAuC/C;;;oDAGoD;AACpD,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,CAAA;AAE/B;;;;;;;;;GASG;AACH,SAAS,kBAAkB,CAAC,IAAa;IACvC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,IAAiB,CAAA;IAC1B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,gBAAgB,CAAC,MAAqB;IAC7C,OAAO,MAAM,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,UAAU,EAAE,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAU;IAEV,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;gBACtC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAA;YAC9C,CAAC;YACD,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC/D,OAAO;gBACL,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,+CAA+C,MAAM,8DAA8D;aAC5H,CAAA;QACH,CAAC;QACD,yEAAyE;QACzE,gEAAgE;QAChE,oEAAoE;QACpE,gCAAgC;QAChC,OAAO,IAAI,EAAE,CAAA;IACf,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,KAAK,CAAC,GAAsB,EAAE,SAAwB,EAAE;IACtE,IAAI,MAAyB,CAAA;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,IAAI,CAAA;IACf,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,OAAO,CAAC,IAAI,CAAC,CAAA;IAEb,GAAG,CAAC,EAAE,CAAC,mBAAmB,EAAE,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;oEAKoE;AACpE,eAAe,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA"}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error hierarchy for `@intutic/gate`.
+ *
+ * Port of `packages/intutic-clawde/intutic_clawde/errors.py` +
+ * `intutic_clawde/gate/gate.py`'s `IntuticGateRefusal`.
+ *
+ * `IntuticGateRefusal` is the load-bearing one: {@link Gate.guard} THROWS this
+ * on a refused call rather than returning a verdict object. That is the
+ * "JS-throw contract" already used elsewhere in this repo's gate vocabulary —
+ * see `services/sync-daemon/src/harness/gateBody.ts`'s emitted gates, which
+ * either `process.exit(2)` or write a `{cancel:true,...}` stdout envelope, and
+ * `packages/mcp-proxy/src/policy.ts`, which throws a `PolicyBlockedError` for
+ * the same reason: a tool call that must not run is an exceptional control
+ * flow event, not a value the caller might forget to check.
+ *
+ * `.message` is prefixed `[Intutic Governance] BLOCKED:` — the same family the
+ * Open WebUI filter and the Python SDK raise — so harnesses and log scrapers
+ * that already recognise that prefix recognise this refusal too.
+ */
+/** Base class for every error this package throws. */
+export declare class GateError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the SDK cannot reach the Intutic control plane. */
+export declare class GateConnectionError extends GateError {
+    constructor(message: string);
+}
+/**
+ * Raised when a tool call must not run.
+ *
+ * The structured fields (`reason`, `code`, `incidentId`) carry the
+ * machine-readable version of the refusal; `.message` carries the
+ * human-readable, prefix-recognisable one.
+ */
+export declare class IntuticGateRefusal extends GateError {
+    readonly reason: string;
+    readonly code: string;
+    readonly incidentId: string | undefined;
+    constructor(reason: string, code: string, incidentId?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sDAAsD;AACtD,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,kEAAkE;AAClE,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,SAAgB,MAAM,EAAE,MAAM,CAAA;IAC9B,SAAgB,IAAI,EAAE,MAAM,CAAA;IAC5B,SAAgB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;gBAElC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAO9D"}

package/dist/errors.js

@@ -0,0 +1,53 @@
+/**
+ * Error hierarchy for `@intutic/gate`.
+ *
+ * Port of `packages/intutic-clawde/intutic_clawde/errors.py` +
+ * `intutic_clawde/gate/gate.py`'s `IntuticGateRefusal`.
+ *
+ * `IntuticGateRefusal` is the load-bearing one: {@link Gate.guard} THROWS this
+ * on a refused call rather than returning a verdict object. That is the
+ * "JS-throw contract" already used elsewhere in this repo's gate vocabulary —
+ * see `services/sync-daemon/src/harness/gateBody.ts`'s emitted gates, which
+ * either `process.exit(2)` or write a `{cancel:true,...}` stdout envelope, and
+ * `packages/mcp-proxy/src/policy.ts`, which throws a `PolicyBlockedError` for
+ * the same reason: a tool call that must not run is an exceptional control
+ * flow event, not a value the caller might forget to check.
+ *
+ * `.message` is prefixed `[Intutic Governance] BLOCKED:` — the same family the
+ * Open WebUI filter and the Python SDK raise — so harnesses and log scrapers
+ * that already recognise that prefix recognise this refusal too.
+ */
+/** Base class for every error this package throws. */
+export class GateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GateError';
+    }
+}
+/** Thrown when the SDK cannot reach the Intutic control plane. */
+export class GateConnectionError extends GateError {
+    constructor(message) {
+        super(message);
+        this.name = 'GateConnectionError';
+    }
+}
+/**
+ * Raised when a tool call must not run.
+ *
+ * The structured fields (`reason`, `code`, `incidentId`) carry the
+ * machine-readable version of the refusal; `.message` carries the
+ * human-readable, prefix-recognisable one.
+ */
+export class IntuticGateRefusal extends GateError {
+    reason;
+    code;
+    incidentId;
+    constructor(reason, code, incidentId) {
+        super(`[Intutic Governance] BLOCKED: ${reason}`);
+        this.name = 'IntuticGateRefusal';
+        this.reason = reason;
+        this.code = code;
+        this.incidentId = incidentId;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sDAAsD;AACtD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;IACzB,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAC/B,MAAM,CAAQ;IACd,IAAI,CAAQ;IACZ,UAAU,CAAoB;IAE9C,YAAY,MAAc,EAAE,IAAY,EAAE,UAAmB;QAC3D,KAAK,CAAC,iCAAiC,MAAM,EAAE,CAAC,CAAA;QAChD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF"}