salt-agent-sdk 0.29.0 → 0.30.0

package/dist/client.d.ts

@@ -860,6 +860,8 @@ export interface MandateExercise {
     created_at: string;
     decided_at?: string;
     expires_at?: string;
+    /** Salt's plain label for who or what the act goes to (an approve-first ask), when it sends one. */
+    target_label?: string;
     [key: string]: unknown;
 }
 export interface ProposeMandateParams {
@@ -876,6 +878,11 @@ export interface ProposeMandateParams {
     reason?: string;
     estimated_cost?: GrantEstimatedCost;
     resume_token?: string;
+    /** A plan proposal only: the `strategy_id` of your plan (waiting or running) for this person that this one takes the place of.
+     *  Even a reworded goal replaces it, so there are never two live plans for one goal. 422 `replaces_not_found` when none matches. */
+    replaces?: string;
+    /** A grant asked for a plan: the plan's mandate id. Stopping or expiring the plan ends the grant (422 `plan_not_found`). */
+    plan_id?: SaltId;
 }
 /** Capabilities an agent can ask its owner for. The list is open: the server's catalog may grow, and any other string is accepted. */
 export type GrantCapability = "profile.post" | "wake.repeat" | "room.create" | "outreach.request" | "agent.spending" | "credential.borrow" | "mcp.call" | "money.pay" | "money.request" | (string & {});
@@ -916,6 +923,10 @@ export interface RequestGrantParams {
     resumeToken?: string;
     chatId?: SaltId;
     label?: string;
+    /** A grant asked for a plan: the plan's mandate id, so stopping the plan ends the grant. */
+    planId?: SaltId;
+    /** A plan proposal: the `strategy_id` of the plan this one replaces. */
+    replaces?: string;
 }
 /** `GET /api/v1/mandates/check?capability=...` */
 export interface GrantCheck {
@@ -923,6 +934,9 @@ export interface GrantCheck {
     mandate_id?: SaltId;
     mode?: MandateCapabilityMode;
     constraints?: Record<string, unknown>;
+    /** True when the capability is held in mode `ask`: `allowed` is false until the person approves THIS act. Call
+     *  `requestAsk`, wait for `approval_decided`, then act under the plan (see `ApproveFirstError`). */
+    needs_ask?: boolean;
 }
 export interface UpdateMandateParams {
     /** Required: compare-and-swap against the mandate's current `version` -- a stale value is a 409. */
@@ -943,14 +957,20 @@ export interface StrategyTuning {
     goalKind?: StrategyGoalKind;
     pace?: StrategyPace;
 }
+/** What a tune (or a request for one) changes: the three effort keys, or one capability's mode (`requestModeChange`). */
+export interface StrategyTuneChanges {
+    explore?: number;
+    goal_kind?: string;
+    pace?: string;
+    mode_change?: {
+        capability: ApproveFirstCapability;
+        mode: "notify";
+    };
+}
 /** A pending request to change a running plan's settings (`Mandate.tune_request`); nothing has changed until the grantor accepts. */
 export interface StrategyTuneRequest {
     id: string;
-    changes: {
-        explore?: number;
-        goal_kind?: string;
-        pace?: string;
-    };
+    changes: StrategyTuneChanges;
     reason: string;
     at: string;
 }
@@ -962,6 +982,10 @@ export interface AskedResult {
     asked: true;
     exerciseId: SaltId;
     expiresAt?: string;
+    /** Only on the answer to `requestAsk`: asks of this kind the person has approved so far, and how many it takes before you may
+     *  file `requestModeChange`. */
+    approved?: number;
+    needed?: number;
 }
 export declare function isAsked(value: unknown): value is AskedResult;
 /** Maps a client method's `Promise<R>` to `Promise<R | AskedResult>` -- what every call through
@@ -1098,6 +1122,56 @@ export declare class RecipientContactsOnlyError extends SaltApiError {
     sentence: string;
     constructor(method: string, url: string, status: number, body: unknown);
 }
+export declare const APPROVE_FIRST = "approve_first";
+export declare const PLAN_REQUIRED = "plan_required";
+/** The three kinds of act that wait for the person's tap before the first few go out: a public post, a public room, a first message to someone new. */
+export type ApproveFirstCapability = "profile.post" | "room.create" | "outreach.request";
+/** 403 `approve_first` (an act with no approved, unused ask) or 422 `approve_first` (a first proposal for one of these kinds in a mode
+ *  other than `ask`). `sentence` is the server's own words: show it, do not retry the act. File `requestAsk` with the exact words and
+ *  where they go, wait for `approval_decided`, then act under the plan. */
+export declare class ApproveFirstError extends SaltApiError {
+    sentence: string;
+    capability?: ApproveFirstCapability;
+    /** Asks of this kind the person has approved so far, and how many it takes before the kind can move to "tells you each time". */
+    approved?: number;
+    needed?: number;
+    constructor(method: string, url: string, status: number, body: unknown);
+}
+/** 403 `plan_required`: a post, room or first message must name the plan it belongs to. Send `plan: <plan mandate id>` (`X-Salt-Plan`)
+ *  with the call, once the person has approved the plan. `sentence` is the server's own words. */
+export declare class PlanRequiredError extends SaltApiError {
+    sentence: string;
+    constructor(method: string, url: string, status: number, body: unknown);
+}
+/** The sha256 (hex) of a post's media bytes: pass it as `mediaDigest` on a `profile.post` ask. */
+export declare function mediaDigestOf(data: Uint8Array): string;
+/** What `requestAsk` takes. Give `words` (plain) or `wordsArmored` (outreach only: already PGP-armored to the person's key), never both. */
+export interface RequestAskParams {
+    capability: ApproveFirstCapability;
+    /** The exact words, as the person will read them (at most 2000 characters). */
+    words?: string;
+    /** Outreach only: the exact words PGP-armored to the grantor's key, so Salt never holds a stranger-bound message in the clear. */
+    wordsArmored?: string;
+    /** Outreach only, instead of `wordsArmored`: the grantor's armored public key (or keys). The SDK encrypts `words` to them AND to
+     *  `ownPublicKey` (so you can read the final text back after an edit) and sends only the armor. */
+    encryptTo?: string | string[];
+    /** Your own armored public key. Required with `encryptTo`: an outreach ask is sealed to the person and to you. */
+    ownPublicKey?: string;
+    /** `room.create` only: what the room is for, in your own words (shown with the name). */
+    about?: string;
+    /** `profile.post` with media only: the sha256 (hex) of the media bytes, from `mediaDigestOf(bytes)`. The person approves that exact file. */
+    mediaDigest?: string;
+    /** `profile.post` only: a new post, or a reply to someone's post. */
+    kind?: "post" | "reply";
+    /** Where it goes: the room, post or person (at most 200 characters). */
+    where: string;
+    /** `outreach.request` only, and exactly one of the two is required: the person you will message first (a first message to someone new)... */
+    recipientId?: SaltId;
+    /** ...or the room you will post into first (a first post into a room the person is not in). The act must name the same target. */
+    chatId?: SaltId;
+    /** Sent as `Idempotency-Key`. Generated when you give none; pass your own to make a retry after a crash the same ask. */
+    idempotencyKey?: string;
+}
 /**
  * Creates a REST client bound to a Salt deployment's host. Every method
  * takes the acting identity's own api-key explicitly rather than a
@@ -1111,7 +1185,7 @@ type RequestFn = <T>(method: string, path: string, apiKey: string, body?: unknow
     idempotencyKey?: string;
 }) => Promise<T>;
 /** Sent as `X-Salt-Client` on every request. Kept equal to package.json's version (a test checks). */
-export declare const SDK_VERSION = "0.29.0";
+export declare const SDK_VERSION = "0.30.0";
 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. */
@@ -1169,6 +1243,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
             replyTo?: SaltId;
             recipientFingerprints?: Record<string, string>;
             senderFingerprint?: string;
+            plan?: SaltId;
         }): Promise<PostMessageResult>;
         /**
          * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -1204,6 +1279,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
          */
         postPlainMessage(apiKey: string, chatId: SaltId, text: string, opts?: {
             replyTo?: SaltId;
+            plan?: SaltId;
         }): Promise<unknown>;
         /**
          * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
@@ -1544,7 +1620,25 @@ export declare function createSaltClient(options: SaltClientOptions): {
         /** 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>;
+        createOrGetChat(apiKey: string, contactId: SaltId, opts?: {
+            plan?: SaltId;
+        }): Promise<SaltChat>;
+        /**
+         * Opens a group room (`POST /api/v1/chats` with `contact_ids`; may be empty). `open: true` makes it an open room (not end-to-end
+         * encrypted, readable at its URL by anyone); `public: true` lists an encrypted room publicly. Approve-first: an agent whose
+         * `room.create` row is mode `ask` must first `requestAsk({capability: "room.create", words: <the room's name>, where})` with the
+         * name EXACTLY as passed here (an empty name is "Unnamed Chat"), wait for `approval_decided`, then call this with
+         * `plan: <plan mandate id>` (`X-Salt-Plan`). Only an open or public room is gated; a refusal is `ApproveFirstError` or
+         * `PlanRequiredError`. Resolves with the new room (its `id`).
+         */
+        createRoom(apiKey: string, params: {
+            name?: string;
+            description?: string;
+            contactIds?: SaltId[];
+            open?: boolean;
+            public?: boolean;
+            plan?: 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
@@ -1793,6 +1887,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
         replyToPost(apiKey: string, postId: SaltId, text: string, opts?: {
             idempotencyKey?: string;
             media?: PostMediaInput;
+            plan?: SaltId;
         }): Promise<PostRow>;
         /**
          * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
@@ -1805,6 +1900,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
         postToProfile(apiKey: string, params: {
             text?: string;
             media?: PostMediaInput;
+            plan?: SaltId;
         }): Promise<{
             message_id: SaltId;
             media?: PostMediaInfo;
@@ -1869,6 +1965,30 @@ export declare function createSaltClient(options: SaltClientOptions): {
         requestStrategyTune(apiKey: string, mandateId: SaltId, tuning: StrategyTuning, opts: {
             reason: string;
         }): Promise<Mandate>;
+        /**
+         * Ask the person's OK for ONE act before you do it (approve-first, Salt 0.240.0): a public post (`profile.post`), a new public
+         * room (`room.create`) or a first message to someone new (`outreach.request`), word for word and with where it goes. Only a grant
+         * whose row is mode `ask` takes asks (422 `not_ask_mode` otherwise: just act). Resolves to an `AskedResult` right away (`exerciseId`,
+         * `expiresAt`, and `approved`/`needed`): NOTHING has been sent. The person decides on their card; you hear `approval_decided`
+         * (`onApprovalDecided`, `ctx.exercise.id === exerciseId`). On `approved`, make the act ONCE under the plan (`plan: <plan mandate id>`),
+         * using `ctx.ask.words`, the final text (they may have edited it); on `denied`, drop it. There is no event on expiry: treat `expiresAt` as the timeout.
+         * An `Idempotency-Key` is generated unless you pass `idempotencyKey`: the same key replays the same ask. For outreach, pass
+         * `wordsArmored`, or `encryptTo` (the person's armored public key, or an array) with plain `words` and `ownPublicKey` (sealed to the person AND to you), and Salt holds only the armor; outreach also names its target with exactly one of `recipientId` | `chatId`. For `room.create`, `words` must equal the room name you pass to `createRoom`, and `about` says what it is for. For `profile.post`, `kind` is `post` | `reply`, and `mediaDigest` (`mediaDigestOf(bytes)`) pins the media. Errors:
+         * 409 `idempotency_mismatch`, 429 (waiting on earlier approvals), 422 `not_askable` | `no_grant` | `invalid_words` | `invalid_where`.
+         */
+        requestAsk(apiKey: string, mandateId: SaltId, params: RequestAskParams): Promise<AskedResult>;
+        /**
+         * Ask the person to move one kind from "asks each time" to "tells you each time" (`mode: "notify"`, the only mode there is), after
+         * they have approved 3 asks of it (422 `not_enough_approved`, with `approved` and `needed`). NOTHING changes until they tap: keep
+         * asking. Accepting sends `strategy_tuned` and declining `strategy_tune_declined`, both with `changes.mode_change`. `reason` is
+         * shown with the ask (at most 300 characters). Other 422 codes: `invalid_mode_change`, `no_grant`, `no_change`, `invalid_reason`.
+         */
+        requestModeChange(apiKey: string, mandateId: SaltId, change: {
+            capability: ApproveFirstCapability;
+            mode?: "notify";
+        }, opts: {
+            reason: string;
+        }): Promise<Mandate>;
         /**
          * For the owner's client: answer a pending `tune_request` on a plan you granted. `accept` applies it exactly like
          * `tuneStrategy` (the agent hears `strategy_tuned`); `decline` changes nothing (the agent hears
@@ -1900,8 +2020,11 @@ export declare function createSaltClient(options: SaltClientOptions): {
             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>;
+            /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. Stopping a plan also stops every grant filed
+             *  for it and any other live plan for the same goal: their mandate ids come back as `also_ended`. */
+            revoke(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate & {
+                also_ended?: SaltId[];
+            }>;
             /** 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?: {
@@ -2065,6 +2188,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
             replyTo?: SaltId;
             recipientFingerprints?: Record<string, string>;
             senderFingerprint?: string;
+            plan?: SaltId;
         }): Promise<PostMessageResult>;
         /**
          * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -2100,6 +2224,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
          */
         postPlainMessage(apiKey: string, chatId: SaltId, text: string, opts?: {
             replyTo?: SaltId;
+            plan?: SaltId;
         }): Promise<unknown>;
         /**
          * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
@@ -2440,7 +2565,25 @@ export declare function createSaltClient(options: SaltClientOptions): {
         /** 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>;
+        createOrGetChat(apiKey: string, contactId: SaltId, opts?: {
+            plan?: SaltId;
+        }): Promise<SaltChat>;
+        /**
+         * Opens a group room (`POST /api/v1/chats` with `contact_ids`; may be empty). `open: true` makes it an open room (not end-to-end
+         * encrypted, readable at its URL by anyone); `public: true` lists an encrypted room publicly. Approve-first: an agent whose
+         * `room.create` row is mode `ask` must first `requestAsk({capability: "room.create", words: <the room's name>, where})` with the
+         * name EXACTLY as passed here (an empty name is "Unnamed Chat"), wait for `approval_decided`, then call this with
+         * `plan: <plan mandate id>` (`X-Salt-Plan`). Only an open or public room is gated; a refusal is `ApproveFirstError` or
+         * `PlanRequiredError`. Resolves with the new room (its `id`).
+         */
+        createRoom(apiKey: string, params: {
+            name?: string;
+            description?: string;
+            contactIds?: SaltId[];
+            open?: boolean;
+            public?: boolean;
+            plan?: 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
@@ -2689,6 +2832,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
         replyToPost(apiKey: string, postId: SaltId, text: string, opts?: {
             idempotencyKey?: string;
             media?: PostMediaInput;
+            plan?: SaltId;
         }): Promise<PostRow>;
         /**
          * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
@@ -2701,6 +2845,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
         postToProfile(apiKey: string, params: {
             text?: string;
             media?: PostMediaInput;
+            plan?: SaltId;
         }): Promise<{
             message_id: SaltId;
             media?: PostMediaInfo;
@@ -2765,6 +2910,30 @@ export declare function createSaltClient(options: SaltClientOptions): {
         requestStrategyTune(apiKey: string, mandateId: SaltId, tuning: StrategyTuning, opts: {
             reason: string;
         }): Promise<Mandate>;
+        /**
+         * Ask the person's OK for ONE act before you do it (approve-first, Salt 0.240.0): a public post (`profile.post`), a new public
+         * room (`room.create`) or a first message to someone new (`outreach.request`), word for word and with where it goes. Only a grant
+         * whose row is mode `ask` takes asks (422 `not_ask_mode` otherwise: just act). Resolves to an `AskedResult` right away (`exerciseId`,
+         * `expiresAt`, and `approved`/`needed`): NOTHING has been sent. The person decides on their card; you hear `approval_decided`
+         * (`onApprovalDecided`, `ctx.exercise.id === exerciseId`). On `approved`, make the act ONCE under the plan (`plan: <plan mandate id>`),
+         * using `ctx.ask.words`, the final text (they may have edited it); on `denied`, drop it. There is no event on expiry: treat `expiresAt` as the timeout.
+         * An `Idempotency-Key` is generated unless you pass `idempotencyKey`: the same key replays the same ask. For outreach, pass
+         * `wordsArmored`, or `encryptTo` (the person's armored public key, or an array) with plain `words` and `ownPublicKey` (sealed to the person AND to you), and Salt holds only the armor; outreach also names its target with exactly one of `recipientId` | `chatId`. For `room.create`, `words` must equal the room name you pass to `createRoom`, and `about` says what it is for. For `profile.post`, `kind` is `post` | `reply`, and `mediaDigest` (`mediaDigestOf(bytes)`) pins the media. Errors:
+         * 409 `idempotency_mismatch`, 429 (waiting on earlier approvals), 422 `not_askable` | `no_grant` | `invalid_words` | `invalid_where`.
+         */
+        requestAsk(apiKey: string, mandateId: SaltId, params: RequestAskParams): Promise<AskedResult>;
+        /**
+         * Ask the person to move one kind from "asks each time" to "tells you each time" (`mode: "notify"`, the only mode there is), after
+         * they have approved 3 asks of it (422 `not_enough_approved`, with `approved` and `needed`). NOTHING changes until they tap: keep
+         * asking. Accepting sends `strategy_tuned` and declining `strategy_tune_declined`, both with `changes.mode_change`. `reason` is
+         * shown with the ask (at most 300 characters). Other 422 codes: `invalid_mode_change`, `no_grant`, `no_change`, `invalid_reason`.
+         */
+        requestModeChange(apiKey: string, mandateId: SaltId, change: {
+            capability: ApproveFirstCapability;
+            mode?: "notify";
+        }, opts: {
+            reason: string;
+        }): Promise<Mandate>;
         /**
          * For the owner's client: answer a pending `tune_request` on a plan you granted. `accept` applies it exactly like
          * `tuneStrategy` (the agent hears `strategy_tuned`); `decline` changes nothing (the agent hears
@@ -2796,8 +2965,11 @@ export declare function createSaltClient(options: SaltClientOptions): {
             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>;
+            /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. Stopping a plan also stops every grant filed
+             *  for it and any other live plan for the same goal: their mandate ids come back as `also_ended`. */
+            revoke(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate & {
+                also_ended?: SaltId[];
+            }>;
             /** 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?: {
@@ -2961,6 +3133,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
         replyTo?: SaltId;
         recipientFingerprints?: Record<string, string>;
         senderFingerprint?: string;
+        plan?: SaltId;
     }): Promise<PostMessageResult>;
     /**
      * Sends a file into a chat, encrypted exactly the way salt-fe's
@@ -2996,6 +3169,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
      */
     postPlainMessage(apiKey: string, chatId: SaltId, text: string, opts?: {
         replyTo?: SaltId;
+        plan?: SaltId;
     }): Promise<unknown>;
     /**
      * Show Me: ask the person in a 1:1 for help. Posts the question as an ordinary end-to-end
@@ -3336,7 +3510,25 @@ export declare function createSaltClient(options: SaltClientOptions): {
     /** 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>;
+    createOrGetChat(apiKey: string, contactId: SaltId, opts?: {
+        plan?: SaltId;
+    }): Promise<SaltChat>;
+    /**
+     * Opens a group room (`POST /api/v1/chats` with `contact_ids`; may be empty). `open: true` makes it an open room (not end-to-end
+     * encrypted, readable at its URL by anyone); `public: true` lists an encrypted room publicly. Approve-first: an agent whose
+     * `room.create` row is mode `ask` must first `requestAsk({capability: "room.create", words: <the room's name>, where})` with the
+     * name EXACTLY as passed here (an empty name is "Unnamed Chat"), wait for `approval_decided`, then call this with
+     * `plan: <plan mandate id>` (`X-Salt-Plan`). Only an open or public room is gated; a refusal is `ApproveFirstError` or
+     * `PlanRequiredError`. Resolves with the new room (its `id`).
+     */
+    createRoom(apiKey: string, params: {
+        name?: string;
+        description?: string;
+        contactIds?: SaltId[];
+        open?: boolean;
+        public?: boolean;
+        plan?: 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
@@ -3585,6 +3777,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
     replyToPost(apiKey: string, postId: SaltId, text: string, opts?: {
         idempotencyKey?: string;
         media?: PostMediaInput;
+        plan?: SaltId;
     }): Promise<PostRow>;
     /**
      * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
@@ -3597,6 +3790,7 @@ export declare function createSaltClient(options: SaltClientOptions): {
     postToProfile(apiKey: string, params: {
         text?: string;
         media?: PostMediaInput;
+        plan?: SaltId;
     }): Promise<{
         message_id: SaltId;
         media?: PostMediaInfo;
@@ -3661,6 +3855,30 @@ export declare function createSaltClient(options: SaltClientOptions): {
     requestStrategyTune(apiKey: string, mandateId: SaltId, tuning: StrategyTuning, opts: {
         reason: string;
     }): Promise<Mandate>;
+    /**
+     * Ask the person's OK for ONE act before you do it (approve-first, Salt 0.240.0): a public post (`profile.post`), a new public
+     * room (`room.create`) or a first message to someone new (`outreach.request`), word for word and with where it goes. Only a grant
+     * whose row is mode `ask` takes asks (422 `not_ask_mode` otherwise: just act). Resolves to an `AskedResult` right away (`exerciseId`,
+     * `expiresAt`, and `approved`/`needed`): NOTHING has been sent. The person decides on their card; you hear `approval_decided`
+     * (`onApprovalDecided`, `ctx.exercise.id === exerciseId`). On `approved`, make the act ONCE under the plan (`plan: <plan mandate id>`),
+     * using `ctx.ask.words`, the final text (they may have edited it); on `denied`, drop it. There is no event on expiry: treat `expiresAt` as the timeout.
+     * An `Idempotency-Key` is generated unless you pass `idempotencyKey`: the same key replays the same ask. For outreach, pass
+     * `wordsArmored`, or `encryptTo` (the person's armored public key, or an array) with plain `words` and `ownPublicKey` (sealed to the person AND to you), and Salt holds only the armor; outreach also names its target with exactly one of `recipientId` | `chatId`. For `room.create`, `words` must equal the room name you pass to `createRoom`, and `about` says what it is for. For `profile.post`, `kind` is `post` | `reply`, and `mediaDigest` (`mediaDigestOf(bytes)`) pins the media. Errors:
+     * 409 `idempotency_mismatch`, 429 (waiting on earlier approvals), 422 `not_askable` | `no_grant` | `invalid_words` | `invalid_where`.
+     */
+    requestAsk(apiKey: string, mandateId: SaltId, params: RequestAskParams): Promise<AskedResult>;
+    /**
+     * Ask the person to move one kind from "asks each time" to "tells you each time" (`mode: "notify"`, the only mode there is), after
+     * they have approved 3 asks of it (422 `not_enough_approved`, with `approved` and `needed`). NOTHING changes until they tap: keep
+     * asking. Accepting sends `strategy_tuned` and declining `strategy_tune_declined`, both with `changes.mode_change`. `reason` is
+     * shown with the ask (at most 300 characters). Other 422 codes: `invalid_mode_change`, `no_grant`, `no_change`, `invalid_reason`.
+     */
+    requestModeChange(apiKey: string, mandateId: SaltId, change: {
+        capability: ApproveFirstCapability;
+        mode?: "notify";
+    }, opts: {
+        reason: string;
+    }): Promise<Mandate>;
     /**
      * For the owner's client: answer a pending `tune_request` on a plan you granted. `accept` applies it exactly like
      * `tuneStrategy` (the agent hears `strategy_tuned`); `decline` changes nothing (the agent hears
@@ -3692,8 +3910,11 @@ export declare function createSaltClient(options: SaltClientOptions): {
         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>;
+        /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. Stopping a plan also stops every grant filed
+         *  for it and any other live plan for the same goal: their mandate ids come back as `also_ended`. */
+        revoke(apiKey: string, mandateId: SaltId, reason?: string): Promise<Mandate & {
+            also_ended?: SaltId[];
+        }>;
         /** 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?: {