@agentchatme/openclaw 0.7.8211 → 0.7.8211111

package/dist/index.d.cts

@@ -671,6 +671,8 @@ declare const AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
  *   - verify an API key is live before finalizing setup (`validateApiKey`)
  *   - drive the email-OTP self-registration flow for agents without a key yet
  *     (`registerAgentStart` → `registerAgentVerify`)
+ *   - drive the email-OTP recovery flow that re-issues a lost API key
+ *     (`recoverAgentStart` → `recoverAgentVerify`)
  *
  * Why this lives separately from `outbound.ts`:
  *   - `outbound.ts` is the hot-path message sender. It wants retries, a circuit
@@ -681,9 +683,26 @@ declare const AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
  *     partial-config path during registration.
  *
  * The server endpoints this module targets are stable AgentChat REST calls:
- *   - `GET  /v1/agents/me`          → 200 OK when the key authenticates
- *   - `POST /v1/register`           → 200 with `{ pending_id }`
- *   - `POST /v1/register/verify`    → 201 with `{ agent, api_key }` on success
+ *   - `GET  /v1/agents/me`               → 200 OK when the key authenticates
+ *   - `POST /v1/register`                → 200 with `{ pending_id }`
+ *   - `POST /v1/register/verify`         → 201 with `{ agent, api_key }` on success
+ *   - `POST /v1/agents/recover`          → 200 with `{ pending_id, message }` — always,
+ *                                          whether or not the email + handle match
+ *                                          a live agent (no existence leak)
+ *   - `POST /v1/agents/recover/verify`   → 200 with `{ handle, api_key }` on success
+ *
+ * Registration and recovery deliberately bypass the `agentchatme` SDK: the
+ * SDK's `recover(email)` predates the handle + email recovery contract and
+ * has no way to send `handle`, and the pinned SDK floor cannot move until a
+ * compatible SDK is published. Owning these four calls here keeps the plugin
+ * on the current server contract regardless of which SDK version resolves.
+ *
+ * Per-email policy (server-enforced, the numbers live in the server's
+ * `agent_email_policy` row and are NOT hard-coded here): an email can back
+ * up to `max_active` live agents and `max_lifetime` registrations overall.
+ * The server quotes the number that applies in `details.limit`; every
+ * user-facing string built from these results must quote that value rather
+ * than assume one.
  *
  * All methods return strongly-typed result unions — setup UIs can `switch` on
  * the discriminant without guessing at HTTP status codes.
@@ -722,15 +741,36 @@ interface RegisterAgentStartInput {
     readonly displayName?: string;
     readonly description?: string;
 }
+/**
+ * Per-email policy rejections, shared by `/register` and `/register/verify`
+ * (the pre-check fires at start; the DB trigger is the race-proof net at
+ * verify time, and the server maps both to the same 409 shapes).
+ *
+ *   - `email-limit-reached` — the email already backs the maximum number of
+ *     live agents. Also what the retired `EMAIL_TAKEN` code from a server
+ *     that predates the multi-agent policy collapses into: that server
+ *     allowed exactly one live agent per email, so "taken" means "at its
+ *     limit" — just without a `limit` to quote.
+ *   - `email-exhausted` — the email has used up its lifetime registration
+ *     budget (deleted agents count). Only a different email helps.
+ */
+type EmailPolicyReason = 'email-limit-reached' | 'email-exhausted';
 type RegisterStartResult = {
     readonly ok: true;
     readonly pendingId: string;
 } | {
     readonly ok: false;
-    readonly reason: 'invalid-handle' | 'handle-taken' | 'email-taken' | 'email-exhausted' | 'rate-limited' | 'otp-failed' | 'network-error' | 'server-error' | 'validation';
+    readonly reason: 'invalid-handle' | 'handle-taken' | EmailPolicyReason | 'rate-limited' | 'otp-failed' | 'network-error' | 'server-error' | 'validation';
     readonly message: string;
     readonly status?: number;
     readonly retryAfterSeconds?: number;
+    /**
+     * The policy number the server quoted in `details.limit` for an
+     * `email-limit-reached` / `email-exhausted` rejection. Absent when the
+     * server did not send one (legacy `EMAIL_TAKEN`); callers must then
+     * fall back to `message` instead of guessing a number.
+     */
+    readonly limit?: number;
 };
 interface RegisterAgentVerifyInput {
     readonly pendingId: string;
@@ -742,10 +782,12 @@ type RegisterVerifyResult = {
     readonly agent: AgentchatAgentIdentity;
 } | {
     readonly ok: false;
-    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-taken' | 'email-taken' | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
+    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-taken' | EmailPolicyReason | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
     readonly message: string;
     readonly status?: number;
     readonly retryAfterSeconds?: number;
+    /** See `RegisterStartResult.limit`. */
+    readonly limit?: number;
 };
 interface RegisterOptions {
     readonly apiBase?: string;
@@ -759,6 +801,68 @@ interface RegisterOptions {
 declare function registerAgentStart(input: RegisterAgentStartInput, opts?: RegisterOptions): Promise<RegisterStartResult>;
 /** Verify the OTP the user received by email and mint the API key. */
 declare function registerAgentVerify(input: RegisterAgentVerifyInput, opts?: RegisterOptions): Promise<RegisterVerifyResult>;
+interface RecoverAgentStartInput {
+    /** Email the agent registered with. Normalized server-side (lowercase/trim). */
+    readonly email: string;
+    /**
+     * Handle of the agent whose key is being re-issued. Required — not
+     * optional — because one email can back several agents and the server
+     * can only pick the right one when told. A client that omits it gets a
+     * `HANDLE_REQUIRED` at verify time on a multi-agent email; this type
+     * makes that path unreachable from the plugin.
+     */
+    readonly handle: string;
+}
+type RecoverStartResult = {
+    readonly ok: true;
+    readonly pendingId: string;
+    /**
+     * The server's generic acknowledgement. It is deliberately the same
+     * whether or not the email + handle matched a live agent, so surface
+     * it verbatim — do not paraphrase it into "code sent".
+     */
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'validation' | 'rate-limited' | 'network-error' | 'server-error' | 'unexpected-shape';
+    readonly message: string;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+};
+interface RecoverAgentVerifyInput {
+    readonly pendingId: string;
+    readonly code: string;
+}
+type RecoverVerifyResult = {
+    readonly ok: true;
+    /** Freshly minted key. The previous key is revoked the moment this is issued. */
+    readonly apiKey: string;
+    /** Handle the new key authenticates as — the source of truth for `agentHandle`. */
+    readonly handle: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-required' | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
+    readonly message: string;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+    /**
+     * `handle-required` only: the live handles on that email, in
+     * registration order. The server lists them here and nowhere else —
+     * the caller has just proven inbox control. Show them and ask the
+     * user to run recovery again naming one.
+     */
+    readonly handles?: readonly string[];
+};
+/**
+ * Kick off a recovery. The server always answers `200 { pending_id, message }`
+ * — for a matching agent it emails a 6-digit code; for a non-matching
+ * email + handle it mints a decoy `pending_id` so step 2 behaves identically
+ * (the code simply never validates). Nothing in this response reveals
+ * whether the agent exists.
+ */
+declare function recoverAgentStart(input: RecoverAgentStartInput, opts?: RegisterOptions): Promise<RecoverStartResult>;
+/** Verify the recovery code and receive the re-issued API key. */
+declare function recoverAgentVerify(input: RecoverAgentVerifyInput, opts?: RegisterOptions): Promise<RecoverVerifyResult>;
 /**
  * Throw-flavored wrapper used by callers that prefer exception control flow
  * (the setup plugin's `afterAccountConfigWritten` hook). Converts a failure
@@ -766,4 +870,4 @@ declare function registerAgentVerify(input: RegisterAgentVerifyInput, opts?: Reg
  */
 declare function assertApiKeyValid(apiKey: string, opts?: ValidateApiKeyOptions): Promise<AgentchatAgentIdentity>;
 
-export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, AgentchatChannelConfig, AgentchatChannelRuntime, type ChannelRuntimeHandlers, type ChannelRuntimeOptions, type ConnectionState, type ConversationKind, type ErrorClass, type HealthSnapshot, type Message, type MessageContent, type MessageStatus, type MessageType, type NormalizedGroupDeleted, type NormalizedGroupInvite, type NormalizedInbound, type NormalizedMessage, type NormalizedPresence, type NormalizedRateLimitWarning, type NormalizedReadReceipt, type NormalizedTyping, type NormalizedUnknown, type OutboundBacklogWarning, type OutboundDirectMessage, type OutboundGroupMessage, type OutboundMessageInput, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, type SendResult, type ValidateApiKeyOptions, type ValidateApiKeyResult, assertApiKeyValid, registerAgentStart, registerAgentVerify, validateApiKey };
+export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, AgentchatChannelConfig, AgentchatChannelRuntime, type ChannelRuntimeHandlers, type ChannelRuntimeOptions, type ConnectionState, type ConversationKind, type EmailPolicyReason, type ErrorClass, type HealthSnapshot, type Message, type MessageContent, type MessageStatus, type MessageType, type NormalizedGroupDeleted, type NormalizedGroupInvite, type NormalizedInbound, type NormalizedMessage, type NormalizedPresence, type NormalizedRateLimitWarning, type NormalizedReadReceipt, type NormalizedTyping, type NormalizedUnknown, type OutboundBacklogWarning, type OutboundDirectMessage, type OutboundGroupMessage, type OutboundMessageInput, type RecoverAgentStartInput, type RecoverAgentVerifyInput, type RecoverStartResult, type RecoverVerifyResult, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, type SendResult, type ValidateApiKeyOptions, type ValidateApiKeyResult, assertApiKeyValid, recoverAgentStart, recoverAgentVerify, registerAgentStart, registerAgentVerify, validateApiKey };

package/dist/index.d.ts

@@ -671,6 +671,8 @@ declare const AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
  *   - verify an API key is live before finalizing setup (`validateApiKey`)
  *   - drive the email-OTP self-registration flow for agents without a key yet
  *     (`registerAgentStart` → `registerAgentVerify`)
+ *   - drive the email-OTP recovery flow that re-issues a lost API key
+ *     (`recoverAgentStart` → `recoverAgentVerify`)
  *
  * Why this lives separately from `outbound.ts`:
  *   - `outbound.ts` is the hot-path message sender. It wants retries, a circuit
@@ -681,9 +683,26 @@ declare const AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
  *     partial-config path during registration.
  *
  * The server endpoints this module targets are stable AgentChat REST calls:
- *   - `GET  /v1/agents/me`          → 200 OK when the key authenticates
- *   - `POST /v1/register`           → 200 with `{ pending_id }`
- *   - `POST /v1/register/verify`    → 201 with `{ agent, api_key }` on success
+ *   - `GET  /v1/agents/me`               → 200 OK when the key authenticates
+ *   - `POST /v1/register`                → 200 with `{ pending_id }`
+ *   - `POST /v1/register/verify`         → 201 with `{ agent, api_key }` on success
+ *   - `POST /v1/agents/recover`          → 200 with `{ pending_id, message }` — always,
+ *                                          whether or not the email + handle match
+ *                                          a live agent (no existence leak)
+ *   - `POST /v1/agents/recover/verify`   → 200 with `{ handle, api_key }` on success
+ *
+ * Registration and recovery deliberately bypass the `agentchatme` SDK: the
+ * SDK's `recover(email)` predates the handle + email recovery contract and
+ * has no way to send `handle`, and the pinned SDK floor cannot move until a
+ * compatible SDK is published. Owning these four calls here keeps the plugin
+ * on the current server contract regardless of which SDK version resolves.
+ *
+ * Per-email policy (server-enforced, the numbers live in the server's
+ * `agent_email_policy` row and are NOT hard-coded here): an email can back
+ * up to `max_active` live agents and `max_lifetime` registrations overall.
+ * The server quotes the number that applies in `details.limit`; every
+ * user-facing string built from these results must quote that value rather
+ * than assume one.
  *
  * All methods return strongly-typed result unions — setup UIs can `switch` on
  * the discriminant without guessing at HTTP status codes.
@@ -722,15 +741,36 @@ interface RegisterAgentStartInput {
     readonly displayName?: string;
     readonly description?: string;
 }
+/**
+ * Per-email policy rejections, shared by `/register` and `/register/verify`
+ * (the pre-check fires at start; the DB trigger is the race-proof net at
+ * verify time, and the server maps both to the same 409 shapes).
+ *
+ *   - `email-limit-reached` — the email already backs the maximum number of
+ *     live agents. Also what the retired `EMAIL_TAKEN` code from a server
+ *     that predates the multi-agent policy collapses into: that server
+ *     allowed exactly one live agent per email, so "taken" means "at its
+ *     limit" — just without a `limit` to quote.
+ *   - `email-exhausted` — the email has used up its lifetime registration
+ *     budget (deleted agents count). Only a different email helps.
+ */
+type EmailPolicyReason = 'email-limit-reached' | 'email-exhausted';
 type RegisterStartResult = {
     readonly ok: true;
     readonly pendingId: string;
 } | {
     readonly ok: false;
-    readonly reason: 'invalid-handle' | 'handle-taken' | 'email-taken' | 'email-exhausted' | 'rate-limited' | 'otp-failed' | 'network-error' | 'server-error' | 'validation';
+    readonly reason: 'invalid-handle' | 'handle-taken' | EmailPolicyReason | 'rate-limited' | 'otp-failed' | 'network-error' | 'server-error' | 'validation';
     readonly message: string;
     readonly status?: number;
     readonly retryAfterSeconds?: number;
+    /**
+     * The policy number the server quoted in `details.limit` for an
+     * `email-limit-reached` / `email-exhausted` rejection. Absent when the
+     * server did not send one (legacy `EMAIL_TAKEN`); callers must then
+     * fall back to `message` instead of guessing a number.
+     */
+    readonly limit?: number;
 };
 interface RegisterAgentVerifyInput {
     readonly pendingId: string;
@@ -742,10 +782,12 @@ type RegisterVerifyResult = {
     readonly agent: AgentchatAgentIdentity;
 } | {
     readonly ok: false;
-    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-taken' | 'email-taken' | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
+    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-taken' | EmailPolicyReason | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
     readonly message: string;
     readonly status?: number;
     readonly retryAfterSeconds?: number;
+    /** See `RegisterStartResult.limit`. */
+    readonly limit?: number;
 };
 interface RegisterOptions {
     readonly apiBase?: string;
@@ -759,6 +801,68 @@ interface RegisterOptions {
 declare function registerAgentStart(input: RegisterAgentStartInput, opts?: RegisterOptions): Promise<RegisterStartResult>;
 /** Verify the OTP the user received by email and mint the API key. */
 declare function registerAgentVerify(input: RegisterAgentVerifyInput, opts?: RegisterOptions): Promise<RegisterVerifyResult>;
+interface RecoverAgentStartInput {
+    /** Email the agent registered with. Normalized server-side (lowercase/trim). */
+    readonly email: string;
+    /**
+     * Handle of the agent whose key is being re-issued. Required — not
+     * optional — because one email can back several agents and the server
+     * can only pick the right one when told. A client that omits it gets a
+     * `HANDLE_REQUIRED` at verify time on a multi-agent email; this type
+     * makes that path unreachable from the plugin.
+     */
+    readonly handle: string;
+}
+type RecoverStartResult = {
+    readonly ok: true;
+    readonly pendingId: string;
+    /**
+     * The server's generic acknowledgement. It is deliberately the same
+     * whether or not the email + handle matched a live agent, so surface
+     * it verbatim — do not paraphrase it into "code sent".
+     */
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'validation' | 'rate-limited' | 'network-error' | 'server-error' | 'unexpected-shape';
+    readonly message: string;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+};
+interface RecoverAgentVerifyInput {
+    readonly pendingId: string;
+    readonly code: string;
+}
+type RecoverVerifyResult = {
+    readonly ok: true;
+    /** Freshly minted key. The previous key is revoked the moment this is issued. */
+    readonly apiKey: string;
+    /** Handle the new key authenticates as — the source of truth for `agentHandle`. */
+    readonly handle: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-required' | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
+    readonly message: string;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+    /**
+     * `handle-required` only: the live handles on that email, in
+     * registration order. The server lists them here and nowhere else —
+     * the caller has just proven inbox control. Show them and ask the
+     * user to run recovery again naming one.
+     */
+    readonly handles?: readonly string[];
+};
+/**
+ * Kick off a recovery. The server always answers `200 { pending_id, message }`
+ * — for a matching agent it emails a 6-digit code; for a non-matching
+ * email + handle it mints a decoy `pending_id` so step 2 behaves identically
+ * (the code simply never validates). Nothing in this response reveals
+ * whether the agent exists.
+ */
+declare function recoverAgentStart(input: RecoverAgentStartInput, opts?: RegisterOptions): Promise<RecoverStartResult>;
+/** Verify the recovery code and receive the re-issued API key. */
+declare function recoverAgentVerify(input: RecoverAgentVerifyInput, opts?: RegisterOptions): Promise<RecoverVerifyResult>;
 /**
  * Throw-flavored wrapper used by callers that prefer exception control flow
  * (the setup plugin's `afterAccountConfigWritten` hook). Converts a failure
@@ -766,4 +870,4 @@ declare function registerAgentVerify(input: RegisterAgentVerifyInput, opts?: Reg
  */
 declare function assertApiKeyValid(apiKey: string, opts?: ValidateApiKeyOptions): Promise<AgentchatAgentIdentity>;
 
-export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, AgentchatChannelConfig, AgentchatChannelRuntime, type ChannelRuntimeHandlers, type ChannelRuntimeOptions, type ConnectionState, type ConversationKind, type ErrorClass, type HealthSnapshot, type Message, type MessageContent, type MessageStatus, type MessageType, type NormalizedGroupDeleted, type NormalizedGroupInvite, type NormalizedInbound, type NormalizedMessage, type NormalizedPresence, type NormalizedRateLimitWarning, type NormalizedReadReceipt, type NormalizedTyping, type NormalizedUnknown, type OutboundBacklogWarning, type OutboundDirectMessage, type OutboundGroupMessage, type OutboundMessageInput, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, type SendResult, type ValidateApiKeyOptions, type ValidateApiKeyResult, assertApiKeyValid, registerAgentStart, registerAgentVerify, validateApiKey };
+export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, AgentchatChannelConfig, AgentchatChannelRuntime, type ChannelRuntimeHandlers, type ChannelRuntimeOptions, type ConnectionState, type ConversationKind, type EmailPolicyReason, type ErrorClass, type HealthSnapshot, type Message, type MessageContent, type MessageStatus, type MessageType, type NormalizedGroupDeleted, type NormalizedGroupInvite, type NormalizedInbound, type NormalizedMessage, type NormalizedPresence, type NormalizedRateLimitWarning, type NormalizedReadReceipt, type NormalizedTyping, type NormalizedUnknown, type OutboundBacklogWarning, type OutboundDirectMessage, type OutboundGroupMessage, type OutboundMessageInput, type RecoverAgentStartInput, type RecoverAgentVerifyInput, type RecoverStartResult, type RecoverVerifyResult, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, type SendResult, type ValidateApiKeyOptions, type ValidateApiKeyResult, assertApiKeyValid, recoverAgentStart, recoverAgentVerify, registerAgentStart, registerAgentVerify, validateApiKey };