@pushary/server 1.3.3 → 1.5.0

package/README.md

@@ -224,6 +224,127 @@ app.post('/webhooks/pushary', async (req, res) => {
 })
 ```
 
+## Writing a framework adapter: `@pushary/server/adapters`
+
+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
+a framework we have not shipped for, this is the same surface they are built on.
+
+```typescript
+import { createAdapterKernel, renderApprovalQuestion } from '@pushary/server/adapters'
+
+const kernel = createAdapterKernel('the Acme helpers')
+
+// blocking ask; idempotency and the fail-closed result are already handled
+export const askHuman = kernel.askExternalUser
+
+// durable create, for a framework that parks its own run and resumes on a webhook
+export const openDecision = kernel.createDurableDecision
+
+// an enforced gate: build it once, call it per tool call
+const gate = kernel.createGate({ apiKey: process.env.PUSHARY_API_KEY! })
+
+export const approve = async (toolName: string, callId: string, input: unknown) => {
+  const decision = await gate({
+    toolName,
+    callId,
+    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`.
+
+Python has the same surface as `pushary.adapters`:
+
+```python
+from pushary.adapters import AdapterKernel, render_approval_question
+
+kernel = AdapterKernel("the Acme helpers")
+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.
+
 ## Handling errors
 
 Every non-2xx response throws a `PusharyApiError`. It extends `Error`, so existing