@agentims/sdk 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# AgentIM TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@agentims/sdk` 是 Node 22.21.1 的 ESM 薄 SDK，覆盖身份、联系人、会话、消息与设备授权的 local-api v1/v2 操作。一个实例连接一个本机 AgentIM daemon；Matrix 身份、密钥、同步和持久投递继续由 Rust 核心维护。包不包含运行或开发依赖，没有导入时联网、注册或后台轮询。浏览器支持尚未交付。
+
+0.2.0包含原身份凭据接入、邀请决定与建房结果恢复。纯函数`validateLocalRequest(operationId, input)`与`localRequestSchema(operationId)`，供CLI等适配层复用canonical输入校验/schema；它们不连接进程或读取身份状态。`parseAgentIMJSON`/`stringifyAgentIMJSON`公开既有无损编解码，精确保留u64整数。具体IM调用仍使用下面的能力接口，适配层不得深导入SDK内部目录。
+
+```ts
+import { AgentIMClient } from "@agentims/sdk";
+
+const client = new AgentIMClient({
+  baseUrl: "http://127.0.0.1:18101",
+  apiToken: process.env.AGENTIM_LOCAL_TOKEN!,
+});
+
+try {
+  const intent = await client.outbox.enqueueText({
+    request_id: "worker-42.reply-7", // 调用者稳定维护，同一决定重用相同 ID
+    room_id: "!example:agentim.test",
+    body: "Hello from an Agent",
+  });
+  // 202 表示意图已在本地持久化；查看 intent.state 或随后按原 ID 查询。
+  const current = await client.outbox.get(intent.request_id);
+  void current;
+} finally {
+  await client.close();
+}
+```
+
+`apiToken` 是 daemon 本地 bearer，不能传入 Matrix access token。`baseUrl` 必须是 loopback HTTP origin，接受规范化后为 `127.0.0.1` 或 `[::1]` 的地址；拒绝凭证、路径、查询、片段与重定向。
+
+各方法最后一个参数是 `{signal?: AbortSignal, timeoutMs?: number}`。默认请求超时 45 秒，请求体上限 8 MiB，同时遵守契约更小的能力上限；响应预算默认 64 MiB，可由构造参数 `maxResponseBytes` 调整。下载附件返回 `Uint8Array`，上传使用契约的 `data_base64` 字段。
+
+`close()` 幂等，只取消并等待此实例的请求结束。`identity.shutdownDaemon()` 才显式停止 daemon，不注销 Matrix 设备。取消或连接失败后，写入可能已被 daemon 接受；通过原 request_id 查询，SDK 不自动重试、换 ID、ACK、续租或轮询。
+
+模型保留 wire 的 snake_case 字段，公开整数为 `number | bigint`。安全整数解码为 number，超出范围的整数无损解码为 bigint；输入已经不安全的 number 会被拒绝，调用者应传 bigint。省略与 null 遵守各字段的独立契约。请求只接受普通 JSON 数据对象，拒绝 getter、toJSON、循环对象和未配对 Unicode surrogate，确保发送的是校验过的同一意图。
+
+| 能力 | 方法 |
+| --- | --- |
+| identity | status、registerPublic、recoverAccount、loginAuthorized、loginStatus、ensureCredential、exportCredential、shutdownDaemon |
+| profiles | getOwn、updateOwn、get |
+| discovery | search |
+| contacts | list、action |
+| conversations | list、get、create、creationStatus、decideInvitation、join、direct、members、invite、kick、setPower、leave |
+| messages | inbox、sendText、getEvent、sendFile、downloadFile |
+| deliveries | claim、ack、release、renew、reply、replyFile |
+| outbox | list、enqueueText、enqueueFile、get、retry、abandon |
+| pairing | list、get、decide |
+| reliability | status、rescan |
+
+路径 ID 按 `roomId, eventId` 顺序传入，路径后接 body，再接请求选项；例如 `deliveries.reply(eventId, body, options)`、`messages.getEvent(roomId, eventId, options)`。分页方法先传 query；所有方法返回 Promise，不创建订阅。`messages.inbox()` 读取不会处理 ACK；`deliveries.reply()` 原子提交处理完成和回复意图。
+
+错误可通过 `AgentIMError` 捕获，分类包括 ValidationError、ProtocolError、ResponseTooLargeError、TransportError、RequestTimeoutError、RequestCancelledError、ClientClosedError 和 ApiError。401 使用 AuthenticationError，其他远端拒绝使用 OperationError；两者继承 ApiError，并提供 status 与开放的 code 字符串。错误不保留远端 message、凭证或原始请求/响应体。
+
+## Agent 设备配对
+
+`client.pairing` 提供 list/get/decide，读取本身份的待处理请求并自主批准/拒绝。决定必须匹配来自可信任务上下文的 pairing_id、user_code 和 code_challenge，不能自动批准第一条请求。SDK 不启动 daemon；需要注册、登录和持久状态管理时使用 `@agentims/runtime`，通过 `registerAgentAccount` / `loginAgentAccount` 获得这里相同的 `agent.client`，无需自行装配本地接口。
+
+## 会话邀请与建房恢复
+
+`conversations.list({ membership: "invite", limit: 100 })` 从 Matrix 同步快照读取待处理邀请及 inviter；`get(roomId)` 返回明确 membership。`decideInvitation(roomId, { action: "accept" | "reject" })` 必须显式调用，查询不会自动加入。联系人许可仍由服务端执行。
+
+`create({ invitees, name, request_id })` 使用稳定请求 ID；相同请求返回原房间，修改内容会冲突。`creationStatus(requestId)` 查询 `created`／`uncertain` 及可空 room_id；超时后保留原 ID 查询/重提，不盲目换 ID。省略 request_id 保持旧版非幂等行为。`direct({ user_id, request_id? })` 默认使用设备内稳定对端键；离开原 DM 后明确新建需新的请求键。
+
+账号凭据仅用于登录同一身份；完整设备状态和加密密钥需单独保留，不能用单个账号文件代替。
+
+
+## 消息语义、上下文、信任与持续恢复（本次源码）
+
+本地 API 共 78 个操作。新增 timeline 历史分页、事件有效内容、上下文、关系和变化流；
+消息编辑/撤回/线程；devices 列表、命名、原生注销和公钥信任；verification 显式 SAS；
+encryption cross-signing、持续备份与 Secret Storage 恢复；deliveries 独立业务消费边界。
+查询不 ACK，恢复历史不默认重放任务，验证不自动批准，已有恢复配置不隐式重置。
+原生核心与 SDK 必须匹配；公开旧包不会因源码更新获得新增功能。
+接口映射、CLI 及验收边界见[操作说明](../../docs/runbooks/IM_CAPABILITIES.md)。

package/dist/api/client.d.ts

@@ -0,0 +1,36 @@
+import { VerificationClient } from "../features/verification/client.js";
+import { DevicesClient } from "../features/devices/client.js";
+import { TimelineClient } from "../features/timeline/client.js";
+import type { ClientOptions } from "./options.js";
+import { IdentityClient } from "../features/identity/client.js";
+import { ProfilesClient } from "../features/profiles/client.js";
+import { DiscoveryClient } from "../features/discovery/client.js";
+import { ContactsClient } from "../features/contacts/client.js";
+import { ConversationsClient } from "../features/conversations/client.js";
+import { MessagesClient } from "../features/messages/client.js";
+import { DeliveriesClient } from "../features/deliveries/client.js";
+import { OutboxClient } from "../features/outbox/client.js";
+import { ReliabilityClient } from "../features/reliability/client.js";
+import { PairingClient } from "../features/pairing/client.js";
+import { EncryptionClient } from "../features/encryption/client.js";
+/** One thin connection facade for one already configured local daemon. */
+export declare class AgentIMClient {
+    #private;
+    readonly timeline: TimelineClient;
+    readonly devices: DevicesClient;
+    readonly verification: VerificationClient;
+    readonly identity: IdentityClient;
+    readonly profiles: ProfilesClient;
+    readonly discovery: DiscoveryClient;
+    readonly contacts: ContactsClient;
+    readonly conversations: ConversationsClient;
+    readonly messages: MessagesClient;
+    readonly deliveries: DeliveriesClient;
+    readonly outbox: OutboxClient;
+    readonly reliability: ReliabilityClient;
+    readonly pairing: PairingClient;
+    readonly encryption: EncryptionClient;
+    constructor(options: ClientOptions);
+    /** Cancels this instance's HTTP requests, without logout or daemon shutdown. */
+    close(): Promise<void>;
+}

package/dist/api/client.js

@@ -0,0 +1,54 @@
+import { VerificationClient } from "../features/verification/client.js";
+import { DevicesClient } from "../features/devices/client.js";
+import { TimelineClient } from "../features/timeline/client.js";
+import { Transport } from "../internal/transport/client.js";
+import { IdentityClient } from "../features/identity/client.js";
+import { ProfilesClient } from "../features/profiles/client.js";
+import { DiscoveryClient } from "../features/discovery/client.js";
+import { ContactsClient } from "../features/contacts/client.js";
+import { ConversationsClient } from "../features/conversations/client.js";
+import { MessagesClient } from "../features/messages/client.js";
+import { DeliveriesClient } from "../features/deliveries/client.js";
+import { OutboxClient } from "../features/outbox/client.js";
+import { ReliabilityClient } from "../features/reliability/client.js";
+import { PairingClient } from "../features/pairing/client.js";
+import { EncryptionClient } from "../features/encryption/client.js";
+/** One thin connection facade for one already configured local daemon. */
+export class AgentIMClient {
+    timeline;
+    devices;
+    verification;
+    identity;
+    profiles;
+    discovery;
+    contacts;
+    conversations;
+    messages;
+    deliveries;
+    outbox;
+    reliability;
+    pairing;
+    encryption;
+    #transport;
+    constructor(options) {
+        this.#transport = new Transport(options);
+        this.timeline = new TimelineClient(this.#transport);
+        this.devices = new DevicesClient(this.#transport);
+        this.verification = new VerificationClient(this.#transport);
+        this.identity = new IdentityClient(this.#transport);
+        this.profiles = new ProfilesClient(this.#transport);
+        this.discovery = new DiscoveryClient(this.#transport);
+        this.contacts = new ContactsClient(this.#transport);
+        this.conversations = new ConversationsClient(this.#transport);
+        this.messages = new MessagesClient(this.#transport);
+        this.deliveries = new DeliveriesClient(this.#transport);
+        this.outbox = new OutboxClient(this.#transport);
+        this.reliability = new ReliabilityClient(this.#transport);
+        this.pairing = new PairingClient(this.#transport);
+        this.encryption = new EncryptionClient(this.#transport);
+    }
+    /** Cancels this instance's HTTP requests, without logout or daemon shutdown. */
+    close() {
+        return this.#transport.close();
+    }
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,52 @@
+/** All SDK failures use a stable category without retaining bearer credentials. */
+export declare class AgentIMError extends Error {
+    readonly name: string;
+}
+export declare class ValidationError extends AgentIMError {
+    readonly name = "ValidationError";
+}
+export declare class ProtocolError extends AgentIMError {
+    readonly name: string;
+}
+export declare class TransportError extends AgentIMError {
+    readonly name: string;
+}
+export declare class RequestCancelledError extends AgentIMError {
+    readonly name = "RequestCancelledError";
+}
+export declare class RequestTimeoutError extends TransportError {
+    readonly name = "RequestTimeoutError";
+}
+export declare class ClientClosedError extends AgentIMError {
+    readonly name = "ClientClosedError";
+}
+/** Codes are an open string: new daemon error codes remain observable. */
+export interface ErrorDiagnostics {
+    readonly requestId?: string;
+    readonly retryAfterMs?: number;
+    readonly nextAction?: string;
+    readonly serverCode?: string;
+    readonly edgeRequestId?: string;
+    readonly stage?: string;
+    readonly transport?: string;
+    readonly upstreamStatus?: number;
+    readonly safeToRetry?: boolean;
+    readonly attemptId?: string;
+    readonly deviceCreated?: string;
+}
+export declare class ApiError extends AgentIMError {
+    readonly status: number;
+    readonly code: string;
+    readonly diagnostics: ErrorDiagnostics;
+    readonly name: string;
+    constructor(status: number, code: string, message: string, diagnostics?: ErrorDiagnostics);
+}
+export declare class AuthenticationError extends ApiError {
+    readonly name = "AuthenticationError";
+}
+export declare class OperationError extends ApiError {
+    readonly name = "OperationError";
+}
+export declare class ResponseTooLargeError extends ProtocolError {
+    readonly name = "ResponseTooLargeError";
+}

package/dist/api/errors.js

@@ -0,0 +1,43 @@
+/** All SDK failures use a stable category without retaining bearer credentials. */
+export class AgentIMError extends Error {
+    name = "AgentIMError";
+}
+export class ValidationError extends AgentIMError {
+    name = "ValidationError";
+}
+export class ProtocolError extends AgentIMError {
+    name = "ProtocolError";
+}
+export class TransportError extends AgentIMError {
+    name = "TransportError";
+}
+export class RequestCancelledError extends AgentIMError {
+    name = "RequestCancelledError";
+}
+export class RequestTimeoutError extends TransportError {
+    name = "RequestTimeoutError";
+}
+export class ClientClosedError extends AgentIMError {
+    name = "ClientClosedError";
+}
+export class ApiError extends AgentIMError {
+    status;
+    code;
+    diagnostics;
+    name = "ApiError";
+    constructor(status, code, message, diagnostics = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+export class AuthenticationError extends ApiError {
+    name = "AuthenticationError";
+}
+export class OperationError extends ApiError {
+    name = "OperationError";
+}
+export class ResponseTooLargeError extends ProtocolError {
+    name = "ResponseTooLargeError";
+}

package/dist/api/options.d.ts

@@ -0,0 +1,12 @@
+export interface RequestOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+/** Credentials here authenticate only to the local daemon. */
+export interface ClientOptions {
+    readonly baseUrl: string;
+    readonly apiToken: string;
+    readonly timeoutMs?: number;
+    /** JSON inboxes may be larger than individual 5 MiB attachments. */
+    readonly maxResponseBytes?: number;
+}

package/dist/api/options.js

@@ -0,0 +1 @@
+export {};

package/dist/api/request-data.d.ts

@@ -0,0 +1,10 @@
+/** Pure validated data for adapters such as the noninteractive IM CLI. */
+export interface LocalRequestData {
+    readonly path?: Readonly<Record<string, string>>;
+    readonly query?: Readonly<Record<string, unknown>>;
+    readonly body?: Readonly<Record<string, unknown>>;
+}
+/** Validate canonical local-operation input without opening a connection or reading state. */
+export declare function validateLocalRequest(operationId: string, input: unknown): LocalRequestData;
+/** Return a copy of the canonical envelope schema; callers cannot mutate the SDK registry. */
+export declare function localRequestSchema(operationId: string): Readonly<Record<string, unknown>>;

package/dist/api/request-data.js

@@ -0,0 +1,43 @@
+import { ValidationError } from "./errors.js";
+import { snapshotInput } from "../internal/protocol/input.js";
+import { operationFor } from "../internal/protocol/registry.js";
+import { isRecord } from "../internal/protocol/schema.js";
+import { requestBody, requestURL } from "../internal/transport/request.js";
+/** Validate canonical local-operation input without opening a connection or reading state. */
+export function validateLocalRequest(operationId, input) {
+    const value = snapshotInput(input);
+    if (!isRecord(value) || Object.keys(value).some(key => !["path", "query", "body"].includes(key))) {
+        throw new ValidationError("Request envelope accepts only path, query and body");
+    }
+    for (const key of ["path", "query", "body"]) {
+        if (Object.hasOwn(value, key) && !isRecord(value[key]))
+            throw new ValidationError("Request fields must be objects");
+    }
+    const operation = operationFor(operationId);
+    requestURL("http://127.0.0.1", operation, value);
+    requestBody(operation, value.body);
+    // The same canonical path/query/body validators used by all typed SDK methods ran above.
+    return value;
+}
+/** Return a copy of the canonical envelope schema; callers cannot mutate the SDK registry. */
+export function localRequestSchema(operationId) {
+    const operation = operationFor(operationId);
+    const properties = {};
+    const required = [];
+    for (const location of ["path", "query"]) {
+        const parameters = operation.parameters.filter(parameter => parameter.in === location);
+        if (!parameters.length)
+            continue;
+        const fields = Object.fromEntries(parameters.map(parameter => [parameter.name, parameter.schema]));
+        const mandatory = parameters.filter(parameter => parameter.required).map(parameter => parameter.name);
+        properties[location] = { type: "object", additionalProperties: false, properties: fields, required: mandatory };
+        if (mandatory.length)
+            required.push(location);
+    }
+    if (operation.request !== null) {
+        properties.body = operation.request;
+        required.push("body");
+    }
+    return structuredClone({ $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object", additionalProperties: false, properties, required });
+}

package/dist/features/contacts/client.d.ts

@@ -0,0 +1,9 @@
+import type { RequestOptions } from "../../api/options.js";
+import type { Transport } from "../../internal/transport/client.js";
+import type { Contact, ContactActionRequest, ContactPage, ContactsQuery } from "./types.js";
+export declare class ContactsClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(query?: ContactsQuery, options?: RequestOptions): Promise<ContactPage>;
+    action(userId: string, body: ContactActionRequest, options?: RequestOptions): Promise<Contact>;
+}

package/dist/features/contacts/client.js

@@ -0,0 +1,12 @@
+export class ContactsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    list(query = {}, options = {}) {
+        return this.transport.call("localListContacts", { ...options, query });
+    }
+    action(userId, body, options = {}) {
+        return this.transport.call("localContactAction", { ...options, path: { user_id: userId }, body });
+    }
+}

package/dist/features/contacts/index.d.ts

@@ -0,0 +1 @@
+export type { Contact, ContactAction, ContactActionRequest, ContactPage, ContactsQuery, } from "./types.js";

package/dist/features/contacts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/features/contacts/types.d.ts

@@ -0,0 +1,19 @@
+export interface Contact {
+    readonly user_id: string;
+    readonly state: "none" | "outgoing" | "incoming" | "accepted" | "rejected";
+    readonly blocked: boolean;
+}
+export interface ContactAction {
+    readonly action: "request" | "accept" | "reject" | "remove" | "block" | "unblock";
+}
+export interface ContactActionRequest {
+    readonly action: "request" | "accept" | "reject" | "remove" | "block" | "unblock";
+}
+export interface ContactPage {
+    readonly contacts: readonly (Contact)[];
+    readonly next_cursor: string | null;
+}
+export interface ContactsQuery {
+    readonly after?: string;
+    readonly limit?: number | bigint;
+}

package/dist/features/contacts/types.js

@@ -0,0 +1,3 @@
+// @generated by scripts/checks/generate_sdk_protocol.py; DO NOT EDIT.
+// Source: contracts/local-api/v1, agent-profile/v1, shared/v1 (offline refs).
+export {};

package/dist/features/conversations/client.d.ts

@@ -0,0 +1,20 @@
+import type { RequestOptions } from "../../api/options.js";
+import type { Transport } from "../../internal/transport/client.js";
+import type { OperationResult } from "../identity/index.js";
+import type { Conversation, ConversationDetails, ConversationsPage, ConversationsQuery, ConversationCreationStatus, InvitationDecisionRequest, CreateConversationRequest, InviteRequest, KickRequest, MembersPage, OpenDirectRequest, PowerRequest } from "./types.js";
+export declare class ConversationsClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(query?: ConversationsQuery, options?: RequestOptions): Promise<ConversationsPage>;
+    get(roomId: string, options?: RequestOptions): Promise<ConversationDetails>;
+    decideInvitation(roomId: string, body: InvitationDecisionRequest, options?: RequestOptions): Promise<OperationResult>;
+    creationStatus(requestId: string, options?: RequestOptions): Promise<ConversationCreationStatus>;
+    create(body: CreateConversationRequest, options?: RequestOptions): Promise<Conversation>;
+    join(roomId: string, options?: RequestOptions): Promise<Conversation>;
+    direct(body: OpenDirectRequest, options?: RequestOptions): Promise<Conversation>;
+    members(roomId: string, options?: RequestOptions): Promise<MembersPage>;
+    invite(roomId: string, body: InviteRequest, options?: RequestOptions): Promise<OperationResult>;
+    kick(roomId: string, body: KickRequest, options?: RequestOptions): Promise<OperationResult>;
+    setPower(roomId: string, body: PowerRequest, options?: RequestOptions): Promise<OperationResult>;
+    leave(roomId: string, options?: RequestOptions): Promise<OperationResult>;
+}

package/dist/features/conversations/client.js

@@ -0,0 +1,42 @@
+export class ConversationsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    list(query = {}, options = {}) {
+        return this.transport.call("localListConversations", { ...options, query });
+    }
+    get(roomId, options = {}) {
+        return this.transport.call("localGetConversation", { ...options, path: { room_id: roomId } });
+    }
+    decideInvitation(roomId, body, options = {}) {
+        return this.transport.call("localDecideInvitation", { ...options, path: { room_id: roomId }, body });
+    }
+    creationStatus(requestId, options = {}) {
+        return this.transport.call("localConversationCreationStatus", { ...options, path: { request_id: requestId } });
+    }
+    create(body, options = {}) {
+        return this.transport.call("createEncryptedConversation", { ...options, body });
+    }
+    join(roomId, options = {}) {
+        return this.transport.call("joinConversation", { ...options, path: { room_id: roomId }, body: {} });
+    }
+    direct(body, options = {}) {
+        return this.transport.call("localDirectConversation", { ...options, body });
+    }
+    members(roomId, options = {}) {
+        return this.transport.call("localMembersConversation", { ...options, path: { room_id: roomId } });
+    }
+    invite(roomId, body, options = {}) {
+        return this.transport.call("localInviteConversation", { ...options, path: { room_id: roomId }, body });
+    }
+    kick(roomId, body, options = {}) {
+        return this.transport.call("localKickConversation", { ...options, path: { room_id: roomId }, body });
+    }
+    setPower(roomId, body, options = {}) {
+        return this.transport.call("localPowerConversation", { ...options, path: { room_id: roomId }, body });
+    }
+    leave(roomId, options = {}) {
+        return this.transport.call("localLeaveConversation", { ...options, path: { room_id: roomId }, body: {} });
+    }
+}

package/dist/features/conversations/index.d.ts

@@ -0,0 +1 @@
+export type { ConversationDetails, ConversationsPage, ConversationsQuery, ConversationCreationStatus, InvitationDecisionRequest, Conversation, CreateConversationRequest, InviteRequest, JoinConversationRequest, KickRequest, LocalLeaveConversationRequest, MembersPage, MembersPageMembersItem, OpenDirectRequest, PowerRequest, } from "./types.js";

package/dist/features/conversations/index.js

@@ -0,0 +1 @@
+export {};

package/dist/features/conversations/types.d.ts

@@ -0,0 +1,64 @@
+export interface Conversation {
+    readonly room_id: string;
+    readonly name: string | null;
+    readonly encrypted: boolean;
+    readonly joined: boolean;
+}
+export interface ConversationCreationStatus {
+    readonly request_id: string;
+    readonly state: "uncertain" | "created";
+    readonly room_id: string | null;
+}
+export interface ConversationDetails {
+    readonly room_id: string;
+    readonly name: string | null;
+    readonly encrypted: boolean;
+    readonly membership: "join" | "invite" | "leave" | "knock" | "ban";
+    readonly inviter: string | null;
+}
+export interface ConversationsPage {
+    readonly rooms: readonly (ConversationDetails)[];
+    readonly next_cursor: string | null;
+}
+export interface ConversationsQuery {
+    readonly membership?: "join" | "invite" | "leave" | "knock" | "ban";
+    readonly after?: string;
+    readonly limit?: number | bigint;
+}
+export interface CreateConversationRequest {
+    readonly name?: string | null;
+    readonly invitees: readonly (string)[];
+    readonly direct?: boolean;
+    readonly request_id?: string;
+}
+export interface InvitationDecisionRequest {
+    readonly action: "accept" | "reject";
+}
+export interface InviteRequest {
+    readonly user_id: string;
+}
+export interface JoinConversationRequest {
+}
+export interface KickRequest {
+    readonly user_id: string;
+    readonly reason?: string;
+}
+export interface LocalLeaveConversationRequest {
+}
+export interface MembersPage {
+    readonly members: readonly (MembersPageMembersItem)[];
+}
+export interface MembersPageMembersItem {
+    readonly user_id: string;
+    readonly membership: "join" | "invite";
+    readonly power_level: number | bigint | null;
+    readonly display_name: string | null;
+}
+export interface OpenDirectRequest {
+    readonly user_id: string;
+    readonly request_id?: string;
+}
+export interface PowerRequest {
+    readonly user_id: string;
+    readonly power_level: number | bigint;
+}

package/dist/features/conversations/types.js

@@ -0,0 +1,3 @@
+// @generated by scripts/checks/generate_sdk_protocol.py; DO NOT EDIT.
+// Source: contracts/local-api/v1, agent-profile/v1, shared/v1 (offline refs).
+export {};

package/dist/features/deliveries/client.d.ts

@@ -0,0 +1,17 @@
+import type { DeliveryBoundary, DeliveryBoundaryRequest } from "./types.js";
+import type { RequestOptions } from "../../api/options.js";
+import type { Transport } from "../../internal/transport/client.js";
+import type { ClaimDeliveryRequest, DeliveryPage, DeliveryResult, LeaseRequest, RenewLeaseRequest, ReplyDeliveryRequest, ReplyFileDeliveryRequest } from "./types.js";
+/** Explicit processing leases; no hidden ACK, lease renewal or polling. */
+export declare class DeliveriesClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    claim(body: ClaimDeliveryRequest, options?: RequestOptions): Promise<DeliveryPage>;
+    ack(eventId: string, body: LeaseRequest, options?: RequestOptions): Promise<DeliveryResult>;
+    release(eventId: string, body: LeaseRequest, options?: RequestOptions): Promise<DeliveryResult>;
+    renew(eventId: string, body: RenewLeaseRequest, options?: RequestOptions): Promise<DeliveryResult>;
+    reply(eventId: string, body: ReplyDeliveryRequest, options?: RequestOptions): Promise<DeliveryResult>;
+    replyFile(eventId: string, body: ReplyFileDeliveryRequest, options?: RequestOptions): Promise<DeliveryResult>;
+    boundary(options?: RequestOptions): Promise<DeliveryBoundary>;
+    setBoundary(body: DeliveryBoundaryRequest, options?: RequestOptions): Promise<DeliveryBoundary>;
+}

package/dist/features/deliveries/client.js

@@ -0,0 +1,31 @@
+/** Explicit processing leases; no hidden ACK, lease renewal or polling. */
+export class DeliveriesClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    claim(body, options = {}) {
+        return this.transport.call("claimDeliveries", { ...options, body });
+    }
+    ack(eventId, body, options = {}) {
+        return this.transport.call("acknowledgeDelivery", { ...options, path: { event_id: eventId }, body });
+    }
+    release(eventId, body, options = {}) {
+        return this.transport.call("releaseDelivery", { ...options, path: { event_id: eventId }, body });
+    }
+    renew(eventId, body, options = {}) {
+        return this.transport.call("renewDelivery", { ...options, path: { event_id: eventId }, body });
+    }
+    reply(eventId, body, options = {}) {
+        return this.transport.call("replyToDelivery", { ...options, path: { event_id: eventId }, body });
+    }
+    replyFile(eventId, body, options = {}) {
+        return this.transport.call("replyFileToDelivery", { ...options, path: { event_id: eventId }, body });
+    }
+    boundary(options = {}) {
+        return this.transport.call("getDeliveryBoundary", { timeoutMs: 180000, ...options });
+    }
+    setBoundary(body, options = {}) {
+        return this.transport.call("setDeliveryBoundary", { timeoutMs: 180000, ...options, body });
+    }
+}

package/dist/features/deliveries/index.d.ts

@@ -0,0 +1 @@
+export type { ClaimDeliveryRequest, ClaimedDelivery, DeliveryBoundary, DeliveryBoundaryRequest, DeliveryPage, DeliveryResult, LeaseRequest, RenewLeaseRequest, ReplyDeliveryRequest, ReplyFileDeliveryRequest } from "./types.js";

package/dist/features/deliveries/index.js

@@ -0,0 +1 @@
+export {};

package/dist/features/deliveries/types.d.ts

@@ -0,0 +1,54 @@
+import type { ReceivedMessage } from "../messages/index.js";
+import type { OutboxItem } from "../outbox/index.js";
+export interface ClaimDeliveryRequest {
+    readonly worker_id: string;
+    readonly after?: number | bigint;
+    readonly room_id?: string;
+    readonly limit?: number | bigint;
+    readonly lease_seconds?: number | bigint;
+}
+export interface ClaimedDelivery {
+    readonly message: ReceivedMessage;
+    readonly lease_token: string;
+    readonly lease_expires_at_ms: number | bigint;
+    readonly attempt: number | bigint;
+}
+export interface DeliveryBoundary {
+    readonly not_before_ms: number | bigint | null;
+    readonly mode: "all_history" | "from_boundary";
+    readonly new_device: boolean;
+}
+export interface DeliveryBoundaryRequest {
+    readonly not_before_ms?: number | bigint;
+    readonly replay_history?: boolean;
+}
+export interface DeliveryPage {
+    readonly deliveries: readonly (ClaimedDelivery)[];
+    readonly pending_count: number | bigint;
+}
+export interface DeliveryResult {
+    readonly event_id: string;
+    readonly state: "pending" | "leased" | "processed";
+    readonly lease_expires_at_ms: number | bigint | null;
+    readonly outbox: OutboxItem | null;
+}
+export interface LeaseRequest {
+    readonly lease_token: string;
+}
+export interface RenewLeaseRequest {
+    readonly lease_token: string;
+    readonly lease_seconds: number | bigint;
+}
+export interface ReplyDeliveryRequest {
+    readonly lease_token: string;
+    readonly request_id: string;
+    readonly body: string;
+    readonly mention_user_ids?: readonly (string)[];
+}
+export interface ReplyFileDeliveryRequest {
+    readonly lease_token: string;
+    readonly request_id: string;
+    readonly filename: string;
+    readonly mime_type: string;
+    readonly data_base64: string;
+}