@pushary/server 1.5.0 → 2.1.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
@@ -226,6 +226,14 @@ app.post('/webhooks/pushary', async (req, res) => {
 
 ## Writing a framework adapter: `@pushary/server/adapters`
 
+Customers answer in the native Pushary app. Confirm, select, and input questions keep their existing meanings; a choice or typed answer is data, not permission to execute a protected tool. Enroll the customer from trusted application identity before asking. Legacy web links remain an optional delivery path.
+
+Both blocking and durable adapter calls accept `DecisionSubject` fields, including `parameters` and `presentation`, plus expiration, reachability, and placeholder settings. Durable calls require an operation-specific idempotency key; persist the returned decision ID alongside the framework's suspended run. Verify callbacks and read the authoritative decision before resuming that run.
+
+For an explicit human gate, set `policy: false`. The gate keeps the full review subject and binds its decision key to the run, call, recipient, question, and complete JSON arguments. `decisionFingerprint(value)` exposes the same stable JSON fingerprint for deferred bindings. It rejects cycles, nonfinite numbers, and non-JSON objects instead of silently dropping action details.
+
+**Upgrade handling:** version 2.1 changes human gate keys. Finish already-started operations on the SDK version that created them, or migrate their persisted bindings explicitly. Do not replay previously executed operations through the new key scheme. A fingerprint identifies the proposed action; the application's execution record and framework persistence still own recovery after an uncertain tool execution.
+
 Every official Pushary adapter (`@pushary/eve`, `@pushary/ai-sdk`,
 `@pushary/langgraph`, `@pushary/mastra`, `@pushary/openai-agents`) is a thin binding
 over one shared kernel, and that kernel is public. If you run an in-house harness, or
@@ -394,3 +402,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

@@ -27,6 +27,7 @@ __export(adapters_exports, {
   UNBOUND_APPROVAL: () => UNBOUND_APPROVAL,
   UNCONFIRMED_PERMIT: () => UNCONFIRMED_PERMIT,
   createAdapterKernel: () => createAdapterKernel,
+  decisionFingerprint: () => decisionFingerprint,
   defaultProtectQuestion: () => defaultProtectQuestion,
   deniedByPolicy: () => deniedByPolicy,
   deriveParameters: () => deriveParameters,
@@ -42,6 +43,7 @@ __export(adapters_exports, {
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(adapters_exports);
+var import_node_crypto = require("crypto");
 
 // src/error.ts
 var PusharyApiError = class _PusharyApiError extends Error {
@@ -92,11 +94,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
   });
@@ -156,6 +159,25 @@ var import_crypto2 = require("crypto");
 // src/util.ts
 var import_crypto = require("crypto");
 var deterministicKey = (parts) => (0, import_crypto.createHash)("sha256").update(parts.join("\0")).digest("hex").slice(0, 40);
+var decisionFingerprint = (value) => {
+  const ancestors = /* @__PURE__ */ new Set();
+  const serialize = (item) => {
+    if (item === null || typeof item === "string" || typeof item === "boolean") return JSON.stringify(item);
+    if (typeof item === "number" && Number.isFinite(item)) return JSON.stringify(item);
+    if (typeof item !== "object" || ancestors.has(item)) {
+      throw new TypeError("Pushary: decision identity must contain finite, acyclic JSON values.");
+    }
+    if (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null) {
+      throw new TypeError("Pushary: decision identity must contain plain JSON objects.");
+    }
+    ancestors.add(item);
+    const entries = Object.entries(item).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const serialized = Array.isArray(item) ? `[${Array.from(item, serialize).join(",")}]` : `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${serialize(entry)}`).join(",")}}`;
+    ancestors.delete(item);
+    return serialized;
+  };
+  return (0, import_crypto.createHash)("sha256").update(serialize(value)).digest("hex");
+};
 var AFFIRMATIVE = /* @__PURE__ */ new Set([
   "yes",
   "y",
@@ -179,64 +201,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,
-      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
-    });
-    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),
@@ -366,6 +404,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}`
@@ -424,9 +463,20 @@ var parseDecisionCallback = (rawBody) => {
 };
 
 // src/adapters.ts
-var DEFAULT_NODE = "ask-human";
 var defaultProtectQuestion = (action, target) => `Approve ${action}${target ? ` ${target}` : ""}?`;
-var idempotencyKeyFor = (input) => deterministicKey([input.externalId, input.node ?? DEFAULT_NODE, input.question]);
+var idempotencyKeyFor = (input) => input.idempotencyKey ?? (0, import_node_crypto.randomUUID)();
+var decisionSubject = (input) => ({
+  toolTarget: input.toolTarget,
+  actor: input.actor,
+  environment: input.environment,
+  parameters: input.parameters,
+  presentation: input.presentation,
+  approvalUrl: input.approvalUrl,
+  expiresInSeconds: input.expiresInSeconds,
+  requireReachable: input.requireReachable,
+  placeholder: input.placeholder,
+  callbackUrl: input.callbackUrl
+});
 var isAffirmative = (answer) => isApproved({ status: "answered", type: "confirm", value: answer ?? null });
 var describeAnswer = (type, result) => {
   if (!result.answered) {
@@ -515,11 +565,12 @@ var createAdapterKernel = (helpersLabel) => {
     ...config.baseUrl ? { baseUrl: config.baseUrl } : {}
   });
   const requireExternalId = (externalId) => {
-    if (!externalId) {
+    if (!externalId?.trim()) {
       throw new Error(
         `Pushary: no end-user to ask. Pass { externalId } to ${helpersLabel}, or run user-scoped auth so the framework supplies one.`
       );
     }
+    if (externalId.length > 256) throw new Error("Pushary: externalId must not exceed 256 characters.");
     return externalId;
   };
   const createGate = (config) => {
@@ -546,8 +597,12 @@ var createAdapterKernel = (helpersLabel) => {
       }
     };
     return async (ask) => {
+      if (!ask.callId?.trim()) throw new Error("Pushary: a stable tool call ID is required to resolve an approval.");
+      requireExternalId(ask.externalId);
       const facts = ask.parameters ?? deriveParameters(ask.input);
+      const idempotencyKey = decisionFingerprint({ ...ask, parameters: facts });
       const evaluation = await evaluate(ask, facts);
+      const includeSubject = evaluation !== null || !usePolicy;
       if (evaluation?.verdict === "allow") {
         return {
           approved: true,
@@ -573,6 +628,7 @@ var createAdapterKernel = (helpersLabel) => {
         question: ask.question,
         type: "confirm",
         externalId: ask.externalId,
+        context: ask.context,
         ...config.agentName ? { agentName: config.agentName } : {},
         ...config.expiresInSeconds ? { expiresInSeconds: config.expiresInSeconds } : {},
         ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {},
@@ -581,11 +637,8 @@ var createAdapterKernel = (helpersLabel) => {
         // 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 ? {
+        ...includeSubject ? {
+          presentation: ask.presentation,
           toolTarget: ask.toolTarget,
           actor: ask.actor,
           environment: ask.environment,
@@ -593,7 +646,7 @@ var createAdapterKernel = (helpersLabel) => {
         } : {},
         // 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])
+        idempotencyKey
       });
       if (result.approved) {
         return {
@@ -602,10 +655,7 @@ var createAdapterKernel = (helpersLabel) => {
             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 ? {
+            ...includeSubject ? {
               toolTarget: ask.toolTarget,
               actor: ask.actor,
               environment: ask.environment,
@@ -618,10 +668,11 @@ var createAdapterKernel = (helpersLabel) => {
     };
   };
   const askExternalUser = (config, input) => client(config).decisions.ask({
+    ...decisionSubject(input),
     question: input.question,
     type: input.type,
     options: input.options,
-    externalId: input.externalId,
+    externalId: requireExternalId(input.externalId),
     context: input.context,
     agentName: config.agentName,
     timeoutMs: config.timeoutMs,
@@ -629,19 +680,23 @@ var createAdapterKernel = (helpersLabel) => {
     // 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,
+    toolName: input.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({
+      ...decisionSubject(input),
       question: input.question,
       type: input.type,
       options: input.options,
-      externalId: input.externalId,
+      externalId: requireExternalId(input.externalId),
       context: input.context,
       callbackUrl: input.callbackUrl,
       agentName: config.agentName,
-      toolName: input.node,
+      toolName: input.toolName ?? input.node,
       idempotencyKey: idempotencyKeyFor(input),
       wait: false
     });
@@ -654,7 +709,7 @@ var createAdapterKernel = (helpersLabel) => {
       deviceCount: created.deviceCount
     };
   };
-  const connect = (config, externalId) => client(config).enroll(externalId);
+  const connect = (config, externalId) => client(config).enroll(requireExternalId(externalId));
   const protect = (config) => {
     const gate = createGate(config);
     const permitClient = client(config);
@@ -716,6 +771,7 @@ var createAdapterKernel = (helpersLabel) => {
   UNBOUND_APPROVAL,
   UNCONFIRMED_PERMIT,
   createAdapterKernel,
+  decisionFingerprint,
   defaultProtectQuestion,
   deniedByPolicy,
   deriveParameters,