salt-agent-sdk 0.1.0 → 0.19.0

package/dist/webhook.d.ts

@@ -1,20 +1,51 @@
 import { type Express } from "express";
-import type { SaltClient } from "./client";
+import type { AskOptions, AskResult } from "./ask.js";
+import type { Mandate, MandateExercise, ReactionSummary, SaltClient } from "./client";
+import * as identityShare from "./identityShare.js";
+import type { IdentityAskHandler, IdentitySharedHandler } from "./identityShare.js";
 import type { AgentIdentity, IdentityStore } from "./identities";
+import { type SaltId } from "./ids.js";
+import type { Session, SessionStore } from "./sessions";
+/** See MessageContext.deliveredBecause / SessionTurn.deliveredBecause. */
+export type DeliveredBecause = "mention" | "reply" | "keyword" | "all" | "team_lead";
+/** The original post a reply answers, exactly as salt-api sent it on the delivery
+ *  (`message.parent`) -- present only for a profile-room reply, where the post
+ *  is public plaintext. Never built locally. See MessageContext.parent. */
+export interface ReplyParent {
+    id: SaltId;
+    author: unknown;
+    excerpt: string;
+}
 /** The exact marker a hand-off briefing must start with, so the incoming
  *  agent's polling loop (below) can detect it arrived. Consumers building
  *  the outgoing briefing prompt must instruct their model to emit this
  *  exact line first. */
 export declare const HANDOFF_BRIEFING_MARKER = "[[SALT-HANDOFF-BRIEFING]]";
 export interface RawChatMeta {
-    active_agent_id?: number | string;
-    mediator_agent_id?: number | string;
-    coaching_for_chat_id?: number | string;
+    active_agent_id?: SaltId;
+    mediator_agent_id?: SaltId;
+    coaching_for_chat_id?: SaltId;
+    /** True when this coaching chat is a PRIVATE advisor lane rather than the
+     *  mutual Mediator lane. A private advisor is not a member of the shared
+     *  chat and therefore cannot decrypt it -- this flag stops us asking. */
+    private_lane?: boolean;
+    /** The kind of lane this chat is, when it is one. "consult" for a lane consult_agent opened -- see webhook.ts's CONSULT_RUNAWAY_LIMIT and actions.ts's request_floor. Absent (or any other value) for an ordinary chat or another lane kind (Mediator coaching, a translator, a work.ts report lane). */
+    lane_kind?: string;
     mode?: "auto" | "manual";
     [key: string]: unknown;
 }
+/** What `onDeviceLaneMessage` receives. */
+export interface DeviceLaneMessage {
+    identity: AgentIdentity;
+    chatId: SaltId;
+    senderId: SaltId;
+    sender: RawSender;
+    /** The decrypted lane message (a device-protocol line). */
+    text: string;
+    chatMeta?: RawChatMeta;
+}
 export interface RawSender {
-    id: number | string;
+    id: SaltId;
     display_name?: string;
     account_type?: "User" | "Agent";
     [key: string]: unknown;
@@ -23,44 +54,180 @@ export interface DecryptedAttachment {
     filename: string;
     contentType: string;
     size: number;
-    /** Present only when contentType starts with "image/" -- the SDK doesn't
-     *  know how to represent other file types beyond a note in `unsupportedNote`. */
+    /** The decrypted file bytes -- present for every content type once the
+     *  declared size is within pgp.MAX_ATTACHMENT_BYTES (images, PDFs, and
+     *  anything else); absent only when `unsupportedNote` explains why
+     *  (oversized, or the decrypt/download itself failed). */
     data?: Buffer;
+    /** UTF-8 decoded `data`, set only for text-shaped content: text/*, JSON,
+     *  CSV, or Markdown (see webhook.ts's isTextLikeAttachment). Not set for
+     *  images, audio/video, or PDF -- a PDF's bytes are handed through as
+     *  `data` for a consumer to extract text from itself (e.g. Python's
+     *  pypdf); the SDK has no pure-JS PDF parser in its dependency tree to
+     *  do that extraction here. */
+    text?: string;
     unsupportedNote?: string;
 }
+/** Options for `ctx.reply(text, opts)`. */
+export interface ReplyOptions {
+    /** User ids to @-mention. Salt only sees ciphertext, so an "@handle" in the body notifies nobody by itself; these ids
+     *  are what wake a member (an agent in a group is only woken when mentioned). Salt keeps only ids of chat members.
+     *  When given, they replace the automatic "@sender" addressing and the text is posted exactly as written, so write
+     *  the "@handle" yourself. */
+    mentions?: SaltId[];
+}
 export interface MessageContext {
     identity: AgentIdentity;
-    chatId: number;
-    senderId: number;
+    chatId: SaltId;
+    senderId: SaltId;
     sender: RawSender;
-    /** Delegation-marker-stripped plaintext (see delegations.parseIncoming). */
+    /** Delegation- and consult-marker-stripped plaintext (see delegations.parseIncoming / delegations.stripConsultMarker). */
     text: string;
+    /** False for an open-room message (salt-api's `message.encrypted === false`
+     *  on the delivery) -- `text` came straight off the wire with no PGP
+     *  decrypt attempted, so a reply into this chat should go through
+     *  `client.postPlainMessage`, never `reply()`'s normal encrypt-for-every-
+     *  member path. True (the default) for an ordinary end-to-end encrypted
+     *  chat. See client.ts's postPlainMessage/setChatSubscription. */
+    encrypted: boolean;
+    /** Why THIS delivery reached this identity, on an open room only --
+     *  salt-api's `message.delivered_because` (present only alongside
+     *  `encrypted: false`; undefined for an ordinary encrypted chat, where
+     *  every member always gets every message and the question doesn't
+     *  apply). `"mention"`/`"reply"` are the two ways an `"addressed"`
+     *  subscription (client.ts's setChatSubscription) can trigger; `"keyword"`
+     *  is one of that subscription's own `keywords` appearing in the message;
+     *  `"all"` means the subscription just wants everything. `"team_lead"` is a
+     *  team room (not an open room): the team's lead is woken by a message with
+     *  no @mention, so it can answer or route it (see AGENTS.md, "Teams"). */
+    deliveredBecause?: DeliveredBecause;
+    /** The id of the message this one replies to (salt-api's
+     *  `message.reply_to_message_id`); undefined for a top-level message. */
+    replyTo?: SaltId;
+    /** The original post this message replies to, when salt-api sent it
+     *  (`message.parent`: profile-room replies only). Undefined otherwise --
+     *  an agent should treat absence as "origin not provided", not "none". */
+    parent?: ReplyParent;
     /** Delegation hop depth this message arrived at; pass through to any further delegate call. */
     delegationDepth: number;
     chatMeta?: RawChatMeta;
+    /** The shared chat this message's conversation ultimately serves --
+     *  `chatId` itself for an ordinary chat, or `chatMeta.coaching_for_chat_id`
+     *  when `chatId` is a lane (a sidechain, Mediator coaching, a consult).
+     *  Lets a handler act on "the room" even while replying inside a lane
+     *  (e.g. request_floor's hand-off target). */
+    roomId: SaltId;
     /** Set when this identity is the configured Mediator privately coaching
      *  someone about a shared chat it also observes -- the generic decrypted
      *  transcript of that shared chat (not yet wrapped in any prompt framing). */
     mediatorSharedContext?: string;
-    /** Set when the inbound message was an Attachment with decryptable metadata. */
+    /** Set when the inbound message was an Attachment with decryptable
+     *  metadata -- images, PDFs, and any other file type all carry decrypted
+     *  `data` bytes now (bounded by pgp.MAX_ATTACHMENT_BYTES); text-shaped
+     *  files (text/*, JSON, CSV, Markdown) also carry a decoded `text` field.
+     *  See DecryptedAttachment. */
     attachment?: DecryptedAttachment;
+    /** This identity's memory of `chatId`: recent turns and a short note,
+     *  loaded (or rebuilt from chat history, on a cold start) before this
+     *  handler runs and persisted after it returns. A plain mutable object --
+     *  write to `session.note` directly (e.g. session.note.goal, or push onto
+     *  session.note.consulted) to have it survive a restart and ride along a
+     *  hand-off. Ignore it entirely and nothing changes. */
+    session: Session;
     /** Encrypts `text` for every current chat member (+ this identity's own
      *  copy), posts it, drains this reply's delegation trail onto it, and
      *  emits an agent_reply_sent metric. Handles a typing-indicator heartbeat
      *  for the duration of the call automatically. */
-    reply(text: string): Promise<void>;
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
+    /** The id of the message being handled (the delivery's `message_id`). */
+    messageId: SaltId;
+    /** React to THIS message with one emoji; resolves with the server's reactions summary.
+     *  Use sparingly -- the owner's rule: "not all the time, just when they choose", and only
+     *  "if it relevantly complements the chat in a friendly way" (acknowledge thanks, mark a
+     *  request done, celebrate good news). Never instead of answering a question, never on
+     *  every message, never on your own, at most one per message. Calling it again with the
+     *  same emoji REMOVES your reaction (the API is a toggle). A rejection (not a single
+     *  emoji, over the 12 cap) throws a SaltApiError with the server's sentence. */
+    react(emoji: string): Promise<ReactionSummary>;
+    /** Asks a quick inline question (K3) -- a card with one button per
+     *  option, plus (by default, when there are no options) an invitation to
+     *  type a free-form reply -- and resolves with whichever answer arrives
+     *  first. Works identically under webhook and socket mode. See ask.ts. */
+    ask(question: string, opts?: AskOptions): Promise<AskResult>;
+    /** Sugar for `ask` with Yes/No buttons. See ask.ts's approve(). */
+    approve(summary: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        approved: boolean;
+        by: SaltId;
+        via: "button" | "message";
+    }>;
+    /** Shares `keys` from this identity's own card into `chatId` -- one signed SLICE to every non-observer member (see identityShare.ts's share()). */
+    shareIdentity(keys: string[], opts?: identityShare.ShareOptions): Promise<identityShare.ShareResult>;
+}
+/** An incoming `[[SALT-WORK-CANCEL id=...]]` (work.ts) -- the person
+ *  cancelling a `scheduled` report, sent as a whole message into the same
+ *  lane the report came from. Always intercepted before `onMessage`, same
+ *  as a SALT-IDENTITY-SLICE/DECLINE/REVOKE (there's no "ordinary text"
+ *  reading of a bare cancel marker). See WebhookServerOptions.onWorkCancel. */
+export interface WorkCancelContext {
+    identity: AgentIdentity;
+    /** The work id named by the marker. */
+    workId: string;
+    /** The chat the cancelled work came from -- matches work.ts's
+     *  WorkTarget.chatId (the room, not the lane the cancel arrived in). */
+    chatId: SaltId;
+    /** The lane chat this cancel message actually arrived in -- the same
+     *  sidechain the report it's cancelling was posted into. Equal to
+     *  `chatId` when, unusually, the cancel didn't arrive inside a lane. */
+    laneId: SaltId;
+    /** Whoever sent the cancel -- the person the work was for. */
+    sender: RawSender;
 }
 export interface CardInteractionContext {
     identity: AgentIdentity;
-    chatId: number;
-    cardId: number | string;
+    chatId: SaltId;
+    cardId: SaltId;
     actionId: string;
     user: RawSender;
     blocks: unknown;
+    /** Every `input` block's current value at tap time, keyed by `block_id`
+     *  (NEW) -- `{}` when the card has no input blocks or the tapped button
+     *  ignored them (pay/handoff buttons always do). See client.ts's
+     *  InputCardBlock / CardInteraction.values. */
+    values: Record<string, string>;
+    /** This identity's memory of `chatId` (see MessageContext.session). Loaded
+     *  before this handler runs, same as everywhere else -- but there's no
+     *  reply() here (a card update IS the response), so nothing is appended
+     *  or persisted afterward. Read it; write session.note if you want, but
+     *  know it won't be saved from this call. */
+    session: Session;
+}
+export interface AppActionContext {
+    identity: AgentIdentity;
+    installationId: SaltId;
+    /** The app's identity and the PINNED version number this installation was running at ask time -- not necessarily the app's latest published version. */
+    app: {
+        id: SaltId;
+        name: string;
+        version: number;
+    };
+    /** Null for a personal ("Your apps") installation -- `reply()` then has nothing to post into and fails soft (logged), the same way `salt.post` on the bridge side rejects with "Not in a chat." */
+    chatId: SaltId | null;
+    /** The ask's own text (1..2000, salt-api-enforced). */
+    text: string;
+    /** The ask's optional structured payload (≤ 16 KB, salt-api-enforced). */
+    data?: Record<string, unknown>;
+    /** The shared state's `version` at ask time -- a snapshot, not a lock; read fresh with `client.apps.state` (or just `setState`'s own conflict) before writing. */
+    stateVersion: number;
+    /** Whoever tapped `salt.ask` inside the app. */
+    sender: RawSender;
+    /** Encrypts `text` for every current chat member (+ this identity's own copy) and posts it -- same closure every other context type gets. A no-op (logged) on a personal installation, which has no chat to post into. */
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
 }
 export interface InvoicePaidContext {
     identity: AgentIdentity;
-    chatId: number;
+    chatId: SaltId;
     buyer: RawSender;
     lineItems: Array<{
         name: string;
@@ -70,23 +237,289 @@ export interface InvoicePaidContext {
     amount: string | number;
     /** True for a "Credits top-up" invoice -- no delivery owed, the credit already landed server-side. */
     isTopUp: boolean;
-    transferRequestId: number | string;
-    reply(text: string): Promise<void>;
+    transferRequestId: SaltId;
+    /** This identity's memory of `chatId` (see MessageContext.session). Whatever you reply() with here is appended as an assistant turn and persisted, same as onMessage. */
+    session: Session;
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
+    /** See MessageContext.ask. */
+    ask(question: string, opts?: AskOptions): Promise<AskResult>;
+    /** See MessageContext.approve. */
+    approve(summary: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        approved: boolean;
+        by: SaltId;
+        via: "button" | "message";
+    }>;
+    /** See MessageContext.shareIdentity. */
+    shareIdentity(keys: string[], opts?: identityShare.ShareOptions): Promise<identityShare.ShareResult>;
+}
+export interface ChatOpenedChat {
+    id: SaltId;
+    name?: string;
+    public?: boolean;
+    managed?: boolean;
+    open_invite?: boolean;
+    mode?: "auto" | "manual";
+    active_agent_id?: SaltId;
+    mediator_agent_id?: SaltId;
+    coaching_for_chat_id?: SaltId;
+    private_lane?: boolean;
+    /** False for an open room (no end-to-end encryption). Absent on an older
+     *  server that predates open rooms, which always means an ordinary
+     *  encrypted chat -- see ChatOpenedContext.encrypted for the resolved,
+     *  defaulted value this SDK actually exposes. */
+    encrypted?: boolean;
+    [key: string]: unknown;
+}
+export interface ChatOpenedMember extends RawSender {
+    observer?: boolean;
+}
+export interface ChatOpenedContext {
+    identity: AgentIdentity;
+    chatId: SaltId;
+    chat: ChatOpenedChat;
+    /** False for an open room -- `chat.encrypted === false` on the payload,
+     *  defaulted to true when the field is absent (an older server, or an
+     *  ordinary encrypted chat, where the question doesn't apply). `reply()`
+     *  below always PGP-encrypts regardless -- greet an open room plainly
+     *  with `client.postPlainMessage(identity.apiKey, chatId, text)` instead,
+     *  same convention as MessageContext.encrypted. */
+    encrypted: boolean;
+    /** The person (or agent -- see `openedBy.account_type`) who newly opened
+     *  this chat: a fresh 1:1, a new group that includes this identity, or an
+     *  add-to-an-existing-group. */
+    openedBy: RawSender;
+    /** Every current member, including this identity's own account. */
+    members: ChatOpenedMember[];
+    openedAt: string;
+    /** This identity's memory of `chatId` (see MessageContext.session). Whatever you reply() with here (e.g. a greeting) is appended as an assistant turn and persisted, same as onMessage. */
+    session: Session;
+    /** Encrypts `text` for every current chat member (+ this identity's own
+     *  copy) and posts it -- the same closure every other context type gets. */
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
+    /** See MessageContext.ask. */
+    ask(question: string, opts?: AskOptions): Promise<AskResult>;
+    /** See MessageContext.approve. */
+    approve(summary: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        approved: boolean;
+        by: SaltId;
+        via: "button" | "message";
+    }>;
+    /** See MessageContext.shareIdentity. */
+    shareIdentity(keys: string[], opts?: identityShare.ShareOptions): Promise<identityShare.ShareResult>;
 }
 export interface HandoffConfirmedContext {
     identity: AgentIdentity;
-    chatId: number;
+    chatId: SaltId;
     reason?: string;
-    reply(text: string): Promise<void>;
+    /** Set only when this hand-off was triggered automatically by the
+     *  consulted agent's request_floor call rather than a model-chosen
+     *  hand_off_to_agent/hand_back_to_concierge: the consult lane's decrypted
+     *  transcript so far (capped), for the briefing to draw on. */
+    consultTranscript?: string;
+    /** This identity's memory of `chatId` (see MessageContext.session): the
+     *  tail and note it built up while it was the active agent here, so a
+     *  briefing composed from it isn't starting cold. Whatever you reply()
+     *  with (the briefing) is appended as an assistant turn and persisted --
+     *  moot once you've handed off, but there if you're ever handed this
+     *  chat again later. */
+    session: Session;
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
+    /** See MessageContext.ask. */
+    ask(question: string, opts?: AskOptions): Promise<AskResult>;
+    /** See MessageContext.approve. */
+    approve(summary: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        approved: boolean;
+        by: SaltId;
+        via: "button" | "message";
+    }>;
+    /** See MessageContext.shareIdentity. */
+    shareIdentity(keys: string[], opts?: identityShare.ShareOptions): Promise<identityShare.ShareResult>;
 }
 export interface HandoffReceivedContext {
     identity: AgentIdentity;
-    chatId: number;
+    chatId: SaltId;
     reason?: string;
     /** The shared chat's decrypted transcript, polled for up to ~20s until
      *  the outgoing agent's HANDOFF_BRIEFING_MARKER shows up (or timeout). */
     context: string;
-    reply(text: string): Promise<void>;
+    /** This identity's memory of `chatId`, seeded from the outgoing agent's
+     *  session note (see sessions.ts's SESSION_NOTE_MARKER) when the briefing
+     *  carried one. Whatever you reply() with here (your introduction) is
+     *  appended as an assistant turn and persisted, so it's already in
+     *  transcriptTail by the time the next onMessage call for this chat runs. */
+    session: Session;
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
+    /** See MessageContext.ask. */
+    ask(question: string, opts?: AskOptions): Promise<AskResult>;
+    /** See MessageContext.approve. */
+    approve(summary: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        approved: boolean;
+        by: SaltId;
+        via: "button" | "message";
+    }>;
+    /** See MessageContext.shareIdentity. */
+    shareIdentity(keys: string[], opts?: identityShare.ShareOptions): Promise<identityShare.ShareResult>;
+}
+export interface MandateOfferedContext {
+    identity: AgentIdentity;
+    mandate: Mandate;
+    /** Accepts THIS mandate (`client.mandates.accept`) -- binds this identity's current key
+     *  fingerprint and moves it to `active`. Call it, or don't: an offer left untouched just stays
+     *  `proposed` until someone accepts it or the 7-day proposal window lapses. */
+    accept(): Promise<Mandate>;
+}
+export interface MandateActivatedContext {
+    identity: AgentIdentity;
+    mandate: Mandate;
+}
+export interface MandatePausedContext {
+    identity: AgentIdentity;
+    mandate: Mandate;
+}
+export interface MandateRevokedContext {
+    identity: AgentIdentity;
+    mandate: Mandate;
+}
+export interface ApprovalRequestedContext {
+    identity: AgentIdentity;
+    exercise: MandateExercise;
+    /** Approve or deny the ask (`client.mandates.decide`). Fires only when THIS identity is the
+     *  mandate's principal (e.g. a governance mandate's `money.pay` ask on an owned agent's own
+     *  account) -- the delegate that made the original call gets `onApprovalDecided` instead, once
+     *  this resolves it one way or the other. */
+    decide(decision: "approve" | "deny", note?: string): Promise<MandateExercise>;
+}
+export interface ApprovalDecidedContext {
+    identity: AgentIdentity;
+    /** Already decided (`exercise.decision` is `"approved"` or `"denied"`) -- informational, so the
+     *  delegate that made the original ask-mode call can resume (or give up on) whatever it was
+     *  doing. */
+    exercise: MandateExercise;
+}
+/** The `end_reason` of a device session. `lost_contact` is the one this SDK names: the computer stopped answering for 15 s mid-session. Any other value is passed through verbatim. */
+export declare const DEVICE_LOST_CONTACT = "lost_contact";
+/** Who a device-lane message must be encrypted for: `{ids}` (account ids, sorted, the caller excluded) or `{open: true}`. */
+export interface DeviceChatBlock {
+    id: SaltId;
+    readers: {
+        ids?: SaltId[];
+        open?: boolean;
+    };
+}
+/** The body of a `device_session_ended` delivery: the session row plus `type`/`event`/`session_id`. Every field beyond `type`, `session_id` and `device_id` may be absent on an older server. */
+export interface DeviceSessionEndedBody {
+    type: "device_session_ended";
+    event?: "ended";
+    session_id: SaltId;
+    id?: SaltId;
+    agent_id?: SaltId;
+    device_id: SaltId;
+    mandate_id?: SaltId | null;
+    /** The device LANE (where commands and results travelled), not the person's 1:1. */
+    chat_id?: SaltId | null;
+    status?: string;
+    intent?: string | null;
+    end_reason?: string | null;
+    requested_at?: string | null;
+    started_at?: string | null;
+    ended_at?: string | null;
+    chat?: DeviceChatBlock;
+    [key: string]: unknown;
+}
+/** The body of a `device_back` delivery: sent once per session that ended `lost_contact`, within 24 h, while the mandate is still active, the first time the computer is seen alive again. */
+export interface DeviceBackBody {
+    type: "device_back";
+    device_id: SaltId;
+    device_name: string;
+    previous_session_id: SaltId;
+    /** When Salt ended that session for lost contact. */
+    offline_at: string | null;
+    /** When the computer was seen alive again. */
+    back_at: string;
+    /** The person's 1:1 with this agent; null when they have none. */
+    chat_id: SaltId | null;
+    chat?: DeviceChatBlock;
+    [key: string]: unknown;
+}
+/**
+ * A device session this identity ran just ended. Fires for EVERY end_reason;
+ * check `lostContact` (end_reason `"lost_contact"`) for the one that needs
+ * words. There is no `reply()` on purpose: `laneChatId` is the device lane
+ * the work travelled in, which the person does not read. Say it in the chat
+ * the work came from (remember it when you open the session) or their 1:1.
+ * Etiquette is in AGENTS.md ("A computer going quiet"): say it once per
+ * `sessionId`, plainly, and say that nothing else was sent. Never claim an
+ * action landed unless a device tool returned it.
+ */
+export interface DeviceSessionEndedContext {
+    identity: AgentIdentity;
+    sessionId: SaltId;
+    deviceId: SaltId;
+    mandateId: SaltId | null;
+    /** The device lane, NOT a chat to answer the person in. */
+    laneChatId: SaltId | null;
+    endReason: string | null;
+    /** `endReason === "lost_contact"`: the computer stopped answering for 15 s mid-session. */
+    lostContact: boolean;
+    intent: string | null;
+    endedAt: string | null;
+    /** The delivery verbatim. */
+    body: DeviceSessionEndedBody;
+}
+/**
+ * The computer that went quiet during one of this identity's sessions is
+ * answering again. Grants nothing: open a NEW session to continue. Offer to
+ * finish, and look at the screen before assuming the last step landed. Fires
+ * once per lost session; say it once.
+ */
+export interface DeviceBackContext {
+    identity: AgentIdentity;
+    deviceId: SaltId;
+    deviceName: string;
+    /** The session that ended `lost_contact` -- also the key to say this once. */
+    previousSessionId: SaltId;
+    offlineAt: string | null;
+    backAt: string;
+    /** The person's 1:1 with this agent, or null when they have none (then `reply()` throws). */
+    chatId: SaltId | null;
+    /** This identity's memory of `chatId`; null when `chatId` is. Whatever you reply() with is appended as an assistant turn and persisted. */
+    session: Session | null;
+    /** The delivery verbatim. */
+    body: DeviceBackBody;
+    /** Encrypts `text` for the 1:1's members and posts it. Throws when `chatId` is null. */
+    reply(text: string, opts?: ReplyOptions): Promise<void>;
+}
+/** A `describe_yourself` delivery: Salt asks this agent to write its own public description (the
+ *  text shown on its profile, card and in the directory). Write it with `ctx.write(text)` -- that is
+ *  `PATCH /api/v1/identity/sections {bio}` by this identity's own api-key; plain text, at most
+ *  `maxLength` (300) characters. No chat is involved and no reply is read. */
+export interface DescribeYourselfContext {
+    identity: AgentIdentity;
+    reason: "created" | "owner_changed" | "owner_asked" | "backfill" | string;
+    agent: {
+        id: SaltId;
+        username: string;
+        display_name: string;
+        category?: string | null;
+    };
+    /** What the owner wrote about this agent. Private to the owner and the agent; null when blank. */
+    ownerDescription: string | null;
+    /** What the public sees now (null when nothing is set). */
+    currentDescription: string | null;
+    capabilities: unknown[];
+    /** Salt's own instruction for how to write it. */
+    guidance: string;
+    maxLength: number;
+    /** Write the description (trimmed to `maxLength`); resolves once Salt has saved it. */
+    write(text: string): Promise<void>;
 }
 export interface Logger {
     info(msg: string): void;
@@ -96,29 +529,195 @@ export interface WebhookServerOptions {
     client: SaltClient;
     identities: IdentityStore;
     pgpPassphrase: string;
-    /** Required in production: must match the X-Salt-Webhook-Secret header
-     *  salt-api's jobs send. Unset (local dev) skips the check entirely --
-     *  encrypted-message webhooks fail safe regardless (forged ciphertext
-     *  never decrypts), but card_interaction/invoice_paid payloads are
-     *  plaintext and would otherwise be actable by anyone who can reach this server. */
-    webhookSharedSecret?: string;
+    /** Verify the HMAC signature salt-api sends on every callback.
+     *
+     *  Defaults ON. Each identity has its OWN signing key, fetched from salt-api
+     *  with that identity's api key and cached. This replaced a single fleet-wide
+     *  WEBHOOK_SHARED_SECRET: because anyone could register an agent pointing at
+     *  their own server, that secret leaked to any caller who asked for it, and a
+     *  secret shared with the parties you authenticate against cannot prove who
+     *  sent a request.
+     *
+     *  Encrypted-message webhooks fail safe regardless (forged ciphertext never
+     *  decrypts), but card_interaction/invoice_paid/chat_opened payloads are
+     *  PLAINTEXT and would otherwise be actable by anyone who can reach this
+     *  server.
+     *
+     *  Set false only for local development against a dev salt-api. */
+    verifySignatures?: boolean;
+    /** Reject signatures older than this, so a captured POST can't be replayed. */
+    signatureToleranceSeconds?: number;
     /** This process's configured Mediator identity, if any -- enables the
      *  "observe the shared chat silently, only speak in private coaching
      *  chats" gate. */
-    mediatorAgentId?: number;
+    mediatorAgentId?: SaltId;
+    /** How many messages from AGENT senders one chat may deliver before this
+     *  process stops answering them there (the count resets whenever a person
+     *  speaks). Default 2: the runaway guard for two hosted agents replying to
+     *  each other. Raise it for a host whose agent legitimately talks with an
+     *  allow-listed agent (a Claude Code channel bridge, say); a positive
+     *  integer. Consult lanes keep their own, higher ceiling. */
+    maxAgentToAgentReplies?: number;
+    /** Where each hosted identity's per-chat session (recent turns + a short
+     *  note) is kept. Defaults to an in-memory store (lost on restart --
+     *  onMessage still gets a session on a cold start, rebuilt from the
+     *  chat's own history). Pass `sessions.FileSessionStore(dir)` to persist
+     *  across restarts; see sessions.ts for the trust boundary that store's
+     *  own doc comment states plainly (plaintext on disk, no extra
+     *  encryption -- the same trust level identities.json already assumes). */
+    sessionStore?: SessionStore;
     logger?: Logger;
     onMessage?: (ctx: MessageContext) => Promise<void> | void;
     onCardInteraction?: (ctx: CardInteractionContext) => Promise<void> | void;
+    /**
+     * Someone tapped `salt.ask` inside an app this identity is the
+     * installation's agent for (`POST /api/v1/app_installations/:id/ask`) --
+     * see AppActionContext. The usual answer is `client.apps.state`/
+     * `setState` (change the shared data) and/or `ctx.reply` (say something
+     * in the chat); `salt.ask`'s own promise on the app side resolves as soon
+     * as the webhook is accepted, regardless of what this handler does.
+     */
+    onAppAction?: (ctx: AppActionContext) => Promise<void> | void;
     onInvoicePaid?: (ctx: InvoicePaidContext) => Promise<void> | void;
+    onChatOpened?: (ctx: ChatOpenedContext) => Promise<void> | void;
     onHandoffConfirmed?: (ctx: HandoffConfirmedContext) => Promise<void> | void;
     onHandoffReceived?: (ctx: HandoffReceivedContext) => Promise<void> | void;
+    /** A mandate was offered to this identity and is waiting to be accepted. See
+     *  MandateOfferedContext -- call `ctx.accept()` to accept it. */
+    onMandateOffered?: (ctx: MandateOfferedContext) => Promise<void> | void;
+    /** A mandate this identity is party to (either side) just became active. */
+    onMandateActivated?: (ctx: MandateActivatedContext) => Promise<void> | void;
+    /** A mandate this identity is party to was paused (e.g. the grantee's key changed). */
+    onMandatePaused?: (ctx: MandatePausedContext) => Promise<void> | void;
+    /** A mandate this identity is party to was revoked. */
+    onMandateRevoked?: (ctx: MandateRevokedContext) => Promise<void> | void;
+    /** This identity is the PRINCIPAL of an ask-mode call someone acting for it just made, and it's
+     *  waiting on a decision. See ApprovalRequestedContext -- call `ctx.decide("approve"|"deny")`. */
+    onApprovalRequested?: (ctx: ApprovalRequestedContext) => Promise<void> | void;
+    /** This identity made the original ask-mode call and its exercise was just decided. */
+    onApprovalDecided?: (ctx: ApprovalDecidedContext) => Promise<void> | void;
+    /** Salt asked this agent to write its own public description (`describe_yourself`). The default is
+     *  a no-op: an agent that does not handle it keeps whatever description its owner gave it. See
+     *  DescribeYourselfContext -- call `ctx.write(text)`. */
+    onDescribeYourself?: (ctx: DescribeYourselfContext) => Promise<void> | void;
+    /**
+     * An incoming `[[SALT-IDENTITY-ASK]]` -- someone asking this identity to
+     * share one or more of its own card sections. Return the subset of
+     * `info.keys` to share (this replies with a signed SLICE) or `null`/
+     * `false` to decline (this replies with a DECLINE); either way the ask
+     * is intercepted and never reaches `onMessage`. Leave this unset and an
+     * incoming ask is NOT intercepted at all -- it reaches `onMessage` as
+     * ordinary text with just the marker line stripped, unanswered. See
+     * identityShare.ts.
+     */
+    onIdentityAsk?: IdentityAskHandler;
+    /**
+     * An incoming `[[SALT-IDENTITY-SLICE]]`, `[[SALT-IDENTITY-DECLINE]]` or
+     * `[[SALT-IDENTITY-REVOKE]]` from someone else -- always intercepted
+     * (never reaches `onMessage`) regardless of whether this is set. A SLICE
+     * is verified against the sender's own public key and, when verified,
+     * recorded on that chat's session (`session.identity[senderId]`, see
+     * sessions.ts) before this fires; a REVOKE removes any slice recorded
+     * under the same id first. See identityShare.ts's IdentitySharedEvent.
+     */
+    onIdentityShared?: IdentitySharedHandler;
+    /**
+     * An incoming `[[SALT-WORK-CANCEL id=...]]` (work.ts) -- always
+     * intercepted, never reaches `onMessage`, whether or not this is set. The
+     * usual answer is a fresh report under the same id with
+     * `status: "cancelled"` (see `createWorkReporter`'s `report`, or
+     * `client.postMessage` directly for a lower-level answer). Leave unset
+     * and a cancel is silently swallowed rather than answered -- the sender
+     * still never sees the marker itself.
+     */
+    onWorkCancel?: (ctx: WorkCancelContext) => Promise<void> | void;
+    /**
+     * A device session this identity ran just ended (`device_session_ended`;
+     * fires for every end_reason, see DeviceSessionEndedContext.lostContact).
+     * Not a chat message: it never reaches `onMessage`. Ignored when the
+     * delivery is the DEVICE's own copy (the computer hosting its own
+     * session), which this process only sees if it hosts the device identity.
+     */
+    onDeviceSessionEnded?: (ctx: DeviceSessionEndedContext) => Promise<void> | void;
+    /**
+     * The computer that stopped answering mid-session is back
+     * (`device_back`): sent once per lost session, within 24 h, while the
+     * mandate is active. See DeviceBackContext.
+     */
+    onDeviceBack?: (ctx: DeviceBackContext) => Promise<void> | void;
+    /**
+     * A device-control session lifecycle delivery (behind salt-api's
+     * `Feature :remote_control`): the body's `type` is
+     * `device_session_request` | `device_session_active` | `device_session_ended`,
+     * carrying the session metadata (ids, caps, budget, chat {id, readers}) the
+     * device needs to build its host. These are NOT chat messages and never reach
+     * `onMessage`; the device client (salt-device) passes them straight to its
+     * session controller. The actual command/result traffic rides the device lane
+     * as ordinary encrypted messages, which DO arrive through `onMessage`. The
+     * `type` is forwarded verbatim as the first argument. The device's own rail also
+     * carries `device_queue`, `device_grants_changed`, `device_owner_changed` and
+     * `device_ask_answered` (`{ask_id, decision, device_id, session_id}`: the person's
+     * phone answered a command or session ask; the answer is authenticated as the
+     * person by Salt). See src/device/.
+     */
+    onDeviceDelivery?: (type: string, body: Record<string, unknown>) => Promise<void> | void;
+    /**
+     * A message on a device-control lane (`chat.lane_kind === "device"`) -- the
+     * wire protocol between a controlling agent and a device. Set by the DEVICE
+     * (salt-device's sidecar): such a message is routed here right after the
+     * own-message check, BEFORE the mention gate, the agent-to-agent reply
+     * cap and session persistence (a command carries no mention, and a device
+     * lane would otherwise stop after two commands), and never reaches
+     * `onMessage`. Not awaited: a long action must not hold up the next
+     * delivery (the device host orders commands itself and must read `cancel`
+     * while one runs). The hook is the gate for WHO may command: check the
+     * sender against the session's agent. Unset, a device lane is handled like
+     * any other chat (the controlling AGENT reads results through `onMessage`).
+     */
+    onDeviceLaneMessage?: (ctx: DeviceLaneMessage) => Promise<void> | void;
     /** Extra fields to merge into the /health JSON response (e.g. which model is configured). */
     healthExtra?: () => Record<string, unknown>;
 }
+/**
+ * Everything about the Salt protocol that is NOT "how do bytes get to this
+ * process" -- signature verification and the decrypt/route/dedup/reply
+ * logic for every webhook event kind. `createWebhookServer` below wraps
+ * this in an Express POST route (the only transport before K2); socket.ts's
+ * `createSocketClient` wraps the SAME dispatcher around a websocket push
+ * connection instead, so a consumer switches delivery mode with no change
+ * to onMessage/onCardInteraction/etc. -- see socket.ts's own doc comment.
+ */
+export declare function createDispatcher(options: WebhookServerOptions): Dispatcher;
+/** What createDispatcher returns -- the two things any transport (an
+ *  Express POST route, socket.ts's websocket push client) needs: verify an
+ *  envelope's signature, then hand its body to the right handler. */
+export interface Dispatcher {
+    verifyEnvelope(agentId: string | undefined, signature: string | undefined, rawBody: string, opts?: {
+        toleranceSeconds?: number;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+        transient: boolean;
+    }>;
+    dispatch(body: Record<string, unknown>, headerAgentId?: SaltId): Promise<void>;
+    /** Settles a pending ctx.ask / delegation wait with this (already
+     *  verified) body if it is the answer, returning true when consumed. Never
+     *  runs a handler, so a transport whose handlers block its frame queue
+     *  (socket.ts) can call it ahead of that queue. */
+    resolveAnswer(body: Record<string, unknown>, headerAgentId?: SaltId): Promise<boolean>;
+}
 /**
  * Creates the Express app for a Salt agent's webhook endpoint. Mount it
  * yourself (e.g. `createWebhookServer(opts).listen(port)`, or grab `.app`
  * to compose it into a bigger server).
+ *
+ * A thin transport wrapper around createDispatcher -- everything about the
+ * Salt protocol itself lives there. Switching a consumer from this to
+ * socket.ts's createSocketClient (K2, an agent with no public URL) is the
+ * same `options` object with `.listen(port)` replaced by `.start()`;
+ * onMessage/onCardInteraction/etc. never change.
  */
 export declare function createWebhookServer(options: WebhookServerOptions): {
     app: Express;