soulnet-dsh 0.1.0

package/lib/types/client/locales.d.ts

@@ -0,0 +1,239 @@
+export declare const NS = "soulmirror";
+export declare const en: {
+    readonly 'view.tab': "SoulMirror";
+    readonly 'sidebar.entry': "SoulMirror";
+    readonly 'sidebar.unread': "{n} unread";
+    readonly 'inbox.title': "SoulMirror";
+    readonly 'inbox.hint': "Your alter speaks to your friends on your behalf. Open SoulMirror to talk to it, watch its conversations and review its drafts; click a friend to open that thread.";
+    readonly 'inbox.friends': "Friends";
+    readonly 'inbox.pending': "Pending requests ({n})";
+    readonly 'inbox.pending.noGreeting': "(no greeting)";
+    readonly 'inbox.pending.accepted': "Accepted {name}.";
+    readonly 'inbox.empty': "No friends yet — paste a card URI below, or /add.";
+    readonly 'inbox.empty.noIdentity': "No identity yet — create one in Settings → SoulMirror network.";
+    readonly 'inbox.noIdentity': "No identity yet";
+    readonly 'inbox.noMessages': "No messages yet";
+    readonly 'inbox.typing': "typing…";
+    readonly 'inbox.online': "online";
+    readonly 'inbox.offline': "offline";
+    readonly 'inbox.open': "Open the thread with {name}";
+    readonly 'inbox.close': "Close";
+    readonly 'inbox.card.copy': "Copy my card URI";
+    readonly 'inbox.card.copied': "Copied";
+    readonly 'inbox.add': "Add";
+    readonly 'inbox.add.placeholder': "Add a friend: paste a card URI (soulmirror://card?…)";
+    readonly 'toast.newMail': "New message from {name}";
+    readonly 'bubble.in': "from {name}";
+    readonly 'bubble.out': "to {name}";
+    readonly 'bubble.mine': "my alter";
+    readonly 'bubble.auto': "auto-reply";
+    readonly 'bubble.note': "SoulMirror";
+    readonly 'settings.nav': "SoulMirror network";
+    readonly 'settings.title': "SoulMirror network";
+    readonly 'settings.intro': "This dsh is a node on the SoulMirror network: an end-to-end encrypted A2A identity, friends, and your alter — one dsh session (\"My alter\") that speaks to every friend on your behalf.";
+    readonly 'settings.status': "Backend";
+    readonly 'settings.status.soulnet': "soulnet light peer";
+    readonly 'settings.status.fake': "in-memory fake";
+    readonly 'settings.state.ready': "running";
+    readonly 'settings.state.starting': "starting…";
+    readonly 'settings.state.restarting': "restarting…";
+    readonly 'settings.state.stopped': "stopped";
+    readonly 'settings.state.error': "error";
+    readonly 'settings.binary': "binary";
+    readonly 'settings.binary.setting': "from the peerBinary setting";
+    readonly 'settings.binary.platform-package': "from the platform package";
+    readonly 'settings.binary.path': "from PATH";
+    readonly 'settings.binary.plugin-bin': "from the plugin bin/ directory";
+    readonly 'settings.identity': "Identity";
+    readonly 'settings.identity.none': "No identity yet. Pick a display name to create one — this generates your key pair locally.";
+    readonly 'settings.identity.name': "Display name";
+    readonly 'settings.identity.create': "Create identity";
+    readonly 'settings.identity.creating': "Creating…";
+    readonly 'settings.card': "My card URI";
+    readonly 'settings.card.copy': "Copy";
+    readonly 'settings.card.copied': "Copied";
+    readonly 'settings.card.hint': "Send this link to people who should add you; they paste it in their SoulMirror (or /add here).";
+    readonly 'settings.backup': "Back up identity.json";
+    readonly 'settings.backup.body': "Your identity is the private key in {path}. Losing it means losing this identity, friends and history — copy the whole a2a/ directory somewhere safe. Moving to SoulMirror later = copying it to ~/.soulmirror/a2a/.";
+    readonly 'settings.config': "Connection";
+    readonly 'settings.config.relay': "Relay URL";
+    readonly 'settings.config.displayName': "Display name (for a new identity)";
+    readonly 'settings.config.backend': "Backend";
+    readonly 'settings.config.peerBinary': "soulnet binary path";
+    readonly 'settings.config.home': "Data directory";
+    readonly 'settings.config.hint': "Changes apply the next time dsh starts (the peer process is spawned with them). Empty path = PATH lookup, then the plugin's bin/; empty directory = $SOULNET_HOME, then ~/.soulnet.";
+    readonly 'settings.config.unavailable': "Settings are editable from a local (loopback) browser only.";
+    readonly 'settings.friends': "Friends";
+    readonly 'settings.friends.hint': "Friends are read-only threads on the SoulMirror page: your alter writes to them, you tell your alter what to say.";
+    readonly 'settings.friends.none': "No friends yet. Paste a card URI below or use /add.";
+    readonly 'settings.friends.open': "Open on the page";
+    readonly 'settings.friends.online': "online";
+    readonly 'settings.friends.offline': "offline";
+    readonly 'settings.friends.unread': "{n} unread";
+    readonly 'settings.friends.typing': "typing…";
+    readonly 'settings.pending': "Pending requests";
+    readonly 'settings.pending.none': "No pending requests.";
+    readonly 'settings.pending.accept': "Accept";
+    readonly 'settings.pending.reject': "Reject";
+    readonly 'settings.add': "Add a friend";
+    readonly 'settings.add.uri': "Card URI (soulmirror://card?…)";
+    readonly 'settings.add.note': "Note / name (optional, also the greeting)";
+    readonly 'settings.add.send': "Send request";
+    readonly 'settings.add.sent': "Request sent to {name}. The thread appears once they accept.";
+    readonly 'settings.error': "Error: {message}";
+    readonly 'settings.refresh': "Refresh";
+    readonly 'onboard.title': "Welcome to the SoulMirror network";
+    readonly 'onboard.body': "Create your A2A identity: a key pair generated on this machine. Others add you by pasting your card URI.";
+    readonly 'onboard.name': "Display name";
+    readonly 'onboard.create': "Create identity";
+    readonly 'onboard.done': "Done";
+    readonly 'onboard.later': "Later";
+    readonly 'onboard.created': "Identity created. Copy your card URI and back up identity.json.";
+    readonly 'onboard.waiting': "The soulnet peer is not running yet ({state}). Check Settings → SoulMirror network.";
+    readonly 'cmd.friends.open': "Open the thread with {name}";
+    readonly 'cmd.friends.none': "No friends yet";
+    readonly 'cmd.soulmirror.page': "Open SoulMirror — My alter";
+    readonly 'cmd.soulmirror.page.detail': "Talk to your alter; friends on the left are its conversations";
+    readonly 'page.title': "SoulMirror";
+    readonly 'page.close': "Back to dsh";
+    readonly 'page.search': "Search friends";
+    readonly 'page.pending': "New friends";
+    readonly 'page.friends': "Friends";
+    readonly 'page.identity.pending': "{n} pending";
+    readonly 'page.drafts.count': "{n} to review";
+    readonly 'page.row.draftTag': "[draft]";
+    readonly 'page.add': "Add friend";
+    readonly 'page.add.uri': "Card URI (soulmirror://card?…)";
+    readonly 'page.add.note': "Note (optional, also the greeting)";
+    readonly 'page.add.send': "Send request";
+    readonly 'page.empty.noFriends': "No friends yet. Paste a card URI under \"Add friend\" at the bottom of the list, or send yours to a friend.";
+    readonly 'page.empty.noFriends.noIdentity': "No identity yet — create one in Settings → SoulMirror network.";
+    readonly 'page.empty.noMatch': "No friend matches \"{query}\".";
+    readonly 'page.header.online': "online";
+    readonly 'page.header.offline': "offline";
+    readonly 'page.header.lastSeen': "last message {age} ago";
+    readonly 'page.header.lastSeen.now': "last message just now";
+    readonly 'page.header.card': "Card";
+    readonly 'page.header.card.title': "Card of {name}";
+    readonly 'page.header.card.copy': "Copy";
+    readonly 'page.header.card.copied': "Copied";
+    readonly 'page.header.markRead': "Mark read";
+    readonly 'page.thread.loading': "Loading…";
+    readonly 'page.thread.loadOlder': "Load older messages";
+    readonly 'page.thread.start': "Start of the conversation";
+    readonly 'page.thread.today': "Today";
+    readonly 'page.thread.yesterday': "Yesterday";
+    readonly 'page.thread.typing': "{name} is typing…";
+    readonly 'page.thread.attachment': "attachment: {name}";
+    readonly 'page.status.sending': "sending…";
+    readonly 'page.status.sent': "sent";
+    readonly 'page.status.queued': "queued — relay unreachable, will retry";
+    readonly 'page.status.error': "not delivered";
+    readonly 'page.status.failed': "failed: {message}";
+    readonly 'page.status.retry': "Retry";
+    readonly 'page.status.discard': "Discard";
+    readonly 'page.composer.send': "Send";
+    readonly 'page.composer.instructing': "Sending…";
+    readonly 'page.composer.direct': "Debug: direct to {name} · end-to-end encrypted · your alter does not see it";
+    readonly 'page.open': "Open SoulMirror";
+    readonly 'alter.me': "My alter";
+    readonly 'alter.row.hint': "Talk to your alter directly";
+    readonly 'alter.row.drafts': "{n} draft(s) waiting for you";
+    readonly 'alter.status.running': "Your alter is working…";
+    readonly 'alter.status.idle': "Ready · one memory shared across every friend";
+    readonly 'alter.status.noSession': "Starting the alter session…";
+    readonly 'alter.openDsh': "Open in dsh";
+    readonly 'alter.openDsh.hint': "The same conversation as a native dsh session (trajectory, tools, approvals).";
+    readonly 'alter.pendbar': "{n} draft(s) of your alter wait for your decision";
+    readonly 'alter.pendbar.go': "Review in {name}'s thread →";
+    readonly 'alter.empty.title': "Tell your alter what to do";
+    readonly 'alter.empty.hint': "It writes to your friends on your behalf (\"tell Bob I am in\"), answers their mail by your diplomacy protocol, and asks you before money, tasks or commitments. Friends on the left are its conversations — read-only for you.";
+    readonly 'alter.composer.placeholder': "Say something to your alter… (Enter to send, Shift+Enter for a new line)";
+    readonly 'alter.composer.hint': "You only talk to your own alter; it speaks to your friends for you.";
+    readonly 'alter.proactive': "proactive";
+    readonly 'alter.thinking': "Your alter is working…";
+    readonly 'alter.item.inbound': "Mail from {name}";
+    readonly 'alter.item.view': "open thread";
+    readonly 'alter.item.send': "To {name}";
+    readonly 'alter.item.send.pending': "sending…";
+    readonly 'alter.item.send.sent': "sent";
+    readonly 'alter.item.send.auto': "sent · auto";
+    readonly 'alter.item.send.draft': "draft — waiting for your review";
+    readonly 'alter.item.send.refused': "not sent";
+    readonly 'alter.item.send.failed': "failed";
+    readonly 'alter.item.note.approved': "You approved the draft to {name}; it was sent";
+    readonly 'alter.item.note.rejected': "You rejected the draft to {name}";
+    readonly 'alter.item.note.revise': "You sent the draft to {name} back for revision";
+    readonly 'alter.item.turnFailed': "The turn failed: {reason}";
+    readonly 'alter.item.revise': "Revision for {name}";
+    readonly 'alter.failed.hint': "No model answer — check the model / API key in dsh, then try again.";
+    readonly 'draft.tag': "Draft";
+    readonly 'draft.title': "Your alter wants to send this";
+    readonly 'draft.title.to': "Your alter wants to send this to {name}";
+    readonly 'draft.openThread': "open thread";
+    readonly 'draft.reason.draft-tier': "Held because this friend's reply tier is \"draft\" (you review before anything goes out).";
+    readonly 'draft.reason.notify-tier': "Held because this friend's reply tier is \"notify\".";
+    readonly 'draft.reason.rate-limited': "Held because the hourly auto-reply cap for this friend is reached.";
+    readonly 'draft.reason.loop-guard-auto': "Held because the mail that woke your alter was itself an automatic reply (loop guard).";
+    readonly 'draft.reason.other-friend': "Held because your alter wants to write to a different friend than the one who wrote.";
+    readonly 'draft.reason.unknown-trigger': "Held because your alter was not acting on your instruction or on this friend's mail.";
+    readonly 'draft.inReplyTo': "in reply to mail from {name}";
+    readonly 'draft.approve': "Send it";
+    readonly 'draft.edit': "Edit";
+    readonly 'draft.editSend': "Send edited";
+    readonly 'draft.revise': "Let the alter revise";
+    readonly 'draft.revise.placeholder': "Tell your alter what to change (it rewrites and sends on your word)…";
+    readonly 'draft.reviseSend': "Send feedback to the alter";
+    readonly 'draft.reject': "Reject";
+    readonly 'draft.cancel': "Cancel";
+    readonly 'friend.banner.prefix': "This is ";
+    readonly 'friend.banner.mine': "your alter";
+    readonly 'friend.banner.middle': "'s conversation with ";
+    readonly 'friend.banner.theirs': "{name}";
+    readonly 'friend.banner.suffix': " — you can't speak here. Tell \"My alter\" instead.";
+    readonly 'friend.banner.go': "Go to My alter";
+    readonly 'friend.empty': "No messages yet — tell \"My alter\" to write to {name}.";
+    readonly 'friend.drafts.pill': "{n} draft(s) waiting for your decision";
+    readonly 'friend.actbar.eye': "Alter ↔ alter · you are the observer";
+    readonly 'friend.actbar.pending': "Drafts";
+    readonly 'friend.actbar.settings': "Protocol & settings";
+    readonly 'friend.actbar.goAlter': "Talk to My alter →";
+    readonly 'friend.debug.placeholder': "Debug: send as myself to {name}… (bypasses the alter)";
+    readonly 'friend.debug.send': "Send as myself";
+    readonly 'tier.notify': "Notify only";
+    readonly 'tier.draft': "Draft — you review before it sends";
+    readonly 'tier.auto': "Auto-reply — no review (rate-limited)";
+    readonly 'tier.default': "Default ({tier})";
+    readonly 'tier.short.notify': "notify";
+    readonly 'tier.short.draft': "draft";
+    readonly 'tier.short.auto': "auto";
+    readonly 'friend.settings.title': "How your alter handles {name}";
+    readonly 'friend.tier': "Reply tier";
+    readonly 'friend.tier.hint': "notify: mail is only shown; draft: your alter drafts a reply and you review it on this page; auto: it sends by itself (max {n}/hour).";
+    readonly 'friend.protocol': "Protocol override for this friend";
+    readonly 'friend.protocol.placeholder': "Rules for this friend only (they win over the global protocol on conflict). Empty = none.";
+    readonly 'friend.protocol.save': "Save";
+    readonly 'friend.protocol.saved': "Saved.";
+    readonly 'protocol.title': "Diplomacy protocol";
+    readonly 'protocol.open': "Protocol";
+    readonly 'protocol.hint': "The principles your alter follows when it speaks to friends on your behalf (global; per-friend overrides live under \"Protocol & settings\" in a friend thread). Saved to {path}; applies from the next turn.";
+    readonly 'protocol.missing': "No protocol.md yet — the peer writes the default when your identity is created; saving here creates it.";
+    readonly 'protocol.save': "Save protocol";
+    readonly 'protocol.saved': "Saved.";
+    readonly 'protocol.reload': "Reload";
+    readonly 'settings.alter': "Your alter";
+    readonly 'settings.alter.intro': "One dsh session (\"My alter\") is your alter: you tell it what to say, it writes to your friends and answers their mail by the diplomacy protocol. In the \"draft\" tier its replies wait for your review on the SoulMirror page; \"auto\" sends by itself (rate-limited); \"notify\" only shows the mail. These settings apply immediately.";
+    readonly 'settings.alter.defaultTier': "Default reply tier";
+    readonly 'settings.alter.perHour': "Auto replies per friend per hour";
+    readonly 'settings.alter.directSend': "Debug: offer \"Send as myself\" in friend threads (bypasses the alter)";
+    readonly 'settings.alter.openPage': "Open SoulMirror";
+    readonly 'settings.alter.openSession': "Open the alter session in dsh";
+    readonly 'settings.alter.legacy': "{n} old per-friend session(s) from before 0.1.0-p4 are kept in dsh but receive no mail; you can delete them.";
+};
+export declare const zh: Record<keyof typeof en, string>;
+export type SoulmirrorKey = keyof typeof en;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        soulmirror: SoulmirrorKey;
+    }
+}

package/lib/types/client/page-state.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure state of the SoulMirror page (P2b): which friend is selected, the
+ * per-friend message thread (archive entries + optimistic outbound bubbles),
+ * and the row / bubble helpers. Folds: `conversation.get` answers (merge by
+ * seq, dedupe by id), SSE `message` frames (inbound), SSE `outbound` frames
+ * (another tab sent), optimistic send → reconcile / fail. No React, no DOM:
+ * unit-tested under node (test/page-state.test.ts). The friend list itself
+ * is the inbox state (./inbox-state.ts); this module only adds the search
+ * filter and the selection rule on top of it.
+ */
+import type { ApiEntry } from './api.ts';
+import { type InboxFriend } from './inbox-state.ts';
+/** One bubble of the thread: an archived entry, or an outbound one not yet acknowledged by the peer. */
+export interface ThreadEntry {
+    /** Archive line number (1-based); 0 while the entry is only optimistic. */
+    readonly seq: number;
+    readonly dir: 'in' | 'out';
+    /** A2A message id; for optimistic entries the client id until the receipt arrives. */
+    readonly id: string;
+    readonly body: string;
+    /** Unix epoch ms. */
+    readonly ts: number;
+    readonly type?: string;
+    readonly auto?: true;
+    /** Outbound delivery state: `sending` (optimistic) | `sent` | `queued` | `error` | `failed` (the send call itself failed). */
+    readonly status?: string;
+    readonly artifactName?: string;
+    /** Client-side id of an optimistic send (stable across reconcile; the React key). */
+    readonly clientId?: string;
+    /** Error text when the send call failed (status `failed`). */
+    readonly error?: string;
+}
+export interface ThreadState {
+    readonly entries: readonly ThreadEntry[];
+    /** The `limit` of the last archive fetch (grows when the owner scrolls up). */
+    readonly window: number;
+    /** The archive has no older entries than the ones loaded. */
+    readonly complete: boolean;
+    readonly loading: boolean;
+    readonly loaded: boolean;
+    readonly error?: string;
+}
+export declare const EMPTY_THREAD: ThreadState;
+/** Entries per archive fetch; the window grows by this much per "load older". */
+export declare const PAGE_SIZE = 50;
+export declare function entryFromApi(entry: ApiEntry): ThreadEntry;
+/** Stable ordering: archived entries by seq, then optimistic ones (seq 0) by time at the tail. */
+export declare function sortThread(entries: readonly ThreadEntry[]): ThreadEntry[];
+/**
+ * Merge archive entries into the thread: an entry with the same seq replaces
+ * the loaded one (status may have moved from queued → sent), an entry with
+ * the same id as an optimistic bubble absorbs it (keeps its clientId so the
+ * React key is stable), everything else is appended. Result sorted.
+ */
+export declare function mergeEntries(existing: readonly ThreadEntry[], incoming: readonly ThreadEntry[]): ThreadEntry[];
+/** Fold one `conversation.get` answer (the last `window` entries) into the thread. */
+export declare function applyArchive(state: ThreadState, entries: readonly ApiEntry[], window: number): ThreadState;
+/** Append one inbound message (SSE `message` frame) to the thread. */
+export declare function applyInbound(state: ThreadState, message: {
+    id: string;
+    body: string;
+    ts: number;
+    seq?: number;
+    type?: string;
+    auto?: true;
+    artifactName?: string;
+}): ThreadState;
+/** Append one archived outbound entry (SSE `outbound` frame from another tab, or our own receipt). */
+export declare function applyOutbound(state: ThreadState, entry: ApiEntry): ThreadState;
+/** The owner pressed Send: show the bubble at once (status `sending`). */
+export declare function addOptimistic(state: ThreadState, draft: {
+    clientId: string;
+    body: string;
+    ts: number;
+}): ThreadState;
+/** The host answered `message.send` with the archived entry: replace the optimistic bubble in place. */
+export declare function reconcileSend(state: ThreadState, clientId: string, entry: ApiEntry): ThreadState;
+/** The send call failed: keep the bubble, mark it `failed` with the error. */
+export declare function failSend(state: ThreadState, clientId: string, error: string): ThreadState;
+/** Remove a failed optimistic bubble (the owner discarded it or retries). */
+export declare function dropEntry(state: ThreadState, clientId: string): ThreadState;
+/** Highest archived seq in the thread (the read cursor to report). */
+export declare function lastSeq(state: ThreadState): number;
+/** Case-insensitive filter over name / remark / card name / fingerprint prefix. */
+export declare function filterFriends(friends: readonly InboxFriend[], query: string): InboxFriend[];
+/** Rows of the middle column: unread first, then newest, then by name; then the search filter. */
+export declare function listRows(friends: readonly InboxFriend[], query: string): InboxFriend[];
+/** Selection key of the pinned first item "My alter" (never a fingerprint). */
+export declare const ALTER_KEY = "alter";
+/**
+ * Which item the page shows on the right: "My alter" (the pinned first item,
+ * also the default — selecting it has no side effect) or the explicitly
+ * selected friend while it is still a friend (selecting a friend marks it
+ * read, so a gone friend never re-selects itself; it falls back to the alter).
+ */
+export declare function resolveSelection(friends: readonly Pick<InboxFriend, 'fp'>[], selected: string | undefined): string;
+/** Local calendar day key (YYYY-MM-DD) for the day separators. */
+export declare function dayKey(ts: number): string;
+export type ThreadRow = {
+    readonly kind: 'day';
+    readonly key: string;
+    readonly ts: number;
+} | {
+    readonly kind: 'entry';
+    readonly key: string;
+    readonly entry: ThreadEntry;
+};
+/** Interleave day separators: one before the first entry of every local day. */
+export declare function withDaySeparators(entries: readonly ThreadEntry[]): ThreadRow[];
+/** Bubble time: HH:MM (24 h, local). */
+export declare function formatClock(ts: number): string;
+/** Day separator label: "Today" / "Yesterday" (via the dictionary) or a local date. */
+export declare function formatDay(ts: number, now: number, labels: {
+    today: string;
+    yesterday: string;
+}): string;

package/lib/types/client/page-store.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Open/closed state and selection of the SoulMirror page plus the per-friend
+ * thread cache and the "My alter" transcript, shared between the sidebar
+ * footer button (`sidebar.footer.action`), the `/soulmirror` popup, the view
+ * tab and the page itself (`shell.overlay`). Threads are folded with the pure
+ * functions of ./page-state.ts: archive fetches (`conversation.get`), SSE
+ * `message` / `outbound` frames (through `networkStore.onFrame`), optimistic
+ * debug sends and their reconcile. The alter transcript is fetched from
+ * `session.history` and refetched (debounced) on every SSE `alter` frame.
+ * One store per page; components read it through `useSyncExternalStore`.
+ */
+import { type ApiChat } from './api.ts';
+import { type ThreadState } from './page-state.ts';
+/** The alter transcript as the page holds it (P4). */
+export interface AlterView {
+    readonly sessionId: string | undefined;
+    readonly status: 'idle' | 'running';
+    readonly chat: ApiChat;
+    readonly loading: boolean;
+    readonly loaded: boolean;
+    /** An instruction is being posted. */
+    readonly instructing: boolean;
+    readonly error?: string;
+}
+export declare const EMPTY_ALTER: AlterView;
+export interface PageSnapshot {
+    readonly open: boolean;
+    /** Selection: `ALTER_KEY` or a friend fingerprint (may point at a friend that is gone; the page resolves it). */
+    readonly selected: string | undefined;
+    /** fp → thread (only for friends whose archive was fetched at least once). */
+    readonly threads: Readonly<Record<string, ThreadState>>;
+    readonly alter: AlterView;
+    /** Draft ids with a decision in flight. */
+    readonly deciding: readonly string[];
+}
+/** Items of the transcript fetched per load. */
+export declare const HISTORY_LIMIT = 200;
+export declare class PageStore {
+    private snapshot;
+    private readonly listeners;
+    private readonly typingSentAt;
+    private readonly typingIdle;
+    private historyTimer;
+    private historyAgain;
+    private seq;
+    constructor();
+    getSnapshot: () => PageSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    private set;
+    private setThread;
+    thread: (fp: string) => ThreadState;
+    private setAlter;
+    /** Fetch the alter transcript (`session.history`). */
+    loadAlter: () => Promise<void>;
+    private scheduleHistory;
+    /**
+     * The owner instructs their alter: the text becomes an owner user/message
+     * in the alter session and wakes a turn; the alter decides what to tell
+     * which friend and sends it with soulmirror_send_message. The transcript
+     * refetches as the session moves (SSE `alter`), the friend thread shows
+     * the alter's send as an outbound bubble (SSE `outbound`).
+     */
+    instruct: (text: string) => Promise<boolean>;
+    /** Decide a pending draft (approve / approve edited / reject / revise). */
+    decideDraft: (id: string, decision: {
+        action: "approve";
+        body?: string;
+    } | {
+        action: "reject";
+    } | {
+        action: "revise";
+        feedback: string;
+    }) => Promise<boolean>;
+    open: (selection?: string) => void;
+    close: () => void;
+    toggle: () => void;
+    select: (selection: string) => void;
+    /** Fetch what the selection needs (the transcript for the alter, the archive for a friend). */
+    private prime;
+    /** Fetch (or re-fetch) the last `window` entries of a friend's archive. */
+    load: (fp: string, window?: number) => Promise<void>;
+    /** The owner scrolled to the top: widen the window by one page. */
+    loadOlder: (fp: string) => Promise<void>;
+    /**
+     * Debug direct send (Settings → "send as myself"): optimistic bubble now,
+     * reconcile with the archived entry the host answers, or mark it failed.
+     */
+    send: (fp: string, body: string) => Promise<boolean>;
+    /** Discard a failed bubble (returns its body so the composer can offer it again). */
+    discard: (fp: string, clientId: string) => string | undefined;
+    /** The owner is typing in the debug composer: best-effort `message.typing on`, throttled; `off` after idle. */
+    noteTyping: (fp: string) => void;
+    stopTyping: (fp: string) => void;
+    private onFrame;
+}
+export declare const pageStore: PageStore;

package/lib/types/client/panel-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Open/closed state of the inbox panel, shared between the sidebar footer
+ * button (`sidebar.footer.action`, inside the sidebar column) and the panel
+ * itself (`shell.overlay`, a root overlay layer). One store per page;
+ * components read it through `useSyncExternalStore`.
+ */
+export interface PanelAnchor {
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+    readonly bottom: number;
+}
+export interface PanelSnapshot {
+    readonly open: boolean;
+    /** Viewport rect of the footer button at open time (the panel sits beside it). */
+    readonly anchor: PanelAnchor | undefined;
+}
+export declare class PanelStore {
+    private snapshot;
+    private readonly listeners;
+    getSnapshot: () => PanelSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    private set;
+    open: (anchor?: PanelAnchor) => void;
+    close: () => void;
+    toggle: (anchor?: PanelAnchor) => void;
+    /** Re-measure (sidebar resized / collapsed while open). */
+    anchorTo: (anchor: PanelAnchor) => void;
+}
+export declare const panelStore: PanelStore;

package/lib/types/client/styles.d.ts

@@ -0,0 +1,2 @@
+export declare function ensureStyles(): void;
+export declare function removeStyles(): void;

package/lib/types/commands/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * soulmirror-commands — host slash commands (`ctx.commands.register`):
+ *
+ *   /card                show this user's card URI
+ *   /friends             list friends (presence, unread); the client half
+ *                        decorates the bare invocation with a popup that opens
+ *                        a friend's session
+ *   /add <card_uri> [note]
+ *                        send a friend request (the human typing the command
+ *                        IS the approval; commands run outside a model turn, so
+ *                        ctx.approval cannot be used here)
+ *   /soulmirror          open the SoulMirror page ("My alter" + friends); the
+ *                        client half decorates the bare invocation with a
+ *                        popup (the page / one friend) — the host handler only
+ *                        prints the hint, since a host command cannot drive
+ *                        the browser UI
+ *
+ * Results are rendered by the composer and never enter model history.
+ * No @deepseek-ai value imports (see ../index.ts header).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "soulmirror-commands";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/types/drafts.d.ts

@@ -0,0 +1,50 @@
+import type { SendGateReason } from './policy.ts';
+export declare const PENDING_FILE = "dsh-pending.json";
+export interface PendingDraft {
+    readonly id: string;
+    /** Target friend. */
+    readonly fp: string;
+    /** Target friend's display name when the draft was stored. */
+    readonly name: string;
+    readonly body: string;
+    /** ISO timestamp. */
+    readonly createdAt: string;
+    /** Why it became a draft (the send gate's reason). */
+    readonly reason: SendGateReason;
+    /** What woke the turn that produced it (for the card's "in reply to …" line). */
+    readonly trigger?: {
+        readonly kind: string;
+        readonly fp?: string;
+        readonly name?: string;
+        readonly messageId?: string;
+    };
+    /** The alter session that produced it. */
+    readonly sessionId?: string;
+}
+/** In-memory copy of dsh-pending.json with write-through. */
+export declare class DraftStore {
+    readonly path: string;
+    private data;
+    private loaded;
+    private writing;
+    constructor(path: string);
+    static at(a2aDir: string): DraftStore;
+    load(): Promise<void>;
+    get isLoaded(): boolean;
+    /** Pending drafts, oldest first; `fp` narrows to one friend. */
+    list(fp?: string): readonly PendingDraft[];
+    get(id: string): PendingDraft | undefined;
+    count(fp?: string): number;
+    /** Pending count per friend fingerprint. */
+    counts(): Record<string, number>;
+    /** Store a new draft (id generated when absent); answers the stored record. */
+    add(draft: Omit<PendingDraft, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+    }): Promise<PendingDraft>;
+    /** Remove one draft; answers it (undefined when unknown). */
+    remove(id: string): Promise<PendingDraft | undefined>;
+    /** Drop every draft of a friend (e.g. the friend was removed). */
+    removeAll(fp: string): Promise<number>;
+    private flush;
+}

package/lib/types/events.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared vocabulary of soulnet-dsh: branded ids and the
+ * `user/message` source tag that marks an inbound A2A mail.
+ *
+ * There is deliberately NO custom SessionEventMap merge here any more. The P0
+ * spike (dsh/SPIKE.md §1) showed that a custom durable event type makes the
+ * session log unloadable (the persistence read path refuses unknown,
+ * non-ignorable types), so every inbound mail is written as an ordinary
+ * `user/message` whose `source` carries the fields below; the client half
+ * recognises that source and renders the message as a chat bubble.
+ *
+ * P4: the same relay source also carries the plugin's own NOTES into the
+ * alter session (the owner approved / rejected / edited a draft) — marked by
+ * `a2a.note`, never woken as a turn, rendered as a system line.
+ *
+ * Keep this file free of runtime imports apart from constants: the client
+ * bundle imports it as well.
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Stable A2A message id (the relay envelope id; replay-safe). */
+export type A2AMessageId = Branded<'A2AMessageId'>;
+/** Fingerprint of a peer's signing key (the A2A identity). */
+export type Fingerprint = Branded<'Fingerprint'>;
+/** `source.plugin` of the `user/message` carrying an inbound A2A mail. */
+export declare const SOULMIRROR_PLUGIN = "soulmirror";
+/** `source.form` of that message: dsh's built-in "a message another agent addressed to this one". */
+export declare const RELAY_FORM = "relay";
+/** Kinds of plugin notes written into the alter session (P4 draft decisions). */
+export type A2ANoteKind = 'draft-approved' | 'draft-rejected' | 'draft-revise';
+/** The extra `a2a` block the host attaches to the relay source (wire-extensible; the literal type is closed upstream). */
+export interface A2ASourceMeta {
+    readonly id: string;
+    readonly fp: string;
+    readonly ts: number;
+    readonly auto?: true;
+    /** A2A message type (`text`, `app_share`, …); absent means `text`. */
+    readonly type?: string;
+    /** Set on the plugin's own notes (draft decisions): not mail, never a turn trigger. */
+    readonly note?: A2ANoteKind;
+    /** Draft id the note refers to. */
+    readonly draftId?: string;
+}
+/** Shape the client renderer derives from such a `user/message` (one bubble). */
+export interface A2AMessageData {
+    readonly id: A2AMessageId;
+    /** `in`: friend → me; `out`: me → friend. */
+    readonly dir: 'in' | 'out';
+    /** Peer fingerprint (the friend this message belongs to). */
+    readonly fp: Fingerprint;
+    /** Display name of the peer at send time. */
+    readonly name: string;
+    readonly body: string;
+    /** Unix epoch ms at the sender. */
+    readonly ts: number;
+    /** Outbound delivery state; absent on inbound. */
+    readonly delivery?: 'queued' | 'sent' | 'failed';
+    /** Set when the message was produced by a peer's auto-reply (loop guard). */
+    readonly auto?: true;
+    /** Set when the row is a plugin note (draft decision), not mail. */
+    readonly note?: A2ANoteKind;
+}