@pushary/server 1.4.0 → 2.0.0

package/README.md

@@ -140,8 +140,8 @@ const { approved, value, status } = await pushary.decisions.ask({
 if (approved) await issueRefund()
 ```
 
-`ask()` creates the decision, derives a collision-safe idempotency key, and polls
-durably until the human answers or the deadline passes (default 55s, serverless-safe).
+`ask()` creates a fresh decision per call and polls
+durably until the human answers or the deadline passes (default 55s for a positive local wait budget).
 `approved` is true only when the person actually said yes, so a declined, expired, or
 unanswered decision safely blocks the action.
 
@@ -195,8 +195,8 @@ import {
 const idempotencyKey = deterministicKey(['run-abc', 'step-3', 'user-123'])
 
 // isApproved(decision: { status, type?, value }): boolean
-// Fail-closed: true ONLY for an answered confirm whose value is yes. Pending,
-// expired, declined and free-text answers all return false.
+// For confirm: true only for an affirmative answer. For select/input: true
+// means answered, not permission to act. Check the actual value for those types.
 isApproved({ status: 'answered', type: 'confirm', value: 'yes' })  // true
 isApproved({ status: 'answered', type: 'confirm', value: 'no' })   // false
 isApproved({ status: 'pending', type: 'confirm', value: null })    // false
@@ -252,14 +252,77 @@ export const approve = async (toolName: string, callId: string, input: unknown)
     sessionId: currentRunId,
     question: renderApprovalQuestion(toolName, input),
     externalId: kernel.requireExternalId(currentUserId),
+    // optional: lets a rule decide on the arguments, not only the action name
+    input,
   })
   return decision // { approved: true } | { approved: false, reason }
 }
 ```
 
+The gate asks your policy before it asks a person. A rule that names the action
+resolves it with nobody paged: `allow` returns approved and opens no decision, `deny`
+returns a reason the model reads, and anything no rule names still asks. A site with
+no rules behaves exactly as before, because a rule has to name the action and `*` is
+never selected. Pass `policy: false` to restore the always-ask gate.
+
 The label passed to `createAdapterKernel` is what appears in the error when a key or
 an end-user is missing, so it names your helpers rather than ours.
 
+### One protected action: `protect()`
+
+`createGate` answers a yes/no. `protect()` is that plus running the thing, so the
+authorize, escalate and execute steps stop being three pieces of plumbing in your
+business code.
+
+```typescript
+const protect = kernel.protect({ apiKey: process.env.PUSHARY_API_KEY! })
+
+const outcome = await protect({
+  action: 'refund.create',
+  target: 'order_4471',
+  externalId: customer.id,
+  facts: { amount: 4800, currency: 'EUR' },   // what a rule may decide on
+  callId: attemptId,
+  runId: sessionId,
+  run: () => stripe.refunds.create({ charge, amount: 4800 }),
+})
+
+outcome.ok ? outcome.result : outcome.reason
+```
+
+A rule that names `refund.create` resolves it with nobody paged. Anything no rule
+names asks a person. `run` is called only after the action is authorized, and an
+error it throws is not caught: reporting it as `ok: false` would be
+indistinguishable from a refusal.
+
+`protect()` is **at most once**. The decision is idempotent — a replay of the same
+`runId` + `callId` + action lands on the same approval instead of asking twice — and
+the approval is then spent against a durable permit before `run` is called. A retry, a
+concurrent worker and a resumed run all reach the same permit and exactly one of them
+proceeds; the rest come back `ok: false` with a reason worded to stop the model rather
+than invite another attempt.
+
+The permit is bound to the exact subject that was authorized — the action, its target,
+the actor, the environment, the end-user and every fact you sent — so changing the
+amount between the approval and the execution leaves you with no permit for the action
+you now want to run. `protect()` then records `succeeded` or `failed` against it; a
+process that dies mid-action leaves the permit unresolved, which is visible and
+reconcilable, rather than an action that ran twice, which is not.
+
+The two calls underneath are public if you own your own execution path:
+`pushary.consumeAuthorization(binding)` and `pushary.recordExecution({ permitId,
+outcome, summary })`. A refusal carries a `refusal` you can branch on:
+`not_authorized`, `action_mismatch`, `expired` or `already_consumed`.
+
+Python is the same two-step surface: `protect = kernel.create_protect()`, then
+`protect(action, run, external_id=..., call_id=..., run_id=...)`. Building it once is
+what makes a missing key raise where the protector is defined rather than on the
+first action.
+
+A runnable end-to-end version, against the sandbox and with no phone involved, is
+in [`examples/protected-action.ts`](./examples/protected-action.ts).
+
+
 Also exported: `describeAnswer` (turn an outcome into an instruction the model cannot
 misread), `resolvePusharyCallback` (verify and parse a webhook in one call),
 `idempotencyKeyFor`, and `isAffirmative`.
@@ -274,6 +337,10 @@ ask_human = kernel.ask_human
 gate = kernel.create_gate()
 ```
 
+`create_gate(policy=False)` is the same escape hatch. Neither language evaluates a
+rule locally; the verdict is the server's, so the two cannot disagree about what a
+policy means.
+
 Both give you what the shipped adapters have: idempotency keyed on the call so a
 replay never asks twice, a denial reason the model can read, and silence treated as a
 no.
@@ -327,3 +394,13 @@ import {
 ## License
 
 MIT. See `LICENSE`.
+
+## Retries and deadlines
+
+For retries of one business operation, pass `idempotencyKey: deterministicKey([runId, stepId, userId])`. Independent asks get fresh keys, even with identical questions. Shared adapter durable creates require this key; missing keys fail before a request is sent. Keep a run ID unique per operation and stable across its retries.
+
+A positive `timeoutMs` covers creation and polling. `timeoutMs: 0` retains create-only behavior. A timeout during creation throws; retry with the same explicit key to recover the decision. A timeout during polling returns the known pending decision ID for later `get()` or a webhook. `signal` cancels the local wait and throws; it does not cancel the remote decision. Other HTTP calls use `requestTimeoutMs` (65 seconds by default).
+
+### Upgrading to 2.0
+
+Upgrade the framework adapter alongside this SDK. Durable helpers now require an explicit `idempotencyKey` tied to the run and step. The 0.3 LangGraph, Mastra and OpenAI adapters support this contract. Earlier adapters must keep the 1.x SDK until migrated. Independent blocking calls no longer deduplicate by question text.

package/dist/adapters.cjs

@@ -20,21 +20,29 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/adapters.ts
 var adapters_exports = {};
 __export(adapters_exports, {
+  DENIED_BY_POLICY: () => DENIED_BY_POLICY,
   DENIED_REFUSED: () => DENIED_REFUSED,
   DENIED_UNANSWERED: () => DENIED_UNANSWERED,
   SIGNATURE_HEADER: () => SIGNATURE_HEADER,
+  UNBOUND_APPROVAL: () => UNBOUND_APPROVAL,
+  UNCONFIRMED_PERMIT: () => UNCONFIRMED_PERMIT,
   createAdapterKernel: () => createAdapterKernel,
+  defaultProtectQuestion: () => defaultProtectQuestion,
+  deniedByPolicy: () => deniedByPolicy,
+  deriveParameters: () => deriveParameters,
   describeAnswer: () => describeAnswer,
   deterministicKey: () => deterministicKey,
   idempotencyKeyFor: () => idempotencyKeyFor,
   isAffirmative: () => isAffirmative,
   isApproved: () => isApproved,
   parseDecisionCallback: () => parseDecisionCallback,
+  refusedPermit: () => refusedPermit,
   renderApprovalQuestion: () => renderApprovalQuestion,
   resolvePusharyCallback: () => resolvePusharyCallback,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(adapters_exports);
+var import_node_crypto = require("crypto");
 
 // src/error.ts
 var PusharyApiError = class _PusharyApiError extends Error {
@@ -85,11 +93,12 @@ var handleResponse = async (response) => {
   }
   return response.json();
 };
-var createRequest = (ctx) => async (method, path, body) => {
+var createRequest = (ctx) => async (method, path, body, options) => {
   const isGet = method === "GET";
   const url = isGet && body ? buildUrl(ctx.baseUrl, path, body) : `${ctx.baseUrl}${path}`;
   const response = await fetch(url, {
     method,
+    signal: options?.signal ?? AbortSignal.timeout(ctx.timeoutMs ?? 65e3),
     headers: ctx.headers,
     body: !isGet && body ? JSON.stringify(body) : void 0
   });
@@ -172,52 +181,80 @@ var DEFAULT_ASK_TIMEOUT_MS = 55e3;
 var createDecisionsResource = (request) => {
   const ask = async (data) => {
     const idempotencyKey = data.idempotencyKey ?? (0, import_crypto2.randomUUID)();
-    const created = await request("POST", "/decisions", {
-      question: data.question,
-      type: data.type,
-      options: data.options,
-      externalId: data.externalId,
-      email: data.email,
-      agentName: data.agentName,
-      context: data.context,
-      placeholder: data.placeholder,
-      expiresInSeconds: data.expiresInSeconds,
-      poweredBy: data.poweredBy,
-      callbackUrl: data.callbackUrl,
-      requireReachable: data.requireReachable,
-      idempotencyKey,
-      wait: false
-    });
-    const type = created.type ?? data.type ?? "confirm";
-    let status = created.status;
-    let answered = created.answered;
-    let value = created.value ?? null;
-    const deadline = Date.now() + Math.max(0, data.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS);
-    while (status === "pending" && Date.now() < deadline) {
-      const waitSeconds = Math.max(
-        1,
-        Math.min(POLL_WINDOW_SECONDS, Math.ceil((deadline - Date.now()) / 1e3))
-      );
-      const polled = await request("GET", `/decisions/${created.decisionId}`, {
-        wait: waitSeconds
-      });
-      status = polled.status;
-      answered = polled.answered;
-      value = polled.value;
+    const timeoutMs = Math.max(0, data.timeoutMs ?? DEFAULT_ASK_TIMEOUT_MS);
+    const deadline = Date.now() + timeoutMs;
+    const controller = new AbortController();
+    const abort = () => controller.abort(data.signal?.reason);
+    if (data.signal?.aborted) abort();
+    else data.signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException("Pushary ask timed out", "TimeoutError")), timeoutMs || 65e3);
+    try {
+      const created = await request("POST", "/decisions", {
+        question: data.question,
+        type: data.type,
+        options: data.options,
+        externalId: data.externalId,
+        email: data.email,
+        agentName: data.agentName,
+        context: data.context,
+        placeholder: data.placeholder,
+        toolName: data.toolName,
+        toolTarget: data.toolTarget,
+        actor: data.actor,
+        environment: data.environment,
+        parameters: data.parameters,
+        // Its changes name parameters rather than carrying values, so what the
+        // person sees is read from the same numbers a rule compares.
+        presentation: data.presentation,
+        approvalUrl: data.approvalUrl,
+        expiresInSeconds: data.expiresInSeconds,
+        poweredBy: data.poweredBy,
+        callbackUrl: data.callbackUrl,
+        requireReachable: data.requireReachable,
+        // Read only by a key issued on your workspace's sandbox site, where the
+        // simulator answers instead of a person. Ignored in production.
+        sandboxOutcome: data.sandboxOutcome,
+        idempotencyKey,
+        wait: false
+      }, { signal: controller.signal });
+      const type = created.type ?? data.type ?? "confirm";
+      let status = created.status;
+      let answered = created.answered;
+      let value = created.value ?? null;
+      while (status === "pending" && Date.now() < deadline) {
+        const waitSeconds = Math.max(
+          1,
+          Math.min(POLL_WINDOW_SECONDS, Math.ceil((deadline - Date.now()) / 1e3))
+        );
+        try {
+          const polled = await request("GET", `/decisions/${created.decisionId}`, {
+            wait: waitSeconds
+          }, { signal: controller.signal });
+          status = polled.status;
+          answered = polled.answered;
+          value = polled.value;
+        } catch (error) {
+          if (controller.signal.aborted && !data.signal?.aborted) break;
+          throw error;
+        }
+      }
+      return {
+        decisionId: created.decisionId,
+        status,
+        answered,
+        value,
+        type,
+        approved: isApproved({ status, type, value }),
+        // Surfaced from the create response so a caller can tell an unanswered
+        // decision that reached nobody (reachable:false) apart from a real decline.
+        reachable: created.reachable,
+        reachableChannels: created.reachableChannels,
+        deviceCount: created.deviceCount
+      };
+    } finally {
+      clearTimeout(timer);
+      data.signal?.removeEventListener("abort", abort);
     }
-    return {
-      decisionId: created.decisionId,
-      status,
-      answered,
-      value,
-      type,
-      approved: isApproved({ status, type, value }),
-      // Surfaced from the create response so a caller can tell an unanswered
-      // decision that reached nobody (reachable:false) apart from a real decline.
-      reachable: created.reachable,
-      reachableChannels: created.reachableChannels,
-      deviceCount: created.deviceCount
-    };
   };
   return Object.freeze({
     create: (data) => request("POST", "/decisions", data),
@@ -237,6 +274,102 @@ var createKeysResource = (request) => Object.freeze({
   revoke: (keyPrefix) => request("DELETE", `/keys/${encodeURIComponent(keyPrefix)}`)
 });
 
+// src/authorize.ts
+var defaultQuestion = (toolName, toolTarget) => `Approve ${toolName}${toolTarget ? ` ${toolTarget}` : ""}?`;
+var authorizationSubject = (input) => ({
+  toolName: input.toolName,
+  toolTarget: input.toolTarget,
+  actor: input.actor,
+  environment: input.environment,
+  parameters: input.parameters
+});
+var createEvaluateAuthorization = (request) => (input) => request("POST", "/authorize", {
+  ...authorizationSubject(input),
+  externalId: input.externalId,
+  question: input.question,
+  agentName: input.agentName
+});
+var createAuthorize = (request, decisions) => {
+  const evaluate = createEvaluateAuthorization(request);
+  return async (input) => {
+    const subject = authorizationSubject(input);
+    const evaluation = await evaluate(input);
+    if (evaluation.verdict !== "requires_human") {
+      return {
+        approved: evaluation.verdict === "allow",
+        resolvedBy: "policy",
+        policy: evaluation.policy,
+        reason: evaluation.reason,
+        decisionId: null,
+        authorizationId: evaluation.authorizationId
+      };
+    }
+    const answer = await decisions.ask({
+      question: input.question ?? defaultQuestion(input.toolName, input.toolTarget),
+      type: "confirm",
+      externalId: input.externalId,
+      agentName: input.agentName,
+      ...subject,
+      timeoutMs: input.timeoutMs,
+      expiresInSeconds: input.expiresInSeconds,
+      idempotencyKey: input.idempotencyKey,
+      requireReachable: input.requireReachable
+    });
+    return {
+      approved: answer.approved,
+      resolvedBy: "human",
+      policy: evaluation.policy,
+      reason: answer.approved ? "A person approved it." : answer.answered ? "A person denied it." : "Nobody answered, so this was not approved.",
+      decisionId: answer.decisionId,
+      authorizationId: null
+    };
+  };
+};
+
+// src/permits.ts
+var REFUSALS = [
+  "not_authorized",
+  "action_mismatch",
+  "expired",
+  "already_consumed"
+];
+var EXECUTION_STATES = ["running", "succeeded", "failed"];
+var refusalOf = (error) => {
+  if (!(error instanceof PusharyApiError)) return null;
+  const body = error.body;
+  const refusal = body?.refusal;
+  if (typeof refusal !== "string" || !REFUSALS.includes(refusal)) return null;
+  const state = body?.executionState;
+  return {
+    consumed: false,
+    refusal,
+    reason: error.message,
+    ...typeof state === "string" && EXECUTION_STATES.includes(state) ? { executionState: state } : {}
+  };
+};
+var createConsumeAuthorization = (request) => async (binding) => {
+  try {
+    const permit = await request("POST", "/authorizations/consume", {
+      authorizationId: binding.authorizationId,
+      toolName: binding.toolName,
+      toolTarget: binding.toolTarget,
+      actor: binding.actor,
+      environment: binding.environment,
+      externalId: binding.externalId,
+      parameters: binding.parameters
+    });
+    return { consumed: true, permit };
+  } catch (error) {
+    const refused = refusalOf(error);
+    if (refused) return refused;
+    throw error;
+  }
+};
+var createRecordExecution = (request) => (receipt) => request("POST", `/authorizations/${encodeURIComponent(receipt.permitId)}/receipt`, {
+  outcome: receipt.outcome,
+  summary: receipt.summary
+});
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://pushary.com/api/v1/server";
 var validateApiKey = (apiKey) => {
@@ -251,6 +384,7 @@ var createContext = (config) => {
   validateApiKey(config.apiKey);
   return Object.freeze({
     baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+    timeoutMs: config.requestTimeoutMs ?? 65e3,
     headers: Object.freeze({
       "Content-Type": "application/json",
       "Authorization": `Bearer ${config.apiKey}`
@@ -260,15 +394,21 @@ var createContext = (config) => {
 var createPusharyServer = (config) => {
   const ctx = createContext(config);
   const request = createRequest(ctx);
+  const decisions = createDecisionsResource(request);
   return Object.freeze({
     subscribers: createSubscribersResource(request),
     campaigns: createCampaignsResource(request),
     templates: createTemplatesResource(request),
     notifications: createNotificationsResource(request),
     flows: createFlowsResource(request),
-    decisions: createDecisionsResource(request),
+    decisions,
     keys: createKeysResource(request),
-    enroll: (externalId) => request("POST", "/enroll", { externalId })
+    authorize: createAuthorize(request, decisions),
+    evaluateAuthorization: createEvaluateAuthorization(request),
+    consumeAuthorization: createConsumeAuthorization(request),
+    recordExecution: createRecordExecution(request),
+    enroll: (externalId) => request("POST", "/enroll", { externalId }),
+    reachability: (externalId) => request("GET", "/reachability", { externalId })
   });
 };
 
@@ -303,8 +443,8 @@ var parseDecisionCallback = (rawBody) => {
 };
 
 // src/adapters.ts
-var DEFAULT_NODE = "ask-human";
-var idempotencyKeyFor = (input) => deterministicKey([input.externalId, input.node ?? DEFAULT_NODE, input.question]);
+var defaultProtectQuestion = (action, target) => `Approve ${action}${target ? ` ${target}` : ""}?`;
+var idempotencyKeyFor = (input) => input.idempotencyKey ?? (0, import_node_crypto.randomUUID)();
 var isAffirmative = (answer) => isApproved({ status: "answered", type: "confirm", value: answer ?? null });
 var describeAnswer = (type, result) => {
   if (!result.answered) {
@@ -331,6 +471,36 @@ var resolvePusharyCallback = (rawBody, signature, secret) => {
 var MAX_INPUT_CHARS = 300;
 var DENIED_UNANSWERED = "No answer from the approver, so this was denied. Do not retry the same action.";
 var DENIED_REFUSED = "The approver denied this action.";
+var DENIED_BY_POLICY = "Denied by policy. Do not retry the same action.";
+var UNBOUND_APPROVAL = "This was approved, but the approval could not be bound to a single execution, so it was not run. Do not retry the same action.";
+var UNCONFIRMED_PERMIT = "This was approved, but it could not be confirmed as still unspent, so it was not run. Ask again rather than retrying this one.";
+var REFUSED_REPLAY = "This authorization was already used. The action has run once and must not run again.";
+var refusedPermit = (refused) => refused.refusal === "already_consumed" ? REFUSED_REPLAY : `${refused.reason} Do not retry the same action.`;
+var deniedByPolicy = (evaluation) => evaluation.reason ? `${evaluation.reason} Do not retry the same action.` : DENIED_BY_POLICY;
+var PARAMETERS_MAX_KEYS = 32;
+var PARAMETER_KEY_MAX_LENGTH = 64;
+var PARAMETER_VALUE_MAX_LENGTH = 200;
+var deriveParameters = (input) => {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) return void 0;
+  const entries = Object.entries(input);
+  if (entries.length === 0 || entries.length > PARAMETERS_MAX_KEYS) return void 0;
+  const parameters = {};
+  for (const [key, value] of entries) {
+    if (key.length === 0 || key.length > PARAMETER_KEY_MAX_LENGTH) return void 0;
+    if (typeof value === "boolean") {
+      parameters[key] = value;
+    } else if (typeof value === "number") {
+      if (!Number.isFinite(value)) return void 0;
+      parameters[key] = value;
+    } else if (typeof value === "string") {
+      if (value.length > PARAMETER_VALUE_MAX_LENGTH) return void 0;
+      parameters[key] = value;
+    } else {
+      return void 0;
+    }
+  }
+  return parameters;
+};
 var renderApprovalQuestion = (toolName, toolInput) => {
   if (toolInput === void 0 || toolInput === null) return `Approve ${toolName}?`;
   const summary = summarise(toolInput);
@@ -375,7 +545,48 @@ var createAdapterKernel = (helpersLabel) => {
       apiKey: requireApiKey(config.apiKey),
       ...config.baseUrl ? { baseUrl: config.baseUrl } : {}
     });
+    const usePolicy = config.policy ?? true;
+    const evaluate = async (ask, facts) => {
+      if (!usePolicy) return null;
+      try {
+        return await gateClient.evaluateAuthorization({
+          toolName: ask.toolName,
+          toolTarget: ask.toolTarget,
+          actor: ask.actor,
+          environment: ask.environment,
+          parameters: facts,
+          externalId: ask.externalId,
+          question: ask.question,
+          ...config.agentName ? { agentName: config.agentName } : {}
+        });
+      } catch {
+        return null;
+      }
+    };
     return async (ask) => {
+      const facts = ask.parameters ?? deriveParameters(ask.input);
+      const evaluation = await evaluate(ask, facts);
+      if (evaluation?.verdict === "allow") {
+        return {
+          approved: true,
+          // Exactly the subject POST /authorize recorded, which is the whole of
+          // what it was sent.
+          ...evaluation.authorizationId ? {
+            authorization: {
+              authorizationId: evaluation.authorizationId,
+              toolName: ask.toolName,
+              toolTarget: ask.toolTarget,
+              actor: ask.actor,
+              environment: ask.environment,
+              externalId: ask.externalId,
+              parameters: facts
+            }
+          } : {}
+        };
+      }
+      if (evaluation?.verdict === "deny") {
+        return { approved: false, reason: deniedByPolicy(evaluation) };
+      }
       const result = await gateClient.decisions.ask({
         question: ask.question,
         type: "confirm",
@@ -384,11 +595,43 @@ var createAdapterKernel = (helpersLabel) => {
         ...config.expiresInSeconds ? { expiresInSeconds: config.expiresInSeconds } : {},
         ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
         ...config.requireReachable ? { requireReachable: config.requireReachable } : {},
+        // The gated tool, recorded on the decision. The gate already knows it
+        // and keyed on it below; sending it is what lets the decision be grouped
+        // and matched later instead of surviving only as prose in the question.
+        toolName: ask.toolName,
+        // The rest of the subject only when the evaluation carried it and the
+        // server accepted it. An evaluation that failed proves nothing about what
+        // this ask would accept, and this path has to stay byte-for-byte the call
+        // that worked before policy existed.
+        ...evaluation ? {
+          toolTarget: ask.toolTarget,
+          actor: ask.actor,
+          environment: ask.environment,
+          parameters: facts
+        } : {},
         // Stable across replays, so a re-run of this call resolves to the same
         // decision instead of asking twice.
         idempotencyKey: deterministicKey([ask.sessionId, ask.callId, ask.toolName])
       });
-      if (result.approved) return { approved: true };
+      if (result.approved) {
+        return {
+          approved: true,
+          authorization: {
+            authorizationId: result.decisionId,
+            toolName: ask.toolName,
+            externalId: ask.externalId,
+            // Mirrors the ask above exactly. The decision recorded the rest of
+            // the subject only when the evaluation carried it, so claiming it
+            // here regardless would describe an action the record does not hold.
+            ...evaluation ? {
+              toolTarget: ask.toolTarget,
+              actor: ask.actor,
+              environment: ask.environment,
+              parameters: facts
+            } : {}
+          }
+        };
+      }
       return { approved: false, reason: result.answered ? DENIED_REFUSED : DENIED_UNANSWERED };
     };
   };
@@ -400,9 +643,17 @@ var createAdapterKernel = (helpersLabel) => {
     context: input.context,
     agentName: config.agentName,
     timeoutMs: config.timeoutMs,
+    // The node/step name doubles as the action label. The default is not
+    // sent: grouping every unnamed ask across every framework under one
+    // bucket would mine into a suggestion to auto-approve "ask-human", which
+    // spans unrelated questions.
+    toolName: input.node,
     idempotencyKey: idempotencyKeyFor(input)
   });
   const createDurableDecision = async (config, input) => {
+    if (!input.idempotencyKey?.trim()) {
+      throw new Error("Pushary: durable decisions require an idempotencyKey tied to the run and step.");
+    }
     const created = await client(config).decisions.create({
       question: input.question,
       type: input.type,
@@ -411,6 +662,7 @@ var createAdapterKernel = (helpersLabel) => {
       context: input.context,
       callbackUrl: input.callbackUrl,
       agentName: config.agentName,
+      toolName: input.node,
       idempotencyKey: idempotencyKeyFor(input),
       wait: false
     });
@@ -424,27 +676,77 @@ var createAdapterKernel = (helpersLabel) => {
     };
   };
   const connect = (config, externalId) => client(config).enroll(externalId);
+  const protect = (config) => {
+    const gate = createGate(config);
+    const permitClient = client(config);
+    const report = async (permitId, outcome, summary) => {
+      try {
+        await permitClient.recordExecution({ permitId, outcome, summary });
+      } catch {
+      }
+    };
+    return async (action) => {
+      const decision = await gate({
+        toolName: action.action,
+        toolTarget: action.target,
+        callId: action.callId,
+        sessionId: action.runId,
+        question: action.question ?? defaultProtectQuestion(action.action, action.target),
+        externalId: action.externalId,
+        actor: action.actor,
+        environment: action.environment,
+        parameters: action.facts
+      });
+      if (!decision.approved) return { ok: false, reason: decision.reason };
+      if (!decision.authorization) return { ok: false, reason: UNBOUND_APPROVAL };
+      let consumed;
+      try {
+        consumed = await permitClient.consumeAuthorization(decision.authorization);
+      } catch {
+        return { ok: false, reason: UNCONFIRMED_PERMIT };
+      }
+      if (!consumed.consumed) return { ok: false, reason: refusedPermit(consumed) };
+      const permitId = consumed.permit.permitId;
+      let result;
+      try {
+        result = await action.run();
+      } catch (error) {
+        await report(permitId, "failed", error instanceof Error ? error.message : "unknown error");
+        throw error;
+      }
+      await report(permitId, "succeeded");
+      return { ok: true, result };
+    };
+  };
   return Object.freeze({
     client,
     askExternalUser,
     createDurableDecision,
     connect,
     createGate,
+    protect,
     requireExternalId
   });
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DENIED_BY_POLICY,
   DENIED_REFUSED,
   DENIED_UNANSWERED,
   SIGNATURE_HEADER,
+  UNBOUND_APPROVAL,
+  UNCONFIRMED_PERMIT,
   createAdapterKernel,
+  defaultProtectQuestion,
+  deniedByPolicy,
+  deriveParameters,
   describeAnswer,
   deterministicKey,
   idempotencyKeyFor,
   isAffirmative,
   isApproved,
   parseDecisionCallback,
+  refusedPermit,
   renderApprovalQuestion,
   resolvePusharyCallback,
   verifyWebhookSignature