@multiagency/sdk 0.3.1

package/schemas/reportCommand.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "commandId": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "expectedVersion": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "report": {
+      "type": "object",
+      "properties": {
+        "agreementId": {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+        },
+        "amount": {
+          "type": "string",
+          "pattern": "^[1-9][0-9]{0,17}$"
+        },
+        "start": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "end": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "contributions": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000
+        },
+        "assessment": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000
+        },
+        "evidence": {
+          "maxItems": 12,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 1000,
+            "format": "uri"
+          }
+        }
+      },
+      "required": [
+        "agreementId",
+        "start",
+        "end",
+        "contributions",
+        "assessment",
+        "evidence"
+      ],
+      "additionalProperties": false
+    },
+    "submit": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "commandId",
+    "id",
+    "expectedVersion",
+    "report",
+    "submit"
+  ],
+  "additionalProperties": false
+}

package/schemas/requestRecord.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "version": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "payee": {
+      "type": "string",
+      "pattern": "^(?=.{2,64}$)([a-z\\d]+[-_])*[a-z\\d]+(\\.([a-z\\d]+[-_])*[a-z\\d]+)*$"
+    },
+    "agreementVersion": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "report": {
+      "type": "object",
+      "properties": {
+        "agreementId": {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+        },
+        "amount": {
+          "type": "string",
+          "pattern": "^[1-9][0-9]{0,17}$"
+        },
+        "start": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "end": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "contributions": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000
+        },
+        "assessment": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000
+        },
+        "evidence": {
+          "maxItems": 12,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 1000,
+            "format": "uri"
+          }
+        }
+      },
+      "required": [
+        "agreementId",
+        "start",
+        "end",
+        "contributions",
+        "assessment",
+        "evidence"
+      ],
+      "additionalProperties": false
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "draft",
+        "submitted",
+        "changes_requested",
+        "approved",
+        "declined"
+      ]
+    },
+    "approvedAmount": {
+      "type": "string",
+      "pattern": "^[1-9][0-9]{0,17}$"
+    },
+    "feedback": {
+      "type": "string"
+    },
+    "reviewedBy": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "at": {
+      "type": "string"
+    },
+    "payment": {
+      "default": null,
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "shared",
+                "isolated"
+              ]
+            },
+            "id": {
+              "type": "string",
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+            },
+            "until": {
+              "type": "string",
+              "format": "date-time",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
+            }
+          },
+          "required": [
+            "mode",
+            "id"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "id",
+    "version",
+    "payee",
+    "agreementVersion",
+    "report",
+    "state",
+    "feedback",
+    "reviewedBy",
+    "at",
+    "payment"
+  ],
+  "additionalProperties": false
+}

package/schemas/session.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "account": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "agreed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "account",
+    "agreed"
+  ],
+  "additionalProperties": false
+}

package/schemas/workOrderList.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "orders": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          },
+          "amount": {
+            "type": "string"
+          },
+          "note": {
+            "type": "string"
+          },
+          "until": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "amount",
+          "note",
+          "until",
+          "createdAt"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "orders"
+  ],
+  "additionalProperties": false
+}

package/schemas/workOrderRequestResult.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "status": {
+      "type": "string",
+      "const": "requested"
+    }
+  },
+  "required": [
+    "id",
+    "status"
+  ],
+  "additionalProperties": false
+}

package/skills/app-server/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: app-server
+description: >
+  Use when building an app's server (for example the MultiAgency dashboard's) that reaches MultiAgency agents for its
+  Organizations through @multiagency/sdk: the deployment's service credential, owner consents and hosted setup signed
+  with the owner's wallet, reads and the owner actions an app may relay, and payout requests sent at most once per
+  requestId and followed by status. Server side only; never in a browser. Not for an owner's own browser app (use
+  owner-workflows) or payees (use payee-workflows).
+metadata:
+  purpose: 'An app server''s access to agents: credential, consents, relayed owner actions, and payout requests by requestId with recovery by state.'
+  type: core
+  library: '@multiagency/sdk'
+  library_version: '0.3.1'
+requires:
+  - getting-started
+  - owner-workflows
+sources:
+  - 'MultiAgency/platform:src/contract/app-client.ts'
+  - 'MultiAgency/platform:src/contract/app-access.ts'
+  - 'MultiAgency/platform:src/contract/app-consent.ts'
+  - 'MultiAgency/platform:docs/agent-access.md'
+---
+
+# An app's server with appClient
+
+Read getting-started and owner-workflows first. `appClient` runs on your server with the deployment's service credential
+(`tap_…`), issued by the platform operator: a server secret, never sent to a browser. A call reaches an agent only
+under a live owner consent for that Organization and agent, and only within the consent's scopes: `read`, `owner`, and
+`payout`. No production MultiAgency host serves the `/apps/v1` routes yet; the operator runs them on a staging host for
+its own tests. Until a production host does, build against the SDK repository's local stack
+(`pnpm test:e2e:stack --app <deployment>`). Use only `/apps/v1` and the confirm page on the platform's host: it serves
+nothing else (no sign-in or owner page), and setup there is for Payables agents only.
+
+## Setup
+
+```ts
+import { appClient } from "@multiagency/sdk";
+
+// `platform` is the platform host's HTTPS origin; `credential` comes from your server's secret store.
+export const platformFor = (platform: `https://${string}`, credential: string) => appClient({ base: platform, credential });
+```
+
+Result: `await app.identity("payout")` answers `{ ok: true, value: { agent, owner, agentId, created, host, deployment } }`.
+`session` (401) means the credential is invalid, expired or revoked: an operator matter, not the user's.
+
+## Connect an Organization's agent: the owner signs a consent
+
+Your server builds the exact consent text and a 32-byte nonce; the owner's wallet signs it with NEP-413, recipient the
+platform host, no callback URL; your server submits it. Show the owner the text the wallet signs.
+
+```ts
+import { appClient, consentMessage, type AppConsentSubmission } from "@multiagency/sdk";
+
+type SignNep413 = (message: string, recipient: string, nonce: Uint8Array) => Promise<{ publicKey: string; signature: string }>;
+
+export async function connect(app: ReturnType<typeof appClient>, host: string, deployment: string, organization: string,
+  agent: string, sign: SignNep413) {
+  const identity = await app.identity(agent);
+  if (!identity.ok) return identity;
+  if (!identity.value.agentId) throw new Error("Not created yet: set it up and create it first");
+  const message = consentMessage({ host, deployment, organization, owner: identity.value.owner, agent, agentId: identity.value.agentId,
+    scopes: ["read", "owner"], expiresAt: new Date(Date.now() + 90 * 86_400_000).toISOString() });
+  const nonce = crypto.getRandomValues(new Uint8Array(32));
+  const signed = await sign(message, host, nonce);
+  const submission: AppConsentSubmission = { message, nonce: btoa(String.fromCharCode(...nonce)), ...signed };
+  let stored = await app.consents.submit(submission);
+  // No answer: the same signed body is safe to submit again; never ask the owner to sign again for that.
+  if (!stored.ok && stored.kind === "unavailable") stored = await app.consents.submit(submission);
+  return stored;
+}
+```
+
+Result: `{ ok: true, value: { consent: { id, scopes, expiresAt, … } } }`; keep `consent.id` with the Organization. A
+`refused` 400 means the text or signature was not accepted; 409 means the agent changed: read `identity` again and ask
+the owner to sign a new text. Later calls answer `forbidden` once the consent ends (expired, revoked, or the owner's
+signing key removed): the owner signs a new one. A 503 means a check went unanswered: read again.
+
+## Relay an owner action
+
+With `owner` scope an app may prepare `agent_create` without payees (naming the key that signed the setup),
+`agent_freeze`, `agent_unfreeze`, `grant_issue`, `grant_revoke`, `policy_update`, and `approval_vote` on a held payout,
+through `app.agent(organization, agent).call(...)`. Everything else is refused before it reaches the agent. A vote the
+platform can't verify (an expired or changed approval, other terms, approving a held withdrawal) is refused before
+anything reaches the provider (`refused`, code `local_authorization_held`), at prepare or at submit.
+
+```ts
+import { appClient, type AppOwnerAction } from "@multiagency/sdk";
+
+type SignNep413Intent = (intent: { standard: "nep413"; payload: { message: string; recipient: string; nonce: string } }) => Promise<Record<string, unknown>>;
+
+/** Prepares an owner action; a readable one the owner signs in your app, any other on the platform's confirm page. */
+export async function ownerAction(app: ReturnType<typeof appClient>, organization: string, agent: string, action: AppOwnerAction,
+  signReadable: SignNep413Intent, openForOwner: (url: string) => void) {
+  const calls = app.agent(organization, agent);
+  const prepared = await calls.call("owner/prepare", { action, signer: "wallet" });
+  if (!prepared.ok) return prepared;
+  const { correlationId, intent, confirm } = prepared.value;
+  if (confirm) openForOwner(confirm.url); // NEP-366: the owner reads the platform's record and signs there
+  else if (intent?.standard === "nep413")
+    await calls.call("owner/submit", { correlationId, signedData: await signReadable(intent) });
+  return calls.call("owner/status", { correlationId });
+}
+```
+
+Result: `owner/status` answers the outcome; read it again until it is final. Open a `confirm` link for the owner right
+away (the intent expires in minutes). It shows the action's terms to whoever holds it; the bytes to sign go only to
+whoever presents the owner's signature over the link's text, which the page asks the wallet for, and `owner/submit`
+through the app is refused for it.
+
+A vote on a held payout names it from `held` (`approvalId`, `correlationId`). The prepared vote's `payment.terms`
+(recipient, asset, amount) are what the platform proved against the provider's evidence: show those to the owner, not
+your own record of the request. The vote's signed text holds only an identifier and a hash, so your display is the only
+place the owner reads the terms. A payout an owner approves can still read `processing` until the provider settles it;
+follow `payouts/status`.
+
+## Set up a hosted agent for an Organization
+
+Before an Organization has an agent, your server builds `setupMessage({ host, deployment, organization, owner, area,
+expiresAt })` (at most an hour ahead) and the owner signs it like a consent; submit it with `app.setup(...)`. The answer
+names the Organization's own agent and a setup consent that lets you relay only its creation: `agent_create` without
+payees, naming the key that signed the setup. Then read `identity` until it is created, and ask the owner to sign a
+consent naming its `agentId`. A 409 means it already exists or the deployment reached its agent limit on the host; a
+503 means a check went unanswered: submit the same body again.
+
+## Request a payout once, and follow it
+
+To fund the agent first, `agentCalls.call("deposit")` (payout scope) answers a one-time address (with `memo`,
+`minAmount` and `expiresAt` when given) that credits USDC to the agent's confidential balance; send exactly there.
+
+Write the `requestId` (1–64 of `[A-Za-z0-9_-]`) and the exact terms to your database before calling. The platform sends
+one request at most once per deployment, Organization, agent and `requestId`. Never send the same payout under a new `requestId` until
+the first is `refused`, or `failed` and checked by a person.
+
+```ts
+import { appClient } from "@multiagency/sdk";
+
+type Terms = { requestId: string; asset: string; recipient: string; amount: string; expectedPolicy: { revision: number; digest: string } };
+
+export async function payOnce(app: ReturnType<typeof appClient>, organization: string, agent: string, terms: Terms) {
+  const agentCalls = app.agent(organization, agent);
+  const asked = await agentCalls.call("payouts/request", { ...terms, delivery: "intents" });
+  if (asked.ok || (asked.kind !== "unknown" && asked.kind !== "unavailable")) return asked;
+  // The answer was lost: read the request by its id. Asking again with the same terms would also send nothing new.
+  return agentCalls.call("payouts/status", { requestId: terms.requestId });
+}
+```
+
+Result: `{ ok: true, value: { requestId, state, status, correlationId, code } }`. `state` is `succeeded`, `failed`
+(FAILED or REFUNDED: not proof that nothing moved, so a person checks), `held` (waiting for the owner's vote),
+`processing`, `refused` (proven not sent, `code` says why, for example `insufficient_balance`; recorded, so a new
+attempt needs a new `requestId`), `unknown`, or
+`not_found` (nothing recorded yet: a request still on its way can read so; ask again with the same `requestId`
+and terms, which sends at most once). `processing` and `unknown` block that agent's payouts until resolved: read
+`payouts/status` later; never pay that request another way meanwhile. Other terms under a used `requestId` are refused
+(`code: "request_conflict"`). A named recipient that doesn't exist on NEAR is refused before anything is recorded
+(`recipient_not_found`: fix the payee, then a new `requestId`); `recipient_unchecked` means the chain didn't answer:
+ask again with the same `requestId`. These two come back as a refused result, not a state.
+
+To pay a NEAR account directly, the owner first agrees it as a withdrawal payee (a `policy_update` with
+`withdrawals: [{ address }]`; the first one turns withdrawals on, an on-chain edit signed on the confirm page). To pay
+wNEAR, the owner also adds `nep141:wrap.near` to the policy's `assets` and sets its per-asset `limits` (the payout
+template has USDC only; without a limit only the USD budget caps it). Then request with `delivery: { chain: "near" }` and
+`asset` wNEAR (arriving as native NEAR, per the provider's docs) or USDC; an asset the policy doesn't include is refused
+`asset_not_allowed` before sending. It is paid from the confidential balance, is public on chain, and may arrive less a
+route fee. A USDC withdrawal's recipient must be registered on the USDC contract (a one-time `storage_deposit` the payee
+makes from any wallet): otherwise it is refused `recipient_not_registered` before anything is recorded, and the same
+`requestId` can be asked again once it is. A `nearcom:` address is never a withdrawal recipient; any other chain is refused `chain_not_supported`. A held
+withdrawal can be rejected, not approved, for now: show the owner the reject choice only. Under the payout template every
+payout is held, so a withdrawal is paid only once the owner turns `owner_approval` off. Fund wNEAR with `deposit` and
+`{ asset: "nep141:wrap.near" }`.
+
+## Common mistakes
+
+- **Asking an owner to sign `Sign in to <platform host>`** (CRITICAL): a signed sign-in is a full platform session that
+  can send payouts without another signature. An app asks only for consent and setup texts.
+- **Sending the credential to a browser** (CRITICAL): whoever holds it acts within every consent the deployment holds.
+- **A new requestId after `unknown`** (CRITICAL): the first may have been sent. Read `payouts/status`.
+- **Treating `failed` as unpaid** (HIGH): a partial payout fails too. A person checks before a new attempt.
+- **Showing your own summary instead of the signed text** (HIGH): the owner must read what the wallet signs.
+- **Asking the owner to sign the confirm page's text ("Open a MultiAgency confirm page.") in your app** (CRITICAL): it
+  is the owner's proof to the platform's page; signed elsewhere, it hands out the bytes for a blind signature.
+- **Withdrawing to a `nearcom:` address** (CRITICAL): it is not on any chain; near.com users are paid through `intents`.
+- **Showing your own record of a held payout when asking for a vote** (HIGH): show the prepared vote's
+  `payment.terms`, which the platform proved; your record may name another payout than the one the vote releases.
+
+## Completion
+
+Every consent you submitted has its id stored or its refusal shown; every payout request has a read state, and none
+reads `unknown` or `processing` without a later `payouts/status` read. Report anything you could not read; do not act
+again.

package/skills/getting-started/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: getting-started
+description: >
+  Use when deciding how an app or external agent should work with MultiAgency agents through @multiagency/sdk: which client
+  to use (owner or payee), how each kind of identity signs in and what the server enforces for it, how results report
+  refused, unavailable and unknown outcomes, and what this package version supports. For owner tasks use owner-workflows;
+  for payee tasks use payee-workflows.
+metadata:
+  purpose: 'Orients an app or agent author: the two clients, the four identities and their server-side limits, recovery kinds, and the supported surface of this package version.'
+  type: lifecycle
+  library: '@multiagency/sdk'
+  library_version: '0.3.1'
+sources:
+  - 'MultiAgency/platform:src/contract/index.ts'
+  - 'MultiAgency/platform:src/contract/payee-entry.ts'
+  - 'MultiAgency/platform:docs/agent-access.md'
+---
+
+# Working with MultiAgency agents
+
+Each agent moves funds for its **owner** (a NEAR account or a Sputnik DAO) only inside the policy the owner signed.
+This package gives apps and agents typed access to two kinds of work. It grants no authority: every call is authorized
+by the gateway and the provider, never by the client or by this guidance.
+
+1. Pick the client for the identity you act as (table below). Result: one of `ownerClient` (entry `@multiagency/sdk`),
+   `appClient` (same entry, an app's server) or `payeeClient` (entry `@multiagency/sdk/payee`, zod only).
+2. Get that identity's session the supported way. Never handle a wallet's private key or copy browser cookies into an
+   agent. Result: calls return data; a `session` (401) result means sign in again.
+3. Do the task with owner-workflows, app-server or payee-workflows.
+4. Keep every identity you send (`correlationId`, `commandId`, request `id`, `planId`) until you have read its outcome.
+   Some owner actions (`pay`, `sweep`, `autopilot/tick`) carry no identity; owner-workflows says how to recover them.
+
+## Identities and what the server enforces
+
+| Identity | How it is obtained | Reaches | Enforced server-side |
+| --- | --- | --- | --- |
+| Owner session | NEP-413 sign-in in a browser at the agent's host (`/gw/challenge` → wallet signs → `/gw/session`) | `/a/<agent>/rpc/*` through `ownerClient` | Access per agent from the wallet owner, or from the DAO policy for a member (propose, vote; execute and manage derived). A member never acts or spends as the DAO alone: owner actions need the owner's signature (a DAO vote). Calls outside access: 403. |
+| Treasury machine credential | Issued by a wallet owner of a Treasury agent from the owner's session (`tmc_…` bearer) | `/machine/v1/a/<agent>/rpc/*` (Treasury's skill helper, not this package) | Fixed scopes (read, prepare, execute-plan, sweep), expiry, revocation, the owner's fresh access re-checked per call. Treasury only; DAO owners cannot issue it. |
+| App deployment credential | Issued by the platform operator per app deployment (`tap_…` bearer, a server secret), plus an owner-signed consent per Organization and agent | `/apps/v1/*` through `appClient` (server side only) | The consent's scopes (`read`, `owner`, `payout`), Organization and agent; owner actions only those the owner can read or the platform builds; the owner's key and ownership re-checked per call; revocation. Wallet owners only. |
+| Payee session | NEP-413 sign-in on the payee entry (`/api/signin`) | `/api/*` on that entry through `payeeClient()` | Only the signed-in account's own invoices, work orders and reports. An account that has only requested onboarding terms is not yet a payee: an agreement makes it one. |
+| Agent connection | Started by the payee from their signed-in browser session (`tac_…` bearer, shown once) | `GET`/`POST /api/compensation`, `GET /api/compensation/session` through `payeeClient({ base, token })` | Bound to host, entry, account and payout agent; expiry (at most 24h) and revocation; every other route 403 with no effect; never a browser session; each call attributed. |
+
+## Results: decide by `kind`, never by message text
+
+| `kind` | Meaning | Nothing was sent? | What to do |
+| --- | --- | --- | --- |
+| `ok: true` | The answer, validated against this version's schema | n/a | Use `value` |
+| `session` | 401: no valid session | Yes | Sign in again (agent connection: start a new one) |
+| `forbidden` | 403: this identity may not do this | Yes | Do not retry; it is a permission, not an outage |
+| `refused` | Refused before anything was sent (optional `code`; owner results also carry the HTTP `status` and oRPC `rpcCode`) | Yes | Correct the input or state, then act again |
+| `busy`, `unresolved` | Owner money actions: another action holds the lock, or an earlier one has no proven outcome | Yes | Follow existing operations, then try again |
+| `provider` | After an owner action, the provider's answer proves it refused; after a read, the provider read failed | Yes, for an action | Check the recorded outcome before acting again |
+| `unavailable` | A read failed or lost its answer | n/a (a read) | Reading again is safe |
+| `unknown` | An action was sent and its outcome is not known (`identity` is the input you sent) | Not known | Never resend. Read the record by the kept identity, or follow owner-workflows when the action has none |
+
+`unavailable` and `unknown` may carry `httpStatus` when the answer was a plain HTTP error rather than an encoded one (a
+proxy page, or a 404 for a procedure the host doesn't have). It is a diagnostic: it doesn't prove that nothing ran. A
+`fetch` you pass in that throws (a timeout, a refused redirect, your own origin check) is a lost answer too: `unavailable`
+for a read and `unknown` for an action. A command-line helper can map these to exit codes, for example `0` for `ok`, `2`
+for a kind that proves nothing was sent, and `3` for `unknown`, so a script never treats an unknown outcome as a failure
+it may retry.
+
+## What this package version supports
+
+`@multiagency/sdk` 0.3.1, entries:
+- `@multiagency/sdk`: `ownerClient` with `OwnerResult`/`OwnerFailure`, `appClient` with `AppRouteResult` and the
+  consent and setup texts (`consentMessage`, `setupMessage`), `ownerOutputs` and `OwnerInputs`/`OwnerOutput`
+  per procedure, `ownerCapabilities` and `mayCall` (display only), gateway discovery (`gatewayDiscovery`,
+  `gatewayDenialScope`), schemas for runs (`RecordingSchema`) and proposals, `ASSETS` and account helpers. It also
+  re-exports the payee entry. Peer: zod ^4.6.5. It bundles `@orpc/client` 2.0.0-beta.47 and loads no other oRPC
+  package, so it runs beside a host that shares its own oRPC. It depends on `@ag-ui/core` 1.0.3.
+- `@multiagency/sdk/contract`: `ownerContract`, `ownerErrors` and `OwnerContract`, for an app implementing a server
+  from the contract. It loads `@orpc/contract` 2.0.0-beta.47, a dependency.
+- `@multiagency/sdk/payee`: `payeeClient` with `Result`/`Failure`, payee and compensation schemas, agent-connection
+  schemas, `payeeContract` and `compatiblePayeeFrontend`. Peer: zod only.
+- `@multiagency/sdk/release-server`: `stage`, `activate`, `readRelease`, `digest` and `releaseServer` for app
+  releases, and the `multiagency-release-server` command. Node only: its types use `@types/node`.
+- `@multiagency/sdk/schemas/*`: JSON Schemas of the payee and compensation wire for non-JavaScript consumers.
+
+Other exports (the owner contract object, server input schemas, capability helpers the gateway uses) are available,
+but they follow the platform's needs and may change without notice.
+
+The payee entry's capability ids are still `supplier-*-v1` (check them with `payeeClient().capabilities()`); an agent
+connection's `role` is `PAYEE_ROLE`. Compare against the exported constants, never against literal strings.
+
+## Completion
+
+The task is done when the client answers `ok` for the reads you need and every action's outcome has been read by its
+kept identity. If a result is `unknown`, the task is not done until the record is read; if it stays unreadable, report
+it rather than acting again.