Actions

Run an instruction, handle one of four results.

const result = await payman.forUser(req.session.userId).run(
  "Pay the Acme invoice for $120",
);

switch (result.kind) {
  case "ok":               // done: render result.message
    break;
  case "needs_connection": // render the connect button
    break;
  case "approval":         // money stopped for the customer
    break;
  case "error":            // show result.guidance
    break;
}

One instruction in, one result out. run() resolves one of four results and never throws for anything that fails remotely; those failures arrive as the error result. Throwing is reserved for your own configuration or store faults.

Call forUser() inside the request handler, once per call. Never hoist it to module scope.

The four results

result.kind	When	What your app does
ok	The action completed	Render message, attributed to the customer’s Payman account.
needs_connection	No connection is held, or it stopped working	Render the connect button. The instruction is stashed for replay.
approval	The action froze for the customer’s approval	Render the approval button. See Approvals.
error	Anything else	Show guidance.

What each result carries

ok

Field	Type	Meaning
message	string	The reply, verbatim. An empty reply stays empty.
agentStatus	string	The run’s final status string.

needs_connection

Field	Type	Meaning
reason	"no_grant" | "credential_rejected"	This user never connected, or the connection stopped working.
connectUrl	string	The consent URL, ready to render as a button.
stashed	boolean	True when the instruction was kept for replay after consent.

approval

Field	Type	Meaning
approval.ref	string	Opaque handle for the frozen operation. Safe to show a model.
approval.channel	"payman_hosted" | "payman_console"	Where the customer approves.
approval.url	string | null	Payman’s approval page. Null exactly when the channel is payman_console.
approval.expiresAt	Date | null	When the approval lapses, about 15 minutes out.
message	string | null	Text produced alongside the freeze, if any.

error

Field	Type	Meaning
code	string	Stable identifier to switch on. Full list in Limits and errors.
retryable	boolean	Worth one more attempt.
retryAfterMs	number?	Wait this long first, when present.
guidance	string	Customer-facing prose. Render it as is.

On the blocking route the SDK retries a retryable failure once before resolving error; streamed turns (runStream(), or run() with onEvent) resolve without a retry. Treat retryable as permission for one more attempt, not a loop. Retrying never silently re-sends money: anything that moves it stops for the customer’s approval first.

What no result carries

Diagnostics such as internal ids, token usage, and raw payloads sit on a non-enumerable symbol, not on the result’s fields. JSON.stringify(result) never includes them, so a result is safe to send to the browser as is.

Sessions

Actions for the same user share one conversation. The SDK mints a session when the connection is stored and continues it on every call; there is nothing to thread through your code.

await payman.forUser(userId).newConversation();

newConversation() starts a fresh thread. It keeps the connection, clears any stashed instruction, and retires stored approval cards. A fresh chat is not a fresh consent.

Streaming

// Progress on the same call: setting onEvent switches run() to streaming.
const result = await payman.forUser(userId).run(text, {
  onEvent: (event) => {
    if (event.type === "progress") {
      setStatus(event.progress.label);   // "Looking up recipients..."
    }
  },
});

// Or iterate the events yourself.
const stream = payman.forUser(userId).runStream(text);
for await (const event of stream) {
  if (event.type === "text") append(event.delta);
}
const final = await stream.result();     // the same four results

onEvent implies streaming: the blocking path emits no events, so setting a listener switches the call over. An explicit stream: false wins, and the listener then hears nothing.

The listener receives every event while run() still resolves the ordinary result, and a listener that throws never breaks the action. handleToolUse() accepts the same option.

event.type	Carries	Meaning
text	delta	The reply as it forms. Append in order.
progress	progress	What the action is doing right now.
elicitation	prompt	A choice question for the customer. Answer with prompt.answer(optionId).
approval	approval	The action froze for approval. Same shape as the approval result.
done	result	The final result, identical to result().

A progress frame is a phase and a label, nothing more. started and completed bracket one step, so replace the current line instead of stacking; waiting is a heartbeat. The label is finished customer-facing copy; render it unchanged.

A stream is consumed once; iterating it twice throws. result() and the done event carry the identical result.