hiloop-sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,823 @@
+/** Hiloop SDK client for agents to interact with the Hiloop platform. */
+import type { KeyPair } from "./crypto.js";
+import type { Channel, ChannelMessage, ChannelParticipant, ConvSession, ConvSessionMessage, ConvSessionParticipant, ConvSessionRole, CreateChannelOptions, CreateConvSessionOptions, CreateInteractionOptions, GuestToken, Interaction, Message, PaginatedResult } from "./types.js";
+export declare class HiloopError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export interface HiloopClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Agent's X25519 secret key (base64). Required for E2E encryption. */
+    secretKey?: string;
+    /** Agent's X25519 public key (base64). Required for E2E encryption. */
+    publicKey?: string;
+    /** Space's public key (base64). Required for E2E encryption. */
+    spacePublicKey?: string;
+    /** Space's public key ID. Required for E2E encryption. */
+    spaceKeyId?: string;
+    /** Server's public key ID. Used as default recipientKeyId for content wrapping. */
+    serverKeyId?: string;
+    timeout?: number;
+}
+export declare class HiloopClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private crypto;
+    private secretKeyB64;
+    private publicKeyB64;
+    constructor(options: HiloopClientOptions);
+    private encryptField;
+    /**
+     * Encrypt multiple fields with a SINGLE shared content key (AES-256-GCM).
+     * The content key is wrapped once using ECDH + HKDF + AES-GCM.
+     *
+     * This avoids the DB unique constraint issue where per-field wrappings
+     * with the same (scope, recipientKeyId) are silently dropped.
+     */
+    private encryptFields;
+    private bytesToBase64;
+    private request;
+    /** Fetch binary content (e.g. file download). Returns raw ArrayBuffer. */
+    private requestBinary;
+    createInteraction(opts: CreateInteractionOptions): Promise<Interaction>;
+    getInteraction(interactionId: string): Promise<Interaction>;
+    /** Try to decrypt encrypted interaction fields using content wrappings. */
+    private decryptInteractionFields;
+    cancelInteraction(interactionId: string): Promise<Interaction>;
+    /** Update description/context on an interaction. Accepts plaintext — auto-encrypts. */
+    updateInteractionContext(interactionId: string, opts: {
+        description?: string;
+        context?: string;
+    }): Promise<Record<string, unknown>>;
+    acknowledgeInteraction(interactionId: string): Promise<Interaction>;
+    /** AG-018/019: Update priority, deadline, or context metadata on a pending interaction. */
+    updateInteractionMetadata(interactionId: string, opts: {
+        priority?: string;
+        deadlineMinutes?: number;
+        encryptedContext?: string;
+    }): Promise<{
+        id: string;
+        priority: string;
+        deadlineAt: string | null;
+        updatedAt: string;
+    }>;
+    /** Get the transition log for an interaction. */
+    getInteractionTransitions(interactionId: string): Promise<{
+        transitions: Record<string, unknown>[];
+    }>;
+    /** HU-073 (agent side): Read pending task control signal (pause/resume/cancel). */
+    getTaskControl(interactionId: string): Promise<{
+        signal: string | null;
+        signalAt: string | null;
+    }>;
+    /** HU-073 (agent side): Acknowledge task control signal, clearing it. */
+    ackTaskControl(interactionId: string): Promise<{
+        acknowledged: string | null;
+    }>;
+    /** Single long-poll for a response (server-side timeout, max ~30s). */
+    awaitResponse(interactionId: string, timeout?: number): Promise<Interaction>;
+    /**
+     * Wait for a human to respond to an interaction, polling repeatedly.
+     * Returns the interaction once it has a response (status is responded/completed),
+     * or throws after the timeout expires.
+     *
+     * @param interactionId - The interaction to wait for
+     * @param timeoutSeconds - Maximum wait time in seconds (default 300, max 3600)
+     */
+    waitForResponse(interactionId: string, timeoutSeconds?: number): Promise<Interaction>;
+    listInteractions(filters?: {
+        status?: string;
+        type?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResult<Interaction>>;
+    sendMessage(interactionId: string, content: string): Promise<Message>;
+    /** Push content blocks to an interaction. */
+    pushContentBlocks(interactionId: string, blocks: Array<{
+        blockType: string;
+        data: Record<string, unknown>;
+        position?: number;
+    }>): Promise<{
+        items: Record<string, unknown>[];
+        count: number;
+    }>;
+    /** List content blocks for an interaction. */
+    listContentBlocks(interactionId: string): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Update a content block. */
+    updateContentBlock(interactionId: string, blockId: string, data: Record<string, unknown>): Promise<{
+        id: string;
+        blockType: string;
+        data: Record<string, unknown>;
+        position: number;
+        updatedAt: string;
+    }>;
+    /** Delete a content block. */
+    deleteContentBlock(interactionId: string, blockId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Upload a file attachment to an interaction (base64-encoded). */
+    uploadAttachment(interactionId: string, opts: {
+        fileName: string;
+        mimeType: string;
+        content: string;
+        messageId?: string;
+    }): Promise<{
+        id: string;
+        fileName: string;
+        mimeType: string;
+        sizeBytes: number;
+        createdAt: string;
+    }>;
+    /** List attachments for an interaction, optionally filtered by messageId. */
+    listAttachments(interactionId: string, messageId?: string): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Download raw binary content of a specific attachment. */
+    getAttachment(interactionId: string, fileId: string): Promise<ArrayBuffer>;
+    /** List all reactions for messages in an interaction. */
+    listInteractionReactions(interactionId: string): Promise<{
+        items: Record<string, unknown>[];
+    }>;
+    /** Add a reaction emoji to a message in an interaction. */
+    addInteractionReaction(interactionId: string, messageId: string, emoji: string): Promise<{
+        id: string;
+        messageId: string;
+        emoji: string;
+        createdAt: string;
+    }>;
+    /** Remove a reaction emoji from a message in an interaction. */
+    removeInteractionReaction(interactionId: string, messageId: string, emoji: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Mark all messages in an interaction as read by this agent. */
+    markInteractionRead(interactionId: string): Promise<{
+        markedRead: number;
+    }>;
+    /** Send a typing indicator for an interaction. */
+    sendInteractionTyping(interactionId: string, isTyping: boolean): Promise<{
+        ok: boolean;
+    }>;
+    listMessages(interactionId: string, page?: number, pageSize?: number): Promise<PaginatedResult<Message>>;
+    /** AD-060: Push agent telemetry activity status + plan to the platform. */
+    pushTelemetry(opts: {
+        status: string;
+        focus?: string;
+        plan?: {
+            name?: string;
+            tasks: Array<{
+                name: string;
+                completed: boolean;
+            }>;
+        };
+    }): Promise<{
+        ok: boolean;
+    }>;
+    /** AG-041: List webhook delivery history for the agent. */
+    listWebhookDeliveries(limit?: number): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** AG-041: Get webhook delivery statistics for the agent. */
+    getWebhookDeliveryStats(): Promise<Record<string, unknown>>;
+    /** AG-041: Manually retry a failed webhook delivery. */
+    retryWebhookDelivery(deliveryId: string): Promise<{
+        queued: boolean;
+        deliveryId: string;
+    }>;
+    /** BL-042: Check remaining plan quota for this space. */
+    getQuota(): Promise<Record<string, unknown>>;
+    /** AD-060: Log an inter-agent communication event for monitoring. */
+    logComm(opts: {
+        direction: "sent" | "received";
+        content: string;
+        otherAgentName?: string;
+    }): Promise<{
+        id: string;
+        createdAt: string;
+    }>;
+    /** Get space encryption info (space public key). */
+    getEncryptionInfo(): Promise<{
+        spaceKeyId: string;
+        spacePublicKey: string;
+    }>;
+    /** Get this agent's currently registered public key. */
+    getAgentPublicKey(): Promise<{
+        keyId: string;
+        publicKey: string;
+        fingerprint: string;
+    }>;
+    /** Register (or confirm) this agent's public key (idempotent). */
+    putAgentPublicKey(publicKey: string, fingerprint: string): Promise<{
+        keyId: string;
+        publicKey: string;
+        fingerprint: string;
+    }>;
+    /** List space teams for this agent's space. */
+    listSpaceTeams(): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Get availability status for a specific space user. */
+    getUserAvailability(userId: string): Promise<{
+        userId: string;
+        availability: string;
+    }>;
+    /** List space users visible to this agent. */
+    listSpaceUsers(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    createConvSession(opts: CreateConvSessionOptions): Promise<ConvSession>;
+    getConvSession(sessionId: string): Promise<ConvSession>;
+    listConvSessions(opts?: {
+        status?: string;
+        isPublic?: boolean;
+        limit?: number;
+        offset?: number;
+        page?: number;
+    }): Promise<ConvSession[]>;
+    closeConvSession(sessionId: string): Promise<ConvSession>;
+    /**
+     * Send a message to a conversation session.
+     * The content must be pre-encrypted using encryptAes() with the shared session key.
+     */
+    /**
+     * Send a message in a conv session. Accepts plaintext — encrypts automatically
+     * using the session message key (`{agentPub}:{AES-GCM ciphertext}` format).
+     */
+    sendConvSessionMessage(sessionId: string, content: string): Promise<ConvSessionMessage>;
+    /** Send a typing indicator to a conv session (HU-034). */
+    sendConvSessionTyping(sessionId: string, typing: boolean): Promise<void>;
+    /** Edit a previously sent conv session message. */
+    editConvSessionMessage(sessionId: string, msgId: string, encryptedContent: string): Promise<ConvSessionMessage>;
+    /** Soft-delete a conv session message. */
+    deleteConvSessionMessage(sessionId: string, msgId: string): Promise<{
+        ok: boolean;
+    }>;
+    listConvSessionTimeline(sessionId: string, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<{
+        items: Record<string, unknown>[];
+    }>;
+    addConvSessionParticipant(sessionId: string, userId: string, role?: ConvSessionRole): Promise<ConvSessionParticipant>;
+    removeConvSessionParticipant(sessionId: string, userId: string): Promise<void>;
+    /** Update a participant's role in a conversation session. */
+    updateConvSessionParticipantRole(sessionId: string, userId: string, role: string): Promise<{
+        ok: boolean;
+    }>;
+    listConvSessionParticipants(sessionId: string): Promise<ConvSessionParticipant[]>;
+    createGuestToken(sessionId: string, opts?: {
+        displayName?: string;
+        expiresInHours?: number;
+    }): Promise<GuestToken>;
+    listGuestTokens(sessionId: string): Promise<GuestToken[]>;
+    revokeGuestToken(sessionId: string, tokenId: string): Promise<void>;
+    /** AG-060: Create multiple interactions in a single API call. */
+    createInteractionBatch(interactions: CreateInteractionOptions[]): Promise<{
+        results: {
+            id: string;
+            kind: string;
+            status: string;
+            error?: string;
+        }[];
+        total: number;
+        successes: number;
+    }>;
+    /** Archive a conversation session. */
+    archiveConvSession(sessionId: string): Promise<ConvSession>;
+    /** Create a group interaction involving multiple participants (AG-061). */
+    createGroupInteraction(opts: CreateInteractionOptions, participants: {
+        userId: string;
+        role?: string;
+    }[]): Promise<{
+        id: string;
+        kind: string;
+        status: string;
+        participants: {
+            userId: string;
+            role: string;
+        }[];
+    }>;
+    /** Add a reference from one interaction to another (AG-062). */
+    addInteractionReference(interactionId: string, targetInteractionId: string, opts?: {
+        referenceType?: string;
+        note?: string;
+    }): Promise<Record<string, unknown>>;
+    /** List all references for an interaction (AG-062). */
+    listInteractionReferences(interactionId: string): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Remove an interaction reference by its ID (AG-062). */
+    removeInteractionReference(interactionId: string, refId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Get public metadata for a public agent by slug. */
+    getPublicAgentInfo(slug: string): Promise<{
+        name: string;
+        description: string | null;
+        slug: string;
+        isPublic: boolean;
+    }>;
+    /** Create an interaction as a public (anonymous) user on a public agent. */
+    createPublicInteraction(slug: string, opts: {
+        encryptedTitle: string;
+        type?: string;
+        priority?: string;
+        deadlineMinutes?: number;
+    }): Promise<{
+        id: string;
+        kind: string;
+        status: string;
+        priority: string;
+        createdAt: string;
+    }>;
+    /** Get the status of a public interaction by slug + ID. */
+    getPublicInteraction(slug: string, interactionId: string): Promise<{
+        id: string;
+        kind: string;
+        status: string;
+        priority: string;
+        encryptedTitle: string | null;
+        encryptedResponse: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Long-poll for a response on a public interaction (returns when responded/completed/cancelled/expired). */
+    awaitPublicInteraction(slug: string, interactionId: string, timeoutMs?: number): Promise<{
+        id: string;
+        status: string;
+        encryptedResponse: string | null;
+        respondedAt: string | null;
+    }>;
+    /** Send a message to a public interaction as an anonymous user. */
+    sendPublicMessage(slug: string, interactionId: string, encryptedContent: string): Promise<{
+        id: string;
+        interactionId: string;
+        senderType: string;
+        encryptedContent: string;
+        createdAt: string;
+    }>;
+    /** List interactions created on a public agent (paginated). */
+    listPublicInteractions(slug: string, opts?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    /** Cancel a public interaction (anonymous user side). */
+    cancelPublicInteraction(slug: string, interactionId: string): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /** Get the transition log for a public interaction. */
+    getPublicInteractionTransitions(slug: string, interactionId: string): Promise<{
+        transitions: Record<string, unknown>[];
+    }>;
+    /** Look up a public session by its public token (no auth required). */
+    getPublicSession(publicToken: string): Promise<{
+        session: Record<string, unknown>;
+    }>;
+    /** Join a public session as a guest using its public token. */
+    joinPublicSession(publicToken: string, displayName: string): Promise<{
+        sessionId: string;
+        guestToken: string;
+    }>;
+    /** Get a human-facing interaction detail view. */
+    getHumanInteraction(interactionId: string): Promise<Record<string, unknown>>;
+    /** Mark an interaction as viewed by the authenticated user. */
+    viewInteraction(interactionId: string): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /** Submit a response to an interaction. */
+    respondToHumanInteraction(interactionId: string, opts: {
+        encryptedResponse: string;
+        responseEventType?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Snooze an interaction until a given ISO datetime. */
+    snoozeInteraction(interactionId: string, snoozedUntil: string): Promise<{
+        id: string;
+        snoozedUntil: string | null;
+    }>;
+    /** Toggle the pinned state of an interaction. */
+    pinInteraction(interactionId: string, pinned: boolean): Promise<{
+        id: string;
+        isPinned: boolean;
+    }>;
+    /** Get the human user's activity feed (all interactions). */
+    getFeed(opts?: {
+        page?: number;
+        pageSize?: number;
+        view?: string;
+        q?: string;
+        type?: string;
+        priority?: string;
+        pinned?: boolean;
+        agentId?: string;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Get badge counts (e.g. open interactions) for the authenticated user. */
+    getBadges(): Promise<{
+        open: number;
+    }>;
+    /** Get the authenticated user's current availability status. */
+    getMyAvailability(): Promise<{
+        status: string;
+    }>;
+    /** Update the authenticated user's availability status. */
+    updateMyAvailability(status: "active" | "away" | "dnd" | "offline"): Promise<{
+        status: string;
+    }>;
+    /** List delegation rules for the authenticated user. */
+    listDelegations(): Promise<{
+        items: Record<string, unknown>[];
+    }>;
+    /** Create a delegation rule for the authenticated user. */
+    createDelegation(opts: {
+        delegateToUserId: string;
+        triggerStatus?: string;
+        delegateToTeamId?: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    /** Remove a delegation rule by delegateId. */
+    deleteDelegation(delegateId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** List sent notifications for the authenticated user. */
+    listNotifications(): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Get notification preferences for the authenticated user. */
+    getNotificationPreferences(): Promise<{
+        preferences: Record<string, unknown>[];
+    }>;
+    /** Update notification preference for a specific channel. */
+    updateNotificationPreference(channel: "push" | "email" | "sms" | "in_app", opts: {
+        enabled?: boolean;
+        quietHoursStart?: number;
+        quietHoursEnd?: number;
+        digestEnabled?: boolean;
+        digestFrequency?: "daily" | "weekly";
+        minPriority?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Register a push token for the authenticated user's device. */
+    registerPushToken(opts: {
+        token: string;
+        platform: "fcm" | "apns" | "apns_voip";
+        deviceId?: string;
+    }): Promise<{
+        id: string;
+        token: string;
+        platform: string;
+    }>;
+    /** Remove the push token for the authenticated user's device. */
+    deletePushToken(opts: {
+        token: string;
+        platform: string;
+    }): Promise<{
+        deleted: boolean;
+    }>;
+    /** Save (upsert) a response draft for an interaction. */
+    saveDraft(interactionId: string, encryptedDraft: string): Promise<{
+        id: string;
+        updatedAt: string;
+    }>;
+    /** Get the saved response draft for an interaction. */
+    getDraft(interactionId: string): Promise<{
+        id: string;
+        encryptedDraft: string;
+        updatedAt: string;
+    } | null>;
+    /** Delete the saved response draft for an interaction. */
+    deleteDraft(interactionId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Unsnooze an interaction before its scheduled snooze time. */
+    unsnoozeInteraction(interactionId: string): Promise<{
+        id: string;
+        snoozedUntil: null;
+    }>;
+    /** Create a milestone alert for an interaction. */
+    createMilestoneAlert(interactionId: string, opts: {
+        encryptedLabel: string;
+        triggerAt: string;
+    }): Promise<{
+        id: string;
+        triggeredAt: string | null;
+    }>;
+    /** List milestone alerts for an interaction. */
+    listMilestoneAlerts(interactionId: string): Promise<{
+        alerts: Record<string, unknown>[];
+    }>;
+    /** Delete a milestone alert. */
+    deleteMilestoneAlert(interactionId: string, alertId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Get the approval chain for an interaction. */
+    getApprovalChain(interactionId: string): Promise<{
+        chain: Record<string, unknown>[];
+    }>;
+    /** Respond to an approval chain step. */
+    respondToApprovalChain(interactionId: string, opts: {
+        decision: string;
+        encryptedComment?: string;
+    }): Promise<{
+        ok: boolean;
+        status: string;
+    }>;
+    /** List comments on an interaction. */
+    listInteractionComments(interactionId: string): Promise<{
+        comments: Record<string, unknown>[];
+    }>;
+    /** Post a comment on an interaction. */
+    createInteractionComment(interactionId: string, opts: {
+        encryptedContent: string;
+        parentId?: string;
+    }): Promise<{
+        id: string;
+        createdAt: string;
+    }>;
+    /** Mark a comment as resolved. */
+    resolveInteractionComment(interactionId: string, commentId: string): Promise<{
+        id: string;
+        isResolved: boolean;
+    }>;
+    /** Delete a comment. */
+    deleteInteractionComment(interactionId: string, commentId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Submit review feedback for an interaction. */
+    submitReviewFeedback(interactionId: string, opts: {
+        rating: number;
+        encryptedFeedback?: string;
+    }): Promise<{
+        id: string;
+        rating: number;
+    }>;
+    /** Cast a vote on an interaction. */
+    voteOnInteraction(interactionId: string, opts: {
+        choice: string;
+        encryptedComment?: string;
+    }): Promise<{
+        id: string;
+        choice: string;
+    }>;
+    /** Get aggregate vote results for an interaction. */
+    getVoteResults(interactionId: string): Promise<{
+        results: Record<string, number>;
+        total: number;
+    }>;
+    /** Get the current user's vote on an interaction. */
+    getMyVote(interactionId: string): Promise<{
+        choice: string | null;
+        id: string | null;
+    }>;
+    /** List tags on an interaction. */
+    getInteractionTags(interactionId: string): Promise<{
+        tags: string[];
+    }>;
+    /** Add a tag to an interaction. */
+    addInteractionTag(interactionId: string, tag: string): Promise<{
+        tags: string[];
+    }>;
+    /** Remove a tag from an interaction. */
+    deleteInteractionTag(interactionId: string, tag: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** List all space-wide tags. */
+    listSpaceTags(): Promise<{
+        tags: string[];
+    }>;
+    /** List response templates for the current user. */
+    listResponseTemplates(): Promise<{
+        templates: Record<string, unknown>[];
+    }>;
+    /** Create a response template. */
+    createResponseTemplate(opts: {
+        encryptedContent: string;
+        type?: string;
+    }): Promise<{
+        id: string;
+        createdAt: string;
+    }>;
+    /** Delete a response template. */
+    deleteResponseTemplate(templateId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Get review feedback for an interaction. */
+    getReviewFeedback(interactionId: string): Promise<{
+        feedback: Record<string, unknown>[];
+    }>;
+    /** Use a response template (increments usage count). */
+    useResponseTemplate(templateId: string): Promise<{
+        id: string;
+        encryptedContent: string;
+    }>;
+    /** List messages for a human interaction. */
+    listInteractionMessages(interactionId: string, opts?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        messages: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Send a message to a human interaction thread. */
+    sendInteractionMessage(interactionId: string, opts: {
+        encryptedContent: string;
+        role?: string;
+    }): Promise<{
+        id: string;
+        createdAt: string;
+    }>;
+    /** Mark messages as read for an interaction. */
+    markMessagesRead(interactionId: string): Promise<{
+        markedCount: number;
+    }>;
+    /** Get aggregated reactions for all messages in an interaction. */
+    getInteractionReactions(interactionId: string): Promise<{
+        reactions: Record<string, unknown>[];
+    }>;
+    /** Add a reaction to a specific message. */
+    addMessageReaction(interactionId: string, messageId: string, emoji: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Remove a reaction from a specific message. */
+    removeMessageReaction(interactionId: string, messageId: string, emoji: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Get agent activity data for the space (for human dashboard). */
+    getAgentActivity(): Promise<{
+        agents: Record<string, unknown>[];
+    }>;
+    /** List interaction references for a human interaction. */
+    listHumanInteractionReferences(interactionId: string): Promise<{
+        references: Record<string, unknown>[];
+    }>;
+    /** Add a reference link between two interactions. */
+    addHumanInteractionReference(interactionId: string, opts: {
+        targetInteractionId: string;
+        type?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** Get current usage and quota for the space. */
+    getUsage(): Promise<{
+        usage: Record<string, unknown>;
+        quota: Record<string, unknown>;
+    }>;
+    /** Get feature gate flags for the current user. */
+    getFeatureGates(): Promise<{
+        gates: Record<string, boolean>;
+    }>;
+    /** Track that the current user is viewing an interaction. */
+    trackInteractionViewing(interactionId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Get who is currently viewing an interaction. */
+    getInteractionViewers(interactionId: string): Promise<{
+        viewers: Record<string, unknown>[];
+    }>;
+    /** Stop tracking viewing presence for an interaction. */
+    stopTrackingViewing(interactionId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Get human-assigned tasks (interactions requiring action). */
+    getHumanTasks(opts?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** List space members (humans). */
+    getHumanMembers(opts?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        members: Record<string, unknown>[];
+        total: number;
+    }>;
+    /** Get aggregated notification digest for the current user. */
+    getNotificationDigest(opts?: {
+        since?: string;
+    }): Promise<{
+        digest: Record<string, unknown>[];
+    }>;
+    /** Create a new agent-to-agent channel. */
+    createChannel(opts: CreateChannelOptions): Promise<Channel>;
+    /** Get a channel by ID. */
+    getChannel(channelId: string): Promise<Channel>;
+    /** List channels with optional filters. */
+    listChannels(filters?: {
+        status?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResult<Channel>>;
+    /** Close a channel. */
+    closeChannel(channelId: string): Promise<Channel>;
+    /** Add a participant to a channel. */
+    addChannelParticipant(channelId: string, agentId: string): Promise<ChannelParticipant>;
+    /** Remove a participant from a channel. */
+    removeChannelParticipant(channelId: string, agentId: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Send a message in a channel. */
+    sendChannelMessage(channelId: string, content: string): Promise<ChannelMessage>;
+    /** List messages in a channel. */
+    listChannelMessages(channelId: string, opts?: {
+        page?: number;
+        pageSize?: number;
+        before?: string;
+        after?: string;
+    }): Promise<PaginatedResult<ChannelMessage>>;
+    /** Log a detailed activity entry visible to the human (thinking, tool calls, decisions). */
+    logActivity(entry: {
+        logType: string;
+        content?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** List participants in a channel. */
+    listChannelParticipants(channelId: string): Promise<{
+        participants: ChannelParticipant[];
+    }>;
+    /** Register or update commands for this agent (batch, max 50). */
+    registerCommands(commands: {
+        name: string;
+        description: string;
+        argumentHint?: string;
+        parameters?: Record<string, unknown>;
+        annotations?: {
+            destructive?: boolean;
+            longRunning?: boolean;
+        };
+    }[]): Promise<{
+        commands: Record<string, unknown>[];
+        count: number;
+    }>;
+    /** List all commands registered by this agent. */
+    listCommands(): Promise<{
+        commands: Record<string, unknown>[];
+    }>;
+    /** Update a registered command by name. */
+    updateCommand(name: string, updates: {
+        description?: string;
+        argumentHint?: string;
+        parameters?: Record<string, unknown>;
+        annotations?: {
+            destructive?: boolean;
+            longRunning?: boolean;
+        };
+    }): Promise<Record<string, unknown>>;
+    /** Remove a registered command by name. */
+    removeCommand(name: string): Promise<{
+        removed: boolean;
+    }>;
+    /** Poll for pending command invocations. */
+    getInvocations(opts?: {
+        status?: string;
+        convSessionId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        invocations: Record<string, unknown>[];
+        count: number;
+    }>;
+    /** Acknowledge a command invocation (pending -> running). */
+    ackInvocation(invocationId: string): Promise<Record<string, unknown>>;
+    /** Mark an invocation as completed. */
+    completeInvocation(invocationId: string, opts?: {
+        result?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Mark an invocation as failed. */
+    failInvocation(invocationId: string, opts?: {
+        error?: string;
+    }): Promise<Record<string, unknown>>;
+    static generateKeyPair(): KeyPair;
+    /** Encrypt plaintext with AES-256-GCM for session messages. */
+    static encryptAes(plaintext: string, keyBase64: string): Promise<string>;
+    /** Decrypt AES-256-GCM ciphertext from session messages. */
+    static decryptAes(ciphertextBase64: string, keyBase64: string): Promise<string>;
+}
+/**
+ * Return all wrappings as-is. Each encrypted field has its own random content
+ * key, so every wrapping is unique even when scope + recipientKeyId match.
+ * The frontend tries each wrapping until one successfully decrypts.
+ */