@vorim/sdk 3.4.3 → 3.6.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog — @vorim/sdk
+
+## 3.5.0
+
+### Added — Runtime Control (gate actions before they happen)
+
+- **`beforeAction(input, { throwOnDeny })`** — call `POST /v1/runtime/decisions`
+  before an agent performs an action and get a typed `RuntimeDecision`
+  (`allow` / `deny` / `modify` / `escalate` / `fallback`). Throws
+  `VorimDeniedError` on `deny` by default (deny is in the body, not the HTTP
+  status, so without this consumers would treat a denial as success).
+- **`waitForDecisionResolution(decisionId, { timeoutMs, pollIntervalMs })`** —
+  poll an `escalate` decision until a human operator resolves it. The resolved
+  verdict is translated for you (`approved → allow`, `denied → deny`) and the
+  raw outcome is exposed as `escalationResolution`. Throws `ESCALATION_TIMEOUT`
+  (408) if still pending at timeout.
+- **`VorimDeniedError`** — carries the full `RuntimeDecision` (`.decision`),
+  status 403, code `DECISION_DENIED`.
+- **`runtimeFailOpen` constructor option** (default `true`) — on a transport
+  failure (network / DNS / timeout / 5xx) `beforeAction` returns a synthetic
+  `fallback` decision so a control-plane blip doesn't block the agent. Set
+  `false` to fail closed. A reachable server returning `deny` always denies.
+- **`emit({ ..., decision_id })`** — carry the `decisionId` from `beforeAction`
+  into the post-action audit event so it links back to the runtime decision
+  that authorised it.
+- New exported types: `BeforeActionInput`, `RuntimeDecision`, `DecisionVerdict`.
+
+### Notes
+
+- `modify` is **client-cooperative**: the SDK returns the sanitised
+  `modifiedPayload`, but your agent must send it. The platform does not sit
+  inline. Carry `decisionId` into `emit()` to keep the action auditable.
+- Malformed/verdict-less decision responses fail **closed** to `deny`.
+
+Requires an API key with the `runtime:decide` scope and a Growth+ plan.

package/README.md

@@ -258,6 +258,72 @@ await vorim.emitBatch([
 ]);
 ```
 
+### Runtime Control (gate actions before they happen)
+
+Ask Vorim whether an action should proceed **before** your agent performs it.
+`beforeAction()` returns a typed decision and, by default, **throws on deny** —
+because a denial is carried in the response body, not the HTTP status, so
+without `throwOnDeny` you'd treat a denial as success.
+
+```typescript
+import { VorimDeniedError } from "@vorim/sdk";
+
+try {
+  const decision = await vorim.beforeAction({
+    agentId: "agid_acme_a1b2c3d4",   // always the public agid_* id
+    actionType: "tool_call",
+    actionTarget: "sendEmail",
+    requiredScope: "agent:communicate",
+    payload: { to: "customer@example.com", body: "..." },
+  });
+
+  // 'modify' verdicts hand back a sanitised payload (e.g. PII masked).
+  const payload = decision.modifiedPayload ?? { to: "customer@example.com" };
+
+  if (decision.decision === "allow" || decision.decision === "modify") {
+    await sendEmail(payload);
+  } else if (decision.decision === "escalate") {
+    // A human must approve. Poll until resolved (or timeout).
+    const resolved = await vorim.waitForDecisionResolution(decision.decisionId);
+    if (resolved.decision === "allow") await sendEmail(payload);
+  }
+
+  // Link the post-action audit event back to the decision.
+  await vorim.emit({
+    agent_id: "agid_acme_a1b2c3d4",
+    event_type: "tool_call",
+    action: "sendEmail",
+    result: "success",
+    decision_id: decision.decisionId,   // ← correlates audit ↔ decision
+  });
+} catch (err) {
+  if (err instanceof VorimDeniedError) {
+    // err.decision carries the reason and decisionId.
+    console.warn("Action denied:", err.decision.reason);
+  } else {
+    throw err;
+  }
+}
+```
+
+**Verdicts:** `allow` · `deny` (throws `VorimDeniedError` by default) ·
+`modify` (use `decision.modifiedPayload`) · `escalate` (poll
+`waitForDecisionResolution`) · `fallback` (engine couldn't decide).
+
+> **`modify` is client-cooperative.** Vorim returns the sanitised
+> `modifiedPayload`; your agent must send it in place of the original. The
+> platform does not sit inline and does not currently enforce that you do —
+> carry `decisionId` into the matching `emit()` so the action stays auditable.
+
+**Fail-open:** if the decision API is unreachable, `beforeAction()` returns a
+synthetic `fallback` decision so a control-plane blip doesn't block your agent.
+Pass `runtimeFailOpen: false` to the constructor to fail closed instead. A
+reachable server returning `deny` always denies, regardless of this flag.
+
+> Requires an API key with the `runtime:decide` scope and a Growth+ plan.
+> `modify` verdicts are produced by policy rules; the rule-authoring API
+> ships in a later release — until then rules are provisioned by Vorim.
+
 ### Trust Verification
 
 ```typescript

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CANONICAL_TOOL_CATALOGUE_VERSION: () => CANONICAL_TOOL_CATALOGUE_VERSION,
+  VorimDeniedError: () => VorimDeniedError,
   VorimError: () => VorimError,
   VorimSDK: () => VorimSDK,
   canonicalPayloadV0: () => canonicalPayloadV0,
@@ -64,10 +65,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}`);
@@ -117,8 +117,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,
@@ -140,6 +143,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
@@ -185,6 +189,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
@@ -281,7 +286,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.
@@ -410,6 +416,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.
@@ -686,7 +835,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 {
@@ -710,7 +864,7 @@ var VorimSDK = class _VorimSDK {
         );
       }
       const json = await response.json();
-      return json.data;
+      return unwrap ? json.data : json;
     } finally {
       clearTimeout(timeoutId);
     }
@@ -745,12 +899,21 @@ 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);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CANONICAL_TOOL_CATALOGUE_VERSION,
+  VorimDeniedError,
   VorimError,
   VorimSDK,
   canonicalPayloadV0,