@atlasent/sdk 1.5.0 → 2.5.0

package/dist/hono.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/hono.ts
@@ -28,6 +38,27 @@ __export(hono_exports, {
 module.exports = __toCommonJS(hono_exports);
 
 // src/errors.ts
+var StreamTimeoutError = class extends Error {
+  name = "StreamTimeoutError";
+  /** Timeout that was exceeded, in milliseconds. */
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`AtlaSent stream timed out after ${timeoutMs}ms with no event`);
+    this.timeoutMs = timeoutMs;
+  }
+};
+var StreamParseError = class extends Error {
+  name = "StreamParseError";
+  /** The raw data string that failed to parse. */
+  rawData;
+  constructor(rawData, cause) {
+    super(`AtlaSent stream received malformed JSON: ${rawData.slice(0, 200)}`);
+    this.rawData = rawData;
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+  }
+};
 var AtlaSentError = class extends Error {
   // Subclasses override to their own literal (e.g. "AtlaSentDeniedError");
   // keep this assignable rather than pinned to a single literal.
@@ -51,6 +82,18 @@ var AtlaSentError = class extends Error {
     this.retryAfterMs = init.retryAfterMs;
   }
 };
+var KNOWN_PERMIT_OUTCOMES = /* @__PURE__ */ new Set([
+  "permit_consumed",
+  "permit_expired",
+  "permit_revoked",
+  "permit_not_found"
+]);
+function normalizePermitOutcome(raw) {
+  if (raw !== void 0 && KNOWN_PERMIT_OUTCOMES.has(raw)) {
+    return raw;
+  }
+  return void 0;
+}
 var AtlaSentDeniedError = class extends AtlaSentError {
   name = "AtlaSentDeniedError";
   /** Policy decision — `"deny"` today; `"hold"` / `"escalate"` reserved. */
@@ -61,6 +104,12 @@ var AtlaSentDeniedError = class extends AtlaSentError {
   reason;
   /** Hash-chained audit-trail entry associated with the decision. */
   auditHash;
+  /**
+   * Discriminator for permit-side denial reasons. Populated only
+   * when the server reported `verified=false` from `/v1-verify-permit`;
+   * `undefined` for evaluate-time denials. See {@link PermitOutcome}.
+   */
+  outcome;
   constructor(init) {
     const msg = init.reason ? `AtlaSent ${init.decision}: ${init.reason}` : `AtlaSent ${init.decision}`;
     const errInit = { status: 200 };
@@ -70,92 +119,620 @@ var AtlaSentDeniedError = class extends AtlaSentError {
     this.evaluationId = init.evaluationId;
     this.reason = init.reason;
     this.auditHash = init.auditHash;
+    this.outcome = init.outcome;
+  }
+  // ── Outcome discriminators ───────────────────────────────────────
+  // Convenience predicates that mirror the operator runbook's matrix.
+  // Callers can compare `outcome` directly; these are sugar so the
+  // common cases are explicit at the call site.
+  /** `true` when the permit was explicitly revoked (D3 endpoint). */
+  get isRevoked() {
+    return this.outcome === "permit_revoked";
+  }
+  /** `true` when the permit's TTL passed before verification. */
+  get isExpired() {
+    return this.outcome === "permit_expired";
+  }
+  /**
+   * `true` when the permit was already consumed by a prior verify
+   * (v1 single-use replay protection).
+   */
+  get isConsumed() {
+    return this.outcome === "permit_consumed";
+  }
+  /**
+   * `true` when the permit id wasn't recognized server-side
+   * (typo, cross-tenant lookup, or pre-issuance race).
+   */
+  get isNotFound() {
+    return this.outcome === "permit_not_found";
   }
 };
 
+// src/types.ts
+var PRODUCTION_DEPLOY_ACTION = "production.deploy";
+var DEPLOY_GATE_CODES = Object.freeze({
+  ALLOW: "ALLOW",
+  DENY_POLICY: "DENY_POLICY",
+  DENY_AUTHORITY: "DENY_AUTHORITY",
+  DENY_ENVIRONMENT: "DENY_ENVIRONMENT",
+  PERMIT_EXPIRED: "PERMIT_EXPIRED",
+  VERIFY_FAILED: "VERIFY_FAILED",
+  ESCALATE_REQUIRED: "ESCALATE_REQUIRED",
+  OVERRIDE_APPROVED: "OVERRIDE_APPROVED"
+});
+
+// src/compat.ts
+function normalizeEvaluateRequest(input) {
+  if ("action" in input && !("action_type" in input)) {
+    console.warn(
+      "[atlasent] Deprecation: action/agent request shape is deprecated. Use action_type/actor_id instead. This compatibility shim will be removed in v3.0.0."
+    );
+    const legacy = input;
+    const normalized = {
+      action_type: legacy.action,
+      actor_id: legacy.agent
+    };
+    if (legacy.context !== void 0) {
+      normalized.context = legacy.context;
+    }
+    return normalized;
+  }
+  return input;
+}
+
+// src/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 2e3,
+  maxDelayMs: 16e3
+};
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  "network",
+  "timeout",
+  "rate_limited",
+  "server_error",
+  "bad_response"
+]);
+function isRetryable(err) {
+  if (!(err instanceof AtlaSentError)) return false;
+  if (err.code === void 0) return false;
+  return RETRYABLE_CODES.has(err.code);
+}
+function computeBackoffMs(attempt, policy = {}, err, random = Math.random) {
+  const merged = mergePolicy(policy);
+  const safeAttempt = Math.max(0, Math.floor(attempt));
+  const exp = Math.min(safeAttempt, 30);
+  const ceiling = Math.min(merged.maxDelayMs, merged.baseDelayMs * 2 ** exp);
+  const jittered = Math.floor(ceiling * clampUnit(random()));
+  const retryAfterMs = err instanceof AtlaSentError && typeof err.retryAfterMs === "number" ? Math.max(0, err.retryAfterMs) : 0;
+  return Math.max(retryAfterMs, jittered);
+}
+function hasAttemptsLeft(attempt, policy = {}) {
+  const merged = mergePolicy(policy);
+  return attempt + 1 < merged.maxAttempts;
+}
+function mergePolicy(policy) {
+  const maxAttempts = Math.max(
+    1,
+    Math.floor(policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts)
+  );
+  const baseDelayMs = Math.max(
+    0,
+    policy.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs
+  );
+  const maxDelayMs = Math.max(
+    baseDelayMs,
+    policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs
+  );
+  return { maxAttempts, baseDelayMs, maxDelayMs };
+}
+function clampUnit(n) {
+  if (!Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n >= 1) return 0.999999999;
+  return n;
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.atlasent.io";
 var DEFAULT_TIMEOUT_MS = 1e4;
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "2.2.0";
+function _buildUserAgent() {
+  const isNode2 = typeof process !== "undefined" && typeof process?.versions?.node === "string";
+  return isNode2 ? `@atlasent/sdk/${SDK_VERSION} node/${process.version}` : `@atlasent/sdk/${SDK_VERSION} browser`;
+}
+var CONTEXT_PROPERTIES_SOFT_CAP = 64;
+function _warnOversizeContext(context) {
+  if (context && Object.keys(context).length > CONTEXT_PROPERTIES_SOFT_CAP) {
+    console.warn(
+      `[atlasent] context has ${Object.keys(context).length} top-level keys (soft cap ${CONTEXT_PROPERTIES_SOFT_CAP}); the server may reject this. Pack richer payloads under a single top-level key.`
+    );
+  }
+}
+function _enforceTls(baseUrl) {
+  const nodeEnvValue = typeof process !== "undefined" && process.env ? process.env.ATLASENT_ALLOW_INSECURE_HTTP : void 0;
+  const allow = nodeEnvValue === "1" || globalThis.ATLASENT_ALLOW_INSECURE_HTTP === "1";
+  if (allow) return baseUrl;
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new AtlaSentError(`Invalid baseUrl: ${baseUrl}`, {
+      code: "bad_request"
+    });
+  }
+  if (parsed.protocol !== "https:") {
+    throw new AtlaSentError(
+      `AtlaSent baseUrl must use https:// (got ${parsed.protocol}). For local development, set ATLASENT_ALLOW_INSECURE_HTTP=1.`,
+      { code: "bad_request" }
+    );
+  }
+  return baseUrl;
+}
+var API_KEY_PATTERN = /^ask_(?:live|test)_[A-Za-z0-9_-]+$/;
+function _validateApiKey(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    throw new AtlaSentError("apiKey is required", { code: "invalid_api_key" });
+  }
+  if (!API_KEY_PATTERN.test(apiKey)) {
+    const head = apiKey.slice(0, 8);
+    throw new AtlaSentError(
+      `AtlaSent apiKey does not match expected shape \`ask_(live|test)_<entropy>\` (got prefix=${JSON.stringify(head)}). Check for whitespace, quotes, or trailing characters.`,
+      { code: "invalid_api_key" }
+    );
+  }
+  return apiKey;
+}
+var isNode = typeof process !== "undefined" && typeof process.versions?.node === "string";
+var NODE_VERSION = isNode ? process.version : null;
+function deployGateEvidence(input) {
+  const evidence = {};
+  if (input.permitId) evidence.permitId = input.permitId;
+  if (input.permitHash) evidence.permitHash = input.permitHash;
+  if (input.auditHash) evidence.auditHash = input.auditHash;
+  if (input.verifiedAt) evidence.verifiedAt = input.verifiedAt;
+  return evidence;
+}
 var AtlaSentClient = class {
   apiKey;
   baseUrl;
   timeoutMs;
   fetchImpl;
+  userAgent;
+  retryPolicy;
   constructor(options) {
     if (!options.apiKey || typeof options.apiKey !== "string") {
       throw new AtlaSentError("apiKey is required", {
         code: "invalid_api_key"
       });
     }
-    this.apiKey = options.apiKey;
-    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (typeof AbortSignal.timeout !== "function") {
+      throw new AtlaSentError(
+        "@atlasent/sdk requires AbortSignal.timeout, which is not available in this runtime. Minimum supported browsers: Chrome 103+, Firefox 100+, Safari 16+. Upgrade your browser or add an AbortSignal.timeout polyfill.",
+        { code: "network" }
+      );
+    }
+    this.apiKey = _validateApiKey(options.apiKey);
+    this.baseUrl = _enforceTls(options.baseUrl ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.userAgent = _buildUserAgent();
+    this.retryPolicy = mergePolicy(options.retryPolicy ?? {});
   }
   /**
    * Ask the policy engine whether an agent action is permitted.
    *
-   * A "DENY" is **not** thrown — it is returned in
+   * Accepts either the current v2.0 shape (`action_type` / `actor_id`)
+   * or the legacy v1.x shape (`action` / `agent`). Legacy callers
+   * receive a deprecation warning via `console.warn`; the shim is
+   * handled by {@link normalizeEvaluateRequest} and will be removed
+   * in v3.0.0.
+   *
+   * A "deny" is **not** thrown — it is returned in
    * `response.decision`. Network errors, invalid API key, rate
    * limits, timeouts, and malformed responses throw
    * {@link AtlaSentError}.
    */
   async evaluate(input) {
+    _warnOversizeContext(input.context);
+    const normalized = normalizeEvaluateRequest(
+      input
+    );
     const body = {
-      action: input.action,
-      agent: input.agent,
-      context: input.context ?? {},
-      api_key: this.apiKey
+      action_type: normalized.action_type,
+      actor_id: normalized.actor_id,
+      context: normalized.context ?? {}
     };
-    const { body: wire, rateLimit } = await this.post("/v1-evaluate", body);
-    if (typeof wire.permitted !== "boolean" || typeof wire.decision_id !== "string") {
+    const { body: wire, rateLimit } = await this.post(
+      "/v1-evaluate",
+      body
+    );
+    let decision = typeof wire.decision === "string" ? wire.decision.toLowerCase() : wire.decision;
+    if (decision === void 0 && typeof wire.permitted === "boolean") {
+      decision = wire.permitted ? "allow" : "deny";
+    }
+    const permitToken = wire.permit_token ?? wire.decision_id;
+    if (decision !== "allow" && decision !== "deny" && decision !== "hold" && decision !== "escalate") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-evaluate: missing `decision` (or legacy `permitted`)",
+        { code: "bad_response" }
+      );
+    }
+    if (decision === "allow" && (typeof permitToken !== "string" || permitToken.length === 0)) {
       throw new AtlaSentError(
-        "Malformed response from /v1-evaluate: missing `permitted` or `decision_id`",
+        "Malformed response from /v1-evaluate: decision='allow' but no `permit_token` (or legacy `decision_id`)",
         { code: "bad_response" }
       );
     }
+    const reason = wire.denial?.reason ?? wire.reason ?? "";
+    const permitId = permitToken ?? "";
     return {
-      decision: wire.permitted ? "ALLOW" : "DENY",
-      permitId: wire.decision_id,
-      reason: wire.reason ?? "",
+      decision,
+      decision_canonical: decision,
+      evaluationId: permitId,
+      permitId,
+      // /v1-evaluate does not return a control-plane-shaped Permit body;
+      // callers needing the full record fetch GET /v1/permits/:id.
+      permit: null,
+      permitToken: decision === "allow" ? permitToken ?? null : null,
+      reasons: reason ? [reason] : [],
+      reason,
       auditHash: wire.audit_hash ?? "",
       timestamp: wire.timestamp ?? "",
       rateLimit
     };
   }
+  /**
+   * Pre-flight evaluation that always returns the constraint trace.
+   *
+   * Wraps `POST /v1-evaluate?include=constraint_trace`. Use this from
+   * a workflow's submission step to surface trivial defects (missing
+   * fields, wrong roles, mis-set context) BEFORE pushing the request
+   * onto an approval queue — only requests that would actually pass
+   * make it through to a human reviewer.
+   *
+   * Returns an {@link EvaluatePreflightResponse} carrying the regular
+   * {@link EvaluateResponse} plus the {@link ConstraintTrace}. Unlike
+   * {@link evaluate}, this method does NOT mark a non-allow as a
+   * thrown condition — the whole point is to inspect both the outcome
+   * AND the per-policy trace, so the caller branches on
+   * `result.evaluation.decision` and reads `result.constraintTrace`
+   * to render the failing stages.
+   *
+   * The constraint-trace shape mirrors `ConstraintTraceResponse` in
+   * atlasent-api (`packages/types/src/index.ts`). On older
+   * atlasent-api deployments that omit the trace, `constraintTrace`
+   * is `null` rather than throwing — forward-compatible degradation.
+   *
+   * Performance: one extra round-trip on submission. Latency is
+   * comparable to {@link evaluate}; the response body is fuller
+   * (includes the per-stage trace) so the wire payload is larger.
+   * If the caller does not need the trace, prefer {@link evaluate}.
+   */
+  async evaluatePreflight(input) {
+    _warnOversizeContext(input.context);
+    const body = {
+      action_type: input.action,
+      actor_id: input.agent,
+      context: input.context ?? {}
+    };
+    const query = new URLSearchParams({ include: "constraint_trace" });
+    const { body: wire, rateLimit } = await this.post(
+      "/v1-evaluate",
+      body,
+      query
+    );
+    let decision = typeof wire.decision === "string" ? wire.decision.toLowerCase() : wire.decision;
+    if (decision === void 0 && typeof wire.permitted === "boolean") {
+      decision = wire.permitted ? "allow" : "deny";
+    }
+    if (decision !== "allow" && decision !== "deny" && decision !== "hold" && decision !== "escalate") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-evaluate: missing `decision` (or legacy `permitted`)",
+        { code: "bad_response" }
+      );
+    }
+    const permitToken = wire.permit_token ?? wire.decision_id;
+    const reason = wire.denial?.reason ?? wire.reason ?? "";
+    const permitId = permitToken ?? "";
+    const evaluation = {
+      decision,
+      decision_canonical: decision,
+      evaluationId: permitId,
+      permitId,
+      // /v1-evaluate does not return a control-plane-shaped Permit body;
+      // callers needing the full record fetch GET /v1/permits/:id.
+      permit: null,
+      permitToken: decision === "allow" ? permitToken ?? null : null,
+      reasons: reason ? [reason] : [],
+      reason,
+      auditHash: wire.audit_hash ?? "",
+      timestamp: wire.timestamp ?? "",
+      rateLimit
+    };
+    let constraintTrace = null;
+    if (wire.constraint_trace !== void 0 && wire.constraint_trace !== null && typeof wire.constraint_trace === "object") {
+      constraintTrace = wire.constraint_trace;
+    }
+    return { evaluation, constraintTrace };
+  }
   /**
    * Verify that a previously issued permit is still valid.
    *
+   * @deprecated Use {@link verifyPermitById} — the canonical REST
+   * surface (`POST /v1/permits/{id}/verify`) returns the unified
+   * verification envelope plus the full {@link PermitRecord}, instead
+   * of the legacy `{verified, outcome, permitHash}` shape this method
+   * emits. Will be removed in `@atlasent/sdk@3`.
+   *
    * A `verified: false` response is **not** thrown — inspect the
    * returned object. Only transport / server errors throw.
    */
   async verifyPermit(input) {
+    _warnOversizeContext(input.context);
     const body = {
-      decision_id: input.permitId,
-      action: input.action ?? "",
-      agent: input.agent ?? "",
-      context: input.context ?? {},
-      api_key: this.apiKey
+      permit_token: input.permitId,
+      action_type: input.action ?? "",
+      actor_id: input.agent ?? ""
     };
+    if (input.environment !== void 0) {
+      body.environment = input.environment;
+    }
+    if (input.execution_hash !== void 0) {
+      body.execution_hash = input.execution_hash;
+    }
     const { body: wire, rateLimit } = await this.post(
       "/v1-verify-permit",
       body
     );
-    if (typeof wire.verified !== "boolean") {
+    const valid = typeof wire.valid === "boolean" ? wire.valid : wire.verified;
+    if (typeof valid !== "boolean") {
       throw new AtlaSentError(
-        "Malformed response from /v1-verify-permit: missing `verified`",
+        "Malformed response from /v1-verify-permit: missing `valid` (or legacy `verified`)",
         { code: "bad_response" }
       );
     }
     return {
-      verified: wire.verified,
+      verified: valid,
       outcome: wire.outcome ?? "",
       permitHash: wire.permit_hash ?? "",
       timestamp: wire.timestamp ?? "",
       rateLimit
     };
   }
+  /**
+   * Run the canonical Deploy Gate V1 flow:
+   * evaluate `production.deploy`, verify the issued permit server-side,
+   * and return allow/block plus audit/evidence metadata.
+   *
+   * This helper never treats a signed/offline permit artifact as sufficient
+   * authorization. Execution is allowed only when `POST /v1-evaluate` returns
+   * `decision: "allow"` with a permit AND `POST /v1-verify-permit` returns
+   * `verified: true` / `valid: true`.
+   */
+  async deployGate(input = {}) {
+    const agent = input.agent ?? "ci-deploy-bot";
+    const action = input.action ?? PRODUCTION_DEPLOY_ACTION;
+    const context = input.context ?? {};
+    const evaluation = await this.evaluate({ agent, action, context });
+    if (evaluation.decision !== "allow") {
+      return {
+        allowed: false,
+        evaluation,
+        reason: evaluation.reason || `Deploy Gate blocked by decision=${evaluation.decision}`,
+        evidence: deployGateEvidence({
+          permitId: evaluation.permitId,
+          auditHash: evaluation.auditHash
+        })
+      };
+    }
+    const verification = await this.verifyPermit({
+      permitId: evaluation.permitId,
+      agent,
+      action,
+      context
+    });
+    if (!verification.verified) {
+      return {
+        allowed: false,
+        evaluation,
+        verification,
+        reason: verification.outcome ? `Deploy Gate blocked by permit verification outcome=${verification.outcome}` : "Deploy Gate blocked because permit verification failed",
+        evidence: deployGateEvidence({
+          permitId: evaluation.permitId,
+          permitHash: verification.permitHash,
+          auditHash: evaluation.auditHash,
+          verifiedAt: verification.timestamp
+        })
+      };
+    }
+    return {
+      allowed: true,
+      evaluation,
+      verification,
+      reason: evaluation.reason || "Deploy Gate permit verified",
+      evidence: deployGateEvidence({
+        permitId: evaluation.permitId,
+        permitHash: verification.permitHash,
+        auditHash: evaluation.auditHash,
+        verifiedAt: verification.timestamp
+      })
+    };
+  }
+  /**
+   * Revoke a previously-issued permit so it can no longer pass
+   * {@link verifyPermit}.
+   *
+   * @deprecated Use {@link revokePermitById} — the canonical REST
+   * surface (`POST /v1/permits/{id}/revoke`) returns the full updated
+   * {@link PermitRecord} with `revoked_at`/`revoked_by`/`revoke_reason`
+   * populated, instead of the legacy `{revoked, permitId}` envelope
+   * this method emits. Will be removed in `@atlasent/sdk@3`.
+   *
+   * Use this when an agent's action is cancelled, superseded, or
+   * determined to be unauthorized after the fact. The revocation is
+   * recorded in the audit log with the optional `reason`.
+   *
+   * Throws {@link AtlaSentError} on transport / auth failures.
+   */
+  async revokePermit(input) {
+    const body = {
+      decision_id: input.permitId,
+      reason: input.reason ?? "",
+      api_key: this.apiKey
+    };
+    const { body: wire, rateLimit } = await this.post("/v1-revoke-permit", body);
+    if (typeof wire.revoked !== "boolean" || typeof wire.decision_id !== "string") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-revoke-permit: missing `revoked` or `decision_id`",
+        { code: "bad_response" }
+      );
+    }
+    return {
+      revoked: wire.revoked,
+      permitId: wire.decision_id,
+      revokedAt: wire.revoked_at,
+      auditHash: wire.audit_hash,
+      rateLimit
+    };
+  }
+  /**
+   * Revoke a permit through the canonical REST surface
+   * (`POST /v1/permits/{permitId}/revoke`).
+   *
+   * Returns the full updated {@link PermitRecord} with `status === 'revoked'`
+   * and `revoked_at` / `revoked_by` / `revoke_reason` populated. After
+   * revocation, subsequent verify calls return `410 PERMIT_REVOKED`.
+   *
+   * Idempotent on `409 permit_revoked` for already-revoked permits;
+   * server returns the existing revoked row in that case.
+   *
+   * Throws {@link AtlaSentError} on `404` (permit not in calling org),
+   * `409` (already in a terminal state), `410` (expired before revoke),
+   * or `429` (rate limited).
+   */
+  async revokePermitById(permitId, input = {}) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const body = {};
+    if (input.reason !== void 0) body.reason = input.reason;
+    const { body: wire, rateLimit } = await this.post(
+      `/v1/permits/${encodeURIComponent(permitId)}/revoke`,
+      body
+    );
+    return { permit: wire, rateLimit };
+  }
+  /**
+   * Verify a permit through the canonical REST surface
+   * (`POST /v1/permits/{permitId}/verify`).
+   *
+   * Returns the unified verification envelope (`valid`,
+   * `verification_type: 'permit'`, `reason`, `verified_at`, `evidence`)
+   * plus the full {@link PermitRecord} fields preserved at the top
+   * level. The `valid` field is the contract — pin to it.
+   *
+   * A `valid: false` is **not** thrown when the server returns 200 with
+   * a denial reason (matches the verify-shape unification on the wire);
+   * it is thrown on 4xx (`404` not found, `410` expired/consumed).
+   */
+  async verifyPermitById(permitId) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const { body: wire, rateLimit } = await this.post(`/v1/permits/${encodeURIComponent(permitId)}/verify`, {});
+    const { valid, verification_type, reason, verified_at, evidence, ...row } = wire;
+    return {
+      valid,
+      verification_type,
+      reason,
+      verified_at,
+      evidence,
+      permit: row,
+      rateLimit
+    };
+  }
+  /**
+   * Get a single permit's full lifecycle state.
+   *
+   * Calls `GET /v1/permits/{permitId}` (the canonical REST surface).
+   * Returns `status`, all timestamps, `revoked_at` / `revoked_by` /
+   * `revoke_reason` (when applicable), and the bound `payload_hash`
+   * / `decision_id`.
+   *
+   * Operator-facing introspection — answers "what state is this permit
+   * in, and why?" without reading audit logs.
+   *
+   * Throws {@link AtlaSentError} on `404` (permit not in calling org)
+   * or `410` (expired before retrieval).
+   */
+  async getPermit(permitId) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const { body: wire, rateLimit } = await this.get(
+      `/v1/permits/${encodeURIComponent(permitId)}`
+    );
+    return { permit: wire, rateLimit };
+  }
+  /**
+   * Poll whether a permit is currently valid.
+   *
+   * Calls `GET /v1/permits/{permitId}/valid` — a lightweight read
+   * returning only the status snapshot optimised for guard heartbeat
+   * polling. Guards with `permitRevalidationIntervalMs` set race this
+   * against `tool.execute()` and throw {@link PermitRevoked} when
+   * `status === "revoked"` arrives.
+   *
+   * Throws {@link AtlaSentError} on transport / auth failures.
+   */
+  async checkPermitValid(permitId) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const { body } = await this.get(
+      `/v1/permits/${encodeURIComponent(permitId)}/valid`
+    );
+    return body;
+  }
+  /**
+   * List permits issued to the calling org, most-recently-issued first.
+   *
+   * Calls `GET /v1/permits` (the canonical REST surface). Cursor-paged.
+   * Filters narrow on server side; pagination uses the `created_at`
+   * timestamp opaquely (`nextCursor`).
+   *
+   * Designed for incident review, debugging, and compliance
+   * reconstruction.
+   */
+  async listPermits(input = {}) {
+    const params = new URLSearchParams();
+    if (input.status) params.set("status", input.status);
+    if (input.actorId) params.set("actor_id", input.actorId);
+    if (input.actionType) params.set("action_type", input.actionType);
+    if (input.from) params.set("from", input.from);
+    if (input.to) params.set("to", input.to);
+    if (input.limit !== void 0) params.set("limit", String(input.limit));
+    if (input.cursor) params.set("cursor", input.cursor);
+    const { body: wire, rateLimit } = await this.get("/v1/permits", params);
+    if (!Array.isArray(wire.permits)) {
+      throw new AtlaSentError(
+        "Malformed response from /v1/permits: missing `permits` array",
+        { code: "bad_response" }
+      );
+    }
+    const result = {
+      permits: wire.permits,
+      total: typeof wire.total === "number" ? wire.total : wire.permits.length,
+      rateLimit
+    };
+    if (wire.next_cursor !== void 0) result.nextCursor = wire.next_cursor;
+    return result;
+  }
   /**
    * Self-introspection: ask the server to describe the API key this
    * client was constructed with. Returns the key's ID, organization,
@@ -170,9 +747,7 @@ var AtlaSentClient = class {
    * taxonomy as {@link AtlaSentClient.evaluate}.
    */
   async keySelf() {
-    const { body: wire, rateLimit } = await this.get(
-      "/v1-api-key-self"
-    );
+    const { body: wire, rateLimit } = await this.get("/v1-api-key-self");
     if (typeof wire.key_id !== "string" || typeof wire.organization_id !== "string") {
       throw new AtlaSentError(
         "Malformed response from /v1-api-key-self: missing `key_id` or `organization_id`",
@@ -247,8 +822,129 @@ var AtlaSentClient = class {
     }
     return { ...wire, rateLimit };
   }
-  async post(path, body) {
-    return this.request(path, "POST", body, void 0);
+  /**
+   * Open a streaming evaluation session against `POST /v1-evaluate-stream`.
+   *
+   * Yields {@link StreamDecisionEvent} and {@link StreamProgressEvent} objects
+   * as the server emits them. The iterator ends cleanly when the server sends
+   * `event: done`; it throws {@link AtlaSentError} on transport errors or when
+   * the server sends `event: error`.
+   *
+   * The final {@link StreamDecisionEvent} (isFinal: true) carries a `permitId`
+   * suitable for passing to {@link verifyPermit} after the stream closes.
+   *
+   * Hardening:
+   * - Throws {@link StreamTimeoutError} when no event arrives within
+   *   `opts.timeoutMs` (default 30 s). Pass `0` to disable.
+   * - Retries up to `opts.maxRetries` times (default 3) with 1 s / 2 s / 4 s
+   *   delays on network drop (before a terminal event). Sends `Last-Event-ID`
+   *   on reconnect when the server has emitted event IDs.
+   * - Throws {@link StreamParseError} on partial / malformed JSON rather than
+   *   crashing with a raw `SyntaxError`.
+   * - Closes cleanly on `event: done` or a decision event with `done: true`.
+   *
+   * ```ts
+   * for await (const event of client.protectStream({ agent, action })) {
+   *   if (event.type === "decision" && event.isFinal) {
+   *     await client.verifyPermit({ permitId: event.permitId });
+   *   }
+   * }
+   * ```
+   */
+  async *protectStream(input, opts = {}) {
+    const streamTimeoutMs = opts.timeoutMs ?? 3e4;
+    const maxRetries = opts.maxRetries ?? 3;
+    const body = {
+      action: input.action,
+      agent: input.agent,
+      context: input.context ?? {},
+      api_key: this.apiKey
+    };
+    const requestId = globalThis.crypto.randomUUID();
+    const url = `${this.baseUrl}/v1-evaluate-stream`;
+    let lastEventId;
+    let retryCount = 0;
+    while (true) {
+      const headers = {
+        Accept: "text/event-stream",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        "User-Agent": this.userAgent,
+        "X-Request-ID": requestId
+      };
+      if (lastEventId !== void 0) {
+        headers["Last-Event-ID"] = lastEventId;
+      }
+      const connectionTimeoutSignal = AbortSignal.timeout(this.timeoutMs);
+      const signal = opts.signal ? AbortSignal.any([connectionTimeoutSignal, opts.signal]) : connectionTimeoutSignal;
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal
+        });
+      } catch (err) {
+        const mapped = mapFetchError(err, requestId);
+        if (mapped.code === "network" && retryCount < maxRetries) {
+          retryCount++;
+          await sleep(1e3 * Math.pow(2, retryCount - 1));
+          continue;
+        }
+        throw mapped;
+      }
+      if (!response.ok) {
+        throw await buildHttpError(response, requestId);
+      }
+      if (!response.body) {
+        throw new AtlaSentError("Expected streaming body from AtlaSent API", {
+          code: "bad_response",
+          status: response.status,
+          requestId
+        });
+      }
+      let streamDone = false;
+      let networkDrop = false;
+      try {
+        for await (const event of parseSseStream(
+          response.body,
+          requestId,
+          streamTimeoutMs,
+          (id) => {
+            lastEventId = id;
+          }
+        )) {
+          yield event;
+          if (event.type === "decision" && event.isFinal) {
+            streamDone = true;
+          }
+        }
+        streamDone = true;
+      } catch (err) {
+        if (err instanceof AtlaSentError && err.code === "network") {
+          networkDrop = true;
+        } else {
+          throw err;
+        }
+      }
+      if (streamDone) break;
+      if (networkDrop && retryCount < maxRetries) {
+        retryCount++;
+        await sleep(1e3 * Math.pow(2, retryCount - 1));
+        continue;
+      }
+      if (networkDrop) {
+        throw new AtlaSentError(
+          `AtlaSent stream dropped after ${retryCount} reconnection attempts`,
+          { code: "network", requestId }
+        );
+      }
+      break;
+    }
+  }
+  async post(path, body, query) {
+    return this.request(path, "POST", body, query);
   }
   async get(path, query) {
     return this.request(path, "GET", void 0, query);
@@ -260,48 +956,623 @@ var AtlaSentClient = class {
     const headers = {
       Accept: "application/json",
       Authorization: `Bearer ${this.apiKey}`,
-      "User-Agent": `@atlasent/sdk/${SDK_VERSION} node/${process.version}`,
+      "User-Agent": this.userAgent,
       "X-Request-ID": requestId
     };
     if (method === "POST") headers["Content-Type"] = "application/json";
-    const init = {
-      method,
-      headers,
-      signal: AbortSignal.timeout(this.timeoutMs)
-    };
-    if (method === "POST") init.body = JSON.stringify(body);
-    let response;
-    try {
-      response = await this.fetchImpl(url, init);
-    } catch (err) {
-      throw mapFetchError(err, requestId);
+    const bodyStr = method === "POST" ? JSON.stringify(body) : void 0;
+    for (let attempt = 0; ; attempt++) {
+      const init = {
+        method,
+        headers,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      };
+      if (bodyStr !== void 0) init.body = bodyStr;
+      let response;
+      try {
+        response = await this.fetchImpl(url, init);
+      } catch (err) {
+        const mapped = mapFetchError(err, requestId);
+        if (isRetryable(mapped) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, mapped));
+          continue;
+        }
+        throw mapped;
+      }
+      if (!response.ok) {
+        const httpErr = await buildHttpError(response, requestId);
+        if (isRetryable(httpErr) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, httpErr));
+          continue;
+        }
+        throw httpErr;
+      }
+      let parsed;
+      try {
+        parsed = await response.json();
+      } catch (err) {
+        const jsonErr = new AtlaSentError(
+          "Invalid JSON response from AtlaSent API",
+          {
+            code: "bad_response",
+            status: response.status,
+            requestId,
+            cause: err
+          }
+        );
+        if (isRetryable(jsonErr) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, jsonErr));
+          continue;
+        }
+        throw jsonErr;
+      }
+      if (parsed === null || typeof parsed !== "object") {
+        const shapeErr = new AtlaSentError(
+          "Expected a JSON object from AtlaSent API",
+          {
+            code: "bad_response",
+            status: response.status,
+            requestId
+          }
+        );
+        if (isRetryable(shapeErr) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, shapeErr));
+          continue;
+        }
+        throw shapeErr;
+      }
+      return {
+        body: parsed,
+        rateLimit: parseRateLimitHeaders(response.headers)
+      };
     }
-    if (!response.ok) {
-      throw await buildHttpError(response, requestId);
+  }
+  /**
+   * Open a new HITL escalation. Bridges a `hold` outcome from
+   * `protect()` to the approval queue: an agent that receives a
+   * `hold` decision calls this to enroll the proposed action for
+   * human review. The returned escalation can then be polled with
+   * `getHitlEscalation()` or driven to terminal by
+   * `approveHitlEscalation()` / `rejectHitlEscalation()`.
+   *
+   * Quorum, pool size, fallback decision and routing inherit from
+   * the server-side policy when omitted from `input`.
+   *
+   * Calls `POST /v1/hitl`.
+   */
+  async createHitlEscalation(input) {
+    const { body, rateLimit } = await this.post(
+      "/v1/hitl",
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * List HITL escalations for the calling org. Defaults to
+   * `status=pending`; pass `status` to query other queues
+   * (`escalated`, `approved`, `rejected`, `auto_approved`,
+   * `timed_out`).
+   *
+   * Calls `GET /v1/hitl`.
+   */
+  async listHitlEscalations(input = {}) {
+    const params = new URLSearchParams();
+    if (input.status) params.set("status", input.status);
+    if (input.agentId) params.set("agent_id", input.agentId);
+    if (input.assignedToUserId)
+      params.set("assigned_to_user_id", input.assignedToUserId);
+    if (input.limit !== void 0) params.set("limit", String(input.limit));
+    if (input.cursor) params.set("cursor", input.cursor);
+    const { body, rateLimit } = await this.get(
+      "/v1/hitl",
+      params
+    );
+    return { data: body, rateLimit };
+  }
+  /**
+   * Get a HITL escalation. The server payload includes a live
+   * `quorum_progress` snapshot when the escalation is still open.
+   *
+   * Calls `GET /v1/hitl/:id`.
+   */
+  async getHitlEscalation(escalationId) {
+    if (!escalationId) {
+      throw new AtlaSentError("escalationId is required", {
+        code: "bad_request"
+      });
     }
-    let parsed;
-    try {
-      parsed = await response.json();
-    } catch (err) {
-      throw new AtlaSentError("Invalid JSON response from AtlaSent API", {
-        code: "bad_response",
-        status: response.status,
-        requestId,
-        cause: err
+    const { body, rateLimit } = await this.get(
+      `/v1/hitl/${encodeURIComponent(escalationId)}`
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * List per-approver vote rows for an escalation.
+   * Calls `GET /v1/hitl/:id/approvals`.
+   */
+  async listHitlApprovals(escalationId) {
+    const { body, rateLimit } = await this.get(`/v1/hitl/${encodeURIComponent(escalationId)}/approvals`);
+    return { approvals: body.approvals ?? [], rateLimit };
+  }
+  /**
+   * List the escalation chain hops for an escalation. Each `/escalate`
+   * call appends one row.
+   * Calls `GET /v1/hitl/:id/chain`.
+   */
+  async getHitlChain(escalationId) {
+    const { body, rateLimit } = await this.get(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/chain`
+    );
+    return { chain: body.chain ?? [], rateLimit };
+  }
+  /**
+   * Record an approve vote. Resolves the escalation only once the
+   * server-side quorum count is satisfied; before that the response
+   * carries a refreshed escalation row with the latest
+   * `quorum_progress`.
+   *
+   * Calls `POST /v1/hitl/:id/approve`. The server returns 409
+   * `duplicate_vote` if the same principal has already voted, and
+   * 409 `already_rejected` if a concurrent reject crossed the line.
+   */
+  async approveHitlEscalation(escalationId, input = {}) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/approve`,
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Record a reject vote. Reject is short-circuit terminal — a single
+   * reject closes the escalation regardless of how many approves have
+   * accumulated.
+   *
+   * Calls `POST /v1/hitl/:id/reject`.
+   */
+  async rejectHitlEscalation(escalationId, input = {}) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/reject`,
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Re-route an open escalation to a higher tier. Bounded by the
+   * escalation's `max_escalation_depth` — the server returns 409
+   * `chain_exhausted` and applies the configured fallback decision
+   * once the ceiling is hit.
+   *
+   * Calls `POST /v1/hitl/:id/escalate`.
+   */
+  async escalateHitlEscalation(escalationId, input) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/escalate`,
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Manually apply the escalation's `fallback_decision`. Useful for
+   * admin recovery of a hung escalation when the cron sweeper hasn't
+   * run yet, or to short-circuit a stuck flow during incident
+   * response.
+   *
+   * Calls `POST /v1/hitl/:id/timeout`.
+   */
+  async timeoutHitlEscalation(escalationId) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/timeout`,
+      {}
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Run a named governance graph traversal query.
+   *
+   * Dispatches to `GET /v1/governance/graph/query?type=<queryType>`.
+   * Each query type returns a different row shape — the return type
+   * narrows automatically based on the literal `queryType` argument.
+   *
+   * `"user_approvals"` requires `params.actor_id` — the server returns
+   * a 400 if it is absent.
+   */
+  async queryGovernanceGraph(queryType, params = {}) {
+    const qs = new URLSearchParams({ type: queryType });
+    if (params.actor_id) qs.set("actor_id", params.actor_id);
+    const { body, rateLimit } = await this.get("/v1/governance/graph/query", qs);
+    return { ...body, rateLimit };
+  }
+  /**
+   * Reconstruct the multi-system execution timeline for a specific incident.
+   *
+   * Calls `GET /v1/governance/timeline/incident/{incidentId}`. Backed
+   * server-side by `reconstruct_incident_chains_v2()`, which fixes the
+   * `executor_id → actor_id` bug that silently produced empty timelines
+   * in the original function.
+   *
+   * Returns full execution rows including the §13.1 columns
+   * (`delegation_chain_id`, `replay_of_execution_id`, `incident_id`,
+   * `policy_version_id`, `bundle_version_id`) alongside the actor
+   * timeline and evidence rows.
+   */
+  async getIncidentTimeline(incidentId) {
+    if (!incidentId) {
+      throw new AtlaSentError("incidentId is required", {
+        code: "bad_request"
       });
     }
-    if (parsed === null || typeof parsed !== "object") {
-      throw new AtlaSentError("Expected a JSON object from AtlaSent API", {
-        code: "bad_response",
-        status: response.status,
-        requestId
+    const { body, rateLimit } = await this.get(`/v1/governance/timeline/incident/${encodeURIComponent(incidentId)}`);
+    return { ...body, rateLimit };
+  }
+  // ── Connector Management ─────────────────────────────────────────────────
+  /**
+   * List connectors registered for the calling org.
+   * Calls `GET /v1/governance/connectors`.
+   */
+  async listConnectors(options = {}) {
+    const params = new URLSearchParams();
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const { body, rateLimit } = await this.get("/v1/governance/connectors", params);
+    const result = {
+      connectors: body.connectors ?? [],
+      total: body.total,
+      rateLimit
+    };
+    if (body.next_cursor) result.nextCursor = body.next_cursor;
+    return result;
+  }
+  /**
+   * Register and install a new connector for the calling org.
+   * Calls `POST /v1/governance/connectors`.
+   */
+  async installConnector(input) {
+    const { body, rateLimit } = await this.post("/v1/governance/connectors", input);
+    return { connector: body, rateLimit };
+  }
+  /**
+   * Store encrypted credentials for a connector.
+   * Calls `POST /v1/governance/connectors/{id}/authenticate`.
+   */
+  async authenticateConnector(connectorId, input) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
       });
     }
+    const { body, rateLimit } = await this.post(
+      `/v1/governance/connectors/${encodeURIComponent(connectorId)}/authenticate`,
+      input
+    );
     return {
-      body: parsed,
-      rateLimit: parseRateLimitHeaders(response.headers)
+      credential_id: body.credential_id,
+      version: body.version,
+      rateLimit
     };
   }
+  /**
+   * Trigger an incremental sync for a connector.
+   * Calls `POST /v1/governance/connectors/{id}/sync`.
+   */
+  async syncConnector(connectorId) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
+      });
+    }
+    const { body, rateLimit } = await this.post(`/v1/governance/connectors/${encodeURIComponent(connectorId)}/sync`, {});
+    return { ...body, rateLimit };
+  }
+  /**
+   * Revoke a connector and all its associated credentials.
+   * Calls `POST /v1/governance/connectors/{id}/revoke`.
+   */
+  async revokeConnector(connectorId, reason) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
+      });
+    }
+    const body = {};
+    if (reason !== void 0) body.reason = reason;
+    const { body: wire, rateLimit } = await this.post(
+      `/v1/governance/connectors/${encodeURIComponent(connectorId)}/revoke`,
+      body
+    );
+    return { ...wire, rateLimit };
+  }
+  /**
+   * Rotate the credentials for a connector.
+   * Calls `POST /v1/governance/connectors/{id}/rotate-credentials`.
+   */
+  async rotateConnectorCredentials(connectorId) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
+      });
+    }
+    const { body, rateLimit } = await this.post(
+      `/v1/governance/connectors/${encodeURIComponent(connectorId)}/rotate-credentials`,
+      {}
+    );
+    return { ...body, rateLimit };
+  }
+  /**
+   * List enforcement policies for the calling org, optionally filtered by connector type.
+   * Calls `GET /v1/governance/enforcement-policies`.
+   */
+  async listEnforcementPolicies(connectorType) {
+    const params = new URLSearchParams();
+    if (connectorType) params.set("connector_type", connectorType);
+    const { body, rateLimit } = await this.get("/v1/governance/enforcement-policies", params);
+    return { policies: body.policies ?? [], total: body.total, rateLimit };
+  }
+  /**
+   * Create or update a connector enforcement policy.
+   * Calls `POST /v1/governance/enforcement-policies`.
+   */
+  async upsertEnforcementPolicy(input) {
+    const { body, rateLimit } = await this.post("/v1/governance/enforcement-policies", input);
+    return { policy: body, rateLimit };
+  }
+  // ── Organizational Risk Graph ─────────────────────────────────────────────
+  /**
+   * Trigger a fresh org-level risk score computation.
+   * Calls `POST /v1/governance/risk/compute`.
+   */
+  async computeOrgRisk(options = {}) {
+    const { body, rateLimit } = await this.post("/v1/governance/risk/compute", options);
+    return { score: body, rateLimit };
+  }
+  /**
+   * Retrieve the most recently computed risk score for the calling org.
+   * Calls `GET /v1/governance/risk/latest`.
+   */
+  async getLatestOrgRisk() {
+    const { body, rateLimit } = await this.get("/v1/governance/risk/latest");
+    return { score: body.score ?? null, rateLimit };
+  }
+  /**
+   * Page through historical org risk scores, most-recent first.
+   * Calls `GET /v1/governance/risk/history`.
+   */
+  async listOrgRiskHistory(options = {}) {
+    const params = new URLSearchParams();
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const { body, rateLimit } = await this.get("/v1/governance/risk/history", params);
+    const result = {
+      scores: body.scores ?? [],
+      total: body.total,
+      rateLimit
+    };
+    if (body.next_cursor) result.nextCursor = body.next_cursor;
+    return result;
+  }
+  // ── Cross-Org Permission Negotiation ──────────────────────────────────────
+  async checkCrossOrgPermission(req) {
+    const { body } = await this.post(
+      "/v1/cross-org/permissions/check",
+      req
+    );
+    return body;
+  }
+  async listCrossOrgPermissionChecks(params) {
+    const qs = new URLSearchParams();
+    if (params?.source_org_id) qs.set("source_org_id", params.source_org_id);
+    if (params?.target_org_id) qs.set("target_org_id", params.target_org_id);
+    if (params?.allowed !== void 0)
+      qs.set("allowed", String(params.allowed));
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    const { body } = await this.get("/v1/cross-org/permissions/checks", qs);
+    return body.checks ?? [];
+  }
+  // ── Anomaly Response Automation ───────────────────────────────────────────
+  async listAnomalyResponseRules() {
+    const { body } = await this.get(
+      "/v1/anomaly-response/rules"
+    );
+    return body.rules ?? [];
+  }
+  async createAnomalyResponseRule(req) {
+    const { body } = await this.post(
+      "/v1/anomaly-response/rules",
+      req
+    );
+    return body;
+  }
+  async updateAnomalyResponseRule(id, updates) {
+    const { body } = await this.post(
+      `/v1/anomaly-response/rules/${encodeURIComponent(id)}/update`,
+      updates
+    );
+    return body;
+  }
+  async deleteAnomalyResponseRule(id) {
+    await this.post(
+      `/v1/anomaly-response/rules/${encodeURIComponent(id)}/delete`,
+      {}
+    );
+  }
+  async triggerAnomalyResponse(req) {
+    const { body } = await this.post(
+      "/v1/anomaly-response/trigger",
+      req
+    );
+    return body.events ?? [];
+  }
+  async listAnomalyResponseEvents(params) {
+    const qs = new URLSearchParams();
+    if (params?.execution_id) qs.set("execution_id", params.execution_id);
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    const { body } = await this.get(
+      "/v1/anomaly-response/events",
+      qs
+    );
+    return body.events ?? [];
+  }
+  // ── Budget Exception Workflows ────────────────────────────────────────────
+  async listBudgetExceptions(params) {
+    const qs = new URLSearchParams();
+    if (params?.status) qs.set("status", params.status);
+    if (params?.budget_policy_id)
+      qs.set("budget_policy_id", params.budget_policy_id);
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params?.offset !== void 0) qs.set("offset", String(params.offset));
+    const { body } = await this.get(
+      "/v1/budget-exceptions",
+      qs
+    );
+    return body.exceptions ?? [];
+  }
+  async getBudgetException(id) {
+    const { body } = await this.get(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}`
+    );
+    return body;
+  }
+  async createBudgetException(req) {
+    const { body } = await this.post(
+      "/v1/budget-exceptions",
+      req
+    );
+    return body;
+  }
+  async approveBudgetException(id, req) {
+    const { body } = await this.post(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}/approve`,
+      req
+    );
+    return body;
+  }
+  async rejectBudgetException(id, review_notes) {
+    const { body } = await this.post(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}/reject`,
+      { review_notes }
+    );
+    return body;
+  }
+  async cancelBudgetException(id) {
+    const { body } = await this.post(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}/cancel`,
+      {}
+    );
+    return body;
+  }
+  // ── Regulatory Escalation Chain ───────────────────────────────────────────
+  async listRegulatoryAuthorityLevels() {
+    const { body } = await this.get(
+      "/v1/regulatory/authority-levels"
+    );
+    return body.levels ?? [];
+  }
+  async createRegulatoryAuthorityLevel(req) {
+    const { body } = await this.post(
+      "/v1/regulatory/authority-levels",
+      req
+    );
+    return body;
+  }
+  async listRegulatoryEscalations(params) {
+    const qs = new URLSearchParams();
+    if (params?.status) qs.set("status", params.status);
+    if (params?.subject_type) qs.set("subject_type", params.subject_type);
+    if (params?.subject_id) qs.set("subject_id", params.subject_id);
+    const { body } = await this.get(
+      "/v1/regulatory/escalations",
+      qs
+    );
+    return body.escalations ?? [];
+  }
+  async createRegulatoryEscalation(req) {
+    const { body } = await this.post(
+      "/v1/regulatory/escalations",
+      req
+    );
+    return body;
+  }
+  async acknowledgeRegulatoryEscalation(id) {
+    const { body } = await this.post(
+      `/v1/regulatory/escalations/${encodeURIComponent(id)}/acknowledge`,
+      {}
+    );
+    return body;
+  }
+  async resolveRegulatoryEscalation(id, resolution, resolution_details) {
+    const { body } = await this.post(
+      `/v1/regulatory/escalations/${encodeURIComponent(id)}/resolve`,
+      { resolution, resolution_details }
+    );
+    return body;
+  }
+  async overrideRegulatoryEscalation(id, reason) {
+    const { body } = await this.post(
+      `/v1/regulatory/escalations/${encodeURIComponent(id)}/override`,
+      { reason }
+    );
+    return body;
+  }
+  // ── Incentive Signal Feedback Loop ────────────────────────────────────────
+  async listSignalActions(signal_id) {
+    const { body } = await this.get(
+      `/v1/governance/signals/${encodeURIComponent(signal_id)}/actions`
+    );
+    return body.actions ?? [];
+  }
+  async recordSignalAction(signal_id, req) {
+    const { body } = await this.post(
+      `/v1/governance/signals/${encodeURIComponent(signal_id)}/actions`,
+      req
+    );
+    return body;
+  }
+  async recordSignalOutcome(signal_id, action_id, req) {
+    const { body } = await this.post(
+      `/v1/governance/signals/${encodeURIComponent(signal_id)}/actions/${encodeURIComponent(action_id)}/outcome`,
+      req
+    );
+    return body;
+  }
+  async getSignalActionSummary() {
+    const { body } = await this.get(
+      "/v1/governance/signals/actions/summary"
+    );
+    return body;
+  }
+  // ── Cross-Org Impersonation ───────────────────────────────────────────────
+  async listImpersonationGrants() {
+    const { body } = await this.get(
+      "/v1/cross-org/impersonation/grants"
+    );
+    return body.grants ?? [];
+  }
+  async createImpersonationGrant(req) {
+    const { body } = await this.post(
+      "/v1/cross-org/impersonation/grants",
+      req
+    );
+    return body;
+  }
+  async revokeImpersonationGrant(id) {
+    await this.post(
+      `/v1/cross-org/impersonation/grants/${encodeURIComponent(id)}/revoke`,
+      {}
+    );
+  }
+  async issueImpersonationToken(grant_id, requested_duration_seconds) {
+    const { body } = await this.post(
+      `/v1/cross-org/impersonation/grants/${encodeURIComponent(grant_id)}/token`,
+      { requested_duration_seconds }
+    );
+    return body;
+  }
+  async validateImpersonationToken(token) {
+    const { body } = await this.post(
+      "/v1/cross-org/impersonation/validate",
+      { token }
+    );
+    return body;
+  }
 };
 function parseRateLimitHeaders(headers) {
   const rawLimit = headers.get("x-ratelimit-limit");
@@ -446,6 +1717,9 @@ function buildAuditEventsQuery(query) {
   }
   return params;
 }
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 function parseRetryAfter(raw) {
   if (!raw) return void 0;
   const seconds = Number(raw);
@@ -457,13 +1731,133 @@ function parseRetryAfter(raw) {
   }
   return void 0;
 }
+async function* parseSseStream(body, requestId, timeoutMs, onEventId) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buf = "";
+  async function readChunk() {
+    if (timeoutMs <= 0) {
+      return reader.read();
+    }
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        reject(new StreamTimeoutError(timeoutMs));
+      }, timeoutMs);
+      reader.read().then(
+        (result) => {
+          clearTimeout(timer);
+          resolve2(result);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  try {
+    for (; ; ) {
+      let done;
+      let value;
+      try {
+        const result = await readChunk();
+        done = result.done;
+        value = result.value;
+      } catch (err) {
+        if (err instanceof StreamTimeoutError) throw err;
+        throw new AtlaSentError(
+          `AtlaSent stream read failed: ${err instanceof Error ? err.message : String(err)}`,
+          { code: "network", requestId, cause: err }
+        );
+      }
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let boundary;
+      while ((boundary = buf.indexOf("\n\n")) !== -1) {
+        const block = buf.slice(0, boundary);
+        buf = buf.slice(boundary + 2);
+        let eventType = "message";
+        let data = "";
+        let eventId;
+        for (const line of block.split("\n")) {
+          if (line.startsWith("event: ")) eventType = line.slice(7).trim();
+          else if (line.startsWith("data: ")) data = line.slice(6);
+          else if (line.startsWith("id: ")) eventId = line.slice(4).trim();
+          else if (line.startsWith("id:")) eventId = line.slice(3).trim();
+        }
+        if (eventId !== void 0) onEventId(eventId);
+        if (!data) continue;
+        if (eventType === "done") return;
+        let parsed;
+        try {
+          parsed = JSON.parse(data);
+        } catch (err) {
+          throw new StreamParseError(data, err);
+        }
+        if (eventType === "error") {
+          const e = parsed;
+          throw new AtlaSentError(
+            e.message ?? "Stream error from AtlaSent API",
+            {
+              code: e.code ?? "server_error",
+              requestId: e.request_id ?? requestId
+            }
+          );
+        }
+        if (eventType === "decision") {
+          const d = parsed;
+          if (typeof d.permitted !== "boolean" || typeof d.decision_id !== "string") {
+            throw new AtlaSentError(
+              "Malformed decision event from AtlaSent API",
+              {
+                code: "bad_response",
+                requestId
+              }
+            );
+          }
+          const streamDecision = d.permitted ? "allow" : "deny";
+          const isFinal = d.is_final ?? false;
+          yield {
+            type: "decision",
+            decision: streamDecision,
+            decision_canonical: streamDecision,
+            permitId: d.decision_id,
+            reason: d.reason ?? "",
+            auditHash: d.audit_hash ?? "",
+            timestamp: d.timestamp ?? "",
+            isFinal
+          };
+          if (isFinal || d.done === true) return;
+        } else if (eventType === "progress") {
+          const p = parsed;
+          yield {
+            type: "progress",
+            stage: String(p["stage"] ?? ""),
+            ...p
+          };
+          if (p.done === true) return;
+        } else {
+          if (parsed !== null && typeof parsed === "object" && parsed.done === true) {
+            return;
+          }
+        }
+      }
+    }
+    if (buf.trim().length > 0) {
+      throw new StreamParseError(buf);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
 
 // src/protect.ts
 var sharedClient = null;
 var overrides = {};
 function getClient() {
   if (sharedClient) return sharedClient;
-  const apiKey = overrides.apiKey ?? process.env.ATLASENT_API_KEY;
+  const envApiKey = typeof process !== "undefined" && process.env ? process.env.ATLASENT_API_KEY : void 0;
+  const apiKey = overrides.apiKey ?? envApiKey;
   if (!apiKey) {
     throw new AtlaSentError(
       "AtlaSent is not configured. Set ATLASENT_API_KEY in the environment, or call atlasent.configure({ apiKey }).",
@@ -472,8 +1866,11 @@ function getClient() {
   }
   const options = { apiKey };
   if (overrides.baseUrl !== void 0) options.baseUrl = overrides.baseUrl;
-  if (overrides.timeoutMs !== void 0) options.timeoutMs = overrides.timeoutMs;
+  if (overrides.timeoutMs !== void 0)
+    options.timeoutMs = overrides.timeoutMs;
   if (overrides.fetch !== void 0) options.fetch = overrides.fetch;
+  if (overrides.retryPolicy !== void 0)
+    options.retryPolicy = overrides.retryPolicy;
   sharedClient = new AtlaSentClient(options);
   return sharedClient;
 }
@@ -482,10 +1879,42 @@ function wireDecisionToDenied(serverDecision) {
   if (lower === "hold" || lower === "escalate") return lower;
   return "deny";
 }
+function sortKeysDeep(val) {
+  if (Array.isArray(val)) return val.map(sortKeysDeep);
+  if (val !== null && typeof val === "object") {
+    return Object.keys(val).sort().reduce((acc, k) => {
+      acc[k] = sortKeysDeep(val[k]);
+      return acc;
+    }, {});
+  }
+  return val;
+}
+async function computeExecutionHash(payload) {
+  const sorted = sortKeysDeep(payload);
+  const canonical = JSON.stringify(sorted);
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.subtle?.digest) {
+    const bytes = new TextEncoder().encode(canonical);
+    const buf = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  try {
+    const { createHash } = await import(
+      /* @vite-ignore */
+      /* webpackIgnore: true */
+      "crypto"
+    );
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+  } catch {
+    console.warn(
+      "[atlasent] Could not compute execution_hash: neither crypto.subtle nor node:crypto is available in this runtime."
+    );
+    return "";
+  }
+}
 async function protect(request) {
   const client = getClient();
   const evaluation = await client.evaluate(request);
-  if (evaluation.decision !== "ALLOW") {
+  if (evaluation.decision !== "allow") {
     throw new AtlaSentDeniedError({
       decision: wireDecisionToDenied(evaluation.decision),
       evaluationId: evaluation.permitId,
@@ -493,19 +1922,35 @@ async function protect(request) {
       auditHash: evaluation.auditHash
     });
   }
+  const environment = request.context?.environment ?? (() => {
+    console.warn(
+      "[atlasent] environment not set on evaluate request \u2014 defaulting to 'production'. Set context.environment explicitly to suppress."
+    );
+    return "production";
+  })();
+  const evaluatePayload = {
+    action_type: request.action,
+    actor_id: request.agent,
+    context: request.context ?? {}
+  };
+  const execution_hash = await computeExecutionHash(evaluatePayload);
   const verifyRequest = {
     permitId: evaluation.permitId,
     agent: request.agent,
-    action: request.action
+    action: request.action,
+    environment,
+    ...execution_hash ? { execution_hash } : {}
   };
   if (request.context !== void 0) verifyRequest.context = request.context;
   const verification = await client.verifyPermit(verifyRequest);
   if (!verification.verified) {
+    const outcome = normalizePermitOutcome(verification.outcome);
     throw new AtlaSentDeniedError({
       decision: "deny",
       evaluationId: evaluation.permitId,
       reason: `Permit failed verification (${verification.outcome})`,
-      auditHash: evaluation.auditHash
+      auditHash: evaluation.auditHash,
+      ...outcome !== void 0 && { outcome }
     });
   }
   return {