@vorim/sdk 3.4.3 → 3.6.0

package/dist/index.d.ts

@@ -85,6 +85,14 @@ interface AuditEventInput {
     delegator_agent_id?: string;
     delegation_chain_id?: string;
     delegation_depth?: number;
+    /**
+     * Runtime-control linkage. When this action was gated through
+     * {@link VorimSDK.beforeAction} before being performed, pass the
+     * returned `decisionId` here (the SDK maps it to `decision_id` on the
+     * wire) so the audit event links back to the runtime decision that
+     * authorised it.
+     */
+    decision_id?: string;
 }
 /**
  * Claims structure for one VAIP -02 § 5 delegation link.
@@ -160,6 +168,68 @@ interface TrustRecord {
     revocation_status: boolean;
     last_active?: string;
 }
+/**
+ * The verdict a runtime decision can carry.
+ *
+ * - `allow`    — proceed with the action.
+ * - `deny`     — do NOT perform the action. {@link VorimSDK.beforeAction}
+ *                throws {@link VorimDeniedError} on this when `throwOnDeny`.
+ * - `modify`   — proceed, but with `modifiedPayload` instead of the
+ *                original payload (e.g. PII masked by a policy rule).
+ * - `escalate` — a human must approve. Poll
+ *                {@link VorimSDK.waitForDecisionResolution} for the outcome.
+ * - `fallback` — the engine could not decide (timeout / error) and the
+ *                org's fail-open/closed setting was applied. `isFallback`
+ *                is true. The SDK also returns this shape locally when the
+ *                decision API is unreachable and `runtimeFailOpen` is set.
+ */
+type DecisionVerdict = 'allow' | 'deny' | 'modify' | 'escalate' | 'fallback';
+/** Input to {@link VorimSDK.beforeAction}. Always use the public `agid_*` id. */
+interface BeforeActionInput {
+    /** Public agent identifier (`agid_*`). UUIDs are accepted but discouraged. */
+    agentId: string;
+    /** Coarse action category, e.g. `tool_call`, `api_request`. */
+    actionType: string;
+    /** Specific target, e.g. the tool name `sendEmail`. */
+    actionTarget?: string;
+    /** The action's arguments. Capped at 64KB serialised by the server. */
+    payload?: Record<string, unknown>;
+    /** Free-form context the policy engine may match on. */
+    context?: Record<string, unknown>;
+    /** Permission scope the action requires; checked against the agent's grants. */
+    requiredScope?: string;
+    /**
+     * Idempotency key. Pass the SAME key when retrying a failed request so
+     * the server returns the original decision instead of creating a new one.
+     */
+    idempotencyKey?: string;
+}
+/** A runtime decision, as returned by {@link VorimSDK.beforeAction}. */
+interface RuntimeDecision {
+    /** Server-assigned id. Carry into {@link AuditEventInput.decision_id}. */
+    decisionId: string;
+    decision: DecisionVerdict;
+    reason: string;
+    /** The policy rule that produced this decision, or null for defaults. */
+    decisionRuleId: string | null;
+    /** Present (object) when `decision === 'modify'`; null otherwise. */
+    modifiedPayload: Record<string, unknown> | null;
+    /** ISO8601 — after this the decision is stale and should not be relied on. */
+    expiresAt: string;
+    latencyMs: number;
+    /** True when the engine fell back (timeout/error/unreachable). */
+    isFallback: boolean;
+    policyVersion: number;
+    /**
+     * The human verdict on an escalation, once resolved by an operator:
+     * `'approved'`, `'denied'`, or `null` if not (yet) an escalation outcome.
+     *
+     * When this is set, {@link decision} is already translated for you
+     * (`approved` → `'allow'`, `denied` → `'deny'`) so the normal verdict
+     * checks work — this field is the raw resolution for callers who want it.
+     */
+    escalationResolution: 'approved' | 'denied' | null;
+}
 
 /**
  * Replayable agent decision evidence helpers.
@@ -324,6 +394,19 @@ interface VorimConfig {
      * a failure). Chain integrity is checked by `@vorim/verify`.
      */
     chainEvents?: boolean;
+    /**
+     * Client-side fail-open behaviour for {@link VorimSDK.beforeAction} when
+     * the runtime decision API itself is unreachable (network error, DNS,
+     * timeout, or 5xx). Default `true`: a transport failure returns a
+     * synthetic `fallback` decision (`decision: 'fallback'`, `isFallback:
+     * true`) so a momentary control-plane outage does not block the agent.
+     * Set `false` to fail closed — `beforeAction` re-throws the transport
+     * error and the caller must decide.
+     *
+     * Note: this governs only transport failures. A reachable server that
+     * returns `deny` still denies regardless of this flag.
+     */
+    runtimeFailOpen?: boolean;
 }
 /**
  * VAIP v0 canonical bytes used by Vorim's per-event signing.
@@ -357,6 +440,7 @@ declare class VorimSDK {
     private autoSign;
     private canonicalForm;
     private chainEvents;
+    private runtimeFailOpen;
     /**
      * In-memory keyring mapping agent_id -> PEM-encoded Ed25519 private key.
      * Populated automatically by register() and registerEphemeral(), or
@@ -576,6 +660,74 @@ declare class VorimSDK {
     revokeAgentDelegation(agentId: string, chainId: string): Promise<{
         revoked: number;
     }>;
+    /**
+     * Gate an agent action BEFORE it is performed. Calls
+     * `POST /v1/runtime/decisions` and returns a typed {@link RuntimeDecision}.
+     *
+     * By default (`throwOnDeny: true`) a `deny` verdict throws
+     * {@link VorimDeniedError} — deny is carried in the response body, not
+     * the HTTP status, so without this the caller would treat a denial as
+     * success. Pass `{ throwOnDeny: false }` to handle deny yourself.
+     *
+     * On a `modify` verdict, use `decision.modifiedPayload` in place of your
+     * original payload (e.g. a policy rule masked PII). This is
+     * client-cooperative: Vorim returns the sanitised payload but does not sit
+     * inline and does not enforce that you send it — carry `decisionId` into
+     * the matching {@link emit} so the action stays auditable. On `escalate`,
+     * poll {@link waitForDecisionResolution} for the human decision.
+     *
+     * Transport failures (network/DNS/timeout/5xx) respect the constructor's
+     * `runtimeFailOpen` flag: when true (default) a synthetic `fallback`
+     * decision is returned so a control-plane blip does not block the agent;
+     * when false the underlying error is re-thrown.
+     *
+     * Always pass the public `agid_*` id as `agentId`.
+     *
+     * @example
+     * const d = await vorim.beforeAction({
+     *   agentId: 'agid_acme_evilbot',
+     *   actionType: 'tool_call',
+     *   actionTarget: 'sendEmail',
+     *   requiredScope: 'agent:communicate',
+     *   payload: { to: 'customer@example.com' },
+     * });
+     * if (d.decision === 'allow') await sendEmail(d.modifiedPayload ?? payload);
+     */
+    beforeAction(input: BeforeActionInput, options?: {
+        throwOnDeny?: boolean;
+    }): Promise<RuntimeDecision>;
+    /**
+     * Poll a decision until it leaves the `escalate` state (a human
+     * approved or denied it) or the timeout elapses. Returns the resolved
+     * decision; throws {@link VorimError} `ESCALATION_TIMEOUT` (408) if the
+     * decision is still pending when the timeout is reached.
+     *
+     * Requires an API key with the `runtime:decide` scope (the same scope
+     * `beforeAction` uses).
+     */
+    waitForDecisionResolution(decisionId: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<RuntimeDecision>;
+    /**
+     * Map a snake_case decision row (from POST or GET) to the camelCase
+     * {@link RuntimeDecision}. The SDK has no generic camelizer, so the
+     * mapping is explicit — and tolerant of either the POST shape
+     * (`decision_rule_id`, `latency_ms`) or absent fields on a GET row.
+     *
+     * Escalation-resolution translation (load-bearing): the server resolves
+     * an escalation by setting `escalation_resolution` but does NOT flip the
+     * row's `decision` column off `'escalate'`. If we returned that verbatim,
+     * a caller's obvious `if (d.decision === 'deny')` check would never fire
+     * on a human DENIAL — a silent fail-open. So when a resolution is present
+     * we translate the verdict: approved → 'allow', denied → 'deny'. The raw
+     * resolution is also surfaced as `escalationResolution` for callers that
+     * want it explicitly.
+     *
+     * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
+     * rather than 'fallback', so the deny check fires on garbled input.
+     */
+    private toRuntimeDecision;
     /**
      * Emit an audit event for an agent action.
      *
@@ -754,6 +906,9 @@ declare class VorimSDK {
     private post;
     private patch;
     private delete;
+    /** Like request() but returns the FULL { data, meta, ... } envelope
+     *  instead of unwrapping to `data`. Used where meta (pagination) matters. */
+    private requestEnvelope;
     private request;
     private pemToArrayBuffer;
     private arrayBufferToBase64;
@@ -764,6 +919,16 @@ declare class VorimError extends Error {
     details?: Record<string, unknown> | undefined;
     constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined);
 }
+/**
+ * Thrown by {@link VorimSDK.beforeAction} when the runtime decision is
+ * `deny` and `throwOnDeny` is left at its default (`true`). Carries the
+ * full {@link RuntimeDecision} so the caller can inspect the reason and
+ * the decision id. Status is 403 with code `DECISION_DENIED`.
+ */
+declare class VorimDeniedError extends VorimError {
+    decision: RuntimeDecision;
+    constructor(decision: RuntimeDecision);
+}
 declare function createVorim(config: VorimConfig): VorimSDK;
 
-export { type Agent, type AgentDelegationRecord, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type DelegationLinkClaims, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type TrustRecord, type VorimConfig, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };
+export { type Agent, type AgentDelegationRecord, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, type BeforeActionInput, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type DecisionVerdict, type DelegationLinkClaims, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type RuntimeDecision, type TrustRecord, type VorimConfig, VorimDeniedError, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };

package/dist/index.js

@@ -17,10 +17,9 @@ function jcsCanonicalise(value) {
     return "[" + value.map(jcsCanonicalise).join(",") + "]";
   }
   if (typeof value === "object") {
-    const keys = Object.keys(value).sort();
-    const parts = keys.map((k) => {
-      return JSON.stringify(k) + ":" + jcsCanonicalise(value[k]);
-    });
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    const parts = keys.map((k) => JSON.stringify(k) + ":" + jcsCanonicalise(obj[k]));
     return "{" + parts.join(",") + "}";
   }
   throw new Error(`jcsCanonicalise: unsupported value type: ${typeof value}`);
@@ -70,8 +69,11 @@ async function prepareReplayContext(inputs) {
 }
 
 // src/index.ts
-var SDK_VERSION = true ? "3.4.3" : "0.0.0";
+var SDK_VERSION = true ? "3.6.0" : "0.0.0";
 var USER_AGENT = `vorim-sdk/${SDK_VERSION}`;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function canonicalPayloadV0(event) {
   return [
     event.event_type,
@@ -93,6 +95,7 @@ var VorimSDK = class _VorimSDK {
   autoSign;
   canonicalForm;
   chainEvents;
+  runtimeFailOpen;
   /**
    * In-memory keyring mapping agent_id -> PEM-encoded Ed25519 private key.
    * Populated automatically by register() and registerEphemeral(), or
@@ -138,6 +141,7 @@ var VorimSDK = class _VorimSDK {
       }
     }
     this.chainEvents = config.chainEvents ?? false;
+    this.runtimeFailOpen = config.runtimeFailOpen ?? true;
   }
   /**
    * Register a previously-issued agent keypair so this SDK instance can
@@ -234,7 +238,8 @@ var VorimSDK = class _VorimSDK {
    */
   async listAgents(params) {
     const qs = new URLSearchParams(params).toString();
-    return this.get(`/agents${qs ? "?" + qs : ""}`);
+    const env = await this.requestEnvelope("GET", `/agents${qs ? "?" + qs : ""}`);
+    return { agents: env.data ?? [], meta: env.meta ?? null };
   }
   /**
    * Update an agent's metadata.
@@ -363,6 +368,149 @@ var VorimSDK = class _VorimSDK {
   async revokeAgentDelegation(agentId, chainId) {
     return this.delete(`/agents/${agentId}/delegations/${chainId}`);
   }
+  // ─── Runtime Control (Strategy A) ──────────────────────────────────
+  /**
+   * Gate an agent action BEFORE it is performed. Calls
+   * `POST /v1/runtime/decisions` and returns a typed {@link RuntimeDecision}.
+   *
+   * By default (`throwOnDeny: true`) a `deny` verdict throws
+   * {@link VorimDeniedError} — deny is carried in the response body, not
+   * the HTTP status, so without this the caller would treat a denial as
+   * success. Pass `{ throwOnDeny: false }` to handle deny yourself.
+   *
+   * On a `modify` verdict, use `decision.modifiedPayload` in place of your
+   * original payload (e.g. a policy rule masked PII). This is
+   * client-cooperative: Vorim returns the sanitised payload but does not sit
+   * inline and does not enforce that you send it — carry `decisionId` into
+   * the matching {@link emit} so the action stays auditable. On `escalate`,
+   * poll {@link waitForDecisionResolution} for the human decision.
+   *
+   * Transport failures (network/DNS/timeout/5xx) respect the constructor's
+   * `runtimeFailOpen` flag: when true (default) a synthetic `fallback`
+   * decision is returned so a control-plane blip does not block the agent;
+   * when false the underlying error is re-thrown.
+   *
+   * Always pass the public `agid_*` id as `agentId`.
+   *
+   * @example
+   * const d = await vorim.beforeAction({
+   *   agentId: 'agid_acme_evilbot',
+   *   actionType: 'tool_call',
+   *   actionTarget: 'sendEmail',
+   *   requiredScope: 'agent:communicate',
+   *   payload: { to: 'customer@example.com' },
+   * });
+   * if (d.decision === 'allow') await sendEmail(d.modifiedPayload ?? payload);
+   */
+  async beforeAction(input, options = {}) {
+    const throwOnDeny = options.throwOnDeny ?? true;
+    const body = {
+      agent_id: input.agentId,
+      action_type: input.actionType,
+      action_target: input.actionTarget,
+      payload: input.payload,
+      context: input.context,
+      required_scope: input.requiredScope,
+      idempotency_key: input.idempotencyKey
+    };
+    let raw;
+    try {
+      raw = await this.post("/runtime/decisions", body);
+    } catch (err) {
+      const status = err instanceof VorimError ? err.status : 0;
+      const isTransport = status === 0 || status >= 500;
+      if (isTransport && this.runtimeFailOpen) {
+        return {
+          decisionId: "",
+          decision: "fallback",
+          reason: "Runtime decision API unreachable; client fail-open applied",
+          decisionRuleId: null,
+          modifiedPayload: null,
+          expiresAt: new Date(Date.now() + 6e4).toISOString(),
+          latencyMs: 0,
+          isFallback: true,
+          policyVersion: 0,
+          escalationResolution: null
+        };
+      }
+      throw err;
+    }
+    const decision = this.toRuntimeDecision(raw);
+    if (decision.decision === "deny" && throwOnDeny) {
+      throw new VorimDeniedError(decision);
+    }
+    return decision;
+  }
+  /**
+   * Poll a decision until it leaves the `escalate` state (a human
+   * approved or denied it) or the timeout elapses. Returns the resolved
+   * decision; throws {@link VorimError} `ESCALATION_TIMEOUT` (408) if the
+   * decision is still pending when the timeout is reached.
+   *
+   * Requires an API key with the `runtime:decide` scope (the same scope
+   * `beforeAction` uses).
+   */
+  async waitForDecisionResolution(decisionId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 3e5;
+    const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+    const start = Date.now();
+    do {
+      const raw = await this.get(`/runtime/decisions/${decisionId}`);
+      if (raw?.decision !== "escalate" || raw?.escalation_resolution) {
+        return this.toRuntimeDecision(raw);
+      }
+      const remaining = timeoutMs - (Date.now() - start);
+      if (remaining <= 0) break;
+      await sleep(Math.min(pollIntervalMs, remaining));
+    } while (Date.now() - start < timeoutMs);
+    throw new VorimError(
+      408,
+      "ESCALATION_TIMEOUT",
+      `Decision ${decisionId} still pending after ${timeoutMs}ms`,
+      { decisionId }
+    );
+  }
+  /**
+   * Map a snake_case decision row (from POST or GET) to the camelCase
+   * {@link RuntimeDecision}. The SDK has no generic camelizer, so the
+   * mapping is explicit — and tolerant of either the POST shape
+   * (`decision_rule_id`, `latency_ms`) or absent fields on a GET row.
+   *
+   * Escalation-resolution translation (load-bearing): the server resolves
+   * an escalation by setting `escalation_resolution` but does NOT flip the
+   * row's `decision` column off `'escalate'`. If we returned that verbatim,
+   * a caller's obvious `if (d.decision === 'deny')` check would never fire
+   * on a human DENIAL — a silent fail-open. So when a resolution is present
+   * we translate the verdict: approved → 'allow', denied → 'deny'. The raw
+   * resolution is also surfaced as `escalationResolution` for callers that
+   * want it explicitly.
+   *
+   * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
+   * rather than 'fallback', so the deny check fires on garbled input.
+   */
+  toRuntimeDecision(raw) {
+    const resolution = raw?.escalation_resolution === "approved" ? "approved" : raw?.escalation_resolution === "denied" ? "denied" : null;
+    const hasVerdict = typeof raw?.decision === "string";
+    let decision;
+    if (raw?.decision === "escalate" && resolution === "approved") decision = "allow";
+    else if (raw?.decision === "escalate" && resolution === "denied") decision = "deny";
+    else if (hasVerdict) decision = raw.decision;
+    else decision = "deny";
+    return {
+      decisionId: raw?.decision_id ?? "",
+      decision,
+      reason: raw?.reason ?? (hasVerdict ? "" : "Malformed decision response (no verdict); failing closed"),
+      decisionRuleId: raw?.decision_rule_id ?? null,
+      modifiedPayload: raw?.modified_payload ?? null,
+      // Avoid '' (Date.parse('') === NaN). A verdict-less row gets an epoch
+      // timestamp so any staleness check treats it as already expired.
+      expiresAt: raw?.expires_at ?? (hasVerdict ? "" : (/* @__PURE__ */ new Date(0)).toISOString()),
+      latencyMs: raw?.latency_ms ?? 0,
+      isFallback: raw?.is_fallback ?? !hasVerdict,
+      policyVersion: raw?.policy_version ?? 0,
+      escalationResolution: resolution
+    };
+  }
   // ─── Audit ────────────────────────────────────────────────────────
   /**
    * Emit an audit event for an agent action.
@@ -639,7 +787,12 @@ var VorimSDK = class _VorimSDK {
   async delete(path) {
     return this.request("DELETE", path);
   }
-  async request(method, path, body) {
+  /** Like request() but returns the FULL { data, meta, ... } envelope
+   *  instead of unwrapping to `data`. Used where meta (pagination) matters. */
+  async requestEnvelope(method, path, body) {
+    return this.request(method, path, body, false);
+  }
+  async request(method, path, body, unwrap = true) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
@@ -663,7 +816,7 @@ var VorimSDK = class _VorimSDK {
         );
       }
       const json = await response.json();
-      return json.data;
+      return unwrap ? json.data : json;
     } finally {
       clearTimeout(timeoutId);
     }
@@ -698,11 +851,20 @@ var VorimError = class extends Error {
   code;
   details;
 };
+var VorimDeniedError = class extends VorimError {
+  constructor(decision) {
+    super(403, "DECISION_DENIED", decision.reason, { decisionId: decision.decisionId });
+    this.decision = decision;
+    this.name = "VorimDeniedError";
+  }
+  decision;
+};
 function createVorim(config) {
   return new VorimSDK(config);
 }
 export {
   CANONICAL_TOOL_CATALOGUE_VERSION,
+  VorimDeniedError,
   VorimError,
   VorimSDK,
   canonicalPayloadV0,