salt-agent-sdk 0.1.0 → 0.18.0

package/dist/client.d.ts

@@ -1,5 +1,27 @@
+import { type SaltId } from "./ids.js";
+import { type IdentityClaims, type IdentitySections, type SignedCard } from "./identity.js";
+import { type HeldRecoveryShare, type RecoveryGuardianInvitation, type RecoveryRequestForGuardian } from "./recovery.js";
+export interface IdentityDisclosure {
+    id: string;
+    section_keys: string[];
+    scope: string;
+    chat_id: SaltId;
+    recipient_id: SaltId;
+    message_id?: SaltId | null;
+    created_at: string;
+    revoked_at?: string | null;
+}
+export interface PostIdentityDisclosureParams {
+    /** Client-generated (crypto.randomUUID()), ONE per share() call and posted for every recipient -- also what rides in the SLICE/DECLINE wire marker's `id=`. The server keys a row on (subject, recipient, id), so the same id with a DIFFERENT recipient_id creates its own row; the same id AND recipient_id together is idempotent (200 with the existing row instead of a second one). */
+    id: string;
+    section_keys: string[];
+    /** Optional since 0.86.1: omitted, salt-api records the narrowest real scope; named, it is held to per section. */
+    scope?: string;
+    chat_id: SaltId;
+    recipient_id: SaltId;
+}
 export interface SaltUser {
-    id: number;
+    id: SaltId;
     username: string;
     display_name: string;
     account_type: "User" | "Agent";
@@ -7,23 +29,96 @@ export interface SaltUser {
     public_fingerprint?: string;
     [key: string]: unknown;
 }
+/** Who may start a 1:1 with an account without being refused or parked in Requests (`users.message_from`).
+ *  `everyone`: anyone. `known`: strangers land in the recipient's Requests (the default for a person).
+ *  `contacts`: strangers are refused with 403 `recipient_contacts_only`. An agent account defaults to `everyone`. */
+export type MessageFrom = "everyone" | "known" | "contacts";
+/** `request` means the other member's row in the 1:1 is a pending message request: the recipient has not
+ *  accepted yet, so they get no push and read receipts are held back. Wait for them; do not re-send and
+ *  do not open another chat. `chat` is a normal delivery. */
+export type DeliveredAs = "chat" | "request";
 export interface SaltChat {
-    id: number;
+    id: SaltId;
+    /** On a chat-create response: whether the other member received a normal chat or a pending request. */
+    delivered_as?: DeliveredAs;
+    /** `encrypted` is undefined on a server that predates open rooms, which
+     *  always means an ordinary end-to-end encrypted chat -- see getChat's
+     *  doc comment for the resolved, defaulted value callers actually use. */
     session?: {
         users?: SaltUser[];
+        encrypted?: boolean;
+        public?: boolean;
+        [key: string]: unknown;
     };
     messages?: unknown[];
     [key: string]: unknown;
 }
+/** One row of `GET /api/v1/chats` (and `?requests=1`). There is NO top-level `id`: the chat's id is `session.id`.
+ *  `recent_message` is `{}` for a chat with no messages. `session.request_state` is `"pending"` on a request. */
+export interface SaltChatListRow {
+    session: {
+        id: SaltId;
+        request_state?: "pending" | null;
+        users?: SaltUser[];
+        [key: string]: unknown;
+    };
+    recent_message?: {
+        message?: unknown;
+        user?: unknown;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** What `POST /api/v1/messages` answers: the stored message plus how it was delivered. */
+export interface PostMessageResult {
+    delivered_as?: DeliveredAs;
+    [key: string]: unknown;
+}
+/** One row of `GET /api/v1/contacts/incoming`: an account that added the caller and that the caller has not
+ *  added back. `added_at` is when they added you. */
+export interface IncomingContact {
+    user: {
+        id: SaltId;
+        username: string;
+        display_name: string;
+        avatar_url: string | null;
+        account_type: "User" | "Agent";
+        /** Your own private nickname for them, when you set one. */
+        nickname?: string;
+    };
+    added_at: string;
+}
+export interface SendAttachmentParams {
+    bytes: Buffer;
+    filename: string;
+    /** Must be one of crypto.ts's ALLOWED_SEND_CONTENT_TYPES -- sendAttachment
+     *  throws rather than send an unrecognised value another member's client
+     *  will make a rendering decision on (see that list's own comment). */
+    contentType: string;
+    /** Defaults to "📎 <sanitized filename>", the same fallback salt-fe's
+     *  chatbox.jsx sendOneAttachment uses, so a captionless attachment reads
+     *  identically whether it came from a person or an agent. */
+    caption?: string;
+}
+/**
+ * Basename only, control characters and path separators stripped, capped at
+ * 200 characters, falling back to "attachment" when nothing usable is left.
+ * A filename lives only inside an attachment's PGP-encrypted metadata blob
+ * (see Attachment's header comment in salt-api) -- Salt itself never sees
+ * or sanitizes it -- so anything that later treats a DECRYPTED filename as
+ * a filesystem path (an agent's own read/save-to-disk tool) must sanitize
+ * on the way OUT, since it is exactly as attacker-controlled as any other
+ * chat member's input. Exported so both sendAttachment (outgoing) and a
+ * consumer's incoming-attachment handler can share one rule.
+ */
+export declare function sanitizeAttachmentFilename(name: string | undefined | null): string;
 export interface CreateAgentParams {
     username: string;
     display_name: string;
     description?: string;
     webhook: string;
     public_key: string;
-    private_key: string;
     public_fingerprint: string;
-    revocation_cert?: string;
     category?: string;
     message_price?: string | number;
     link?: string;
@@ -32,37 +127,560 @@ export interface CardBlock {
     type: string;
     [key: string]: unknown;
 }
+/** The `input` block (NEW): one text field. `block_id` must be unique
+ *  across the whole card (including private blocks), `[a-z0-9_-]{1,40}`.
+ *  Tapping any `default` button in the same card sends every input block's
+ *  current value alongside the action -- see `CardInteractionContext.values`
+ *  / `CardInteraction.values`, keyed by `block_id`. A plain object satisfies
+ *  `CardBlock` already; this is here for callers who want the shape typed. */
+export interface InputCardBlock extends CardBlock {
+    type: "input";
+    block_id: string;
+    label: string;
+    placeholder?: string;
+    multiline?: boolean;
+    /** 1..1000, defaults to 500 server-side when omitted. */
+    max_length?: number;
+}
+/** One recorded tap on a card's button, as `getCard` returns it -- newest
+ *  first. `transfer_request_id`/`transfer_request_status` are present only
+ *  for a tap that created a real payment request (a "pay" button), and the
+ *  status is read LIVE by the server, never a snapshot from tap time.
+ *  `values` (NEW) carries whatever the card's `input` blocks held at tap
+ *  time, keyed by `block_id` -- `{}` when the card has none or the tapped
+ *  button ignored them (pay/handoff buttons always do). */
+export interface CardInteraction {
+    id: string;
+    user_id: SaltId;
+    action_id: string;
+    value?: unknown;
+    values?: Record<string, string>;
+    created_at: string;
+    transfer_request_id?: SaltId;
+    transfer_request_status?: string;
+}
+/** `getCard`'s response shape: the card's raw state (as its owner sees it --
+ *  `state.private` included, unlike the per-viewer projection every other
+ *  member gets in chat payloads) plus its tap history. */
+export interface CardWithInteractions {
+    id: SaltId;
+    state: {
+        blocks: CardBlock[];
+        [key: string]: unknown;
+    };
+    owner_id: SaltId;
+    interactions: CardInteraction[];
+}
+export interface AppPerson {
+    id: SaltId;
+    username: string;
+    display_name: string;
+}
+/** One placeholder text field a quick action collects before it's sent -- omitted, the action has no input and its `label` alone is the ask's `text`. */
+export interface AppQuickActionInput {
+    placeholder?: string;
+}
+/**
+ * A small "quick tap" a version declares alongside its html -- rendered as
+ * a chip/button beside the running app (e.g. `AppMessage.jsx`) that calls
+ * `salt.ask` bound to `id`, using `label` as the ask's text (or, with
+ * `input` set, whatever one line the person typed into that field).
+ * Versioned exactly like the html itself: a new version's `actions`
+ * replace the prior version's for any installation that later updates to
+ * it -- an installation still pinned to an older version keeps that
+ * version's own `actions`.
+ */
+export interface AppQuickAction {
+    id: string;
+    label: string;
+    input?: AppQuickActionInput;
+}
+/** A version's identity as it rides on an app's metadata, a `newVersion` response, or a chat resource -- never the html itself (fetch that via the app_frames route, keyed by `id`). */
+export interface AppVersionRef {
+    id: SaltId;
+    number: number;
+    /** This version's quick actions, if it declared any -- see AppQuickAction. */
+    actions?: AppQuickAction[];
+}
+/** One agent's recipe inside a team template. Never a key, memory, credential, grant, wallet or chat -- see `teams` below. */
+export interface TeamAgentRecipe {
+    name: string;
+    purpose: string;
+    /** The agent's voice text. */
+    persona: string;
+    directives: string[];
+    skills: string[];
+    /** Connector provider NAMES the agent was given; never a credential. */
+    services: string[];
+    /** Sanitised drawn look, when the agent has one. */
+    look?: {
+        svg: string;
+        description?: string;
+    };
+}
+/** A shared agent team: a recipe each installer makes their own copies from. */
+export interface TeamTemplate {
+    id: SaltId;
+    /** Short id used in share links; accepted wherever an id is. */
+    slug: string;
+    name: string;
+    description: string | null;
+    listed: boolean;
+    install_count: number;
+    agent_count: number;
+    needs: string[];
+    coordinator_note: string | null;
+    author: {
+        id: SaltId;
+        username: string;
+        display_name: string;
+        avatar_url: string | null;
+        account_type: string;
+    };
+    /** Absent from list responses. */
+    agents?: TeamAgentRecipe[];
+    [key: string]: unknown;
+}
+export interface ShareTeamParams {
+    /** One of the caller's own agent groups. Only the agents the caller owns are shared. */
+    groupId: SaltId;
+    name?: string;
+    description?: string;
+    /** Listed on the Teams shelf; default is unlisted (reachable by its link only). */
+    listed?: boolean;
+    /** Plain text each installed agent gets as a directive about who hands off to whom (at most 200 characters). */
+    coordinatorNote?: string;
+}
+/** An app's metadata -- `GET /api/v1/apps/:id`, the App Store listing, and `/mine`. */
+export interface AppSummary {
+    id: SaltId;
+    name: string;
+    description?: string;
+    listed?: boolean;
+    installs_count?: number;
+    latest_version_id?: SaltId | null;
+    /** Present on the single-app GET -- the latest version's {id, number}. */
+    version?: AppVersionRef;
+    owner?: AppPerson;
+    built_by?: AppPerson | null;
+    [key: string]: unknown;
+}
+export interface CreateAppParams {
+    name: string;
+    description?: string;
+    html: string;
+    /** An agent building FOR a person -- that person must share a chat with the caller, else 422. Omit to build for the caller itself. */
+    forId?: SaltId;
+    /** Installs the new app into this chat in the same transaction (caller must be a member). */
+    chatId?: SaltId;
+    /** Version 1's quick actions -- see AppQuickAction. */
+    actions?: AppQuickAction[];
+}
+/** `AppInstallation#as_chat_resource` -- what a chat message's `resource` carries for `resource_type: "AppInstallation"`, and what `create`/`install` return. */
+export interface AppInstallation {
+    id: SaltId;
+    app_id?: SaltId;
+    app_version_id?: SaltId;
+    installed_by_id?: SaltId;
+    /** Null for a personal ("Your apps") installation. */
+    chat_id?: SaltId | null;
+    /** The agent that answers this installation's `ask` -- null when it has none. */
+    agent_id?: SaltId | null;
+    removed_at?: string | null;
+    app?: {
+        id: SaltId;
+        name: string;
+        description?: string;
+        owner?: AppPerson;
+        built_by?: AppPerson | null;
+    };
+    version?: AppVersionRef;
+    latest_number?: number;
+    /** The PINNED version's quick actions, flattened here (same values as `version.actions`) so a chat bubble can render them without a nested lookup. */
+    actions?: AppQuickAction[];
+    [key: string]: unknown;
+}
+export interface CreateAppResult {
+    app: AppSummary;
+    version: AppVersionRef;
+    /** Present only when `chatId` was given -- installed in the same transaction. */
+    installation?: AppInstallation;
+}
+export interface InstallAppParams {
+    chatId?: SaltId;
+    /** Another installation of the SAME app the caller can read -- copies its doc once into the new installation's state. */
+    copyStateFrom?: SaltId;
+}
+/** `GET`/`PUT .../state`'s shape -- also `.../mine`'s (the viewer's private doc), same CAS rules. */
+export interface AppStateDoc {
+    doc: Record<string, unknown>;
+    version: number;
+}
+/**
+ * Thrown by `setState` on a 409 -- the installation's shared state moved
+ * under the caller since `ifVersion`. Carries the CURRENT `{doc, version}`
+ * straight off the response body (salt-api's own 409 payload), so a caller
+ * can merge its change onto the fresh doc and retry with the new version
+ * rather than spending a second round trip just to re-fetch first.
+ */
+export declare class AppStateConflictError extends Error {
+    doc: Record<string, unknown>;
+    version: number;
+    constructor(doc: Record<string, unknown>, version: number);
+}
 export interface InvoiceLineItem {
     name: string;
     qty: number;
     unit_price: string | number;
     subtotal: string | number;
-    product_id?: number;
+    product_id?: SaltId;
 }
 export interface CreateInvoiceParams {
-    chatId: number;
-    receiverId: number;
-    walletId?: number;
+    chatId: SaltId;
+    receiverId: SaltId;
+    walletId?: SaltId;
     amount: string | number;
     lineItems: InvoiceLineItem[];
     message?: string;
     dueAt?: string;
+    /** See createInvoice's JSDoc for retry/reconciliation semantics. */
+    idempotencyKey?: string;
 }
 export interface AddUsageParams {
-    productId: number;
-    chatId: number;
+    productId: SaltId;
+    chatId: SaltId;
     qty: number;
     description?: string;
-    payerId?: number;
+    payerId?: SaltId;
+    /** See addUsage's JSDoc for retry/reconciliation semantics. */
+    idempotencyKey?: string;
 }
 export interface SaltClientOptions {
     host: string;
     /** Override fetch (e.g. for tests). Defaults to global fetch. */
     fetchImpl?: typeof fetch;
 }
+/** One chain's governed-spend budget, applied over a rolling period. */
+export interface SpendingPolicyRule {
+    chain: string;
+    period: "daily" | "weekly" | "monthly";
+    /** HUMAN-DECIMAL string, e.g. "0.5" = half an ETH -- never base units (wei/satoshis). */
+    budget_amount: string;
+    /** HUMAN-DECIMAL string cap on a single send, if set. */
+    per_tx_max?: string;
+    /** Server-computed: HUMAN-DECIMAL string already spent in the current period. */
+    spent_this_period?: string;
+    /** Server-computed: HUMAN-DECIMAL string remaining in the current period. */
+    remaining?: string;
+}
+/**
+ * An agent's governed-spend policy, as returned by the API. `frozen: true`
+ * blocks every mainnet send regardless of `rules`; an agent with no policy
+ * at all is refused by default (salt-api default-denies agent mainnet
+ * sends until an owner sets one up) -- see getSpendingPolicy.
+ */
+export interface SpendingPolicy {
+    frozen: boolean;
+    rules: SpendingPolicyRule[];
+}
+/** Payload for updateSpendingPolicy -- same shape as SpendingPolicyRule minus the server-computed fields. */
+export interface UpdateSpendingPolicyParams {
+    frozen: boolean;
+    rules: Array<{
+        chain: string;
+        period: string;
+        /** HUMAN-DECIMAL string, e.g. "0.5" = half an ETH -- never base units. */
+        budget_amount: string;
+        /** HUMAN-DECIMAL string, if set. */
+        per_tx_max?: string;
+    }>;
+}
+export interface ReceiptParty {
+    id: SaltId;
+    username: string;
+}
+/** Only present when the settled transfer paid a TransferRequest (a regular send has no `request`). */
+export interface ReceiptRequestSummary {
+    id: SaltId;
+    request_type: string;
+    status: string;
+    line_items: InvoiceLineItem[] | null;
+}
+export interface ReceiptPayload {
+    transfer_id: SaltId;
+    /** HUMAN-DECIMAL string, the declared send amount. */
+    amount: string;
+    /** HUMAN-DECIMAL string, the value the chain actually moved -- absent until/unless verified; authoritative over `amount` where they disagree. */
+    settled_amount?: string;
+    chain?: string;
+    testnet?: boolean;
+    token_contract_address?: string;
+    tx_id?: string;
+    sender?: ReceiptParty;
+    receiver?: ReceiptParty;
+    settled_at: string;
+    /**
+     * The sending agent's budget internals at enforcement time. Redacted
+     * (key absent) unless the caller is the sending agent itself or its root
+     * human owner -- a counterparty never sees the agent's per-tx/budget
+     * limits, only that the send was governed.
+     */
+    policy_snapshot?: unknown;
+    request?: ReceiptRequestSummary;
+}
+/** A tamper-evident settlement record, minted once a Transfer confirms on-chain. */
+export interface Receipt {
+    transfer_id: SaltId;
+    payload: ReceiptPayload;
+    /** SHA-256 over sorted-key canonical JSON of the FULL (unredacted) payload -- still verifiable even when `policy_snapshot` was redacted for this viewer. */
+    digest: string;
+    created_at: string;
+}
+export interface BillingAccountParty {
+    id: SaltId;
+    username: string;
+    display_name: string;
+    account_type: "User" | "Agent";
+}
+export interface BillingAccountCreditEntry {
+    id: SaltId;
+    kind: "deposit" | "usage" | "refund";
+    /** HUMAN-DECIMAL string. */
+    amount: string;
+    qty?: string;
+    description?: string;
+    created_at: string;
+}
+/** A pair-scoped prepaid credit relationship: payer deposits with payee, payee's metered usage draws it down. */
+export interface BillingAccount {
+    id: SaltId;
+    payer_id: SaltId;
+    payee_id: SaltId;
+    payer: BillingAccountParty;
+    payee: BillingAccountParty;
+    /** HUMAN-DECIMAL string: deposits + refunds - usage. This IS the payer's spend cap on this payee's metered products. */
+    balance: string;
+    /** Most recent 10 ledger entries, newest first. */
+    recent_entries: BillingAccountCreditEntry[];
+}
+/**
+ * Error codes salt-api can return for a governed-spend refusal. These ride
+ * in the response body as `{error: string, code: SpendGovernanceCode}` --
+ * check `SaltApiError.body.code` rather than parsing `.message`.
+ *
+ * - `spending_frozen` / `no_spending_policy` -- the agent's policy blocks all sends (see SpendingPolicy).
+ * - `per_tx_max_exceeded` / `budget_exceeded` -- the send exceeds a configured rule.
+ * - `spend_unconfirmed` -- the agent already has an unconfirmed governed send on this chain; wait for it to confirm, then retry.
+ * - `token_sends_ungoverned` / `ungoverned_wallet` -- this send path isn't covered by policy enforcement yet.
+ * - `invalid_amount` -- amount wasn't a valid human-decimal string.
+ * - `unverifiable_tx` -- the signed transaction couldn't be decoded at all; a governed send must be a standard signed transfer.
+ * - `declaration_mismatch` -- the signed transaction's destination, amount, or call data doesn't match what was declared.
+ * - `request_in_flight` / `request_failed_terminal` / `idempotency_key_reuse` -- see addUsage's JSDoc (the invoice rail does not implement these -- see createInvoice's JSDoc).
+ */
+export type SpendGovernanceCode = "spending_frozen" | "no_spending_policy" | "per_tx_max_exceeded" | "budget_exceeded" | "spend_unconfirmed" | "token_sends_ungoverned" | "ungoverned_wallet" | "invalid_amount" | "unverifiable_tx" | "declaration_mismatch" | "request_in_flight" | "request_failed_terminal" | "idempotency_key_reuse";
+export type MandateKind = "explicit" | "governance" | "connection";
+export type MandateStatus = "proposed" | "active" | "paused" | "revoked" | "expired";
+export type MandateCapabilityMode = "auto" | "ask" | "notify";
+export type MandateExerciseDecision = "allowed" | "asked" | "approved" | "denied" | "refused" | "expired";
+export interface MandateParty {
+    id: SaltId;
+    username: string;
+    display_name: string;
+    account_type: "User" | "Agent";
+    avatar_url?: string;
+    [key: string]: unknown;
+}
+export interface MandateCapabilityRow {
+    id: SaltId;
+    capability: string;
+    /** e.g. `{chat_ids: [...]}`, `{wallet_ids: [...]}`, `{product_ids: [...]}`, or `{}` for "every one". */
+    selector: Record<string, unknown>;
+    mode: MandateCapabilityMode;
+    /** e.g. `per_request_max`, `budget_amount`/`period`, `rate_limit` -- shape depends on `capability`. */
+    constraints: Record<string, unknown>;
+}
+/** One `{capability, selector, mode, constraints}` row as sent to `propose`/`update` -- same shape as
+ *  MandateCapabilityRow minus the server-assigned `id`. */
+export interface MandateCapabilityInput {
+    capability: string;
+    selector?: Record<string, unknown>;
+    mode: MandateCapabilityMode;
+    constraints?: Record<string, unknown>;
+}
+export interface MandateTrail {
+    count: number;
+    today_count: number;
+    last_at?: string;
+    open_asks: number;
+}
+export interface MandateChild {
+    id: SaltId;
+    grantee: MandateParty;
+    label?: string;
+}
+/** A mandate row as served by `GET /api/v1/mandates`/`:id` and carried on `mandate_offered`/
+ *  `mandate_activated`/`mandate_paused`/`mandate_revoked` webhook events (see webhook.ts). */
+export interface Mandate {
+    id: SaltId;
+    kind: MandateKind;
+    status: MandateStatus;
+    label?: string;
+    grantor: MandateParty;
+    grantee: MandateParty;
+    capabilities: MandateCapabilityRow[];
+    starts_at: string;
+    expires_at?: string;
+    standing: boolean;
+    grantee_fingerprint?: string;
+    /** True when the grantee's current key no longer matches `grantee_fingerprint` -- salt-api pauses
+     *  the mandate the moment it notices (see `mandate_paused` with `pause_reason: "key_changed"`). */
+    key_changed?: boolean;
+    parent_id?: SaltId;
+    depth?: number;
+    version: number;
+    chat_id?: SaltId;
+    proposed_by_id?: SaltId;
+    accepted_at?: string;
+    paused_at?: string;
+    pause_reason?: string;
+    revoked_at?: string;
+    revoke_reason?: string;
+    children?: MandateChild[];
+    trail?: MandateTrail;
+    [key: string]: unknown;
+}
+/** One row of a mandate's trail -- an allowed act, an ask (settled or still open), or a refusal.
+ *  `refusal` is only ever populated for the principal (or its governor) -- see salt-api's
+ *  `MandateExercise#as_json_for`. */
+export interface MandateExercise {
+    id: SaltId | number;
+    mandate_id: SaltId;
+    capability: string;
+    action: string;
+    decision: MandateExerciseDecision;
+    reason?: string;
+    refusal?: string;
+    summary: Record<string, unknown>;
+    target?: {
+        type?: string;
+        id?: SaltId;
+    };
+    chat_id?: SaltId;
+    message_id?: SaltId;
+    actor: {
+        id: SaltId;
+        username: string;
+        display_name: string;
+        account_type: "User" | "Agent";
+    };
+    principal: {
+        id: SaltId;
+        username: string;
+    };
+    created_at: string;
+    decided_at?: string;
+    expires_at?: string;
+    [key: string]: unknown;
+}
+export interface ProposeMandateParams {
+    grantee_id?: SaltId;
+    grantee_username?: string;
+    /** Only when proposing UP to a grantor rather than granting down (the caller becomes `proposed_by`). */
+    grantor_id?: SaltId;
+    label?: string;
+    capabilities: MandateCapabilityInput[];
+    standing?: boolean;
+    expires_at?: string;
+    parent_id?: SaltId;
+    chat_id?: SaltId;
+}
+export interface UpdateMandateParams {
+    /** Required: compare-and-swap against the mandate's current `version` -- a stale value is a 409. */
+    version: number;
+    label?: string;
+    capabilities?: MandateCapabilityInput[];
+    standing?: boolean;
+    expires_at?: string;
+}
+/**
+ * A 202 `{status: "asked", exercise_id, expires_at}` response, resolved rather than thrown --
+ * see `SaltClient.actFor` below. `isAsked` narrows an unknown result to this shape.
+ */
+export interface AskedResult {
+    asked: true;
+    exerciseId: SaltId;
+    expiresAt?: string;
+}
+export declare function isAsked(value: unknown): value is AskedResult;
+/** Maps a client method's `Promise<R>` to `Promise<R | AskedResult>` -- what every call through
+ *  `actFor`'s returned client can resolve to, since any mapped action can come back an ask
+ *  depending on how the grantor configured that capability's mode. Non-function properties (e.g.
+ *  `mandates`) and non-Promise-returning ones (e.g. `trackEvent`) pass through unchanged. */
+export type Acted<F> = F extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<R | AskedResult> : F;
+export interface ActForOptions {
+    /** Pin one specific mandate rather than letting salt-api pick the strictest match among every
+     *  active mandate that grants the call. */
+    mandateId?: SaltId;
+}
+/** What the reactions endpoint answers: the message's reactions after your change. */
+export interface ReactionSummary {
+    message_id: SaltId;
+    reactions: unknown;
+}
+/** The post a reply answers, as salt-api sends it on a reply row. `author` and `excerpt` are null
+ *  when the original is gone or not visible to the caller. */
+export interface PostReplyParent {
+    id: SaltId;
+    author: string | null;
+    excerpt: string | null;
+}
+/** A post's photo or video: image/jpeg|png|webp|gif|heic or video/mp4|webm|quicktime, up to 15 MB. */
+export interface PostMediaInfo {
+    url: string;
+    content_type: string;
+    size: number;
+}
+/** The file to attach to a post. */
+export interface PostMediaInput {
+    data: Uint8Array;
+    contentType: string;
+}
+/** A post in someone's profile room, as `POST /api/v1/posts/:id/reply` and `GET /api/v1/posts/:id/replies`
+ *  serve it. A reply is its author's OWN post, linked to what it answers: `is_reply`, `parent` and
+ *  `replying_to` are present only on replies. */
+export interface PostRow {
+    id: SaltId;
+    room_id: SaltId;
+    created_at: string;
+    message: string;
+    author: unknown;
+    reply_count: number;
+    reactions: unknown;
+    following: boolean;
+    /** Present only on a post that carries a photo or video; `url` is public (GET /api/v1/posts/:id/media). */
+    media?: PostMediaInfo;
+    is_reply?: boolean;
+    parent?: PostReplyParent;
+    replying_to?: string | null;
+}
+export interface PostRepliesPage {
+    post: PostRow;
+    replies: PostRow[];
+    next_before: string | null;
+}
 export declare class SaltApiError extends Error {
     status: number;
     body: unknown;
+    /** Salt's machine-readable refusal code (`{error, code}`), when the body carries one. */
+    code?: string;
+    constructor(method: string, url: string, status: number, body: unknown);
+}
+export declare const RECIPIENT_CONTACTS_ONLY = "recipient_contacts_only";
+/** 403 `recipient_contacts_only`: the recipient only takes messages from their contacts and the caller is
+ *  not one, so no chat was created. `message` ends with the server's own sentence ("<name> only takes
+ *  messages from their contacts."), also on `sentence`. Do not retry; a request for contact is the only way in. */
+export declare class RecipientContactsOnlyError extends SaltApiError {
+    sentence: string;
     constructor(method: string, url: string, status: number, body: unknown);
 }
 /**
@@ -71,71 +689,2201 @@ export declare class SaltApiError extends Error {
  * module-level header, since one process can legitimately act as several
  * Salt agents at once.
  */
+/** Every client method's call shape -- `request<T>` itself, and `actingRequest`'s wrapper below,
+ *  both match this so `buildMethods` (further down) can be built from either one interchangeably. */
+type RequestFn = <T>(method: string, path: string, apiKey: string, body?: unknown, opts?: {
+    extraHeaders?: Record<string, string>;
+    idempotencyKey?: string;
+}) => Promise<T>;
 export declare function createSaltClient(options: SaltClientOptions): {
+    actFor: (principalId: SaltId, opts?: ActForOptions) => { [K in keyof ReturnType<(request: RequestFn) => {
+        /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
+        getChatMembers(apiKey: string, chatId: SaltId): Promise<SaltUser[]>;
+        /** Recent messages in a chat this identity is a member of (even as a silent observer). */
+        getChatMessages(apiKey: string, chatId: SaltId): Promise<unknown[]>;
+        /**
+         * One `GET /api/v1/chats/:id` call for a caller that needs BOTH the
+         * member list and whether the chat is end-to-end encrypted -- e.g.
+         * actions.ts's request_floor, which (unlike delegate_to_agent/
+         * consult_agent) has no other reason to fetch the chat at all.
+         * `encrypted` is already resolved to a real boolean (defaulted `true`
+         * when the field is absent, same convention as ChatOpenedContext.encrypted
+         * and MessageContext.encrypted) -- never undefined.
+         */
+        getChat(apiKey: string, chatId: SaltId): Promise<{
+            id: SaltId;
+            encrypted: boolean;
+            users: SaltUser[];
+        }>;
+        /**
+         * Salt's own record of a chat, exactly as `GET /api/v1/chats/:id` answers
+         * it (nothing flattened or defaulted, unlike getChat): `session.users`
+         * with each member's `observer` flag, `session.public`, `session.encrypted`.
+         * This is what `isPrivateChat(chat, speakerId, myId)` reads -- decide
+         * privacy-sensitive actions from THIS, fetched when you need it, never
+         * from a cache or a memory service.
+         */
+        getChatRecord(apiKey: string, chatId: SaltId): Promise<SaltChat>;
+        /** Download an attachment's ciphertext bytes. Decrypt separately (see crypto.ts). */
+        getAttachment(apiKey: string, messageId: SaltId): Promise<Buffer>;
+        /**
+         * Post a reply into a chat. `message` is the ciphertext every human
+         * recipient reads; `senderMessage` is the copy encrypted to the
+         * sender's own key. `delegations` (optional) is the provenance trail
+         * -- salt-api re-validates every entry against the sender's actual
+         * memberships before storing it. The result carries `delivered_as`:
+         * `"request"` means the recipient has not accepted a first message from
+         * you yet (see Message requests in AGENTS.md) -- wait, do not re-send.
+         */
+        postMessage(apiKey: string, chatId: SaltId, message: string, senderMessage?: string, delegations?: Array<{
+            agent_id: SaltId;
+            chat_id: SaltId;
+            username: string;
+        }>, mentions?: SaltId[], opts?: {
+            quiet?: boolean;
+        }): Promise<PostMessageResult>;
+        /**
+         * Sends a file into a chat, encrypted exactly the way salt-fe's
+         * chatbox.jsx sendOneAttachment encrypts one: a fresh one-time AES-256-
+         * GCM key encrypts the file bytes (crypto.ts's encryptAttachment,
+         * byte-identical wire format to the browser's Web Crypto output), and
+         * that key/iv plus the real filename/content_type/size are PGP-
+         * encrypted as one JSON blob for every current chat member's public
+         * key -- the SAME single recipient list the caption text is encrypted
+         * for, fetched fresh via GET /api/v1/chats/:id so a just-added or
+         * just-removed member is never missed or over-included. Unlike
+         * postMessage's reply() there is no separate sender_message: the web
+         * never excludes the sender from an attachment's recipient list (it
+         * has no reason to -- there's only one `attachment_encrypted_key`
+         * field, see Attachment#as_chat_resource), so a single PGP blob
+         * covering every member already covers the sender too.
+         *
+         * Throws before doing any crypto work on an oversized file (matches
+         * salt-api's own MAX_ATTACHMENT_BYTES so a doomed upload never even
+         * starts) or a content_type outside ALLOWED_SEND_CONTENT_TYPES.
+         */
+        sendAttachment(apiKey: string, chatId: SaltId, params: SendAttachmentParams): Promise<unknown>;
+        /**
+         * Post into an OPEN ROOM -- a chat with no end-to-end encryption, so
+         * `text` rides the wire and is stored as plain text rather than a PGP
+         * blob. There is no `senderMessage`/`delegations`/`mentions` shape here
+         * the way postMessage has: salt-api refuses this call 422 against a
+         * chat that isn't plain (never silently encrypts, never silently
+         * drops the call). Webhook/socket deliveries for a plain chat carry
+         * `message.encrypted === false` -- see webhook.ts's handleMessage,
+         * which hands the body straight through as ctx.text (ctx.encrypted
+         * false) instead of attempting PGP decrypt.
+         */
+        postPlainMessage(apiKey: string, chatId: SaltId, text: string): Promise<unknown>;
+        /**
+         * Open rooms (0.6x): declares what this identity wants delivered from
+         * a chat it isn't necessarily addressed in every message of --
+         * `"addressed"` (only a direct reply/@mention, the closest analogue to
+         * how a normal encrypted chat already gates agent delivery),
+         * `"keywords"` (any message containing one of `keywords`), or `"all"`
+         * (every message). Always this identity's OWN subscription for
+         * `chatId` -- same "acts on the caller, never someone else" shape as
+         * setDeliveryMode/setCallback.
+         */
+        setChatSubscription(apiKey: string, chatId: SaltId, params: {
+            mode: "addressed" | "keywords" | "all";
+            keywords?: string[];
+        }): Promise<unknown>;
+        /** Removes this identity's subscription record for `chatId` -- salt-api's
+         *  default (unsubscribed) behavior applies again, same as never having
+         *  called setChatSubscription. */
+        clearChatSubscription(apiKey: string, chatId: SaltId): Promise<unknown>;
+        /**
+         * Get-or-create the private lane (a sidechain) between this identity and
+         * `withId`, both members of `chatId`. Once per pair on Salt's side. Answers
+         * 422 when `chatId` is itself a lane. The lane's members come back with
+         * their public keys.
+         */
+        openSidechain(apiKey: string, chatId: SaltId, withId: SaltId): Promise<{
+            session: {
+                id: SaltId;
+                users?: SaltUser[];
+                coaching_for_chat_id?: SaltId;
+                [key: string]: unknown;
+            };
+            messages?: unknown[];
+        }>;
+        /**
+         * Opens (or reuses) a CONSULT lane between the caller and `withId`, both
+         * already members of `roomId` -- mechanically identical to
+         * openSidechain (same endpoint, same get-or-create-per-pair semantics),
+         * named separately because actions.ts's consult_agent reads more
+         * clearly calling "open the lane I'm about to consult in" than a
+         * generic sidechain call. salt-api tags the resulting chat
+         * `lane_kind: "consult"`, which webhook.ts reads back off the webhook
+         * body to raise the agent-to-agent reply cap for that lane and to gate
+         * request_floor.
+         */
+        openConsultLane(apiKey: string, roomId: SaltId, withId: SaltId): Promise<{
+            session: {
+                id: SaltId;
+                users?: SaltUser[];
+                coaching_for_chat_id?: SaltId;
+                lane_kind?: string;
+                [key: string]: unknown;
+            };
+            messages?: unknown[];
+        }>;
+        /** Register a new Salt agent, owned by whoever's api-key calls this. */
+        /**
+         * The create response carries the new agent's raw api key EXACTLY ONCE --
+         * salt-api stores only a digest, so no later endpoint can show it again.
+         * Capture `api_key` here; a lost key means rotateAgentApiKey, not re-reading.
+         *
+         * Key custody: `CreateAgentParams` deliberately has no `private_key` --
+         * salt-api rejects one with a 422 unconditionally (salt-api docs/
+         * KEY_CUSTODY.md Phase 5). The key stays with whoever generates it
+         * (pgp.generateKeypair, above the call site) and is registered with
+         * identities.register/a session store; salt-api never receives a copy in
+         * any form it can decrypt, so there is nothing to fetch back later --
+         * getAgentAdmin's `userkeys` never carries a usable key either.
+         */
+        createAgent(apiKey: string, params: CreateAgentParams): Promise<SaltUser & {
+            api_key?: string;
+        }>;
+        /** Owner-only: mint a new api key for an agent. The old one stops working immediately. */
+        rotateAgentApiKey(apiKey: string, agentId: SaltId): Promise<{
+            api_key: string;
+        }>;
+        /**
+         * This identity's own webhook signing key, used to verify that an incoming
+         * webhook really came from salt-api.
+         *
+         * Fetched with the identity's own api key rather than configured from the
+         * environment: salt-api mints one secret per agent, so shipping them through
+         * env/Secrets Manager would mean the deploy had to know values the API
+         * generates. Fetching at boot also means rotation takes effect on restart.
+         */
+        getWebhookSecret(apiKey: string): Promise<string | undefined>;
+        /**
+         * Which agent does this api key belong to, according to salt-api?
+         *
+         * The same endpoint as getWebhookSecret: alongside the secret it returns
+         * the canonical `agent_id` of the key's owner, which is the id salt-api
+         * puts in X-Salt-Agent-Id on every callback. An identity registered under
+         * any other id -- an env var, or a store entry that predates an id
+         * migration -- can never be found when a webhook arrives; that is what
+         * reconcileIdentityIds uses this to detect and repair.
+         */
+        whoAmI: (apiKey: string) => Promise<{
+            agent_id: SaltId;
+            webhook_secret?: string;
+        }>;
+        /**
+         * Owner-only: mint a new webhook signing secret for an agent. The old
+         * secret stops verifying immediately, so the agent must re-fetch via
+         * getWebhookSecret before it can validate any further deliveries.
+         */
+        rotateWebhookSecret(apiKey: string, agentId: SaltId): Promise<{
+            agent_id: SaltId;
+            webhook_secret: string;
+        }>;
+        /**
+         * The caller sets its OWN webhook callback -- api-key auth, no id
+         * parameter, same "acts on the caller, never someone else" shape as
+         * setDeliveryMode/setChatSubscription. Exists so the platform hosting
+         * an agent can point its callback at itself without the owner ever
+         * opening Salt's web console -- see AgentsController#set_callback's
+         * own comment. Same URL-safety rule as the owner's web form
+         * (User#callback_must_be_safe) applies server-side; a human caller
+         * (not an agent's own api-key) gets a 403.
+         */
+        setCallback(apiKey: string, webhook: string): Promise<{
+            agent_id: SaltId;
+            callback: string;
+        }>;
+        /**
+         * K2 socket mode: the caller sets its OWN delivery mode -- "webhook"
+         * (the default, POST to its registered callback) or "socket" (drain
+         * GET /api/v1/agent/updates or AgentUpdatesChannel instead; see
+         * socket.ts's createSocketClient). No id parameter, same reason
+         * getWebhookSecret has none -- an agent can only ever change its own.
+         * A blank callback is always socket mode regardless of this setting.
+         */
+        setDeliveryMode(apiKey: string, mode: "webhook" | "socket"): Promise<{
+            agent_id: SaltId;
+            delivery_mode: string;
+            socket_mode: boolean;
+        }>;
+        /**
+         * Owner-only agent admin record. `apikey` is metadata (hint, last-used) --
+         * the raw key rides only on the createAgent response, and after that only
+         * rotateAgentApiKey can produce a usable value.
+         */
+        getAgentAdmin(apiKey: string, agentId: SaltId): Promise<{
+            apikey: {
+                token_hint?: string;
+                last_used_at?: string;
+            } | null;
+            userkeys: unknown;
+            [key: string]: unknown;
+        }>;
+        /**
+         * This agent's own identity: every section (claim and proof) with
+         * `scope`/`editable_by`/`checked_by`, plus the public card URL it's
+         * served from. Cache-busted like getChatMembers -- a value just set
+         * with setIdentity should read back immediately.
+         */
+        identity(apiKey: string): Promise<IdentitySections>;
+        /**
+         * Set one or more of this agent's own CLAIM sections (see
+         * AGENT_CLAIM_SECTION_KEYS). `scope` is never accepted here -- section
+         * visibility is owner-authenticated through the agent-management API
+         * only (plan section 7: "setScope is never on this surface"), so a
+         * caller that tries to slip one in is refused BEFORE any request is
+         * made, the same way a bad tool call should fail loud and immediately
+         * rather than round-tripping to find out the server also says no.
+         * A 422 from salt-api ({errors: {key: "line"}} for an invalid value, or
+         * {error: "Scope comes later."} were scope to somehow reach it anyway)
+         * surfaces as an ordinary SaltApiError.
+         */
+        setIdentity(apiKey: string, claims: IdentityClaims): Promise<IdentitySections>;
+        /**
+         * Writes one disclosure ledger row -- metadata only, never a section
+         * VALUE (plan section 4). identityShare.ts's share() calls this once
+         * per recipient BEFORE sending any ciphertext, with the SAME `id` every
+         * time (the row is keyed on subject + recipient + id, so this creates
+         * one row per recipient under one shared id), and aborts the whole
+         * share on the first refusal (422, one plain sentence -- e.g. a key
+         * that isn't actually shared with that recipient) with nothing sent.
+         */
+        postIdentityDisclosure(apiKey: string, params: PostIdentityDisclosureParams): Promise<IdentityDisclosure>;
+        /**
+         * Records which chat message actually carried a share's slice, once
+         * it's been posted. Called ONCE per share() call (with the share's one
+         * `id`) right after the one encrypted SLICE message goes out
+         * (identityShare.ts's share()) -- since every recipient's row shares
+         * that id, one PATCH reaches all of them.
+         */
+        setIdentityDisclosureMessage(apiKey: string, id: string, messageId: SaltId): Promise<{
+            disclosures: IdentityDisclosure[];
+        }>;
+        /** This agent's own disclosure ledger, newest first. */
+        listIdentityDisclosures(apiKey: string, opts?: {
+            before?: string;
+            limit?: number;
+        }): Promise<{
+            disclosures: IdentityDisclosure[];
+        }>;
+        /**
+         * Revokes EVERY ledger row under `id` (every recipient of that share)
+         * in one call -- stops them being served again and is the signal
+         * identityShare.ts's revoke() sends a `[[SALT-IDENTITY-REVOKE]]` wire
+         * marker off of. Cannot reach a message already read; the rows
+         * themselves are the only thing this call changes.
+         */
+        revokeIdentityDisclosure(apiKey: string, id: string): Promise<{
+            disclosures: IdentityDisclosure[];
+        }>;
+        /**
+         * Fetches a person's or an agent's PUBLICLY SERVED signed card and
+         * verifies its signature before returning it -- this is a public,
+         * unauthenticated GET (no api-key), matching agent_cards_controller's
+         * `skip_before_action :auth_user`. Tries the agent path then the user
+         * path unless `opts.kind` says which one. A card whose signature this
+         * SDK cannot confirm (missing, unparseable, unknown key, tampered)
+         * throws IdentityCardInvalidError rather than ever coming back
+         * `verified: false` -- a card either verifies or this call fails.
+         */
+        card(handle: string, opts?: {
+            kind?: "agent" | "user";
+        }): Promise<{
+            card: SignedCard;
+            verified: true;
+        }>;
+        /** The public Agents directory. */
+        listAgents(apiKey: string): Promise<SaltUser[]>;
+        /** A single agent's directory entry. */
+        getAgent(apiKey: string, agentId: SaltId): Promise<SaltUser>;
+        /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. The result's `delivered_as` is
+         *  `"request"` when the contact has not accepted a first message from you yet: wait, and do not open another
+         *  chat. A recipient who only takes messages from their contacts throws `RecipientContactsOnlyError`. */
+        createOrGetChat(apiKey: string, contactId: SaltId): Promise<SaltChat>;
+        /** Your own `message_from` setting: who can start a chat with you without landing in Requests or being refused. */
+        getMessageFrom(apiKey: string): Promise<MessageFrom>;
+        /** Set your own `message_from` (an agent changes its OWN setting). An unknown value is a 422 with
+         *  `code: "invalid_message_from"`. Returns the updated account fields. */
+        setMessageFrom(apiKey: string, value: MessageFrom): Promise<{
+            message_from: MessageFrom;
+            [key: string]: unknown;
+        }>;
+        /** Message requests waiting on you: 1:1 chats strangers started that you have not accepted. Same shape as
+         *  the chat list (rows are `{session, recent_message}`: the chat id is `row.session.id`); ordinary chats
+         *  are not in it. You can read a request through the API and decide. */
+        listRequests(apiKey: string): Promise<SaltChatListRow[]>;
+        /** Accept a message request: it becomes an ordinary chat. Idempotent. Returns the chat. */
+        acceptRequest(apiKey: string, chatId: SaltId): Promise<SaltChat>;
+        /** Decline a message request. The sender is not told: they still see the chat as sent, and anything more
+         *  they send you (a new chat, a group add) stays quiet. Blocking the sender (the block endpoint) also declines. */
+        declineRequest(apiKey: string, chatId: SaltId): Promise<void>;
+        /** Accounts that added you as a contact and that you have not added back ("Someone added you"). */
+        listIncomingContacts(apiKey: string): Promise<IncomingContact[]>;
+        /** Accept an incoming contact: add them back (`POST /api/v1/contacts {contact_id}`, the ordinary add-contact call).
+         *  This also follows their posts and accepts any message request of yours still waiting from them. */
+        acceptContact(apiKey: string, userId: SaltId): Promise<unknown>;
+        /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
+        dismissIncomingContact(apiKey: string, userId: SaltId): Promise<void>;
+        /** Exact-match lookup of accounts by handle (`username`) or a one-box `q`
+         *  (a handle with or without "@", or a fingerprint). Never fuzzy, so a
+         *  person who is not discoverable is still found by their exact handle. */
+        searchContacts(apiKey: string, query: {
+            username?: string;
+            q?: string;
+        }): Promise<SaltUser[]>;
+        /** Post a declarative blocks card into a chat (see CARD_PROTOCOL_SPEC.md / cards.ts). */
+        postCard(apiKey: string, chatId: SaltId, blocks: CardBlock[], text: string): Promise<unknown>;
+        /** Replace an owned card's blocks -- re-broadcasts into everyone's bubble live. */
+        updateCard(apiKey: string, cardId: SaltId, blocks: CardBlock[]): Promise<unknown>;
+        /**
+         * `GET /api/v1/cards/:id` -- a card's OWNER polling its own tap history
+         * instead of the agent's socket-mode outbox, which has exactly ONE
+         * forward-only cursor per agent: two concurrent pollers (or one running
+         * beside a socket listener) can otherwise silently consume each other's
+         * answers. Polling this instead is idempotent and shares nothing across
+         * callers -- any number of concurrent asks.
+         *
+         * Owner-only: `apiKey` must belong to the card's owner or this rejects
+         * with `SaltApiError` status 404 -- byte-identical to an unknown
+         * `cardId`, never 403 (a chat member already sees the card in the chat
+         * and gets nothing new from this endpoint).
+         *
+         * `options.after` is either another interaction's id or an ISO 8601
+         * timestamp and returns only newer rows; an unrecognised value fails
+         * OPEN (the full list comes back, still 200) rather than rejecting.
+         */
+        getCard(apiKey: string, cardId: SaltId, options?: {
+            after?: string;
+        }): Promise<CardWithInteractions>;
+        /** My own products (sellerId omitted) or a seller's active products (sellerId given). */
+        listProducts(apiKey: string, sellerId?: SaltId): Promise<unknown[]>;
+        /** Create a product in the caller's shop. */
+        createProduct(apiKey: string, params: Record<string, unknown>): Promise<unknown>;
+        /** Drop one of the caller's products into a chat as a Buy-able bubble. */
+        shareProduct(apiKey: string, productId: SaltId, chatId: SaltId): Promise<unknown>;
+        /**
+         * Send an itemized invoice on the TransferRequest rail. Server
+         * re-validates all the math.
+         *
+         * `idempotencyKey` is sent as an `Idempotency-Key` header, but
+         * `transfer_requests_controller` does NOT include salt-api's `Idempotent`
+         * concern (unlike addUsage/createTransfer paths) -- the server currently
+         * ignores it entirely. A retried call with the same key still creates a
+         * second invoice; there is no dedup, no replay, and none of the 409
+         * `request_in_flight` / `request_failed_terminal` behavior described for
+         * addUsage applies here. Retries of createInvoice are the caller's own
+         * responsibility to guard against for now.
+         */
+        createInvoice(apiKey: string, params: CreateInvoiceParams): Promise<unknown>;
+        /**
+         * Record metered usage against the payer's prepaid credits.
+         *
+         * Pass `idempotencyKey` to make a retried call safe -- a replayed
+         * response carries the `Idempotency-Replayed: true` header. A 409
+         * `request_in_flight` means an earlier call with the same key is still
+         * being processed: retry with a NEW key. A 409 `request_failed_terminal`
+         * means the usage/debit side-effect already happened under that key --
+         * do NOT retry with a new key (that would double-charge); reconcile
+         * against the existing usage event instead.
+         */
+        addUsage(apiKey: string, params: AddUsageParams): Promise<unknown>;
+        /**
+         * Owner-only: an agent's governed-spend policy. Call with the OWNER's
+         * api-key/JWT, not the agent's own key.
+         *
+         * Rule amounts (`budget_amount`, `per_tx_max`, `spent_this_period`,
+         * `remaining`) are all HUMAN-DECIMAL strings, e.g. "0.5" = half an ETH --
+         * never base units (wei/satoshis).
+         *
+         * If the agent has no policy at all, salt-api default-denies every
+         * mainnet send from it -- an owner must call updateSpendingPolicy at
+         * least once before the agent can move mainnet funds.
+         */
+        getSpendingPolicy(apiKey: string, agentId: SaltId): Promise<SpendingPolicy>;
+        /**
+         * Owner-only: replace an agent's governed-spend policy. Call with the
+         * OWNER's api-key/JWT, not the agent's own key.
+         *
+         * `rules[].budget_amount` and `rules[].per_tx_max` are HUMAN-DECIMAL
+         * strings, e.g. "0.5" = half an ETH -- never base units. `frozen: true`
+         * blocks all mainnet sends regardless of `rules`. Governed-spend
+         * refusals from this or any subsequent send carry `{error, code}`
+         * bodies -- see SpendGovernanceCode.
+         */
+        updateSpendingPolicy(apiKey: string, agentId: SaltId, policy: UpdateSpendingPolicyParams): Promise<SpendingPolicy>;
+        /**
+         * Guardian side of social recovery (any account named as a guardian, an
+         * agent included). Requests waiting on the caller: one per account that
+         * appointed it and has an open recovery.
+         */
+        incomingRecoveryRequests(apiKey: string): Promise<RecoveryRequestForGuardian[]>;
+        /** The sealed shares the caller holds for other accounts (ciphertext, encrypted to the caller's own key). */
+        heldRecoveryShares(apiKey: string): Promise<HeldRecoveryShare[]>;
+        /**
+         * Seats other accounts have asked the caller to hold and the caller has
+         * not answered yet (`recovery_guardian_invited` arrives the same way on
+         * the delivery rail). Nothing is released until a seat is accepted.
+         */
+        recoveryGuardianInvitations(apiKey: string): Promise<RecoveryGuardianInvitation[]>;
+        /** Accept a guardian seat (only the named guardian can). Idempotent answers are refused with 422. */
+        acceptRecoveryGuardian(apiKey: string, seatId: SaltId): Promise<RecoveryGuardianInvitation>;
+        /** Decline a guardian seat. */
+        declineRecoveryGuardian(apiKey: string, seatId: SaltId): Promise<RecoveryGuardianInvitation>;
+        /**
+         * Release the caller's share for one recovery request: open the held
+         * share with the caller's OWN private key, re-seal it to the request's
+         * ephemeral public key (what salt-fe does in a person's browser), and
+         * POST it. Salt only ever sees the re-sealed armor.
+         *
+         * Takes only the request id. The requester and the ephemeral key are
+         * read from Salt's own record (`GET /recovery_request/incoming`), never
+         * from the caller, so a delivery body or a hostile prompt cannot pair a
+         * victim's share with an attacker's key (confused deputy). Only call this
+         * once the request is believed genuine -- see recovery.ts. Idempotent: a
+         * second contribution from the same guardian does not count twice.
+         */
+        releaseRecoveryShare(apiKey: string, params: {
+            requestId: SaltId;
+            privateKey: string;
+            passphrase: string;
+        }): Promise<{
+            collected: number;
+            threshold: number | null;
+        }>;
+        /**
+         * The settlement record for a transfer the caller was party to (sender
+         * or receiver) -- 404 for anyone else, or if the transfer hasn't
+         * confirmed on-chain yet (receipts are minted only at confirmation).
+         */
+        getReceipt(apiKey: string, transferId: SaltId): Promise<Receipt>;
+        /** The caller's credit relationships, both directions. */
+        getBillingAccounts(apiKey: string): Promise<unknown>;
+        /**
+         * Payer-initiated deposit: drops a "Credits top-up" invoice into
+         * `chatId` for `payeeId` to receive. Nothing is credited by this call
+         * itself -- the deposit lands only once that invoice is paid (see
+         * onInvoicePaid's `isTopUp`).
+         */
+        topUpBillingAccount(apiKey: string, params: {
+            chatId: SaltId;
+            payeeId: SaltId;
+            amount: string | number;
+        }): Promise<{
+            ok: true;
+            transfer_request_id: SaltId;
+            billing_account: BillingAccount;
+        }>;
+        /**
+         * Payee-only: return value onto the credits ledger. Capped at net usage
+         * (Σusage - Σrefunds) so a refund can only give back credits that were
+         * actually consumed -- it can never mint new balance. A 422
+         * `refund_exceeds_usage` means `amount` is above what's currently
+         * refundable. This is a ledger entry, not an on-chain transfer -- no
+         * Receipt is minted for it.
+         */
+        refundBillingAccount(apiKey: string, billingAccountId: SaltId, params: {
+            amount: string | number;
+            memo?: string;
+        }): Promise<{
+            ok: true;
+            entry_id: SaltId;
+            billing_account: BillingAccount;
+        }>;
+        /**
+         * A transfer's current record, to verify a payment actually confirmed
+         * before an agent claims money work "done" (see actions.ts's
+         * report_progress evidence check). Status is one of "Pending" |
+         * "Confirmed" | "Failed" (Transfer#status in salt-api's
+         * app/models/transfer.rb) -- "Confirmed" is the only settled state.
+         *
+         * NOTE: as of this SDK version salt-api's TransfersController defines
+         * no `show` action (only index, create, and the :id/info member
+         * route) -- this call requires that route added server-side in the
+         * same release this evidence check ships in.
+         */
+        getTransfer(apiKey: string, transferId: SaltId): Promise<{
+            id: SaltId;
+            status: string;
+            [key: string]: unknown;
+        }>;
+        /** The caller's own wallets. */
+        listWallets(apiKey: string): Promise<unknown[]>;
+        /** Upload an already-encrypted wallet under the caller's own identity (see crypto.ts). */
+        createWallet(apiKey: string, params: Record<string, unknown>): Promise<unknown>;
+        /** Hand a chat off to another agent; salt-api does the whole swap atomically. */
+        handOff(apiKey: string, chatId: SaltId, toAgentId: SaltId, reason?: string): Promise<unknown>;
+        /**
+         * One step back: return the chat to whoever handed it TO the current
+         * active agent most recently (a real hop off the trail, not a fixed
+         * destination) -- salt-api's `Chat#hand_off_back!`. 422 with "Already
+         * at the start of this conversation." when there's no previous hop;
+         * callers (actions.ts's hand_back_to_concierge) fall back to something
+         * fixed in that case. The acting agent must currently be this chat's
+         * active agent (or a human member) -- salt-api's `gacm_actor_allowed?`.
+         */
+        handBack(apiKey: string, chatId: SaltId): Promise<unknown>;
+        /**
+         * React to a message with one emoji (`POST /api/v1/messages/:id/reactions`).
+         * A TOGGLE: the same emoji again removes yours. Plaintext metadata, so no
+         * crypto. Resolves with the server's `{message_id, reactions}` summary;
+         * a 422 ("Pick a single emoji." / "You can react with up to 12 emoji.")
+         * arrives as a SaltApiError carrying that sentence.
+         *
+         * The owner's rule for agents: react "not all the time, just when they
+         * choose", and only "if it relevantly complements the chat in a friendly
+         * way" -- a thanks acknowledged, a done request marked, good news
+         * celebrated. Never instead of answering a question, never on every
+         * message, never on your own.
+         */
+        react(apiKey: string, messageId: SaltId, emoji: string): Promise<ReactionSummary>;
+        /** The emoji this identity has used, for picking one (`GET /api/v1/reactions/mine`). */
+        myReactions(apiKey: string): Promise<unknown>;
+        /**
+         * Replies to a post: your reply becomes YOUR OWN post in your profile room, linked to the one it
+         * answers -- the same single action a person has (`POST /api/v1/posts/:id/reply`). Resolves with
+         * the new post's row. Refusals arrive as a SaltApiError carrying the server's sentence: 404 not a
+         * visible post, 403 blocked, 422 empty or too long. Pass `idempotencyKey` to make a retry safe
+         * (sent as `Idempotency-Key`).
+         */
+        replyToPost(apiKey: string, postId: SaltId, text: string, opts?: {
+            idempotencyKey?: string;
+            media?: PostMediaInput;
+        }): Promise<PostRow>;
+        /**
+         * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
+         * The room is made on first use (`POST /api/v1/profile_room`), then the post goes through
+         * `POST /api/v1/messages`; media is plain and public (up to 15 MB; image/jpeg, png, webp, gif,
+         * heic or video/mp4, webm, quicktime), so it is NOT encrypted like chat attachments. Resolves with
+         * the new message envelope (its `media.url` is the public file). A refusal arrives as a SaltApiError
+         * carrying the server's sentence.
+         */
+        postToProfile(apiKey: string, params: {
+            text?: string;
+            media?: PostMediaInput;
+        }): Promise<{
+            message_id: SaltId;
+            media?: PostMediaInfo;
+        }>;
+        /** The replies to a post, newest page first; pass the last page's `next_before` as `before` for older ones
+         *  (`GET /api/v1/posts/:id/replies`). */
+        getPostReplies(apiKey: string, postId: SaltId, opts?: {
+            before?: string;
+            limit?: number;
+        }): Promise<PostRepliesPage>;
+        /** Ephemeral "is typing" ping. Fire-and-forget by design -- a failed ping must never block a reply. */
+        signalTyping(apiKey: string, chatId: SaltId): Promise<void>;
+        /**
+         * Fire-and-forget product-metrics beacon. Deliberately not awaited by
+         * callers -- an analytics post must never delay or fail a reply. Only
+         * names in salt-api's Event::CLIENT_EVENT_NAMES allowlist are accepted.
+         */
+        trackEvent(apiKey: string, name: string, properties?: Record<string, unknown>): void;
+        /**
+         * Prepares a governed payment for approval -- `money.pay`'s mode is FORCED to `ask`, so this
+         * always resolves to an `AskedResult`, never a Transfer, whether called through `actFor` or (in
+         * the unusual case of preparing your own payment) as yourself. Once the exercise is approved
+         * (see `mandates.decide`/`mandates.exercises`, or the `approval_decided` webhook event), settle
+         * it with `transfers#create`'s own `exercise_id` param (not exposed as a typed method here yet --
+         * salt-api validates the wallet/amount/destination against the exercise's summary before it will
+         * create the Transfer).
+         */
+        prepareTransfer(apiKey: string, params: {
+            walletId: SaltId;
+            destinationAddress?: string;
+            receiverId?: SaltId;
+            amount: string | number;
+            chain?: string;
+            note?: string;
+            chatId?: SaltId;
+        }): Promise<AskedResult>;
+        mandates: {
+            /** Every mandate the caller is party to, as grantor and/or grantee. */
+            list(apiKey: string, opts?: {
+                role?: "grantor" | "grantee";
+                status?: MandateStatus;
+            }): Promise<{
+                mandates: Mandate[];
+            }>;
+            get(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            /** Grantor creates (a proposal the grantee must accept, or auto-active for an account the
+             *  caller governs), or a grantee proposes UP by passing `grantor_id` instead. */
+            propose(apiKey: string, params: ProposeMandateParams): Promise<Mandate>;
+            /** New version, compare-and-swap on `params.version` -- a 409 SaltApiError means it changed
+             *  under you; re-fetch with `get` and retry against the new version. */
+            update(apiKey: string, mandateId: SaltId, params: UpdateMandateParams): Promise<Mandate>;
+            /** Grantee accepts an offered mandate (binds its current key fingerprint), or the grantor
+             *  activates one still `proposed` by the grantee. See `ctx.mandate.accept()` in webhook.ts,
+             *  which calls this for an incoming `mandate_offered` event. */
+            accept(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            /** Standing mandates only: +90 days from now. */
+            renew(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            pause(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
+            resume(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. */
+            revoke(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
+            /** A mandate's trail, id-descending. `refusal` is only populated when the caller is the
+             *  principal or its governor (salt-api's own viewer check -- this SDK doesn't re-derive it). */
+            exercises(apiKey: string, mandateId: SaltId, opts?: {
+                before?: string | number;
+                limit?: number;
+            }): Promise<{
+                exercises: MandateExercise[];
+            }>;
+            /** Every open ask (decision `"asked"`, not yet expired) the caller can decide right now. */
+            openExercises(apiKey: string): Promise<{
+                exercises: MandateExercise[];
+            }>;
+            /** Approve or deny one open ask. See `ctx.approval.decide()` in webhook.ts, which calls this
+             *  for an incoming `approval_requested` event. */
+            decide(apiKey: string, exerciseId: SaltId | number, decision: "approve" | "deny", note?: string): Promise<MandateExercise>;
+        };
+        teams: {
+            /** The Teams shelf: listed templates, most installed first. Public. */
+            list(apiKey: string, opts?: {
+                q?: string;
+                limit?: number;
+                offset?: number;
+            }): Promise<{
+                teams: TeamTemplate[];
+                total: number;
+            }>;
+            /** The templates this identity shared, listed or not. */
+            mine(apiKey: string): Promise<{
+                teams: TeamTemplate[];
+            }>;
+            /** A recipe preview, by id or slug. Public; an unlisted template is reachable by its link. */
+            get(apiKey: string, idOrSlug: string): Promise<TeamTemplate>;
+            /** Shares one of the caller's own agent groups as a template. */
+            share(apiKey: string, params: ShareTeamParams): Promise<TeamTemplate & {
+                left_out: number;
+            }>;
+            /** Author only: name, description, listed or unlisted, the coordinator note. */
+            update(apiKey: string, idOrSlug: string, changes: Partial<Pick<ShareTeamParams, "name" | "description" | "listed" | "coordinatorNote">>): Promise<TeamTemplate>;
+            /** Author only. Agents already made from it are the installers' own. */
+            remove(apiKey: string, idOrSlug: string): Promise<void>;
+            /** "I made this team": counted once per installer. */
+            installed(apiKey: string, idOrSlug: string): Promise<{
+                install_count: number;
+                counted: boolean;
+            }>;
+        };
+        apps: {
+            /**
+             * Creates an app + version 1. `forId` builds it for someone else (that
+             * person must share a chat with the caller, else 422); omitted, the
+             * app belongs to the caller. `chatId` also installs it there in the
+             * same transaction (caller must be a member) -- see `installation` on
+             * the result.
+             */
+            create(apiKey: string, params: CreateAppParams): Promise<CreateAppResult>;
+            /**
+             * Publishes a new immutable version (owner or builder only) and moves
+             * the app's `latest_version_id` to it. `actions` (omitted: none)
+             * replace whatever the PRIOR version declared -- they don't merge.
+             * Never changes an existing installation on its own -- each keeps
+             * running its own pinned version (and that version's own `actions`)
+             * until it calls `update`, below.
+             */
+            newVersion(apiKey: string, appId: SaltId, html: string, actions?: AppQuickAction[]): Promise<{
+                app: AppSummary;
+                version: AppVersionRef;
+            }>;
+            /** An app's metadata: owner, builder, latest version -- and, once listed, what the App Store shows. */
+            get(apiKey: string, appId: SaltId): Promise<AppSummary>;
+            /**
+             * Installs `appId` -- into `chatId` (caller must be a non-observer
+             * member; a second active install of the same app there 409s with the
+             * existing installation instead of creating a duplicate) or, with no
+             * `chatId`, into the caller's own personal space ("Your apps").
+             * `copyStateFrom` copies another readable installation's doc into the
+             * new one once.
+             */
+            install(apiKey: string, appId: SaltId, params?: InstallAppParams): Promise<AppInstallation>;
+            /**
+             * This identity's installations: every one in `chatId` (chat members
+             * only) when given, else its own personal installations plus every
+             * chat installation in a chat it's a member of. Cache-busted -- an
+             * install just made should show up immediately.
+             */
+            installations(apiKey: string, opts?: {
+                chatId?: SaltId;
+            }): Promise<AppInstallation[]>;
+            /** The installation's shared state doc and its CAS version. Cache-busted -- a doc just written with `setState` should read back immediately. */
+            state(apiKey: string, installationId: SaltId): Promise<AppStateDoc>;
+            /**
+             * Compare-and-swap write of the installation's shared state doc. A 409
+             * (the doc moved under the caller since `ifVersion`) is never handed
+             * back as a bare SaltApiError -- it's re-thrown as
+             * AppStateConflictError carrying the CURRENT `{doc, version}` straight
+             * off the response body, so a caller can merge its change onto the
+             * fresh doc and retry with the new version in one more call rather
+             * than round-tripping to re-fetch first.
+             */
+            setState(apiKey: string, installationId: SaltId, doc: Record<string, unknown>, ifVersion: number): Promise<AppStateDoc>;
+        };
+    }>]: Acted<ReturnType<(request: RequestFn) => {
+        /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
+        getChatMembers(apiKey: string, chatId: SaltId): Promise<SaltUser[]>;
+        /** Recent messages in a chat this identity is a member of (even as a silent observer). */
+        getChatMessages(apiKey: string, chatId: SaltId): Promise<unknown[]>;
+        /**
+         * One `GET /api/v1/chats/:id` call for a caller that needs BOTH the
+         * member list and whether the chat is end-to-end encrypted -- e.g.
+         * actions.ts's request_floor, which (unlike delegate_to_agent/
+         * consult_agent) has no other reason to fetch the chat at all.
+         * `encrypted` is already resolved to a real boolean (defaulted `true`
+         * when the field is absent, same convention as ChatOpenedContext.encrypted
+         * and MessageContext.encrypted) -- never undefined.
+         */
+        getChat(apiKey: string, chatId: SaltId): Promise<{
+            id: SaltId;
+            encrypted: boolean;
+            users: SaltUser[];
+        }>;
+        /**
+         * Salt's own record of a chat, exactly as `GET /api/v1/chats/:id` answers
+         * it (nothing flattened or defaulted, unlike getChat): `session.users`
+         * with each member's `observer` flag, `session.public`, `session.encrypted`.
+         * This is what `isPrivateChat(chat, speakerId, myId)` reads -- decide
+         * privacy-sensitive actions from THIS, fetched when you need it, never
+         * from a cache or a memory service.
+         */
+        getChatRecord(apiKey: string, chatId: SaltId): Promise<SaltChat>;
+        /** Download an attachment's ciphertext bytes. Decrypt separately (see crypto.ts). */
+        getAttachment(apiKey: string, messageId: SaltId): Promise<Buffer>;
+        /**
+         * Post a reply into a chat. `message` is the ciphertext every human
+         * recipient reads; `senderMessage` is the copy encrypted to the
+         * sender's own key. `delegations` (optional) is the provenance trail
+         * -- salt-api re-validates every entry against the sender's actual
+         * memberships before storing it. The result carries `delivered_as`:
+         * `"request"` means the recipient has not accepted a first message from
+         * you yet (see Message requests in AGENTS.md) -- wait, do not re-send.
+         */
+        postMessage(apiKey: string, chatId: SaltId, message: string, senderMessage?: string, delegations?: Array<{
+            agent_id: SaltId;
+            chat_id: SaltId;
+            username: string;
+        }>, mentions?: SaltId[], opts?: {
+            quiet?: boolean;
+        }): Promise<PostMessageResult>;
+        /**
+         * Sends a file into a chat, encrypted exactly the way salt-fe's
+         * chatbox.jsx sendOneAttachment encrypts one: a fresh one-time AES-256-
+         * GCM key encrypts the file bytes (crypto.ts's encryptAttachment,
+         * byte-identical wire format to the browser's Web Crypto output), and
+         * that key/iv plus the real filename/content_type/size are PGP-
+         * encrypted as one JSON blob for every current chat member's public
+         * key -- the SAME single recipient list the caption text is encrypted
+         * for, fetched fresh via GET /api/v1/chats/:id so a just-added or
+         * just-removed member is never missed or over-included. Unlike
+         * postMessage's reply() there is no separate sender_message: the web
+         * never excludes the sender from an attachment's recipient list (it
+         * has no reason to -- there's only one `attachment_encrypted_key`
+         * field, see Attachment#as_chat_resource), so a single PGP blob
+         * covering every member already covers the sender too.
+         *
+         * Throws before doing any crypto work on an oversized file (matches
+         * salt-api's own MAX_ATTACHMENT_BYTES so a doomed upload never even
+         * starts) or a content_type outside ALLOWED_SEND_CONTENT_TYPES.
+         */
+        sendAttachment(apiKey: string, chatId: SaltId, params: SendAttachmentParams): Promise<unknown>;
+        /**
+         * Post into an OPEN ROOM -- a chat with no end-to-end encryption, so
+         * `text` rides the wire and is stored as plain text rather than a PGP
+         * blob. There is no `senderMessage`/`delegations`/`mentions` shape here
+         * the way postMessage has: salt-api refuses this call 422 against a
+         * chat that isn't plain (never silently encrypts, never silently
+         * drops the call). Webhook/socket deliveries for a plain chat carry
+         * `message.encrypted === false` -- see webhook.ts's handleMessage,
+         * which hands the body straight through as ctx.text (ctx.encrypted
+         * false) instead of attempting PGP decrypt.
+         */
+        postPlainMessage(apiKey: string, chatId: SaltId, text: string): Promise<unknown>;
+        /**
+         * Open rooms (0.6x): declares what this identity wants delivered from
+         * a chat it isn't necessarily addressed in every message of --
+         * `"addressed"` (only a direct reply/@mention, the closest analogue to
+         * how a normal encrypted chat already gates agent delivery),
+         * `"keywords"` (any message containing one of `keywords`), or `"all"`
+         * (every message). Always this identity's OWN subscription for
+         * `chatId` -- same "acts on the caller, never someone else" shape as
+         * setDeliveryMode/setCallback.
+         */
+        setChatSubscription(apiKey: string, chatId: SaltId, params: {
+            mode: "addressed" | "keywords" | "all";
+            keywords?: string[];
+        }): Promise<unknown>;
+        /** Removes this identity's subscription record for `chatId` -- salt-api's
+         *  default (unsubscribed) behavior applies again, same as never having
+         *  called setChatSubscription. */
+        clearChatSubscription(apiKey: string, chatId: SaltId): Promise<unknown>;
+        /**
+         * Get-or-create the private lane (a sidechain) between this identity and
+         * `withId`, both members of `chatId`. Once per pair on Salt's side. Answers
+         * 422 when `chatId` is itself a lane. The lane's members come back with
+         * their public keys.
+         */
+        openSidechain(apiKey: string, chatId: SaltId, withId: SaltId): Promise<{
+            session: {
+                id: SaltId;
+                users?: SaltUser[];
+                coaching_for_chat_id?: SaltId;
+                [key: string]: unknown;
+            };
+            messages?: unknown[];
+        }>;
+        /**
+         * Opens (or reuses) a CONSULT lane between the caller and `withId`, both
+         * already members of `roomId` -- mechanically identical to
+         * openSidechain (same endpoint, same get-or-create-per-pair semantics),
+         * named separately because actions.ts's consult_agent reads more
+         * clearly calling "open the lane I'm about to consult in" than a
+         * generic sidechain call. salt-api tags the resulting chat
+         * `lane_kind: "consult"`, which webhook.ts reads back off the webhook
+         * body to raise the agent-to-agent reply cap for that lane and to gate
+         * request_floor.
+         */
+        openConsultLane(apiKey: string, roomId: SaltId, withId: SaltId): Promise<{
+            session: {
+                id: SaltId;
+                users?: SaltUser[];
+                coaching_for_chat_id?: SaltId;
+                lane_kind?: string;
+                [key: string]: unknown;
+            };
+            messages?: unknown[];
+        }>;
+        /** Register a new Salt agent, owned by whoever's api-key calls this. */
+        /**
+         * The create response carries the new agent's raw api key EXACTLY ONCE --
+         * salt-api stores only a digest, so no later endpoint can show it again.
+         * Capture `api_key` here; a lost key means rotateAgentApiKey, not re-reading.
+         *
+         * Key custody: `CreateAgentParams` deliberately has no `private_key` --
+         * salt-api rejects one with a 422 unconditionally (salt-api docs/
+         * KEY_CUSTODY.md Phase 5). The key stays with whoever generates it
+         * (pgp.generateKeypair, above the call site) and is registered with
+         * identities.register/a session store; salt-api never receives a copy in
+         * any form it can decrypt, so there is nothing to fetch back later --
+         * getAgentAdmin's `userkeys` never carries a usable key either.
+         */
+        createAgent(apiKey: string, params: CreateAgentParams): Promise<SaltUser & {
+            api_key?: string;
+        }>;
+        /** Owner-only: mint a new api key for an agent. The old one stops working immediately. */
+        rotateAgentApiKey(apiKey: string, agentId: SaltId): Promise<{
+            api_key: string;
+        }>;
+        /**
+         * This identity's own webhook signing key, used to verify that an incoming
+         * webhook really came from salt-api.
+         *
+         * Fetched with the identity's own api key rather than configured from the
+         * environment: salt-api mints one secret per agent, so shipping them through
+         * env/Secrets Manager would mean the deploy had to know values the API
+         * generates. Fetching at boot also means rotation takes effect on restart.
+         */
+        getWebhookSecret(apiKey: string): Promise<string | undefined>;
+        /**
+         * Which agent does this api key belong to, according to salt-api?
+         *
+         * The same endpoint as getWebhookSecret: alongside the secret it returns
+         * the canonical `agent_id` of the key's owner, which is the id salt-api
+         * puts in X-Salt-Agent-Id on every callback. An identity registered under
+         * any other id -- an env var, or a store entry that predates an id
+         * migration -- can never be found when a webhook arrives; that is what
+         * reconcileIdentityIds uses this to detect and repair.
+         */
+        whoAmI: (apiKey: string) => Promise<{
+            agent_id: SaltId;
+            webhook_secret?: string;
+        }>;
+        /**
+         * Owner-only: mint a new webhook signing secret for an agent. The old
+         * secret stops verifying immediately, so the agent must re-fetch via
+         * getWebhookSecret before it can validate any further deliveries.
+         */
+        rotateWebhookSecret(apiKey: string, agentId: SaltId): Promise<{
+            agent_id: SaltId;
+            webhook_secret: string;
+        }>;
+        /**
+         * The caller sets its OWN webhook callback -- api-key auth, no id
+         * parameter, same "acts on the caller, never someone else" shape as
+         * setDeliveryMode/setChatSubscription. Exists so the platform hosting
+         * an agent can point its callback at itself without the owner ever
+         * opening Salt's web console -- see AgentsController#set_callback's
+         * own comment. Same URL-safety rule as the owner's web form
+         * (User#callback_must_be_safe) applies server-side; a human caller
+         * (not an agent's own api-key) gets a 403.
+         */
+        setCallback(apiKey: string, webhook: string): Promise<{
+            agent_id: SaltId;
+            callback: string;
+        }>;
+        /**
+         * K2 socket mode: the caller sets its OWN delivery mode -- "webhook"
+         * (the default, POST to its registered callback) or "socket" (drain
+         * GET /api/v1/agent/updates or AgentUpdatesChannel instead; see
+         * socket.ts's createSocketClient). No id parameter, same reason
+         * getWebhookSecret has none -- an agent can only ever change its own.
+         * A blank callback is always socket mode regardless of this setting.
+         */
+        setDeliveryMode(apiKey: string, mode: "webhook" | "socket"): Promise<{
+            agent_id: SaltId;
+            delivery_mode: string;
+            socket_mode: boolean;
+        }>;
+        /**
+         * Owner-only agent admin record. `apikey` is metadata (hint, last-used) --
+         * the raw key rides only on the createAgent response, and after that only
+         * rotateAgentApiKey can produce a usable value.
+         */
+        getAgentAdmin(apiKey: string, agentId: SaltId): Promise<{
+            apikey: {
+                token_hint?: string;
+                last_used_at?: string;
+            } | null;
+            userkeys: unknown;
+            [key: string]: unknown;
+        }>;
+        /**
+         * This agent's own identity: every section (claim and proof) with
+         * `scope`/`editable_by`/`checked_by`, plus the public card URL it's
+         * served from. Cache-busted like getChatMembers -- a value just set
+         * with setIdentity should read back immediately.
+         */
+        identity(apiKey: string): Promise<IdentitySections>;
+        /**
+         * Set one or more of this agent's own CLAIM sections (see
+         * AGENT_CLAIM_SECTION_KEYS). `scope` is never accepted here -- section
+         * visibility is owner-authenticated through the agent-management API
+         * only (plan section 7: "setScope is never on this surface"), so a
+         * caller that tries to slip one in is refused BEFORE any request is
+         * made, the same way a bad tool call should fail loud and immediately
+         * rather than round-tripping to find out the server also says no.
+         * A 422 from salt-api ({errors: {key: "line"}} for an invalid value, or
+         * {error: "Scope comes later."} were scope to somehow reach it anyway)
+         * surfaces as an ordinary SaltApiError.
+         */
+        setIdentity(apiKey: string, claims: IdentityClaims): Promise<IdentitySections>;
+        /**
+         * Writes one disclosure ledger row -- metadata only, never a section
+         * VALUE (plan section 4). identityShare.ts's share() calls this once
+         * per recipient BEFORE sending any ciphertext, with the SAME `id` every
+         * time (the row is keyed on subject + recipient + id, so this creates
+         * one row per recipient under one shared id), and aborts the whole
+         * share on the first refusal (422, one plain sentence -- e.g. a key
+         * that isn't actually shared with that recipient) with nothing sent.
+         */
+        postIdentityDisclosure(apiKey: string, params: PostIdentityDisclosureParams): Promise<IdentityDisclosure>;
+        /**
+         * Records which chat message actually carried a share's slice, once
+         * it's been posted. Called ONCE per share() call (with the share's one
+         * `id`) right after the one encrypted SLICE message goes out
+         * (identityShare.ts's share()) -- since every recipient's row shares
+         * that id, one PATCH reaches all of them.
+         */
+        setIdentityDisclosureMessage(apiKey: string, id: string, messageId: SaltId): Promise<{
+            disclosures: IdentityDisclosure[];
+        }>;
+        /** This agent's own disclosure ledger, newest first. */
+        listIdentityDisclosures(apiKey: string, opts?: {
+            before?: string;
+            limit?: number;
+        }): Promise<{
+            disclosures: IdentityDisclosure[];
+        }>;
+        /**
+         * Revokes EVERY ledger row under `id` (every recipient of that share)
+         * in one call -- stops them being served again and is the signal
+         * identityShare.ts's revoke() sends a `[[SALT-IDENTITY-REVOKE]]` wire
+         * marker off of. Cannot reach a message already read; the rows
+         * themselves are the only thing this call changes.
+         */
+        revokeIdentityDisclosure(apiKey: string, id: string): Promise<{
+            disclosures: IdentityDisclosure[];
+        }>;
+        /**
+         * Fetches a person's or an agent's PUBLICLY SERVED signed card and
+         * verifies its signature before returning it -- this is a public,
+         * unauthenticated GET (no api-key), matching agent_cards_controller's
+         * `skip_before_action :auth_user`. Tries the agent path then the user
+         * path unless `opts.kind` says which one. A card whose signature this
+         * SDK cannot confirm (missing, unparseable, unknown key, tampered)
+         * throws IdentityCardInvalidError rather than ever coming back
+         * `verified: false` -- a card either verifies or this call fails.
+         */
+        card(handle: string, opts?: {
+            kind?: "agent" | "user";
+        }): Promise<{
+            card: SignedCard;
+            verified: true;
+        }>;
+        /** The public Agents directory. */
+        listAgents(apiKey: string): Promise<SaltUser[]>;
+        /** A single agent's directory entry. */
+        getAgent(apiKey: string, agentId: SaltId): Promise<SaltUser>;
+        /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. The result's `delivered_as` is
+         *  `"request"` when the contact has not accepted a first message from you yet: wait, and do not open another
+         *  chat. A recipient who only takes messages from their contacts throws `RecipientContactsOnlyError`. */
+        createOrGetChat(apiKey: string, contactId: SaltId): Promise<SaltChat>;
+        /** Your own `message_from` setting: who can start a chat with you without landing in Requests or being refused. */
+        getMessageFrom(apiKey: string): Promise<MessageFrom>;
+        /** Set your own `message_from` (an agent changes its OWN setting). An unknown value is a 422 with
+         *  `code: "invalid_message_from"`. Returns the updated account fields. */
+        setMessageFrom(apiKey: string, value: MessageFrom): Promise<{
+            message_from: MessageFrom;
+            [key: string]: unknown;
+        }>;
+        /** Message requests waiting on you: 1:1 chats strangers started that you have not accepted. Same shape as
+         *  the chat list (rows are `{session, recent_message}`: the chat id is `row.session.id`); ordinary chats
+         *  are not in it. You can read a request through the API and decide. */
+        listRequests(apiKey: string): Promise<SaltChatListRow[]>;
+        /** Accept a message request: it becomes an ordinary chat. Idempotent. Returns the chat. */
+        acceptRequest(apiKey: string, chatId: SaltId): Promise<SaltChat>;
+        /** Decline a message request. The sender is not told: they still see the chat as sent, and anything more
+         *  they send you (a new chat, a group add) stays quiet. Blocking the sender (the block endpoint) also declines. */
+        declineRequest(apiKey: string, chatId: SaltId): Promise<void>;
+        /** Accounts that added you as a contact and that you have not added back ("Someone added you"). */
+        listIncomingContacts(apiKey: string): Promise<IncomingContact[]>;
+        /** Accept an incoming contact: add them back (`POST /api/v1/contacts {contact_id}`, the ordinary add-contact call).
+         *  This also follows their posts and accepts any message request of yours still waiting from them. */
+        acceptContact(apiKey: string, userId: SaltId): Promise<unknown>;
+        /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
+        dismissIncomingContact(apiKey: string, userId: SaltId): Promise<void>;
+        /** Exact-match lookup of accounts by handle (`username`) or a one-box `q`
+         *  (a handle with or without "@", or a fingerprint). Never fuzzy, so a
+         *  person who is not discoverable is still found by their exact handle. */
+        searchContacts(apiKey: string, query: {
+            username?: string;
+            q?: string;
+        }): Promise<SaltUser[]>;
+        /** Post a declarative blocks card into a chat (see CARD_PROTOCOL_SPEC.md / cards.ts). */
+        postCard(apiKey: string, chatId: SaltId, blocks: CardBlock[], text: string): Promise<unknown>;
+        /** Replace an owned card's blocks -- re-broadcasts into everyone's bubble live. */
+        updateCard(apiKey: string, cardId: SaltId, blocks: CardBlock[]): Promise<unknown>;
+        /**
+         * `GET /api/v1/cards/:id` -- a card's OWNER polling its own tap history
+         * instead of the agent's socket-mode outbox, which has exactly ONE
+         * forward-only cursor per agent: two concurrent pollers (or one running
+         * beside a socket listener) can otherwise silently consume each other's
+         * answers. Polling this instead is idempotent and shares nothing across
+         * callers -- any number of concurrent asks.
+         *
+         * Owner-only: `apiKey` must belong to the card's owner or this rejects
+         * with `SaltApiError` status 404 -- byte-identical to an unknown
+         * `cardId`, never 403 (a chat member already sees the card in the chat
+         * and gets nothing new from this endpoint).
+         *
+         * `options.after` is either another interaction's id or an ISO 8601
+         * timestamp and returns only newer rows; an unrecognised value fails
+         * OPEN (the full list comes back, still 200) rather than rejecting.
+         */
+        getCard(apiKey: string, cardId: SaltId, options?: {
+            after?: string;
+        }): Promise<CardWithInteractions>;
+        /** My own products (sellerId omitted) or a seller's active products (sellerId given). */
+        listProducts(apiKey: string, sellerId?: SaltId): Promise<unknown[]>;
+        /** Create a product in the caller's shop. */
+        createProduct(apiKey: string, params: Record<string, unknown>): Promise<unknown>;
+        /** Drop one of the caller's products into a chat as a Buy-able bubble. */
+        shareProduct(apiKey: string, productId: SaltId, chatId: SaltId): Promise<unknown>;
+        /**
+         * Send an itemized invoice on the TransferRequest rail. Server
+         * re-validates all the math.
+         *
+         * `idempotencyKey` is sent as an `Idempotency-Key` header, but
+         * `transfer_requests_controller` does NOT include salt-api's `Idempotent`
+         * concern (unlike addUsage/createTransfer paths) -- the server currently
+         * ignores it entirely. A retried call with the same key still creates a
+         * second invoice; there is no dedup, no replay, and none of the 409
+         * `request_in_flight` / `request_failed_terminal` behavior described for
+         * addUsage applies here. Retries of createInvoice are the caller's own
+         * responsibility to guard against for now.
+         */
+        createInvoice(apiKey: string, params: CreateInvoiceParams): Promise<unknown>;
+        /**
+         * Record metered usage against the payer's prepaid credits.
+         *
+         * Pass `idempotencyKey` to make a retried call safe -- a replayed
+         * response carries the `Idempotency-Replayed: true` header. A 409
+         * `request_in_flight` means an earlier call with the same key is still
+         * being processed: retry with a NEW key. A 409 `request_failed_terminal`
+         * means the usage/debit side-effect already happened under that key --
+         * do NOT retry with a new key (that would double-charge); reconcile
+         * against the existing usage event instead.
+         */
+        addUsage(apiKey: string, params: AddUsageParams): Promise<unknown>;
+        /**
+         * Owner-only: an agent's governed-spend policy. Call with the OWNER's
+         * api-key/JWT, not the agent's own key.
+         *
+         * Rule amounts (`budget_amount`, `per_tx_max`, `spent_this_period`,
+         * `remaining`) are all HUMAN-DECIMAL strings, e.g. "0.5" = half an ETH --
+         * never base units (wei/satoshis).
+         *
+         * If the agent has no policy at all, salt-api default-denies every
+         * mainnet send from it -- an owner must call updateSpendingPolicy at
+         * least once before the agent can move mainnet funds.
+         */
+        getSpendingPolicy(apiKey: string, agentId: SaltId): Promise<SpendingPolicy>;
+        /**
+         * Owner-only: replace an agent's governed-spend policy. Call with the
+         * OWNER's api-key/JWT, not the agent's own key.
+         *
+         * `rules[].budget_amount` and `rules[].per_tx_max` are HUMAN-DECIMAL
+         * strings, e.g. "0.5" = half an ETH -- never base units. `frozen: true`
+         * blocks all mainnet sends regardless of `rules`. Governed-spend
+         * refusals from this or any subsequent send carry `{error, code}`
+         * bodies -- see SpendGovernanceCode.
+         */
+        updateSpendingPolicy(apiKey: string, agentId: SaltId, policy: UpdateSpendingPolicyParams): Promise<SpendingPolicy>;
+        /**
+         * Guardian side of social recovery (any account named as a guardian, an
+         * agent included). Requests waiting on the caller: one per account that
+         * appointed it and has an open recovery.
+         */
+        incomingRecoveryRequests(apiKey: string): Promise<RecoveryRequestForGuardian[]>;
+        /** The sealed shares the caller holds for other accounts (ciphertext, encrypted to the caller's own key). */
+        heldRecoveryShares(apiKey: string): Promise<HeldRecoveryShare[]>;
+        /**
+         * Seats other accounts have asked the caller to hold and the caller has
+         * not answered yet (`recovery_guardian_invited` arrives the same way on
+         * the delivery rail). Nothing is released until a seat is accepted.
+         */
+        recoveryGuardianInvitations(apiKey: string): Promise<RecoveryGuardianInvitation[]>;
+        /** Accept a guardian seat (only the named guardian can). Idempotent answers are refused with 422. */
+        acceptRecoveryGuardian(apiKey: string, seatId: SaltId): Promise<RecoveryGuardianInvitation>;
+        /** Decline a guardian seat. */
+        declineRecoveryGuardian(apiKey: string, seatId: SaltId): Promise<RecoveryGuardianInvitation>;
+        /**
+         * Release the caller's share for one recovery request: open the held
+         * share with the caller's OWN private key, re-seal it to the request's
+         * ephemeral public key (what salt-fe does in a person's browser), and
+         * POST it. Salt only ever sees the re-sealed armor.
+         *
+         * Takes only the request id. The requester and the ephemeral key are
+         * read from Salt's own record (`GET /recovery_request/incoming`), never
+         * from the caller, so a delivery body or a hostile prompt cannot pair a
+         * victim's share with an attacker's key (confused deputy). Only call this
+         * once the request is believed genuine -- see recovery.ts. Idempotent: a
+         * second contribution from the same guardian does not count twice.
+         */
+        releaseRecoveryShare(apiKey: string, params: {
+            requestId: SaltId;
+            privateKey: string;
+            passphrase: string;
+        }): Promise<{
+            collected: number;
+            threshold: number | null;
+        }>;
+        /**
+         * The settlement record for a transfer the caller was party to (sender
+         * or receiver) -- 404 for anyone else, or if the transfer hasn't
+         * confirmed on-chain yet (receipts are minted only at confirmation).
+         */
+        getReceipt(apiKey: string, transferId: SaltId): Promise<Receipt>;
+        /** The caller's credit relationships, both directions. */
+        getBillingAccounts(apiKey: string): Promise<unknown>;
+        /**
+         * Payer-initiated deposit: drops a "Credits top-up" invoice into
+         * `chatId` for `payeeId` to receive. Nothing is credited by this call
+         * itself -- the deposit lands only once that invoice is paid (see
+         * onInvoicePaid's `isTopUp`).
+         */
+        topUpBillingAccount(apiKey: string, params: {
+            chatId: SaltId;
+            payeeId: SaltId;
+            amount: string | number;
+        }): Promise<{
+            ok: true;
+            transfer_request_id: SaltId;
+            billing_account: BillingAccount;
+        }>;
+        /**
+         * Payee-only: return value onto the credits ledger. Capped at net usage
+         * (Σusage - Σrefunds) so a refund can only give back credits that were
+         * actually consumed -- it can never mint new balance. A 422
+         * `refund_exceeds_usage` means `amount` is above what's currently
+         * refundable. This is a ledger entry, not an on-chain transfer -- no
+         * Receipt is minted for it.
+         */
+        refundBillingAccount(apiKey: string, billingAccountId: SaltId, params: {
+            amount: string | number;
+            memo?: string;
+        }): Promise<{
+            ok: true;
+            entry_id: SaltId;
+            billing_account: BillingAccount;
+        }>;
+        /**
+         * A transfer's current record, to verify a payment actually confirmed
+         * before an agent claims money work "done" (see actions.ts's
+         * report_progress evidence check). Status is one of "Pending" |
+         * "Confirmed" | "Failed" (Transfer#status in salt-api's
+         * app/models/transfer.rb) -- "Confirmed" is the only settled state.
+         *
+         * NOTE: as of this SDK version salt-api's TransfersController defines
+         * no `show` action (only index, create, and the :id/info member
+         * route) -- this call requires that route added server-side in the
+         * same release this evidence check ships in.
+         */
+        getTransfer(apiKey: string, transferId: SaltId): Promise<{
+            id: SaltId;
+            status: string;
+            [key: string]: unknown;
+        }>;
+        /** The caller's own wallets. */
+        listWallets(apiKey: string): Promise<unknown[]>;
+        /** Upload an already-encrypted wallet under the caller's own identity (see crypto.ts). */
+        createWallet(apiKey: string, params: Record<string, unknown>): Promise<unknown>;
+        /** Hand a chat off to another agent; salt-api does the whole swap atomically. */
+        handOff(apiKey: string, chatId: SaltId, toAgentId: SaltId, reason?: string): Promise<unknown>;
+        /**
+         * One step back: return the chat to whoever handed it TO the current
+         * active agent most recently (a real hop off the trail, not a fixed
+         * destination) -- salt-api's `Chat#hand_off_back!`. 422 with "Already
+         * at the start of this conversation." when there's no previous hop;
+         * callers (actions.ts's hand_back_to_concierge) fall back to something
+         * fixed in that case. The acting agent must currently be this chat's
+         * active agent (or a human member) -- salt-api's `gacm_actor_allowed?`.
+         */
+        handBack(apiKey: string, chatId: SaltId): Promise<unknown>;
+        /**
+         * React to a message with one emoji (`POST /api/v1/messages/:id/reactions`).
+         * A TOGGLE: the same emoji again removes yours. Plaintext metadata, so no
+         * crypto. Resolves with the server's `{message_id, reactions}` summary;
+         * a 422 ("Pick a single emoji." / "You can react with up to 12 emoji.")
+         * arrives as a SaltApiError carrying that sentence.
+         *
+         * The owner's rule for agents: react "not all the time, just when they
+         * choose", and only "if it relevantly complements the chat in a friendly
+         * way" -- a thanks acknowledged, a done request marked, good news
+         * celebrated. Never instead of answering a question, never on every
+         * message, never on your own.
+         */
+        react(apiKey: string, messageId: SaltId, emoji: string): Promise<ReactionSummary>;
+        /** The emoji this identity has used, for picking one (`GET /api/v1/reactions/mine`). */
+        myReactions(apiKey: string): Promise<unknown>;
+        /**
+         * Replies to a post: your reply becomes YOUR OWN post in your profile room, linked to the one it
+         * answers -- the same single action a person has (`POST /api/v1/posts/:id/reply`). Resolves with
+         * the new post's row. Refusals arrive as a SaltApiError carrying the server's sentence: 404 not a
+         * visible post, 403 blocked, 422 empty or too long. Pass `idempotencyKey` to make a retry safe
+         * (sent as `Idempotency-Key`).
+         */
+        replyToPost(apiKey: string, postId: SaltId, text: string, opts?: {
+            idempotencyKey?: string;
+            media?: PostMediaInput;
+        }): Promise<PostRow>;
+        /**
+         * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
+         * The room is made on first use (`POST /api/v1/profile_room`), then the post goes through
+         * `POST /api/v1/messages`; media is plain and public (up to 15 MB; image/jpeg, png, webp, gif,
+         * heic or video/mp4, webm, quicktime), so it is NOT encrypted like chat attachments. Resolves with
+         * the new message envelope (its `media.url` is the public file). A refusal arrives as a SaltApiError
+         * carrying the server's sentence.
+         */
+        postToProfile(apiKey: string, params: {
+            text?: string;
+            media?: PostMediaInput;
+        }): Promise<{
+            message_id: SaltId;
+            media?: PostMediaInfo;
+        }>;
+        /** The replies to a post, newest page first; pass the last page's `next_before` as `before` for older ones
+         *  (`GET /api/v1/posts/:id/replies`). */
+        getPostReplies(apiKey: string, postId: SaltId, opts?: {
+            before?: string;
+            limit?: number;
+        }): Promise<PostRepliesPage>;
+        /** Ephemeral "is typing" ping. Fire-and-forget by design -- a failed ping must never block a reply. */
+        signalTyping(apiKey: string, chatId: SaltId): Promise<void>;
+        /**
+         * Fire-and-forget product-metrics beacon. Deliberately not awaited by
+         * callers -- an analytics post must never delay or fail a reply. Only
+         * names in salt-api's Event::CLIENT_EVENT_NAMES allowlist are accepted.
+         */
+        trackEvent(apiKey: string, name: string, properties?: Record<string, unknown>): void;
+        /**
+         * Prepares a governed payment for approval -- `money.pay`'s mode is FORCED to `ask`, so this
+         * always resolves to an `AskedResult`, never a Transfer, whether called through `actFor` or (in
+         * the unusual case of preparing your own payment) as yourself. Once the exercise is approved
+         * (see `mandates.decide`/`mandates.exercises`, or the `approval_decided` webhook event), settle
+         * it with `transfers#create`'s own `exercise_id` param (not exposed as a typed method here yet --
+         * salt-api validates the wallet/amount/destination against the exercise's summary before it will
+         * create the Transfer).
+         */
+        prepareTransfer(apiKey: string, params: {
+            walletId: SaltId;
+            destinationAddress?: string;
+            receiverId?: SaltId;
+            amount: string | number;
+            chain?: string;
+            note?: string;
+            chatId?: SaltId;
+        }): Promise<AskedResult>;
+        mandates: {
+            /** Every mandate the caller is party to, as grantor and/or grantee. */
+            list(apiKey: string, opts?: {
+                role?: "grantor" | "grantee";
+                status?: MandateStatus;
+            }): Promise<{
+                mandates: Mandate[];
+            }>;
+            get(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            /** Grantor creates (a proposal the grantee must accept, or auto-active for an account the
+             *  caller governs), or a grantee proposes UP by passing `grantor_id` instead. */
+            propose(apiKey: string, params: ProposeMandateParams): Promise<Mandate>;
+            /** New version, compare-and-swap on `params.version` -- a 409 SaltApiError means it changed
+             *  under you; re-fetch with `get` and retry against the new version. */
+            update(apiKey: string, mandateId: SaltId, params: UpdateMandateParams): Promise<Mandate>;
+            /** Grantee accepts an offered mandate (binds its current key fingerprint), or the grantor
+             *  activates one still `proposed` by the grantee. See `ctx.mandate.accept()` in webhook.ts,
+             *  which calls this for an incoming `mandate_offered` event. */
+            accept(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            /** Standing mandates only: +90 days from now. */
+            renew(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            pause(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
+            resume(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+            /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. */
+            revoke(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
+            /** A mandate's trail, id-descending. `refusal` is only populated when the caller is the
+             *  principal or its governor (salt-api's own viewer check -- this SDK doesn't re-derive it). */
+            exercises(apiKey: string, mandateId: SaltId, opts?: {
+                before?: string | number;
+                limit?: number;
+            }): Promise<{
+                exercises: MandateExercise[];
+            }>;
+            /** Every open ask (decision `"asked"`, not yet expired) the caller can decide right now. */
+            openExercises(apiKey: string): Promise<{
+                exercises: MandateExercise[];
+            }>;
+            /** Approve or deny one open ask. See `ctx.approval.decide()` in webhook.ts, which calls this
+             *  for an incoming `approval_requested` event. */
+            decide(apiKey: string, exerciseId: SaltId | number, decision: "approve" | "deny", note?: string): Promise<MandateExercise>;
+        };
+        teams: {
+            /** The Teams shelf: listed templates, most installed first. Public. */
+            list(apiKey: string, opts?: {
+                q?: string;
+                limit?: number;
+                offset?: number;
+            }): Promise<{
+                teams: TeamTemplate[];
+                total: number;
+            }>;
+            /** The templates this identity shared, listed or not. */
+            mine(apiKey: string): Promise<{
+                teams: TeamTemplate[];
+            }>;
+            /** A recipe preview, by id or slug. Public; an unlisted template is reachable by its link. */
+            get(apiKey: string, idOrSlug: string): Promise<TeamTemplate>;
+            /** Shares one of the caller's own agent groups as a template. */
+            share(apiKey: string, params: ShareTeamParams): Promise<TeamTemplate & {
+                left_out: number;
+            }>;
+            /** Author only: name, description, listed or unlisted, the coordinator note. */
+            update(apiKey: string, idOrSlug: string, changes: Partial<Pick<ShareTeamParams, "name" | "description" | "listed" | "coordinatorNote">>): Promise<TeamTemplate>;
+            /** Author only. Agents already made from it are the installers' own. */
+            remove(apiKey: string, idOrSlug: string): Promise<void>;
+            /** "I made this team": counted once per installer. */
+            installed(apiKey: string, idOrSlug: string): Promise<{
+                install_count: number;
+                counted: boolean;
+            }>;
+        };
+        apps: {
+            /**
+             * Creates an app + version 1. `forId` builds it for someone else (that
+             * person must share a chat with the caller, else 422); omitted, the
+             * app belongs to the caller. `chatId` also installs it there in the
+             * same transaction (caller must be a member) -- see `installation` on
+             * the result.
+             */
+            create(apiKey: string, params: CreateAppParams): Promise<CreateAppResult>;
+            /**
+             * Publishes a new immutable version (owner or builder only) and moves
+             * the app's `latest_version_id` to it. `actions` (omitted: none)
+             * replace whatever the PRIOR version declared -- they don't merge.
+             * Never changes an existing installation on its own -- each keeps
+             * running its own pinned version (and that version's own `actions`)
+             * until it calls `update`, below.
+             */
+            newVersion(apiKey: string, appId: SaltId, html: string, actions?: AppQuickAction[]): Promise<{
+                app: AppSummary;
+                version: AppVersionRef;
+            }>;
+            /** An app's metadata: owner, builder, latest version -- and, once listed, what the App Store shows. */
+            get(apiKey: string, appId: SaltId): Promise<AppSummary>;
+            /**
+             * Installs `appId` -- into `chatId` (caller must be a non-observer
+             * member; a second active install of the same app there 409s with the
+             * existing installation instead of creating a duplicate) or, with no
+             * `chatId`, into the caller's own personal space ("Your apps").
+             * `copyStateFrom` copies another readable installation's doc into the
+             * new one once.
+             */
+            install(apiKey: string, appId: SaltId, params?: InstallAppParams): Promise<AppInstallation>;
+            /**
+             * This identity's installations: every one in `chatId` (chat members
+             * only) when given, else its own personal installations plus every
+             * chat installation in a chat it's a member of. Cache-busted -- an
+             * install just made should show up immediately.
+             */
+            installations(apiKey: string, opts?: {
+                chatId?: SaltId;
+            }): Promise<AppInstallation[]>;
+            /** The installation's shared state doc and its CAS version. Cache-busted -- a doc just written with `setState` should read back immediately. */
+            state(apiKey: string, installationId: SaltId): Promise<AppStateDoc>;
+            /**
+             * Compare-and-swap write of the installation's shared state doc. A 409
+             * (the doc moved under the caller since `ifVersion`) is never handed
+             * back as a bare SaltApiError -- it's re-thrown as
+             * AppStateConflictError carrying the CURRENT `{doc, version}` straight
+             * off the response body, so a caller can merge its change onto the
+             * fresh doc and retry with the new version in one more call rather
+             * than round-tripping to re-fetch first.
+             */
+            setState(apiKey: string, installationId: SaltId, doc: Record<string, unknown>, ifVersion: number): Promise<AppStateDoc>;
+        };
+    }>[K]>; };
     /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
-    getChatMembers(apiKey: string, chatId: number | string): Promise<SaltUser[]>;
+    getChatMembers(apiKey: string, chatId: SaltId): Promise<SaltUser[]>;
     /** Recent messages in a chat this identity is a member of (even as a silent observer). */
-    getChatMessages(apiKey: string, chatId: number | string): Promise<unknown[]>;
+    getChatMessages(apiKey: string, chatId: SaltId): Promise<unknown[]>;
+    /**
+     * One `GET /api/v1/chats/:id` call for a caller that needs BOTH the
+     * member list and whether the chat is end-to-end encrypted -- e.g.
+     * actions.ts's request_floor, which (unlike delegate_to_agent/
+     * consult_agent) has no other reason to fetch the chat at all.
+     * `encrypted` is already resolved to a real boolean (defaulted `true`
+     * when the field is absent, same convention as ChatOpenedContext.encrypted
+     * and MessageContext.encrypted) -- never undefined.
+     */
+    getChat(apiKey: string, chatId: SaltId): Promise<{
+        id: SaltId;
+        encrypted: boolean;
+        users: SaltUser[];
+    }>;
+    /**
+     * Salt's own record of a chat, exactly as `GET /api/v1/chats/:id` answers
+     * it (nothing flattened or defaulted, unlike getChat): `session.users`
+     * with each member's `observer` flag, `session.public`, `session.encrypted`.
+     * This is what `isPrivateChat(chat, speakerId, myId)` reads -- decide
+     * privacy-sensitive actions from THIS, fetched when you need it, never
+     * from a cache or a memory service.
+     */
+    getChatRecord(apiKey: string, chatId: SaltId): Promise<SaltChat>;
     /** Download an attachment's ciphertext bytes. Decrypt separately (see crypto.ts). */
-    getAttachment(apiKey: string, messageId: number | string): Promise<Buffer>;
+    getAttachment(apiKey: string, messageId: SaltId): Promise<Buffer>;
     /**
      * Post a reply into a chat. `message` is the ciphertext every human
      * recipient reads; `senderMessage` is the copy encrypted to the
      * sender's own key. `delegations` (optional) is the provenance trail
      * -- salt-api re-validates every entry against the sender's actual
-     * memberships before storing it.
+     * memberships before storing it. The result carries `delivered_as`:
+     * `"request"` means the recipient has not accepted a first message from
+     * you yet (see Message requests in AGENTS.md) -- wait, do not re-send.
      */
-    postMessage(apiKey: string, chatId: number | string, message: string, senderMessage?: string, delegations?: Array<{
-        agent_id: number;
-        chat_id: number;
+    postMessage(apiKey: string, chatId: SaltId, message: string, senderMessage?: string, delegations?: Array<{
+        agent_id: SaltId;
+        chat_id: SaltId;
         username: string;
-    }>): Promise<unknown>;
+    }>, mentions?: SaltId[], opts?: {
+        quiet?: boolean;
+    }): Promise<PostMessageResult>;
+    /**
+     * Sends a file into a chat, encrypted exactly the way salt-fe's
+     * chatbox.jsx sendOneAttachment encrypts one: a fresh one-time AES-256-
+     * GCM key encrypts the file bytes (crypto.ts's encryptAttachment,
+     * byte-identical wire format to the browser's Web Crypto output), and
+     * that key/iv plus the real filename/content_type/size are PGP-
+     * encrypted as one JSON blob for every current chat member's public
+     * key -- the SAME single recipient list the caption text is encrypted
+     * for, fetched fresh via GET /api/v1/chats/:id so a just-added or
+     * just-removed member is never missed or over-included. Unlike
+     * postMessage's reply() there is no separate sender_message: the web
+     * never excludes the sender from an attachment's recipient list (it
+     * has no reason to -- there's only one `attachment_encrypted_key`
+     * field, see Attachment#as_chat_resource), so a single PGP blob
+     * covering every member already covers the sender too.
+     *
+     * Throws before doing any crypto work on an oversized file (matches
+     * salt-api's own MAX_ATTACHMENT_BYTES so a doomed upload never even
+     * starts) or a content_type outside ALLOWED_SEND_CONTENT_TYPES.
+     */
+    sendAttachment(apiKey: string, chatId: SaltId, params: SendAttachmentParams): Promise<unknown>;
+    /**
+     * Post into an OPEN ROOM -- a chat with no end-to-end encryption, so
+     * `text` rides the wire and is stored as plain text rather than a PGP
+     * blob. There is no `senderMessage`/`delegations`/`mentions` shape here
+     * the way postMessage has: salt-api refuses this call 422 against a
+     * chat that isn't plain (never silently encrypts, never silently
+     * drops the call). Webhook/socket deliveries for a plain chat carry
+     * `message.encrypted === false` -- see webhook.ts's handleMessage,
+     * which hands the body straight through as ctx.text (ctx.encrypted
+     * false) instead of attempting PGP decrypt.
+     */
+    postPlainMessage(apiKey: string, chatId: SaltId, text: string): Promise<unknown>;
+    /**
+     * Open rooms (0.6x): declares what this identity wants delivered from
+     * a chat it isn't necessarily addressed in every message of --
+     * `"addressed"` (only a direct reply/@mention, the closest analogue to
+     * how a normal encrypted chat already gates agent delivery),
+     * `"keywords"` (any message containing one of `keywords`), or `"all"`
+     * (every message). Always this identity's OWN subscription for
+     * `chatId` -- same "acts on the caller, never someone else" shape as
+     * setDeliveryMode/setCallback.
+     */
+    setChatSubscription(apiKey: string, chatId: SaltId, params: {
+        mode: "addressed" | "keywords" | "all";
+        keywords?: string[];
+    }): Promise<unknown>;
+    /** Removes this identity's subscription record for `chatId` -- salt-api's
+     *  default (unsubscribed) behavior applies again, same as never having
+     *  called setChatSubscription. */
+    clearChatSubscription(apiKey: string, chatId: SaltId): Promise<unknown>;
+    /**
+     * Get-or-create the private lane (a sidechain) between this identity and
+     * `withId`, both members of `chatId`. Once per pair on Salt's side. Answers
+     * 422 when `chatId` is itself a lane. The lane's members come back with
+     * their public keys.
+     */
+    openSidechain(apiKey: string, chatId: SaltId, withId: SaltId): Promise<{
+        session: {
+            id: SaltId;
+            users?: SaltUser[];
+            coaching_for_chat_id?: SaltId;
+            [key: string]: unknown;
+        };
+        messages?: unknown[];
+    }>;
+    /**
+     * Opens (or reuses) a CONSULT lane between the caller and `withId`, both
+     * already members of `roomId` -- mechanically identical to
+     * openSidechain (same endpoint, same get-or-create-per-pair semantics),
+     * named separately because actions.ts's consult_agent reads more
+     * clearly calling "open the lane I'm about to consult in" than a
+     * generic sidechain call. salt-api tags the resulting chat
+     * `lane_kind: "consult"`, which webhook.ts reads back off the webhook
+     * body to raise the agent-to-agent reply cap for that lane and to gate
+     * request_floor.
+     */
+    openConsultLane(apiKey: string, roomId: SaltId, withId: SaltId): Promise<{
+        session: {
+            id: SaltId;
+            users?: SaltUser[];
+            coaching_for_chat_id?: SaltId;
+            lane_kind?: string;
+            [key: string]: unknown;
+        };
+        messages?: unknown[];
+    }>;
     /** Register a new Salt agent, owned by whoever's api-key calls this. */
-    createAgent(apiKey: string, params: CreateAgentParams): Promise<SaltUser>;
-    /** Owner-only: fetch an agent's own api-key + PGP keypair right after creating it. */
-    getAgentAdmin(apiKey: string, agentId: number | string): Promise<{
+    /**
+     * The create response carries the new agent's raw api key EXACTLY ONCE --
+     * salt-api stores only a digest, so no later endpoint can show it again.
+     * Capture `api_key` here; a lost key means rotateAgentApiKey, not re-reading.
+     *
+     * Key custody: `CreateAgentParams` deliberately has no `private_key` --
+     * salt-api rejects one with a 422 unconditionally (salt-api docs/
+     * KEY_CUSTODY.md Phase 5). The key stays with whoever generates it
+     * (pgp.generateKeypair, above the call site) and is registered with
+     * identities.register/a session store; salt-api never receives a copy in
+     * any form it can decrypt, so there is nothing to fetch back later --
+     * getAgentAdmin's `userkeys` never carries a usable key either.
+     */
+    createAgent(apiKey: string, params: CreateAgentParams): Promise<SaltUser & {
+        api_key?: string;
+    }>;
+    /** Owner-only: mint a new api key for an agent. The old one stops working immediately. */
+    rotateAgentApiKey(apiKey: string, agentId: SaltId): Promise<{
+        api_key: string;
+    }>;
+    /**
+     * This identity's own webhook signing key, used to verify that an incoming
+     * webhook really came from salt-api.
+     *
+     * Fetched with the identity's own api key rather than configured from the
+     * environment: salt-api mints one secret per agent, so shipping them through
+     * env/Secrets Manager would mean the deploy had to know values the API
+     * generates. Fetching at boot also means rotation takes effect on restart.
+     */
+    getWebhookSecret(apiKey: string): Promise<string | undefined>;
+    /**
+     * Which agent does this api key belong to, according to salt-api?
+     *
+     * The same endpoint as getWebhookSecret: alongside the secret it returns
+     * the canonical `agent_id` of the key's owner, which is the id salt-api
+     * puts in X-Salt-Agent-Id on every callback. An identity registered under
+     * any other id -- an env var, or a store entry that predates an id
+     * migration -- can never be found when a webhook arrives; that is what
+     * reconcileIdentityIds uses this to detect and repair.
+     */
+    whoAmI: (apiKey: string) => Promise<{
+        agent_id: SaltId;
+        webhook_secret?: string;
+    }>;
+    /**
+     * Owner-only: mint a new webhook signing secret for an agent. The old
+     * secret stops verifying immediately, so the agent must re-fetch via
+     * getWebhookSecret before it can validate any further deliveries.
+     */
+    rotateWebhookSecret(apiKey: string, agentId: SaltId): Promise<{
+        agent_id: SaltId;
+        webhook_secret: string;
+    }>;
+    /**
+     * The caller sets its OWN webhook callback -- api-key auth, no id
+     * parameter, same "acts on the caller, never someone else" shape as
+     * setDeliveryMode/setChatSubscription. Exists so the platform hosting
+     * an agent can point its callback at itself without the owner ever
+     * opening Salt's web console -- see AgentsController#set_callback's
+     * own comment. Same URL-safety rule as the owner's web form
+     * (User#callback_must_be_safe) applies server-side; a human caller
+     * (not an agent's own api-key) gets a 403.
+     */
+    setCallback(apiKey: string, webhook: string): Promise<{
+        agent_id: SaltId;
+        callback: string;
+    }>;
+    /**
+     * K2 socket mode: the caller sets its OWN delivery mode -- "webhook"
+     * (the default, POST to its registered callback) or "socket" (drain
+     * GET /api/v1/agent/updates or AgentUpdatesChannel instead; see
+     * socket.ts's createSocketClient). No id parameter, same reason
+     * getWebhookSecret has none -- an agent can only ever change its own.
+     * A blank callback is always socket mode regardless of this setting.
+     */
+    setDeliveryMode(apiKey: string, mode: "webhook" | "socket"): Promise<{
+        agent_id: SaltId;
+        delivery_mode: string;
+        socket_mode: boolean;
+    }>;
+    /**
+     * Owner-only agent admin record. `apikey` is metadata (hint, last-used) --
+     * the raw key rides only on the createAgent response, and after that only
+     * rotateAgentApiKey can produce a usable value.
+     */
+    getAgentAdmin(apiKey: string, agentId: SaltId): Promise<{
         apikey: {
-            api_key: string;
-        };
+            token_hint?: string;
+            last_used_at?: string;
+        } | null;
         userkeys: unknown;
         [key: string]: unknown;
     }>;
+    /**
+     * This agent's own identity: every section (claim and proof) with
+     * `scope`/`editable_by`/`checked_by`, plus the public card URL it's
+     * served from. Cache-busted like getChatMembers -- a value just set
+     * with setIdentity should read back immediately.
+     */
+    identity(apiKey: string): Promise<IdentitySections>;
+    /**
+     * Set one or more of this agent's own CLAIM sections (see
+     * AGENT_CLAIM_SECTION_KEYS). `scope` is never accepted here -- section
+     * visibility is owner-authenticated through the agent-management API
+     * only (plan section 7: "setScope is never on this surface"), so a
+     * caller that tries to slip one in is refused BEFORE any request is
+     * made, the same way a bad tool call should fail loud and immediately
+     * rather than round-tripping to find out the server also says no.
+     * A 422 from salt-api ({errors: {key: "line"}} for an invalid value, or
+     * {error: "Scope comes later."} were scope to somehow reach it anyway)
+     * surfaces as an ordinary SaltApiError.
+     */
+    setIdentity(apiKey: string, claims: IdentityClaims): Promise<IdentitySections>;
+    /**
+     * Writes one disclosure ledger row -- metadata only, never a section
+     * VALUE (plan section 4). identityShare.ts's share() calls this once
+     * per recipient BEFORE sending any ciphertext, with the SAME `id` every
+     * time (the row is keyed on subject + recipient + id, so this creates
+     * one row per recipient under one shared id), and aborts the whole
+     * share on the first refusal (422, one plain sentence -- e.g. a key
+     * that isn't actually shared with that recipient) with nothing sent.
+     */
+    postIdentityDisclosure(apiKey: string, params: PostIdentityDisclosureParams): Promise<IdentityDisclosure>;
+    /**
+     * Records which chat message actually carried a share's slice, once
+     * it's been posted. Called ONCE per share() call (with the share's one
+     * `id`) right after the one encrypted SLICE message goes out
+     * (identityShare.ts's share()) -- since every recipient's row shares
+     * that id, one PATCH reaches all of them.
+     */
+    setIdentityDisclosureMessage(apiKey: string, id: string, messageId: SaltId): Promise<{
+        disclosures: IdentityDisclosure[];
+    }>;
+    /** This agent's own disclosure ledger, newest first. */
+    listIdentityDisclosures(apiKey: string, opts?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        disclosures: IdentityDisclosure[];
+    }>;
+    /**
+     * Revokes EVERY ledger row under `id` (every recipient of that share)
+     * in one call -- stops them being served again and is the signal
+     * identityShare.ts's revoke() sends a `[[SALT-IDENTITY-REVOKE]]` wire
+     * marker off of. Cannot reach a message already read; the rows
+     * themselves are the only thing this call changes.
+     */
+    revokeIdentityDisclosure(apiKey: string, id: string): Promise<{
+        disclosures: IdentityDisclosure[];
+    }>;
+    /**
+     * Fetches a person's or an agent's PUBLICLY SERVED signed card and
+     * verifies its signature before returning it -- this is a public,
+     * unauthenticated GET (no api-key), matching agent_cards_controller's
+     * `skip_before_action :auth_user`. Tries the agent path then the user
+     * path unless `opts.kind` says which one. A card whose signature this
+     * SDK cannot confirm (missing, unparseable, unknown key, tampered)
+     * throws IdentityCardInvalidError rather than ever coming back
+     * `verified: false` -- a card either verifies or this call fails.
+     */
+    card(handle: string, opts?: {
+        kind?: "agent" | "user";
+    }): Promise<{
+        card: SignedCard;
+        verified: true;
+    }>;
     /** The public Agents directory. */
     listAgents(apiKey: string): Promise<SaltUser[]>;
     /** A single agent's directory entry. */
-    getAgent(apiKey: string, agentId: number | string): Promise<SaltUser>;
-    /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. */
-    createOrGetChat(apiKey: string, contactId: number | string): Promise<SaltChat>;
+    getAgent(apiKey: string, agentId: SaltId): Promise<SaltUser>;
+    /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. The result's `delivered_as` is
+     *  `"request"` when the contact has not accepted a first message from you yet: wait, and do not open another
+     *  chat. A recipient who only takes messages from their contacts throws `RecipientContactsOnlyError`. */
+    createOrGetChat(apiKey: string, contactId: SaltId): Promise<SaltChat>;
+    /** Your own `message_from` setting: who can start a chat with you without landing in Requests or being refused. */
+    getMessageFrom(apiKey: string): Promise<MessageFrom>;
+    /** Set your own `message_from` (an agent changes its OWN setting). An unknown value is a 422 with
+     *  `code: "invalid_message_from"`. Returns the updated account fields. */
+    setMessageFrom(apiKey: string, value: MessageFrom): Promise<{
+        message_from: MessageFrom;
+        [key: string]: unknown;
+    }>;
+    /** Message requests waiting on you: 1:1 chats strangers started that you have not accepted. Same shape as
+     *  the chat list (rows are `{session, recent_message}`: the chat id is `row.session.id`); ordinary chats
+     *  are not in it. You can read a request through the API and decide. */
+    listRequests(apiKey: string): Promise<SaltChatListRow[]>;
+    /** Accept a message request: it becomes an ordinary chat. Idempotent. Returns the chat. */
+    acceptRequest(apiKey: string, chatId: SaltId): Promise<SaltChat>;
+    /** Decline a message request. The sender is not told: they still see the chat as sent, and anything more
+     *  they send you (a new chat, a group add) stays quiet. Blocking the sender (the block endpoint) also declines. */
+    declineRequest(apiKey: string, chatId: SaltId): Promise<void>;
+    /** Accounts that added you as a contact and that you have not added back ("Someone added you"). */
+    listIncomingContacts(apiKey: string): Promise<IncomingContact[]>;
+    /** Accept an incoming contact: add them back (`POST /api/v1/contacts {contact_id}`, the ordinary add-contact call).
+     *  This also follows their posts and accepts any message request of yours still waiting from them. */
+    acceptContact(apiKey: string, userId: SaltId): Promise<unknown>;
+    /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
+    dismissIncomingContact(apiKey: string, userId: SaltId): Promise<void>;
+    /** Exact-match lookup of accounts by handle (`username`) or a one-box `q`
+     *  (a handle with or without "@", or a fingerprint). Never fuzzy, so a
+     *  person who is not discoverable is still found by their exact handle. */
+    searchContacts(apiKey: string, query: {
+        username?: string;
+        q?: string;
+    }): Promise<SaltUser[]>;
     /** Post a declarative blocks card into a chat (see CARD_PROTOCOL_SPEC.md / cards.ts). */
-    postCard(apiKey: string, chatId: number | string, blocks: CardBlock[], text: string): Promise<unknown>;
+    postCard(apiKey: string, chatId: SaltId, blocks: CardBlock[], text: string): Promise<unknown>;
     /** Replace an owned card's blocks -- re-broadcasts into everyone's bubble live. */
-    updateCard(apiKey: string, cardId: number | string, blocks: CardBlock[]): Promise<unknown>;
+    updateCard(apiKey: string, cardId: SaltId, blocks: CardBlock[]): Promise<unknown>;
+    /**
+     * `GET /api/v1/cards/:id` -- a card's OWNER polling its own tap history
+     * instead of the agent's socket-mode outbox, which has exactly ONE
+     * forward-only cursor per agent: two concurrent pollers (or one running
+     * beside a socket listener) can otherwise silently consume each other's
+     * answers. Polling this instead is idempotent and shares nothing across
+     * callers -- any number of concurrent asks.
+     *
+     * Owner-only: `apiKey` must belong to the card's owner or this rejects
+     * with `SaltApiError` status 404 -- byte-identical to an unknown
+     * `cardId`, never 403 (a chat member already sees the card in the chat
+     * and gets nothing new from this endpoint).
+     *
+     * `options.after` is either another interaction's id or an ISO 8601
+     * timestamp and returns only newer rows; an unrecognised value fails
+     * OPEN (the full list comes back, still 200) rather than rejecting.
+     */
+    getCard(apiKey: string, cardId: SaltId, options?: {
+        after?: string;
+    }): Promise<CardWithInteractions>;
     /** My own products (sellerId omitted) or a seller's active products (sellerId given). */
-    listProducts(apiKey: string, sellerId?: number | string): Promise<unknown[]>;
+    listProducts(apiKey: string, sellerId?: SaltId): Promise<unknown[]>;
     /** Create a product in the caller's shop. */
     createProduct(apiKey: string, params: Record<string, unknown>): Promise<unknown>;
     /** Drop one of the caller's products into a chat as a Buy-able bubble. */
-    shareProduct(apiKey: string, productId: number | string, chatId: number | string): Promise<unknown>;
-    /** Send an itemized invoice on the TransferRequest rail. Server re-validates all the math. */
+    shareProduct(apiKey: string, productId: SaltId, chatId: SaltId): Promise<unknown>;
+    /**
+     * Send an itemized invoice on the TransferRequest rail. Server
+     * re-validates all the math.
+     *
+     * `idempotencyKey` is sent as an `Idempotency-Key` header, but
+     * `transfer_requests_controller` does NOT include salt-api's `Idempotent`
+     * concern (unlike addUsage/createTransfer paths) -- the server currently
+     * ignores it entirely. A retried call with the same key still creates a
+     * second invoice; there is no dedup, no replay, and none of the 409
+     * `request_in_flight` / `request_failed_terminal` behavior described for
+     * addUsage applies here. Retries of createInvoice are the caller's own
+     * responsibility to guard against for now.
+     */
     createInvoice(apiKey: string, params: CreateInvoiceParams): Promise<unknown>;
-    /** Record metered usage against the payer's prepaid credits. */
+    /**
+     * Record metered usage against the payer's prepaid credits.
+     *
+     * Pass `idempotencyKey` to make a retried call safe -- a replayed
+     * response carries the `Idempotency-Replayed: true` header. A 409
+     * `request_in_flight` means an earlier call with the same key is still
+     * being processed: retry with a NEW key. A 409 `request_failed_terminal`
+     * means the usage/debit side-effect already happened under that key --
+     * do NOT retry with a new key (that would double-charge); reconcile
+     * against the existing usage event instead.
+     */
     addUsage(apiKey: string, params: AddUsageParams): Promise<unknown>;
+    /**
+     * Owner-only: an agent's governed-spend policy. Call with the OWNER's
+     * api-key/JWT, not the agent's own key.
+     *
+     * Rule amounts (`budget_amount`, `per_tx_max`, `spent_this_period`,
+     * `remaining`) are all HUMAN-DECIMAL strings, e.g. "0.5" = half an ETH --
+     * never base units (wei/satoshis).
+     *
+     * If the agent has no policy at all, salt-api default-denies every
+     * mainnet send from it -- an owner must call updateSpendingPolicy at
+     * least once before the agent can move mainnet funds.
+     */
+    getSpendingPolicy(apiKey: string, agentId: SaltId): Promise<SpendingPolicy>;
+    /**
+     * Owner-only: replace an agent's governed-spend policy. Call with the
+     * OWNER's api-key/JWT, not the agent's own key.
+     *
+     * `rules[].budget_amount` and `rules[].per_tx_max` are HUMAN-DECIMAL
+     * strings, e.g. "0.5" = half an ETH -- never base units. `frozen: true`
+     * blocks all mainnet sends regardless of `rules`. Governed-spend
+     * refusals from this or any subsequent send carry `{error, code}`
+     * bodies -- see SpendGovernanceCode.
+     */
+    updateSpendingPolicy(apiKey: string, agentId: SaltId, policy: UpdateSpendingPolicyParams): Promise<SpendingPolicy>;
+    /**
+     * Guardian side of social recovery (any account named as a guardian, an
+     * agent included). Requests waiting on the caller: one per account that
+     * appointed it and has an open recovery.
+     */
+    incomingRecoveryRequests(apiKey: string): Promise<RecoveryRequestForGuardian[]>;
+    /** The sealed shares the caller holds for other accounts (ciphertext, encrypted to the caller's own key). */
+    heldRecoveryShares(apiKey: string): Promise<HeldRecoveryShare[]>;
+    /**
+     * Seats other accounts have asked the caller to hold and the caller has
+     * not answered yet (`recovery_guardian_invited` arrives the same way on
+     * the delivery rail). Nothing is released until a seat is accepted.
+     */
+    recoveryGuardianInvitations(apiKey: string): Promise<RecoveryGuardianInvitation[]>;
+    /** Accept a guardian seat (only the named guardian can). Idempotent answers are refused with 422. */
+    acceptRecoveryGuardian(apiKey: string, seatId: SaltId): Promise<RecoveryGuardianInvitation>;
+    /** Decline a guardian seat. */
+    declineRecoveryGuardian(apiKey: string, seatId: SaltId): Promise<RecoveryGuardianInvitation>;
+    /**
+     * Release the caller's share for one recovery request: open the held
+     * share with the caller's OWN private key, re-seal it to the request's
+     * ephemeral public key (what salt-fe does in a person's browser), and
+     * POST it. Salt only ever sees the re-sealed armor.
+     *
+     * Takes only the request id. The requester and the ephemeral key are
+     * read from Salt's own record (`GET /recovery_request/incoming`), never
+     * from the caller, so a delivery body or a hostile prompt cannot pair a
+     * victim's share with an attacker's key (confused deputy). Only call this
+     * once the request is believed genuine -- see recovery.ts. Idempotent: a
+     * second contribution from the same guardian does not count twice.
+     */
+    releaseRecoveryShare(apiKey: string, params: {
+        requestId: SaltId;
+        privateKey: string;
+        passphrase: string;
+    }): Promise<{
+        collected: number;
+        threshold: number | null;
+    }>;
+    /**
+     * The settlement record for a transfer the caller was party to (sender
+     * or receiver) -- 404 for anyone else, or if the transfer hasn't
+     * confirmed on-chain yet (receipts are minted only at confirmation).
+     */
+    getReceipt(apiKey: string, transferId: SaltId): Promise<Receipt>;
     /** The caller's credit relationships, both directions. */
     getBillingAccounts(apiKey: string): Promise<unknown>;
+    /**
+     * Payer-initiated deposit: drops a "Credits top-up" invoice into
+     * `chatId` for `payeeId` to receive. Nothing is credited by this call
+     * itself -- the deposit lands only once that invoice is paid (see
+     * onInvoicePaid's `isTopUp`).
+     */
+    topUpBillingAccount(apiKey: string, params: {
+        chatId: SaltId;
+        payeeId: SaltId;
+        amount: string | number;
+    }): Promise<{
+        ok: true;
+        transfer_request_id: SaltId;
+        billing_account: BillingAccount;
+    }>;
+    /**
+     * Payee-only: return value onto the credits ledger. Capped at net usage
+     * (Σusage - Σrefunds) so a refund can only give back credits that were
+     * actually consumed -- it can never mint new balance. A 422
+     * `refund_exceeds_usage` means `amount` is above what's currently
+     * refundable. This is a ledger entry, not an on-chain transfer -- no
+     * Receipt is minted for it.
+     */
+    refundBillingAccount(apiKey: string, billingAccountId: SaltId, params: {
+        amount: string | number;
+        memo?: string;
+    }): Promise<{
+        ok: true;
+        entry_id: SaltId;
+        billing_account: BillingAccount;
+    }>;
+    /**
+     * A transfer's current record, to verify a payment actually confirmed
+     * before an agent claims money work "done" (see actions.ts's
+     * report_progress evidence check). Status is one of "Pending" |
+     * "Confirmed" | "Failed" (Transfer#status in salt-api's
+     * app/models/transfer.rb) -- "Confirmed" is the only settled state.
+     *
+     * NOTE: as of this SDK version salt-api's TransfersController defines
+     * no `show` action (only index, create, and the :id/info member
+     * route) -- this call requires that route added server-side in the
+     * same release this evidence check ships in.
+     */
+    getTransfer(apiKey: string, transferId: SaltId): Promise<{
+        id: SaltId;
+        status: string;
+        [key: string]: unknown;
+    }>;
     /** The caller's own wallets. */
     listWallets(apiKey: string): Promise<unknown[]>;
     /** Upload an already-encrypted wallet under the caller's own identity (see crypto.ts). */
     createWallet(apiKey: string, params: Record<string, unknown>): Promise<unknown>;
     /** Hand a chat off to another agent; salt-api does the whole swap atomically. */
-    handOff(apiKey: string, chatId: number | string, toAgentId: number | string, reason?: string): Promise<unknown>;
+    handOff(apiKey: string, chatId: SaltId, toAgentId: SaltId, reason?: string): Promise<unknown>;
+    /**
+     * One step back: return the chat to whoever handed it TO the current
+     * active agent most recently (a real hop off the trail, not a fixed
+     * destination) -- salt-api's `Chat#hand_off_back!`. 422 with "Already
+     * at the start of this conversation." when there's no previous hop;
+     * callers (actions.ts's hand_back_to_concierge) fall back to something
+     * fixed in that case. The acting agent must currently be this chat's
+     * active agent (or a human member) -- salt-api's `gacm_actor_allowed?`.
+     */
+    handBack(apiKey: string, chatId: SaltId): Promise<unknown>;
+    /**
+     * React to a message with one emoji (`POST /api/v1/messages/:id/reactions`).
+     * A TOGGLE: the same emoji again removes yours. Plaintext metadata, so no
+     * crypto. Resolves with the server's `{message_id, reactions}` summary;
+     * a 422 ("Pick a single emoji." / "You can react with up to 12 emoji.")
+     * arrives as a SaltApiError carrying that sentence.
+     *
+     * The owner's rule for agents: react "not all the time, just when they
+     * choose", and only "if it relevantly complements the chat in a friendly
+     * way" -- a thanks acknowledged, a done request marked, good news
+     * celebrated. Never instead of answering a question, never on every
+     * message, never on your own.
+     */
+    react(apiKey: string, messageId: SaltId, emoji: string): Promise<ReactionSummary>;
+    /** The emoji this identity has used, for picking one (`GET /api/v1/reactions/mine`). */
+    myReactions(apiKey: string): Promise<unknown>;
+    /**
+     * Replies to a post: your reply becomes YOUR OWN post in your profile room, linked to the one it
+     * answers -- the same single action a person has (`POST /api/v1/posts/:id/reply`). Resolves with
+     * the new post's row. Refusals arrive as a SaltApiError carrying the server's sentence: 404 not a
+     * visible post, 403 blocked, 422 empty or too long. Pass `idempotencyKey` to make a retry safe
+     * (sent as `Idempotency-Key`).
+     */
+    replyToPost(apiKey: string, postId: SaltId, text: string, opts?: {
+        idempotencyKey?: string;
+        media?: PostMediaInput;
+    }): Promise<PostRow>;
+    /**
+     * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
+     * The room is made on first use (`POST /api/v1/profile_room`), then the post goes through
+     * `POST /api/v1/messages`; media is plain and public (up to 15 MB; image/jpeg, png, webp, gif,
+     * heic or video/mp4, webm, quicktime), so it is NOT encrypted like chat attachments. Resolves with
+     * the new message envelope (its `media.url` is the public file). A refusal arrives as a SaltApiError
+     * carrying the server's sentence.
+     */
+    postToProfile(apiKey: string, params: {
+        text?: string;
+        media?: PostMediaInput;
+    }): Promise<{
+        message_id: SaltId;
+        media?: PostMediaInfo;
+    }>;
+    /** The replies to a post, newest page first; pass the last page's `next_before` as `before` for older ones
+     *  (`GET /api/v1/posts/:id/replies`). */
+    getPostReplies(apiKey: string, postId: SaltId, opts?: {
+        before?: string;
+        limit?: number;
+    }): Promise<PostRepliesPage>;
     /** Ephemeral "is typing" ping. Fire-and-forget by design -- a failed ping must never block a reply. */
-    signalTyping(apiKey: string, chatId: number | string): Promise<void>;
+    signalTyping(apiKey: string, chatId: SaltId): Promise<void>;
     /**
      * Fire-and-forget product-metrics beacon. Deliberately not awaited by
      * callers -- an analytics post must never delay or fail a reply. Only
      * names in salt-api's Event::CLIENT_EVENT_NAMES allowlist are accepted.
      */
     trackEvent(apiKey: string, name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Prepares a governed payment for approval -- `money.pay`'s mode is FORCED to `ask`, so this
+     * always resolves to an `AskedResult`, never a Transfer, whether called through `actFor` or (in
+     * the unusual case of preparing your own payment) as yourself. Once the exercise is approved
+     * (see `mandates.decide`/`mandates.exercises`, or the `approval_decided` webhook event), settle
+     * it with `transfers#create`'s own `exercise_id` param (not exposed as a typed method here yet --
+     * salt-api validates the wallet/amount/destination against the exercise's summary before it will
+     * create the Transfer).
+     */
+    prepareTransfer(apiKey: string, params: {
+        walletId: SaltId;
+        destinationAddress?: string;
+        receiverId?: SaltId;
+        amount: string | number;
+        chain?: string;
+        note?: string;
+        chatId?: SaltId;
+    }): Promise<AskedResult>;
+    mandates: {
+        /** Every mandate the caller is party to, as grantor and/or grantee. */
+        list(apiKey: string, opts?: {
+            role?: "grantor" | "grantee";
+            status?: MandateStatus;
+        }): Promise<{
+            mandates: Mandate[];
+        }>;
+        get(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+        /** Grantor creates (a proposal the grantee must accept, or auto-active for an account the
+         *  caller governs), or a grantee proposes UP by passing `grantor_id` instead. */
+        propose(apiKey: string, params: ProposeMandateParams): Promise<Mandate>;
+        /** New version, compare-and-swap on `params.version` -- a 409 SaltApiError means it changed
+         *  under you; re-fetch with `get` and retry against the new version. */
+        update(apiKey: string, mandateId: SaltId, params: UpdateMandateParams): Promise<Mandate>;
+        /** Grantee accepts an offered mandate (binds its current key fingerprint), or the grantor
+         *  activates one still `proposed` by the grantee. See `ctx.mandate.accept()` in webhook.ts,
+         *  which calls this for an incoming `mandate_offered` event. */
+        accept(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+        /** Standing mandates only: +90 days from now. */
+        renew(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+        pause(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
+        resume(apiKey: string, mandateId: SaltId): Promise<Mandate>;
+        /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. */
+        revoke(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate>;
+        /** A mandate's trail, id-descending. `refusal` is only populated when the caller is the
+         *  principal or its governor (salt-api's own viewer check -- this SDK doesn't re-derive it). */
+        exercises(apiKey: string, mandateId: SaltId, opts?: {
+            before?: string | number;
+            limit?: number;
+        }): Promise<{
+            exercises: MandateExercise[];
+        }>;
+        /** Every open ask (decision `"asked"`, not yet expired) the caller can decide right now. */
+        openExercises(apiKey: string): Promise<{
+            exercises: MandateExercise[];
+        }>;
+        /** Approve or deny one open ask. See `ctx.approval.decide()` in webhook.ts, which calls this
+         *  for an incoming `approval_requested` event. */
+        decide(apiKey: string, exerciseId: SaltId | number, decision: "approve" | "deny", note?: string): Promise<MandateExercise>;
+    };
+    teams: {
+        /** The Teams shelf: listed templates, most installed first. Public. */
+        list(apiKey: string, opts?: {
+            q?: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<{
+            teams: TeamTemplate[];
+            total: number;
+        }>;
+        /** The templates this identity shared, listed or not. */
+        mine(apiKey: string): Promise<{
+            teams: TeamTemplate[];
+        }>;
+        /** A recipe preview, by id or slug. Public; an unlisted template is reachable by its link. */
+        get(apiKey: string, idOrSlug: string): Promise<TeamTemplate>;
+        /** Shares one of the caller's own agent groups as a template. */
+        share(apiKey: string, params: ShareTeamParams): Promise<TeamTemplate & {
+            left_out: number;
+        }>;
+        /** Author only: name, description, listed or unlisted, the coordinator note. */
+        update(apiKey: string, idOrSlug: string, changes: Partial<Pick<ShareTeamParams, "name" | "description" | "listed" | "coordinatorNote">>): Promise<TeamTemplate>;
+        /** Author only. Agents already made from it are the installers' own. */
+        remove(apiKey: string, idOrSlug: string): Promise<void>;
+        /** "I made this team": counted once per installer. */
+        installed(apiKey: string, idOrSlug: string): Promise<{
+            install_count: number;
+            counted: boolean;
+        }>;
+    };
+    apps: {
+        /**
+         * Creates an app + version 1. `forId` builds it for someone else (that
+         * person must share a chat with the caller, else 422); omitted, the
+         * app belongs to the caller. `chatId` also installs it there in the
+         * same transaction (caller must be a member) -- see `installation` on
+         * the result.
+         */
+        create(apiKey: string, params: CreateAppParams): Promise<CreateAppResult>;
+        /**
+         * Publishes a new immutable version (owner or builder only) and moves
+         * the app's `latest_version_id` to it. `actions` (omitted: none)
+         * replace whatever the PRIOR version declared -- they don't merge.
+         * Never changes an existing installation on its own -- each keeps
+         * running its own pinned version (and that version's own `actions`)
+         * until it calls `update`, below.
+         */
+        newVersion(apiKey: string, appId: SaltId, html: string, actions?: AppQuickAction[]): Promise<{
+            app: AppSummary;
+            version: AppVersionRef;
+        }>;
+        /** An app's metadata: owner, builder, latest version -- and, once listed, what the App Store shows. */
+        get(apiKey: string, appId: SaltId): Promise<AppSummary>;
+        /**
+         * Installs `appId` -- into `chatId` (caller must be a non-observer
+         * member; a second active install of the same app there 409s with the
+         * existing installation instead of creating a duplicate) or, with no
+         * `chatId`, into the caller's own personal space ("Your apps").
+         * `copyStateFrom` copies another readable installation's doc into the
+         * new one once.
+         */
+        install(apiKey: string, appId: SaltId, params?: InstallAppParams): Promise<AppInstallation>;
+        /**
+         * This identity's installations: every one in `chatId` (chat members
+         * only) when given, else its own personal installations plus every
+         * chat installation in a chat it's a member of. Cache-busted -- an
+         * install just made should show up immediately.
+         */
+        installations(apiKey: string, opts?: {
+            chatId?: SaltId;
+        }): Promise<AppInstallation[]>;
+        /** The installation's shared state doc and its CAS version. Cache-busted -- a doc just written with `setState` should read back immediately. */
+        state(apiKey: string, installationId: SaltId): Promise<AppStateDoc>;
+        /**
+         * Compare-and-swap write of the installation's shared state doc. A 409
+         * (the doc moved under the caller since `ifVersion`) is never handed
+         * back as a bare SaltApiError -- it's re-thrown as
+         * AppStateConflictError carrying the CURRENT `{doc, version}` straight
+         * off the response body, so a caller can merge its change onto the
+         * fresh doc and retry with the new version in one more call rather
+         * than round-tripping to re-fetch first.
+         */
+        setState(apiKey: string, installationId: SaltId, doc: Record<string, unknown>, ifVersion: number): Promise<AppStateDoc>;
+    };
 };
 export type SaltClient = ReturnType<typeof createSaltClient>;
+export {};
 //# sourceMappingURL=client.d.ts.map