@pushary/server 1.4.0 → 1.5.0

package/README.md

@@ -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.

package/dist/adapters.cjs

@@ -20,16 +20,23 @@ 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
@@ -181,10 +188,22 @@ var createDecisionsResource = (request) => {
       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
     });
@@ -237,6 +256,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) => {
@@ -260,15 +375,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 })
   });
 };
 
@@ -304,6 +425,7 @@ 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 isAffirmative = (answer) => isApproved({ status: "answered", type: "confirm", value: answer ?? null });
 var describeAnswer = (type, result) => {
@@ -331,6 +453,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 +527,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 +577,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,6 +625,11 @@ 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) => {
@@ -411,6 +641,7 @@ var createAdapterKernel = (helpersLabel) => {
       context: input.context,
       callbackUrl: input.callbackUrl,
       agentName: config.agentName,
+      toolName: input.node,
       idempotencyKey: idempotencyKeyFor(input),
       wait: false
     });
@@ -424,27 +655,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