@awiki/dsh-plugin 0.2.4 → 0.3.0-rc.1

package/lib/types/index.js

@@ -35,7 +35,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 };
 import { Context } from '@deepseek-ai/cordis';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { settingsNamespace } from '@deepseek-ai/dsh-settings';
@@ -43,17 +43,23 @@ import { AWIKI_CLEAR_LOCAL_DATA_CONFIRMATION, AWIKI_LOGOUT_CONFIRMATION } from "
 import { AwikiExternalHttpAuthError, createAwikiExternalHttpAuth, externalHttpAuthError, mapProviderError as mapExternalHttpProviderError, } from "./external-http-auth.js";
 import { downloadedAttachment } from "./sdk-adapter.js";
 import { registerAwikiTools } from "./tools.js";
+import { mailInboxRequest, mailMarkReadRequest, mailReadRequest, mailSendRequest, } from "./mail.js";
 import { AwikiSettingsSchema, validateAwikiSettings, } from "./settings.js";
 import { AWIKI_SETTINGS_NAMESPACE, DEFAULT_AWIKI_DOMAIN, normalizeAwikiDomain } from "./domain.js";
 import { AWIKI_SETTINGS_RPC_CHANNEL } from "./settings-rpc-contract.js";
 import { createAwikiSettingsRpcHandler } from "./settings-rpc.js";
 import { AwikiSessionStore } from "./session.js";
+import { AwikiImageAttachmentCache, minimumImageAttachmentCacheMaxBytes } from "./attachment-cache.js";
+import { AwikiSentMailStore, isLocalSentMailId } from "./sent-mail-store.js";
+import { AwikiAgentListener, DshAwikiListenerAgentRuntime, } from "./listener.js";
 export { AWIKI_CLEAR_LOCAL_DATA_CONFIRMATION, AWIKI_LOGOUT_CONFIRMATION } from "./types.js";
 export { AWIKI_EXTERNAL_HTTP_MAX_BODY_BYTES, AwikiExternalHttpAuthError, } from "./external-http-auth.js";
 export { AWIKI_DOMAIN_FIELD, AWIKI_SETTINGS_NAMESPACE, AwikiSettingsSchema, DEFAULT_AWIKI_DOMAIN, normalizeAwikiDomain, validateAwikiSettings, } from "./settings.js";
-export { AWIKI_HISTORY_TOOL, AWIKI_IDENTITY_STATUS_TOOL, AWIKI_LIST_CONVERSATIONS_TOOL, AWIKI_SEND_ATTACHMENT_TOOL, AWIKI_SEND_MESSAGE_TOOL, } from "./tools.js";
+export { AWIKI_HISTORY_TOOL, AWIKI_IDENTITY_STATUS_TOOL, AWIKI_LIST_CONVERSATIONS_TOOL, AWIKI_MAIL_ACCOUNT_TOOL, AWIKI_MAIL_INBOX_TOOL, AWIKI_MAIL_MARK_READ_TOOL, AWIKI_MAIL_READ_TOOL, AWIKI_MAIL_SEND_TOOL, AWIKI_SEND_ATTACHMENT_TOOL, AWIKI_SEND_MESSAGE_TOOL, } from "./tools.js";
 /** Default maximum attachment size: 10 MiB. */
 export const DEFAULT_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+/** Default private on-disk budget for verified image previews: 64 MiB. */
+export const DEFAULT_IMAGE_ATTACHMENT_CACHE_MAX_BYTES = 64 * 1024 * 1024;
 /** Default browser polling interval while the AWiki drawer is open. */
 export const DEFAULT_POLL_INTERVAL_MS = 3_000;
 /** Default AWiki production service origin. */
@@ -69,13 +75,18 @@ export const Config = z.object({
     userServiceUrl: z.string().default(DEFAULT_AWIKI_SERVICE_URL),
     userServiceDomain: z.string().default(DEFAULT_AWIKI_DOMAIN),
     messageServiceUrl: z.string().default(DEFAULT_AWIKI_SERVICE_URL),
+    mailServiceUrl: z.string(),
     messageServicePublicUrl: z.string().default(DEFAULT_AWIKI_SERVICE_URL),
     messageServiceDid: z.string().default(DEFAULT_AWIKI_MESSAGE_SERVICE_DID),
     allowedAttachmentOrigins: z.array(z.string()).default([]),
     allowInsecureLoopbackForTesting: z.boolean().default(false),
     stateRoot: z.string(),
     attachmentMaxBytes: z.number().default(DEFAULT_ATTACHMENT_MAX_BYTES),
+    imageAttachmentCacheMaxBytes: z.number().default(DEFAULT_IMAGE_ATTACHMENT_CACHE_MAX_BYTES),
     pollIntervalMs: z.number().default(DEFAULT_POLL_INTERVAL_MS),
+    listenerEnabled: z.boolean().default(false),
+    listenerAllowedPeers: z.array(z.string()).default([]),
+    listenerWorkspacePath: z.string(),
     summaryMaxInputBytes: z.number().default(DEFAULT_SUMMARY_MAX_INPUT_BYTES),
 });
 const FAILURE_CODES = new Set([
@@ -90,15 +101,22 @@ const FAILURE_CODES = new Set([
     'forbidden',
     'conflict',
     'rate-limited',
+    'group-membership-required',
+    'group-identity-stale',
     'attachment-too-large',
     'summary-unavailable',
     'summary-timeout',
     'summary-cancelled',
     'summary-invalid-output',
     'summary-failed',
+    'delivery-unknown',
     'network',
     'remote',
 ]);
+const LISTENER_RESTART_BASE_DELAY_MS = 1_000;
+const LISTENER_RESTART_MAX_DELAY_MS = 30_000;
+const LISTENER_RESTART_MAX_ATTEMPT = 6;
+const LISTENER_STABLE_RESET_MS = 60_000;
 const FAILURE_MESSAGES = {
     'not-registered': 'No AWiki identity is registered for this deployment.',
     'signed-out': 'This installation is signed out of AWiki.',
@@ -111,12 +129,15 @@ const FAILURE_MESSAGES = {
     'forbidden': 'The AWiki operation is not permitted.',
     'conflict': 'The AWiki operation conflicts with current state.',
     'rate-limited': 'The AWiki service rate-limited the request.',
+    'group-membership-required': 'The active AWiki identity is not a member of this group.',
+    'group-identity-stale': 'The AWiki group identity binding is still recovering.',
     'attachment-too-large': 'The attachment exceeds this deployment\'s size limit.',
     'summary-unavailable': 'AI summary is unavailable. Check the current default model configuration.',
     'summary-timeout': 'AI summary timed out. Try again.',
     'summary-cancelled': 'AI summary was cancelled. Try again.',
     'summary-invalid-output': 'The model returned an invalid summary. Try again.',
     'summary-failed': 'AI summary could not be generated. Try again.',
+    'delivery-unknown': 'Mail delivery could not be confirmed. Inspect the mailbox before retrying.',
     'network': 'The AWiki service could not be reached.',
     'remote': 'The AWiki service rejected the operation.',
 };
@@ -170,42 +191,83 @@ function attachmentOrigins(raw, messageServicePublicUrl, allowInsecureLoopbackFo
     }
     return origins;
 }
+/** Resolve the explicit listener allowlist without accepting wildcards or ambiguous whitespace. */
+function listenerAllowedPeers(raw, enabled) {
+    const peers = (raw ?? []).map((peer) => {
+        if (peer !== peer.trim() || peer.length === 0 || peer.length > 2_048 || /[\u0000-\u001f\u007f]/u.test(peer)) {
+            throw new TypeError('awiki: listenerAllowedPeers entries must be non-empty exact Handles or DIDs');
+        }
+        if (peer === '*')
+            throw new TypeError('awiki: listenerAllowedPeers does not accept wildcards');
+        return peer.startsWith('did:') ? peer : peer.toLowerCase();
+    });
+    if (peers.length > 100 || new Set(peers).size !== peers.length) {
+        throw new TypeError('awiki: listenerAllowedPeers must contain at most 100 unique entries');
+    }
+    if (enabled && peers.length === 0) {
+        throw new TypeError('awiki: listenerAllowedPeers must contain at least one Handle or DID when listenerEnabled is true');
+    }
+    return peers;
+}
 /** Resolve and validate every deployment choice before publishing the service. */
 function resolveConfig(config) {
     const allowInsecureLoopbackForTesting = config.allowInsecureLoopbackForTesting ?? false;
     const configuredStateRoot = config.stateRoot?.trim();
     const configuredDshHome = process.env.DSH_HOME?.trim();
+    const dshHome = configuredDshHome === undefined || configuredDshHome.length === 0
+        ? join(homedir(), '.dsh')
+        : configuredDshHome;
     const stateRoot = configuredStateRoot === undefined || configuredStateRoot.length === 0
-        ? join(configuredDshHome === undefined || configuredDshHome.length === 0 ? join(homedir(), '.dsh') : configuredDshHome, 'awiki', 'im-core')
+        ? join(dshHome, 'awiki', 'im-core')
         : configuredStateRoot;
-    if (stateRoot.length === 0)
-        throw new TypeError('awiki: stateRoot must be non-empty');
+    if (!isAbsolute(stateRoot))
+        throw new TypeError('awiki: stateRoot must be an absolute path');
     const attachmentMaxBytes = config.attachmentMaxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES;
     if (!Number.isSafeInteger(attachmentMaxBytes) || attachmentMaxBytes < 1) {
         throw new TypeError('awiki: attachmentMaxBytes must be a positive safe integer');
     }
+    const imageAttachmentCacheMaxBytes = config.imageAttachmentCacheMaxBytes ?? DEFAULT_IMAGE_ATTACHMENT_CACHE_MAX_BYTES;
+    if (!Number.isSafeInteger(imageAttachmentCacheMaxBytes)
+        || imageAttachmentCacheMaxBytes < minimumImageAttachmentCacheMaxBytes(attachmentMaxBytes)) {
+        throw new TypeError('awiki: imageAttachmentCacheMaxBytes cannot retain one maximum-sized attachment');
+    }
     const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1_000 || pollIntervalMs > 60_000) {
         throw new TypeError('awiki: pollIntervalMs must be a safe integer from 1000 through 60000');
     }
+    const listenerEnabled = config.listenerEnabled ?? false;
+    const listenerWorkspacePath = config.listenerWorkspacePath?.trim() || join(dshHome, 'workspaces', 'awiki');
+    if (!isAbsolute(listenerWorkspacePath)) {
+        throw new TypeError('awiki: listenerWorkspacePath must be an absolute path');
+    }
+    const allowedPeers = listenerAllowedPeers(config.listenerAllowedPeers, listenerEnabled);
     const summaryMaxInputBytes = config.summaryMaxInputBytes ?? DEFAULT_SUMMARY_MAX_INPUT_BYTES;
     if (!Number.isSafeInteger(summaryMaxInputBytes) || summaryMaxInputBytes < 1_024) {
         throw new TypeError('awiki: summaryMaxInputBytes must be a safe integer of at least 1024');
     }
     const userServiceUrl = serviceUrl('userServiceUrl', config.userServiceUrl ?? DEFAULT_AWIKI_SERVICE_URL, allowInsecureLoopbackForTesting);
     const messageServiceUrl = serviceUrl('messageServiceUrl', config.messageServiceUrl ?? DEFAULT_AWIKI_SERVICE_URL, allowInsecureLoopbackForTesting);
+    const mailServiceUrl = serviceUrl('mailServiceUrl', config.mailServiceUrl ?? userServiceUrl, allowInsecureLoopbackForTesting);
     const messageServicePublicUrl = serviceUrl('messageServicePublicUrl', config.messageServicePublicUrl ?? DEFAULT_AWIKI_SERVICE_URL, allowInsecureLoopbackForTesting);
     return {
         userServiceUrl,
         userServiceDomain: serviceDomain(config.userServiceDomain ?? DEFAULT_AWIKI_DOMAIN),
         messageServiceUrl,
+        mailServiceUrl,
         messageServicePublicUrl,
         messageServiceDid: serviceDid(config.messageServiceDid ?? DEFAULT_AWIKI_MESSAGE_SERVICE_DID),
         allowedAttachmentOrigins: attachmentOrigins(config.allowedAttachmentOrigins, messageServicePublicUrl, allowInsecureLoopbackForTesting),
         allowInsecureLoopbackForTesting,
         stateRoot,
         attachmentMaxBytes,
+        imageAttachmentCacheMaxBytes,
         pollIntervalMs,
+        listenerEnabled,
+        listener: {
+            allowedPeers,
+            workspacePath: listenerWorkspacePath,
+            stateRoot,
+        },
         summaryMaxInputBytes,
     };
 }
@@ -234,6 +296,208 @@ function normalizeFailure(error) {
     }
     return failure('remote');
 }
+const MAX_GROUP_NAME_CHARACTERS = 100;
+const MAX_GROUP_INITIAL_MEMBERS = 50;
+const MAX_GROUP_MEMBER_CHARACTERS = 512;
+const MAX_PROFILE_DISPLAY_NAME_CHARACTERS = 50;
+const MAX_PROFILE_BIO_CHARACTERS = 100;
+const MAX_PROFILE_TAGS = 5;
+const MAX_PROFILE_TAG_CHARACTERS = 30;
+const MAX_MESSAGE_CHARACTERS = 20_000;
+function normalizeCreateGroupRequest(request) {
+    if (typeof request?.name !== 'string' || !Array.isArray(request.members))
+        return undefined;
+    const name = request.name.trim();
+    if (name.length === 0 || Array.from(name).length > MAX_GROUP_NAME_CHARACTERS)
+        return undefined;
+    if (request.members.length > MAX_GROUP_INITIAL_MEMBERS)
+        return undefined;
+    const members = [];
+    const seen = new Set();
+    for (const raw of request.members) {
+        if (typeof raw !== 'string')
+            return undefined;
+        const member = raw.trim().replace(/^@+/u, '');
+        if (member.length === 0 || Array.from(member).length > MAX_GROUP_MEMBER_CHARACTERS)
+            return undefined;
+        if (seen.has(member))
+            continue;
+        seen.add(member);
+        members.push(member);
+    }
+    return { name, members };
+}
+function normalizeMember(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const member = value.trim().replace(/^@+/u, '');
+    return member.length > 0 && Array.from(member).length <= MAX_GROUP_MEMBER_CHARACTERS
+        ? member
+        : undefined;
+}
+function normalizeGroupDid(value) {
+    if (typeof value !== 'string' || !value.startsWith('did:') || value.length > 2_048)
+        return undefined;
+    return value;
+}
+/** Rebuild the browser-safe recovery DTO instead of trusting provider object shape. */
+function publicGroupRebindRecoverySummary(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const candidate = value;
+    const counts = [candidate.processed, candidate.completed, candidate.pending, candidate.blocked];
+    if (counts.some(count => !Number.isSafeInteger(count) || count < 0 || count > 0xffff_ffff)) {
+        return undefined;
+    }
+    return {
+        processed: candidate.processed,
+        completed: candidate.completed,
+        pending: candidate.pending,
+        blocked: candidate.blocked,
+    };
+}
+function normalizeProfileRequest(request) {
+    if (typeof request?.displayName !== 'string' || typeof request.bio !== 'string' || !Array.isArray(request.tags))
+        return undefined;
+    const displayName = request.displayName.trim();
+    const bio = request.bio.trim();
+    if (displayName.length === 0
+        || Array.from(displayName).length > MAX_PROFILE_DISPLAY_NAME_CHARACTERS
+        || Array.from(bio).length > MAX_PROFILE_BIO_CHARACTERS
+        || request.tags.length > MAX_PROFILE_TAGS)
+        return undefined;
+    const tags = [];
+    const seen = new Set();
+    for (const raw of request.tags) {
+        if (typeof raw !== 'string')
+            return undefined;
+        const tag = raw.trim();
+        const key = tag.toLocaleLowerCase();
+        if (tag.length === 0 || Array.from(tag).length > MAX_PROFILE_TAG_CHARACTERS || seen.has(key))
+            return undefined;
+        seen.add(key);
+        tags.push(tag);
+    }
+    return { displayName, bio, tags };
+}
+function normalizeRecoveryOperation(request) {
+    if (typeof request?.operationId !== 'string')
+        return undefined;
+    const operationId = request.operationId.trim();
+    return operationId.length > 0 && operationId.length <= 512 ? { operationId } : undefined;
+}
+function normalizeRecoveryOtpRequest(request) {
+    if (typeof request?.fullHandle !== 'string' || typeof request.phone !== 'string')
+        return undefined;
+    const fullHandle = request.fullHandle.trim().replace(/^@+/u, '');
+    const phone = request.phone.trim();
+    if (fullHandle.length === 0 || fullHandle.length > 512 || phone.length < 5 || phone.length > 32)
+        return undefined;
+    return { fullHandle, phone };
+}
+function normalizeRecoveryPrepareRequest(request) {
+    const operation = normalizeRecoveryOperation(request);
+    if (operation === undefined || typeof request.phone !== 'string' || typeof request.otp !== 'string')
+        return undefined;
+    const phone = request.phone.trim();
+    const otp = request.otp.trim();
+    if (phone.length < 5 || phone.length > 32 || !/^\d{4,12}$/u.test(otp))
+        return undefined;
+    return { ...operation, phone, otp };
+}
+const IDENTITY_ACCESS_RESPONSE_MAX_BYTES = 64 * 1024;
+/** Read one untrusted discovery response without buffering beyond the fixed Host limit. */
+async function readBoundedResponseText(response, maxBytes) {
+    const declaredLength = response.headers.get('content-length');
+    if (declaredLength !== null && /^\d+$/u.test(declaredLength) && Number(declaredLength) > maxBytes)
+        return undefined;
+    if (response.body === null)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            length += result.value.byteLength;
+            if (length > maxBytes) {
+                await reader.cancel();
+                return undefined;
+            }
+            chunks.push(Uint8Array.from(result.value));
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+/** Resolve one configured-domain Handle without widening registration authority. */
+function identityAccessTarget(request, configuredDomain) {
+    if (typeof request?.handle !== 'string')
+        return undefined;
+    const raw = request.handle.trim();
+    if (raw.length === 0 || raw.length > 255 || /[\u0000-\u001f\u007f]/u.test(raw))
+        return undefined;
+    const lowered = raw.replace(/[A-Z]/gu, character => character.toLowerCase());
+    const handle = lowered.startsWith('wba://') ? lowered.slice('wba://'.length) : lowered;
+    const dot = handle.indexOf('.');
+    const localPart = (dot < 0 ? handle : handle.slice(0, dot)).trim();
+    const domain = (dot < 0 ? configuredDomain : handle.slice(dot + 1)).trim().replace(/\.$/u, '');
+    if (localPart.length === 0 || domain !== configuredDomain)
+        return undefined;
+    return { localPart, fullHandle: `${localPart}.${configuredDomain}` };
+}
+function normalizeSendTextRequest(request) {
+    if (typeof request?.text !== 'string' || typeof request.idempotencyKey !== 'string'
+        || typeof request.target !== 'object' || request.target === null)
+        return undefined;
+    const text = request.text;
+    const codePoints = Array.from(text);
+    if (text.trim().length === 0 || codePoints.length > MAX_MESSAGE_CHARACTERS
+        || request.idempotencyKey.length === 0 || request.idempotencyKey.length > 512)
+        return undefined;
+    if (request.target.kind === 'direct') {
+        if (typeof request.target.peer !== 'string' || request.mentions !== undefined)
+            return undefined;
+    }
+    else if (request.target.kind === 'group') {
+        if (typeof request.target.group !== 'string')
+            return undefined;
+    }
+    else
+        return undefined;
+    if (request.mentions === undefined)
+        return request;
+    if (!Array.isArray(request.mentions) || request.mentions.length === 0 || request.mentions.length > 100)
+        return undefined;
+    const ids = new Set();
+    let previousEnd = 0;
+    const mentions = [...request.mentions].sort((left, right) => left.start - right.start || left.end - right.end);
+    for (const mention of mentions) {
+        if (typeof mention !== 'object' || mention === null
+            || typeof mention.id !== 'string' || mention.id.trim() === '' || ids.has(mention.id)
+            || !Number.isSafeInteger(mention.start) || !Number.isSafeInteger(mention.end)
+            || mention.start < previousEnd || mention.start < 0 || mention.end <= mention.start || mention.end > codePoints.length
+            || typeof mention.did !== 'string' || !mention.did.startsWith('did:')
+            || (mention.displayName !== undefined && typeof mention.displayName !== 'string'))
+            return undefined;
+        ids.add(mention.id);
+        previousEnd = mention.end;
+    }
+    return { ...request, mentions };
+}
 /** Normalize summary-provider failures without returning prompts, model output, routes, or causes. */
 function normalizeSummaryFailure(error) {
     if (error instanceof SummaryProviderUnavailableError)
@@ -367,17 +631,40 @@ let AwikiService = (() => {
     let _getSession_decorators;
     let _logout_decorators;
     let _login_decorators;
+    let _inspectIdentityAccess_decorators;
     let _sendRegistrationOtp_decorators;
     let _registerIdentity_decorators;
     let _updateDisplayName_decorators;
+    let _getProfile_decorators;
+    let _updateProfile_decorators;
+    let _sendRecoveryOtp_decorators;
+    let _prepareRecovery_decorators;
+    let _activateRecovery_decorators;
+    let _getRecoveryStatus_decorators;
+    let _resumeRecovery_decorators;
+    let _discardRecovery_decorators;
     let _resolvePeer_decorators;
+    let _createGroup_decorators;
+    let _getGroup_decorators;
+    let _joinGroup_decorators;
+    let _leaveGroup_decorators;
+    let _listGroupMembers_decorators;
+    let _addGroupMember_decorators;
+    let _removeGroupMember_decorators;
+    let _resumeGroupRebindRecovery_decorators;
     let _listConversations_decorators;
     let _getHistory_decorators;
+    let _getLocalHistory_decorators;
     let _summarizeConversation_decorators;
     let _markConversationRead_decorators;
     let _sendText_decorators;
     let _sendAttachment_decorators;
     let _downloadAttachment_decorators;
+    let _getMailAccount_decorators;
+    let _listMailInbox_decorators;
+    let _readMail_decorators;
+    let _markMailRead_decorators;
+    let _sendMail_decorators;
     let _clearLocalData_decorators;
     return class AwikiService extends _classSuper {
         static {
@@ -387,34 +674,80 @@ let AwikiService = (() => {
             _getSession_decorators = [Remote];
             _logout_decorators = [Remote];
             _login_decorators = [Remote];
+            _inspectIdentityAccess_decorators = [Remote];
             _sendRegistrationOtp_decorators = [Remote];
             _registerIdentity_decorators = [Remote];
             _updateDisplayName_decorators = [Remote];
+            _getProfile_decorators = [Remote];
+            _updateProfile_decorators = [Remote];
+            _sendRecoveryOtp_decorators = [Remote];
+            _prepareRecovery_decorators = [Remote];
+            _activateRecovery_decorators = [Remote];
+            _getRecoveryStatus_decorators = [Remote];
+            _resumeRecovery_decorators = [Remote];
+            _discardRecovery_decorators = [Remote];
             _resolvePeer_decorators = [Remote];
+            _createGroup_decorators = [Remote];
+            _getGroup_decorators = [Remote];
+            _joinGroup_decorators = [Remote];
+            _leaveGroup_decorators = [Remote];
+            _listGroupMembers_decorators = [Remote];
+            _addGroupMember_decorators = [Remote];
+            _removeGroupMember_decorators = [Remote];
+            _resumeGroupRebindRecovery_decorators = [Remote];
             _listConversations_decorators = [Remote];
             _getHistory_decorators = [Remote];
+            _getLocalHistory_decorators = [Remote];
             _summarizeConversation_decorators = [Remote];
             _markConversationRead_decorators = [Remote];
             _sendText_decorators = [Remote];
             _sendAttachment_decorators = [Remote];
             _downloadAttachment_decorators = [Remote];
+            _getMailAccount_decorators = [Remote];
+            _listMailInbox_decorators = [Remote];
+            _readMail_decorators = [Remote];
+            _markMailRead_decorators = [Remote];
+            _sendMail_decorators = [Remote];
             _clearLocalData_decorators = [Remote];
             __esDecorate(this, null, _getConfig_decorators, { kind: "method", name: "getConfig", static: false, private: false, access: { has: obj => "getConfig" in obj, get: obj => obj.getConfig }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getIdentity_decorators, { kind: "method", name: "getIdentity", static: false, private: false, access: { has: obj => "getIdentity" in obj, get: obj => obj.getIdentity }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getSession_decorators, { kind: "method", name: "getSession", static: false, private: false, access: { has: obj => "getSession" in obj, get: obj => obj.getSession }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _logout_decorators, { kind: "method", name: "logout", static: false, private: false, access: { has: obj => "logout" in obj, get: obj => obj.logout }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _login_decorators, { kind: "method", name: "login", static: false, private: false, access: { has: obj => "login" in obj, get: obj => obj.login }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _inspectIdentityAccess_decorators, { kind: "method", name: "inspectIdentityAccess", static: false, private: false, access: { has: obj => "inspectIdentityAccess" in obj, get: obj => obj.inspectIdentityAccess }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendRegistrationOtp_decorators, { kind: "method", name: "sendRegistrationOtp", static: false, private: false, access: { has: obj => "sendRegistrationOtp" in obj, get: obj => obj.sendRegistrationOtp }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _registerIdentity_decorators, { kind: "method", name: "registerIdentity", static: false, private: false, access: { has: obj => "registerIdentity" in obj, get: obj => obj.registerIdentity }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _updateDisplayName_decorators, { kind: "method", name: "updateDisplayName", static: false, private: false, access: { has: obj => "updateDisplayName" in obj, get: obj => obj.updateDisplayName }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getProfile_decorators, { kind: "method", name: "getProfile", static: false, private: false, access: { has: obj => "getProfile" in obj, get: obj => obj.getProfile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _updateProfile_decorators, { kind: "method", name: "updateProfile", static: false, private: false, access: { has: obj => "updateProfile" in obj, get: obj => obj.updateProfile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _sendRecoveryOtp_decorators, { kind: "method", name: "sendRecoveryOtp", static: false, private: false, access: { has: obj => "sendRecoveryOtp" in obj, get: obj => obj.sendRecoveryOtp }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _prepareRecovery_decorators, { kind: "method", name: "prepareRecovery", static: false, private: false, access: { has: obj => "prepareRecovery" in obj, get: obj => obj.prepareRecovery }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _activateRecovery_decorators, { kind: "method", name: "activateRecovery", static: false, private: false, access: { has: obj => "activateRecovery" in obj, get: obj => obj.activateRecovery }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getRecoveryStatus_decorators, { kind: "method", name: "getRecoveryStatus", static: false, private: false, access: { has: obj => "getRecoveryStatus" in obj, get: obj => obj.getRecoveryStatus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _resumeRecovery_decorators, { kind: "method", name: "resumeRecovery", static: false, private: false, access: { has: obj => "resumeRecovery" in obj, get: obj => obj.resumeRecovery }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _discardRecovery_decorators, { kind: "method", name: "discardRecovery", static: false, private: false, access: { has: obj => "discardRecovery" in obj, get: obj => obj.discardRecovery }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _resolvePeer_decorators, { kind: "method", name: "resolvePeer", static: false, private: false, access: { has: obj => "resolvePeer" in obj, get: obj => obj.resolvePeer }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _createGroup_decorators, { kind: "method", name: "createGroup", static: false, private: false, access: { has: obj => "createGroup" in obj, get: obj => obj.createGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getGroup_decorators, { kind: "method", name: "getGroup", static: false, private: false, access: { has: obj => "getGroup" in obj, get: obj => obj.getGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _joinGroup_decorators, { kind: "method", name: "joinGroup", static: false, private: false, access: { has: obj => "joinGroup" in obj, get: obj => obj.joinGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _leaveGroup_decorators, { kind: "method", name: "leaveGroup", static: false, private: false, access: { has: obj => "leaveGroup" in obj, get: obj => obj.leaveGroup }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listGroupMembers_decorators, { kind: "method", name: "listGroupMembers", static: false, private: false, access: { has: obj => "listGroupMembers" in obj, get: obj => obj.listGroupMembers }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _addGroupMember_decorators, { kind: "method", name: "addGroupMember", static: false, private: false, access: { has: obj => "addGroupMember" in obj, get: obj => obj.addGroupMember }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _removeGroupMember_decorators, { kind: "method", name: "removeGroupMember", static: false, private: false, access: { has: obj => "removeGroupMember" in obj, get: obj => obj.removeGroupMember }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _resumeGroupRebindRecovery_decorators, { kind: "method", name: "resumeGroupRebindRecovery", static: false, private: false, access: { has: obj => "resumeGroupRebindRecovery" in obj, get: obj => obj.resumeGroupRebindRecovery }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _listConversations_decorators, { kind: "method", name: "listConversations", static: false, private: false, access: { has: obj => "listConversations" in obj, get: obj => obj.listConversations }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getHistory_decorators, { kind: "method", name: "getHistory", static: false, private: false, access: { has: obj => "getHistory" in obj, get: obj => obj.getHistory }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getLocalHistory_decorators, { kind: "method", name: "getLocalHistory", static: false, private: false, access: { has: obj => "getLocalHistory" in obj, get: obj => obj.getLocalHistory }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _summarizeConversation_decorators, { kind: "method", name: "summarizeConversation", static: false, private: false, access: { has: obj => "summarizeConversation" in obj, get: obj => obj.summarizeConversation }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _markConversationRead_decorators, { kind: "method", name: "markConversationRead", static: false, private: false, access: { has: obj => "markConversationRead" in obj, get: obj => obj.markConversationRead }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendText_decorators, { kind: "method", name: "sendText", static: false, private: false, access: { has: obj => "sendText" in obj, get: obj => obj.sendText }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendAttachment_decorators, { kind: "method", name: "sendAttachment", static: false, private: false, access: { has: obj => "sendAttachment" in obj, get: obj => obj.sendAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _downloadAttachment_decorators, { kind: "method", name: "downloadAttachment", static: false, private: false, access: { has: obj => "downloadAttachment" in obj, get: obj => obj.downloadAttachment }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getMailAccount_decorators, { kind: "method", name: "getMailAccount", static: false, private: false, access: { has: obj => "getMailAccount" in obj, get: obj => obj.getMailAccount }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listMailInbox_decorators, { kind: "method", name: "listMailInbox", static: false, private: false, access: { has: obj => "listMailInbox" in obj, get: obj => obj.listMailInbox }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _readMail_decorators, { kind: "method", name: "readMail", static: false, private: false, access: { has: obj => "readMail" in obj, get: obj => obj.readMail }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _markMailRead_decorators, { kind: "method", name: "markMailRead", static: false, private: false, access: { has: obj => "markMailRead" in obj, get: obj => obj.markMailRead }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _sendMail_decorators, { kind: "method", name: "sendMail", static: false, private: false, access: { has: obj => "sendMail" in obj, get: obj => obj.sendMail }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _clearLocalData_decorators, { kind: "method", name: "clearLocalData", static: false, private: false, access: { has: obj => "clearLocalData" in obj, get: obj => obj.clearLocalData }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
@@ -422,25 +755,33 @@ let AwikiService = (() => {
         static Config = Config;
         resolved = __runInitializers(this, _instanceExtraInitializers);
         sessionStore;
+        imageAttachmentCache;
+        sentMailStore;
         startupUserServiceDomain;
         settingsProvider;
         provider;
         signedOut;
         sessionMutation = Promise.resolve();
         sessionRevision = 0;
+        activeIdentityDid;
         activeSummaryRequests = new Set();
         summaryProvider;
+        hostContext;
         /** Trusted same-process external HTTP authentication dispatcher. Never Remote. */
         externalHttpAuth;
+        workspaceContext;
         /**
          * @param ctx - owning Host context.
          * @param config - service endpoints, SDK state path, and public limits.
          */
         constructor(ctx, config) {
             super(ctx, 'awiki');
+            this.hostContext = ctx;
             this.resolved = resolveConfig(config);
             this.externalHttpAuth = createAwikiExternalHttpAuth(() => this.acquireExternalHttpAuthSession());
             this.sessionStore = new AwikiSessionStore(this.resolved.stateRoot);
+            this.imageAttachmentCache = new AwikiImageAttachmentCache(this.resolved.stateRoot, this.resolved.attachmentMaxBytes, this.resolved.imageAttachmentCacheMaxBytes);
+            this.sentMailStore = new AwikiSentMailStore(this.resolved.stateRoot);
             this.startupUserServiceDomain = this.resolved.userServiceDomain;
             ctx.inject(['settings'], (settingsCtx) => {
                 const provider = settingsCtx.settings;
@@ -461,6 +802,20 @@ let AwikiService = (() => {
             ctx.inject(['connection'], (connectionCtx) => {
                 connectionCtx.connection.rpc.handle(AWIKI_SETTINGS_RPC_CHANNEL, createAwikiSettingsRpcHandler(() => this.settingsProvider), { authority: 'loopback' });
             });
+            ctx.inject(['workspaceRegistry'], (workspaceCtx) => {
+                this.workspaceContext = workspaceCtx;
+                const provider = this.provider;
+                if (provider !== undefined)
+                    void this.startListener(provider);
+                workspaceCtx.effect(() => async () => {
+                    if (this.workspaceContext !== workspaceCtx)
+                        return;
+                    this.workspaceContext = undefined;
+                    const current = this.provider;
+                    if (current !== undefined)
+                        await this.stopListener(current);
+                }, 'awiki: release Workspace listener composition');
+            });
             registerAwikiTools(ctx, this);
             ctx.effect(() => async () => {
                 const provider = this.provider;
@@ -485,6 +840,7 @@ let AwikiService = (() => {
                 userServiceUrl: this.resolved.userServiceUrl,
                 userServiceDomain: this.startupUserServiceDomain,
                 messageServiceUrl: this.resolved.messageServiceUrl,
+                mailServiceUrl: this.resolved.mailServiceUrl,
                 messageServicePublicUrl: this.resolved.messageServicePublicUrl,
                 messageServiceDid: this.resolved.messageServiceDid,
                 allowedAttachmentOrigins: this.resolved.allowedAttachmentOrigins,
@@ -492,8 +848,14 @@ let AwikiService = (() => {
                 allowInsecureLoopbackForTesting: this.resolved.allowInsecureLoopbackForTesting,
                 stateRoot: this.resolved.stateRoot,
             });
-            const provider = { client };
+            const provider = {
+                client,
+                listenerRestartAttempt: 0,
+                listenerGeneration: 0,
+                listenerRecoveryBlocked: false,
+            };
             this.provider = provider;
+            void this.startListener(provider);
             return () => this.disposeProvider(provider);
         }
         /** Register one replaceable conversation-summary provider for this deployment. */
@@ -527,16 +889,22 @@ let AwikiService = (() => {
          * Read the deployment's identity status.
          * @returns The public deployment identity or `null`.
          */
-        getIdentity() {
-            return this.run(client => client.getIdentity());
+        async getIdentity() {
+            const result = await this.run(client => client.getIdentity());
+            if (result.ok)
+                this.activeIdentityDid = result.value?.did;
+            return result;
         }
         /** Return the local registration and sign-in state without exposing secrets. */
         async getSession() {
-            if (await this.isSignedOut())
+            if (await this.isSignedOut()) {
+                this.activeIdentityDid = undefined;
                 return { ok: true, value: { status: 'signed-out' } };
+            }
             const identity = await this.run(client => client.getIdentity(), { allowSignedOut: true });
             if (!identity.ok)
                 return identity;
+            this.activeIdentityDid = identity.value?.did;
             return identity.value === null
                 ? { ok: true, value: { status: 'unregistered' } }
                 : { ok: true, value: { status: 'active', identity: identity.value } };
@@ -557,8 +925,14 @@ let AwikiService = (() => {
                 try {
                     await this.sessionStore.signOut();
                     this.signedOut = true;
+                    this.activeIdentityDid = undefined;
                     this.invalidateSummaries();
-                    return { ok: true, value: { status: 'signed-out' } };
+                    const session = { status: 'signed-out' };
+                    this.publishSession(session);
+                    const provider = this.provider;
+                    if (provider !== undefined)
+                        await this.stopListener(provider);
+                    return { ok: true, value: session };
                 }
                 catch {
                     return { ok: false, error: failure('remote') };
@@ -576,19 +950,70 @@ let AwikiService = (() => {
                 try {
                     await this.sessionStore.signIn();
                     this.signedOut = false;
+                    this.activeIdentityDid = identity.value.did;
                     this.invalidateSummaries();
-                    return { ok: true, value: { status: 'active', identity: identity.value } };
+                    const session = { status: 'active', identity: identity.value };
+                    this.publishSession(session);
+                    const provider = this.provider;
+                    if (provider !== undefined)
+                        void this.startListener(provider);
+                    return { ok: true, value: session };
                 }
                 catch {
                     return { ok: false, error: failure('remote') };
                 }
             });
         }
-        /**
-         * Send one Legacy registration verification code.
-         * @param request - Handle and phone used for the registration challenge.
-         * @returns Public retry timing or a closed failure.
-         */
+        /** Classify one configured-domain Handle before selecting the registration or recovery OTP purpose. */
+        async inspectIdentityAccess(request) {
+            const target = identityAccessTarget(request, this.startupUserServiceDomain);
+            if (target === undefined)
+                return { ok: false, error: failure('invalid-request') };
+            const endpoint = new URL(`/.well-known/handle/${encodeURIComponent(target.localPart)}`, this.resolved.userServiceUrl);
+            const abort = new AbortController();
+            const timeout = setTimeout(() => { abort.abort(); }, 10_000);
+            let response;
+            try {
+                response = await fetch(endpoint, {
+                    method: 'GET',
+                    headers: { accept: 'application/json', 'cache-control': 'no-store' },
+                    cache: 'no-store',
+                    redirect: 'error',
+                    signal: abort.signal,
+                });
+            }
+            catch {
+                return { ok: false, error: failure('network') };
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            if (response.status === 404) {
+                return { ok: true, value: { status: 'available', fullHandle: target.fullHandle } };
+            }
+            if (!response.ok)
+                return { ok: false, error: failure('remote') };
+            try {
+                const text = await readBoundedResponseText(response, IDENTITY_ACCESS_RESPONSE_MAX_BYTES);
+                if (text === undefined)
+                    return { ok: false, error: failure('remote') };
+                const value = JSON.parse(text);
+                if (typeof value !== 'object' || value === null)
+                    return { ok: false, error: failure('remote') };
+                const binding = value;
+                if (binding.handle !== target.fullHandle
+                    || typeof binding.did !== 'string'
+                    || !binding.did.startsWith('did:')
+                    || typeof binding.status !== 'string'
+                    || binding.status.length === 0) {
+                    return { ok: false, error: failure('remote') };
+                }
+                return { ok: true, value: { status: 'existing', fullHandle: target.fullHandle } };
+            }
+            catch {
+                return { ok: false, error: failure('remote') };
+            }
+        }
         sendRegistrationOtp(request) {
             return this.run(client => client.sendRegistrationOtp(request));
         }
@@ -597,16 +1022,88 @@ let AwikiService = (() => {
          * @param request - Handle, phone, and verification code for registration.
          * @returns The new public identity or a closed failure.
          */
-        registerIdentity(request) {
-            return this.run(client => client.registerIdentity(request));
+        async registerIdentity(request) {
+            const result = await this.run(client => client.registerIdentity(request));
+            if (result.ok)
+                await this.activateRegisteredIdentity(result.value);
+            return result;
         }
         /**
          * Update the deployment identity's public WNS display name.
          * @param request - replacement display name selected by the user.
          * @returns The updated public identity or a closed failure.
          */
-        updateDisplayName(request) {
-            return this.run(client => client.updateDisplayName(request));
+        async updateDisplayName(request) {
+            const result = await this.run(client => client.updateDisplayName(request));
+            if (result.ok)
+                this.activeIdentityDid = result.value.did;
+            return result;
+        }
+        /** Return the public editable profile for the active identity. */
+        getProfile() {
+            return this.run(client => client.getProfile());
+        }
+        /** Update Display Name, bio, and tags after applying product limits in the Host. */
+        updateProfile(request) {
+            const normalized = normalizeProfileRequest(request);
+            if (normalized === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.updateProfile(normalized));
+        }
+        /** Start durable phone recovery for one existing full Handle. */
+        sendRecoveryOtp(request) {
+            const normalized = normalizeRecoveryOtpRequest(request);
+            if (normalized === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.sendRecoveryOtp(normalized), { allowSignedOut: true });
+        }
+        /** Verify a recovery OTP and freeze its exact intent before the remote commit. */
+        prepareRecovery(request) {
+            const normalized = normalizeRecoveryPrepareRequest(request);
+            if (normalized === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.prepareRecovery(normalized), { allowSignedOut: true });
+        }
+        /** Attempt one prepared recovery commit; uncertain outcomes remain durable in Core. */
+        async activateRecovery(request) {
+            const normalized = normalizeRecoveryOperation(request);
+            if (normalized === undefined)
+                return { ok: false, error: failure('invalid-request') };
+            const result = await this.run(client => client.activateRecovery(normalized), { allowSignedOut: true });
+            if (result.ok && !await this.applyRecoveredSession(result.value)) {
+                return { ok: false, error: failure('remote') };
+            }
+            return result;
+        }
+        /** Read durable recovery state before deciding whether a retry is valid. */
+        async getRecoveryStatus(request) {
+            const normalized = normalizeRecoveryOperation(request);
+            if (normalized === undefined)
+                return { ok: false, error: failure('invalid-request') };
+            const result = await this.run(client => client.getRecoveryStatus(normalized), { allowSignedOut: true });
+            if (result.ok && !await this.applyRecoveredSession(result.value)) {
+                return { ok: false, error: failure('remote') };
+            }
+            return result;
+        }
+        /** Resume only the exact Core-owned operation selected by the browser. */
+        async resumeRecovery(request) {
+            const normalized = normalizeRecoveryOperation(request);
+            if (normalized === undefined)
+                return { ok: false, error: failure('invalid-request') };
+            const result = await this.run(client => client.resumeRecovery(normalized), { allowSignedOut: true });
+            if (result.ok && !await this.applyRecoveredSession(result.value)) {
+                return { ok: false, error: failure('remote') };
+            }
+            return result;
+        }
+        /** Discard only a pre-attempt operation; Core rejects post-attempt deletion. */
+        async discardRecovery(request) {
+            const normalized = normalizeRecoveryOperation(request);
+            if (normalized === undefined)
+                return { ok: false, error: failure('invalid-request') };
+            const result = await this.run(client => client.discardRecovery(normalized), { allowSignedOut: true });
+            return result.ok ? { ok: true, value: { completed: true } } : result;
         }
         /**
          * Resolve one Handle or DID before the browser opens a direct chat.
@@ -616,6 +1113,96 @@ let AwikiService = (() => {
         resolvePeer(request) {
             return this.run(client => client.resolvePeer(request.peer));
         }
+        /**
+         * Create one group, then settle every initial-member invitation without hiding a created group.
+         * @param request - bounded group name and initial Handle/DID values.
+         * @returns The created conversation and per-member outcomes.
+         */
+        async createGroup(request) {
+            const normalized = normalizeCreateGroupRequest(request);
+            if (normalized === undefined)
+                return { ok: false, error: failure('invalid-request') };
+            const created = await this.run(client => client.createGroup(normalized.name));
+            if (!created.ok)
+                return created;
+            const addedMembers = [];
+            const failedMembers = [];
+            for (const member of normalized.members) {
+                const result = await this.run(client => client.addGroupMember(created.value.groupDid, member));
+                if (result.ok)
+                    addedMembers.push(result.value);
+                else
+                    failedMembers.push({ member, error: result.error });
+            }
+            return {
+                ok: true,
+                value: { conversation: created.value, addedMembers, failedMembers },
+            };
+        }
+        /** Return one authoritative group snapshot for permission-aware UI. */
+        getGroup(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            if (groupDid === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.getGroup(groupDid));
+        }
+        /** Join one open group and return its authoritative membership state. */
+        joinGroup(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            if (groupDid === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.joinGroup(groupDid));
+        }
+        /** Leave one group. Core rejects owner leave and unsupported security profiles. */
+        async leaveGroup(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            if (groupDid === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            const result = await this.run(client => client.leaveGroup(groupDid));
+            return result.ok ? { ok: true, value: { completed: true } } : result;
+        }
+        /** Read one authoritative versioned member page. */
+        listGroupMembers(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            if (groupDid === undefined
+                || (request.cursor !== undefined && (typeof request.cursor !== 'string' || request.cursor.length > 4_096))
+                || (request.limit !== undefined && (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 100))) {
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            }
+            return this.run(client => client.listGroupMembers({
+                groupDid,
+                ...request.cursor === undefined ? {} : { cursor: request.cursor },
+                ...request.limit === undefined ? {} : { limit: request.limit },
+            }));
+        }
+        /** Invite one ordinary member after group creation. */
+        addGroupMember(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            const member = normalizeMember(request?.member);
+            if (groupDid === undefined || member === undefined || (request.role !== undefined && request.role !== 'member')) {
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            }
+            return this.run(client => client.addGroupMember(groupDid, member));
+        }
+        /** Remove one member. The authoritative Core role check remains decisive. */
+        removeGroupMember(request) {
+            const groupDid = normalizeGroupDid(request?.groupDid);
+            const member = normalizeMember(request?.member);
+            if (groupDid === undefined || member === undefined) {
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            }
+            return this.run(client => client.removeGroupMember(groupDid, member));
+        }
+        /** Resume durable group membership convergence after account sync restores old groups. */
+        async resumeGroupRebindRecovery() {
+            const result = await this.run(client => client.resumeGroupRebindRecovery());
+            if (!result.ok)
+                return result;
+            const summary = publicGroupRebindRecoverySummary(result.value);
+            return summary === undefined
+                ? { ok: false, error: failure('remote') }
+                : { ok: true, value: summary };
+        }
         /**
          * List direct and existing group conversations.
          * @param request - Optional opaque cursor and page limit.
@@ -632,6 +1219,10 @@ let AwikiService = (() => {
         getHistory(request) {
             return this.run(client => client.getHistory(request));
         }
+        /** Read one committed local conversation page without sync, history, or Directory RPC. */
+        getLocalHistory(request) {
+            return this.run(client => client.getLocalHistory(request));
+        }
         /**
          * Read real AWiki history, enforce range and byte caps, then invoke the configured model once.
          * @param request - selected conversation and its unread snapshot at open time.
@@ -736,7 +1327,10 @@ let AwikiService = (() => {
          * @returns The accepted public message or a closed failure.
          */
         sendText(request) {
-            return this.run(client => client.sendText(request));
+            const normalized = normalizeSendTextRequest(request);
+            if (normalized === undefined)
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            return this.run(client => client.sendText(normalized));
         }
         /**
          * Upload and send one attachment after Host validation.
@@ -747,16 +1341,29 @@ let AwikiService = (() => {
             const decoded = decodeAttachment(request.bytesBase64, this.resolved.attachmentMaxBytes);
             if (!decoded.ok)
                 return decoded;
-            return this.run(client => client.sendAttachment({
-                target: request.target,
-                attachment: {
-                    fileName: request.fileName,
-                    mimeType: request.mimeType,
-                    bytes: decoded.value,
-                },
-                ...request.caption === undefined ? {} : { caption: request.caption },
-                idempotencyKey: request.idempotencyKey,
-            }), { skipAttachmentByteValidation: true });
+            return this.run(async (client) => {
+                const message = await client.sendAttachment({
+                    target: request.target,
+                    attachment: {
+                        fileName: request.fileName,
+                        mimeType: request.mimeType,
+                        bytes: decoded.value,
+                    },
+                    ...request.caption === undefined ? {} : { caption: request.caption },
+                    idempotencyKey: request.idempotencyKey,
+                });
+                if (message.content.kind === 'attachment') {
+                    const ownerDid = this.activeIdentityDid ?? (await client.getIdentity().catch(() => null))?.did;
+                    if (ownerDid !== undefined) {
+                        this.activeIdentityDid = ownerDid;
+                        await this.imageAttachmentCache.write(ownerDid, message.id, {
+                            attachment: message.content.attachment,
+                            bytes: decoded.value,
+                        }).catch(() => undefined);
+                    }
+                }
+                return message;
+            }, { skipAttachmentByteValidation: true });
         }
         /**
          * Download and encode one provider-verified attachment.
@@ -764,16 +1371,112 @@ let AwikiService = (() => {
          * @returns Verified public metadata and canonical Base64 bytes, or a closed failure.
          */
         async downloadAttachment(request) {
-            const result = await this.run(client => client.downloadAttachment(request), { skipAttachmentByteValidation: true });
+            try {
+                if (await this.isSignedOut())
+                    return { ok: false, error: failure('signed-out') };
+            }
+            catch {
+                return { ok: false, error: failure('remote') };
+            }
+            if (this.provider !== undefined && this.activeIdentityDid !== undefined) {
+                const cached = await this.imageAttachmentCache.read(this.activeIdentityDid, request);
+                if (cached !== undefined)
+                    return this.publicDownloadedAttachment(cached);
+            }
+            const result = await this.run(async (client) => {
+                const identity = this.activeIdentityDid === undefined ? await client.getIdentity() : undefined;
+                const ownerDid = this.activeIdentityDid ?? identity?.did;
+                if (ownerDid === undefined)
+                    throw Object.assign(new Error('not registered'), { name: 'AwikiSdkError', code: 'not-registered' });
+                this.activeIdentityDid = ownerDid;
+                const cached = await this.imageAttachmentCache.read(ownerDid, request);
+                if (cached !== undefined)
+                    return cached;
+                const downloaded = await client.downloadAttachment(request);
+                await this.imageAttachmentCache.write(ownerDid, request.messageId, downloaded).catch(() => undefined);
+                return downloaded;
+            }, { skipAttachmentByteValidation: true });
             if (!result.ok)
                 return result;
-            if (result.value.bytes.byteLength > this.resolved.attachmentMaxBytes) {
+            return this.publicDownloadedAttachment(result.value);
+        }
+        /** Revalidate cached/provider bytes before crossing the browser Remote boundary. */
+        publicDownloadedAttachment(value) {
+            if (value.bytes.byteLength > this.resolved.attachmentMaxBytes) {
                 return { ok: false, error: failure('attachment-too-large') };
             }
-            if (result.value.bytes.byteLength !== result.value.attachment.size) {
+            if (value.bytes.byteLength !== value.attachment.size) {
                 return { ok: false, error: failure('remote') };
             }
-            return { ok: true, value: downloadedAttachment(result.value) };
+            return { ok: true, value: downloadedAttachment(value) };
+        }
+        /** Return the deployment identity's public mailbox state. */
+        getMailAccount() {
+            return this.run(client => client.getMailAccount());
+        }
+        /** List one bounded mailbox page on explicit browser/tool demand. */
+        async listMailInbox(request) {
+            let normalized;
+            try {
+                normalized = mailInboxRequest(request ?? {});
+            }
+            catch {
+                return { ok: false, error: failure('invalid-request') };
+            }
+            return this.run(async (client) => {
+                if (normalized.folder !== 'sent')
+                    return client.listMailInbox(normalized);
+                return this.sentMailStore.list(await this.ownerDid(client), normalized);
+            });
+        }
+        /** Read one bounded plain-text mail message. */
+        async readMail(request) {
+            let normalized;
+            try {
+                normalized = mailReadRequest(request);
+            }
+            catch {
+                return { ok: false, error: failure('invalid-request') };
+            }
+            return this.run(async (client) => {
+                if (!isLocalSentMailId(normalized.messageId))
+                    return client.readMail(normalized);
+                const local = await this.sentMailStore.read(await this.ownerDid(client), normalized.messageId);
+                if (local === undefined) {
+                    throw Object.assign(new Error('sent mail not found'), { name: 'AwikiSdkError', code: 'not-found' });
+                }
+                return local;
+            });
+        }
+        /** Mark explicitly selected mail messages read. Browser callers require an explicit click. */
+        markMailRead(request) {
+            return this.runValidatedMail(() => mailMarkReadRequest(request), (client, normalized) => client.markMailRead(normalized));
+        }
+        /** Send one plain-text mail once. Browser callers require an explicit confirmation. */
+        async sendMail(request) {
+            let normalized;
+            try {
+                normalized = mailSendRequest(request);
+            }
+            catch {
+                return { ok: false, error: failure('invalid-request') };
+            }
+            return this.run(async (client) => {
+                const result = await client.sendMail(normalized);
+                if (!result.accepted)
+                    return result;
+                try {
+                    const ownerDid = await this.ownerDid(client);
+                    const account = await client.getMailAccount().catch(() => undefined);
+                    await this.sentMailStore.append(ownerDid, normalized, result, account);
+                    return result;
+                }
+                catch {
+                    return result.warnings.length >= 100
+                        ? result
+                        : { ...result, warnings: [...result.warnings, 'Sent history could not be saved locally.'] };
+                }
+            });
         }
         /**
          * Permanently remove the exact SDK-owned local state after an explicit browser acknowledgement.
@@ -786,13 +1489,25 @@ let AwikiService = (() => {
                 return Promise.resolve({ ok: false, error: failure('invalid-request') });
             }
             return this.mutateSession(async () => {
+                const provider = this.provider;
+                if (provider !== undefined)
+                    await this.stopListener(provider);
                 const result = await this.run(client => client.clearLocalData(), { allowSignedOut: true });
-                if (!result.ok)
+                if (!result.ok) {
+                    if (provider !== undefined && this.provider === provider)
+                        void this.startListener(provider);
                     return result;
+                }
                 try {
+                    await this.imageAttachmentCache.clear();
+                    await this.sentMailStore.clear();
                     await this.sessionStore.signIn();
                     this.signedOut = false;
+                    this.activeIdentityDid = undefined;
                     this.invalidateSummaries();
+                    this.publishSession({ status: 'unregistered' });
+                    if (provider !== undefined && this.provider === provider)
+                        void this.startListener(provider);
                     return result;
                 }
                 catch {
@@ -800,6 +1515,45 @@ let AwikiService = (() => {
                 }
             });
         }
+        /** Re-enter only after Core confirms that the exact recovered identity is applied locally. */
+        async applyRecoveredSession(progress) {
+            if (progress.phase !== 'applied')
+                return true;
+            return this.mutateSession(async () => {
+                const provider = this.provider;
+                if (provider === undefined)
+                    return false;
+                try {
+                    const identity = await provider.client.getIdentity();
+                    if (identity === null || identity.did !== progress.currentDid)
+                        return false;
+                    if (this.signedOut === false && this.activeIdentityDid === identity.did)
+                        return true;
+                    await this.sessionStore.signIn();
+                    this.signedOut = false;
+                    this.activeIdentityDid = identity.did;
+                    this.invalidateSummaries();
+                    const session = { status: 'active', identity };
+                    this.publishSession(session);
+                    await provider.listenerStartup;
+                    await this.startListener(provider);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        /** Publish one newly registered identity and start its listener through the existing session path. */
+        async activateRegisteredIdentity(identity) {
+            this.activeIdentityDid = identity.did;
+            this.publishSession({ status: 'active', identity });
+            const provider = this.provider;
+            if (provider !== undefined) {
+                await provider.listenerStartup;
+                await this.startListener(provider);
+            }
+        }
         /** Invalidate cached session work and cancel every model request still owned by the old session. */
         invalidateSummaries() {
             this.sessionRevision += 1;
@@ -807,6 +1561,20 @@ let AwikiService = (() => {
                 controller.abort();
             this.activeSummaryRequests.clear();
         }
+        /** Publish a committed session transition to same-process Host consumers. */
+        publishSession(session) {
+            this.hostContext.emit('awiki/session', session);
+        }
+        /** Resolve and cache the owner binding required by private Host-side projections. */
+        async ownerDid(client) {
+            const identity = this.activeIdentityDid === undefined ? await client.getIdentity() : undefined;
+            const ownerDid = this.activeIdentityDid ?? identity?.did;
+            if (ownerDid === undefined) {
+                throw Object.assign(new Error('not registered'), { name: 'AwikiSdkError', code: 'not-registered' });
+            }
+            this.activeIdentityDid = ownerDid;
+            return ownerDid;
+        }
         /** Invoke the current client and normalize every rejection to a public result. */
         async run(operation, options = {}) {
             try {
@@ -826,6 +1594,17 @@ let AwikiService = (() => {
                 return { ok: false, error: normalizeFailure(error) };
             }
         }
+        /** Validate mail input before entering the provider and preserve fixed public failures. */
+        runValidatedMail(validate, operation) {
+            let request;
+            try {
+                request = validate();
+            }
+            catch {
+                return Promise.resolve({ ok: false, error: failure('invalid-request') });
+            }
+            return this.run(client => operation(client, request));
+        }
         /** Read and cache the private Host-owned session marker. */
         async isSignedOut() {
             this.signedOut ??= await this.sessionStore.isSignedOut();
@@ -879,11 +1658,163 @@ let AwikiService = (() => {
             this.sessionMutation = pending.then(() => undefined, () => undefined);
             return pending;
         }
+        /** Start one exact identity-bound listener, atomically releasing a failed startup. */
+        startListener(provider) {
+            if (!this.resolved.listenerEnabled
+                || provider.listener !== undefined
+                || provider.listenerRecoveryBlocked
+                || this.provider !== provider) {
+                return Promise.resolve();
+            }
+            if (provider.listenerStartup !== undefined)
+                return provider.listenerStartup;
+            if (provider.listenerCleanup !== undefined || provider.listenerRestartTimer !== undefined)
+                return Promise.resolve();
+            const workspaceContext = this.workspaceContext;
+            const source = provider.client.listener;
+            if (workspaceContext === undefined || source === undefined)
+                return Promise.resolve();
+            const generation = provider.listenerGeneration;
+            const logger = this.ctx.logger('awiki-listener');
+            const startup = (async () => {
+                if (await this.isSignedOut())
+                    return;
+                if (await provider.client.getIdentity() === null)
+                    return;
+                if (!this.listenerFenceMatches(provider, workspaceContext, generation))
+                    return;
+                const agents = new DshAwikiListenerAgentRuntime(workspaceContext, this.resolved.listener.workspacePath);
+                const listener = new AwikiAgentListener(source, agents, this.resolved.listener, logger);
+                provider.listener = listener;
+                try {
+                    await listener.start();
+                }
+                catch (error) {
+                    if (provider.listener === listener)
+                        delete provider.listener;
+                    try {
+                        await listener.dispose();
+                    }
+                    catch {
+                        provider.listenerRecoveryBlocked = true;
+                    }
+                    if (!provider.listenerRecoveryBlocked && provider.listenerRestartAttempt > 0) {
+                        this.scheduleListenerRestart(provider, workspaceContext, generation);
+                    }
+                    throw error;
+                }
+                if (!this.listenerFenceMatches(provider, workspaceContext, generation)) {
+                    if (provider.listener === listener)
+                        delete provider.listener;
+                    try {
+                        await listener.dispose();
+                    }
+                    catch (error) {
+                        provider.listenerRecoveryBlocked = true;
+                        throw error;
+                    }
+                    return;
+                }
+                provider.listenerStartedAt = Date.now();
+                void listener.whenTerminated().then((result) => {
+                    if (result.kind === 'failed') {
+                        this.releaseFailedListener(provider, listener, workspaceContext, generation, result.error);
+                    }
+                });
+            })();
+            const observed = startup
+                .catch((error) => {
+                logger.warn('AWiki listener startup failed: %s', error instanceof Error ? error.message : 'unknown failure');
+            })
+                .finally(() => {
+                if (provider.listenerStartup === observed)
+                    delete provider.listenerStartup;
+            });
+            provider.listenerStartup = observed;
+            return observed;
+        }
+        async stopListener(provider) {
+            provider.listenerGeneration += 1;
+            provider.listenerRestartAttempt = 0;
+            delete provider.listenerStartedAt;
+            const timer = provider.listenerRestartTimer;
+            if (timer !== undefined) {
+                delete provider.listenerRestartTimer;
+                clearTimeout(timer);
+            }
+            await provider.listenerStartup;
+            await provider.listenerCleanup;
+            const listener = provider.listener;
+            if (listener === undefined)
+                return;
+            delete provider.listener;
+            try {
+                await listener.dispose();
+            }
+            catch (error) {
+                provider.listenerRecoveryBlocked = true;
+                throw error;
+            }
+        }
+        listenerFenceMatches(provider, workspaceContext, generation) {
+            return this.provider === provider
+                && this.workspaceContext === workspaceContext
+                && provider.listenerGeneration === generation;
+        }
+        releaseFailedListener(provider, listener, workspaceContext, generation, error) {
+            if (provider.listener !== listener)
+                return;
+            delete provider.listener;
+            const startedAt = provider.listenerStartedAt;
+            delete provider.listenerStartedAt;
+            if (startedAt !== undefined && Date.now() - startedAt >= LISTENER_STABLE_RESET_MS) {
+                provider.listenerRestartAttempt = 0;
+            }
+            const logger = this.ctx.logger('awiki-listener');
+            logger.warn('AWiki listener lifecycle failed: %s', error instanceof Error ? error.message : 'unknown failure');
+            let disposed = false;
+            const cleanup = listener.dispose()
+                .then(() => { disposed = true; }, (cleanupError) => {
+                provider.listenerRecoveryBlocked = true;
+                logger.warn('AWiki listener cleanup failed: %s', cleanupError instanceof Error ? cleanupError.message : 'unknown failure');
+            });
+            const observed = cleanup.finally(() => {
+                if (provider.listenerCleanup === observed)
+                    delete provider.listenerCleanup;
+                if (disposed)
+                    this.scheduleListenerRestart(provider, workspaceContext, generation);
+            });
+            provider.listenerCleanup = observed;
+        }
+        scheduleListenerRestart(provider, workspaceContext, generation) {
+            if (provider.listenerRestartTimer !== undefined
+                || !this.listenerFenceMatches(provider, workspaceContext, generation))
+                return;
+            provider.listenerRestartAttempt = Math.min(provider.listenerRestartAttempt + 1, LISTENER_RESTART_MAX_ATTEMPT);
+            const exponent = provider.listenerRestartAttempt - 1;
+            const delay = Math.min(LISTENER_RESTART_BASE_DELAY_MS * 2 ** exponent, LISTENER_RESTART_MAX_DELAY_MS);
+            const timer = setTimeout(() => {
+                if (provider.listenerRestartTimer !== timer)
+                    return;
+                delete provider.listenerRestartTimer;
+                if (!this.listenerFenceMatches(provider, workspaceContext, generation))
+                    return;
+                void this.startListener(provider);
+            }, delay);
+            provider.listenerRestartTimer = timer;
+        }
         /** Clear one exact provider slot before joining its one shared disposal. */
         disposeProvider(provider) {
             if (this.provider === provider)
                 this.provider = undefined;
-            provider.disposal ??= provider.client.dispose();
+            provider.disposal ??= (async () => {
+                try {
+                    await this.stopListener(provider);
+                }
+                finally {
+                    await provider.client.dispose();
+                }
+            })();
             return provider.disposal;
         }
     };