soulnet-dsh 0.1.0

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

@@ -0,0 +1,424 @@
+/**
+ * Browser side of the host HTTP API (see ../api/index.ts): typed fetch
+ * helpers, a Server-Sent-Events subscription, and one small shared store
+ * (React `useSyncExternalStore` shape) holding the last known network state.
+ * Same-origin requests only; dsh web serves the bundle and `/soulmirror/api/`
+ * from the same loopback server.
+ */
+import { type InboxState, type MailNotice } from './inbox-state.ts';
+export declare const API_BASE = "/soulmirror/api/";
+export interface ApiIdentity {
+    fp: string;
+    name: string;
+    cardUri: string;
+    createdAt?: string;
+}
+export type ReplyTier = 'notify' | 'draft' | 'auto';
+export interface ApiFriend {
+    fp: string;
+    name: string;
+    remark?: string;
+    cardName?: string;
+    online?: boolean;
+    unread: number;
+    count: number;
+    lastTs?: number;
+    lastBody?: string;
+    typing?: boolean;
+    /** Per-friend diplomacy protocol override (friends.yaml `protocol`). */
+    protocol?: string;
+    /** Effective reply tier (P3); `tierExplicit` when stored for this friend rather than the global default. */
+    tier?: ReplyTier;
+    tierExplicit?: true;
+    /** Pending drafts of the alter to this friend (P4). */
+    drafts?: number;
+}
+/** What woke a turn of the alter session. */
+export interface ApiTrigger {
+    kind: 'owner' | 'inbound' | 'inbound-auto' | 'unknown';
+    fp?: string;
+    name?: string;
+    messageId?: string;
+}
+export type ApiSendOutcome = 'sent' | 'draft-queued' | 'refused' | 'failed';
+/** The alter's latest state (host `session.latest`, SSE `alter`; see src/alter-state.ts). */
+export interface ApiAlterLatest {
+    instruction?: {
+        text: string;
+        ts: number;
+        seq: number;
+    };
+    note?: {
+        text: string;
+        ts: number;
+        seq: number;
+        turn: number;
+    };
+    sent?: {
+        body: string;
+        fingerprint?: string;
+        ts: number;
+        outcome?: ApiSendOutcome;
+        gate?: string;
+        draftId?: string;
+        detail?: string;
+    };
+    turn?: {
+        turn: number;
+        reason: string;
+        failed: boolean;
+        ts: number;
+        message?: string;
+        open: boolean;
+    };
+    trigger: ApiTrigger;
+    seq: number;
+}
+export interface ApiAlterState {
+    sessionId: string;
+    status: 'idle' | 'running';
+    latest: ApiAlterLatest;
+}
+/** One item of the "My alter" transcript (host `session.history`; see src/alter-state.ts `chatFromEvents`). */
+export type ApiChatItem = {
+    kind: 'owner';
+    key: string;
+    ts: number;
+    text: string;
+    revise?: {
+        name: string;
+        fp: string;
+    };
+} | {
+    kind: 'alter';
+    key: string;
+    ts: number;
+    text: string;
+    turn: number;
+} | {
+    kind: 'inbound';
+    key: string;
+    ts: number;
+    fp: string;
+    name: string;
+    id: string;
+    body: string;
+    auto: boolean;
+    type?: string;
+} | {
+    kind: 'send';
+    key: string;
+    ts: number;
+    fp: string;
+    body: string;
+    outcome?: ApiSendOutcome;
+    gate?: string;
+    draftId?: string;
+    detail?: string;
+    auto: boolean;
+} | {
+    kind: 'note';
+    key: string;
+    ts: number;
+    note: 'draft-approved' | 'draft-rejected' | 'draft-revise';
+    fp: string;
+    text: string;
+    draftId?: string;
+} | {
+    kind: 'turn-failed';
+    key: string;
+    ts: number;
+    turn: number;
+    reason: string;
+    message?: string;
+};
+export interface ApiChat {
+    items: ApiChatItem[];
+    running: boolean;
+    seq: number;
+}
+export interface ApiHistory {
+    sessionId: string | null;
+    status: 'idle' | 'running';
+    chat: ApiChat;
+}
+/** A pending draft of the alter (P4; src/drafts.ts). */
+export interface ApiDraft {
+    id: string;
+    fp: string;
+    name: string;
+    body: string;
+    createdAt: string;
+    reason: string;
+    trigger?: {
+        kind: string;
+        fp?: string;
+        name?: string;
+        messageId?: string;
+    };
+    sessionId?: string;
+}
+/** Alter-wide settings as the host resolves them (live). */
+export interface ApiAlterConfig {
+    sessionId: string | null;
+    status: 'idle' | 'running';
+    defaultTier: ReplyTier;
+    autoReplyPerHour: number;
+    directSend: boolean;
+    protocolPath: string;
+    protocolExists: boolean;
+    legacyFriendSessions: Record<string, string>;
+}
+export interface ApiPending {
+    id: string;
+    fp: string;
+    name: string;
+    greeting: string;
+    createdAt?: string;
+}
+/** One archived conversation entry (`conversation.get`, `message.send`, SSE `outbound`). */
+export interface ApiEntry {
+    seq: number;
+    dir: 'in' | 'out';
+    id: string;
+    body: string;
+    ts: number;
+    type?: string;
+    auto?: true;
+    status?: string;
+    artifactName?: string;
+}
+export interface ApiStatus {
+    backend: 'fake' | 'soulnet';
+    state: 'starting' | 'ready' | 'restarting' | 'stopped' | 'error';
+    pid?: number;
+    restarts: number;
+    lastError?: string;
+    relay?: string;
+    home?: string;
+    protocol?: string;
+    version?: string;
+    binary?: string;
+    binarySource?: 'setting' | 'platform-package' | 'path' | 'plugin-bin' | string;
+}
+export interface ApiState {
+    backend: 'fake' | 'soulnet';
+    status: ApiStatus;
+    home: string;
+    settingsNamespace: string;
+    identity: ApiIdentity | null;
+    friends: ApiFriend[];
+    pending: ApiPending[];
+    drafts: ApiDraft[];
+    alter?: ApiAlterConfig;
+    error?: string;
+}
+export declare class ApiError extends Error {
+    readonly code: number;
+    readonly httpStatus: number;
+    readonly name = "ApiError";
+    constructor(message: string, code: number, httpStatus: number);
+}
+export declare const api: {
+    state: () => Promise<ApiState>;
+    createIdentity: (name: string) => Promise<{
+        identity: ApiIdentity;
+    }>;
+    parseCard: (uri: string) => Promise<{
+        fp: string;
+        name: string;
+        uri: string;
+    }>;
+    addFriend: (cardUri: string, note?: string) => Promise<{
+        friend: ApiFriend;
+    }>;
+    accept: (id: string, note?: string) => Promise<{
+        friend: ApiFriend;
+    }>;
+    reject: (id: string) => Promise<{
+        ok: true;
+    }>;
+    markRead: (fp: string, seq?: number) => Promise<{
+        ok: true;
+    }>;
+    /** Archive of one friend: `since` = only seq > since, `limit` = the last N entries. */
+    conversation: (fp: string, opts?: {
+        since?: number;
+        limit?: number;
+    }) => Promise<{
+        entries: ApiEntry[];
+        typing: boolean;
+    }>;
+    /** Debug: direct send to a friend through the peer (bypasses the alter); answers the archived entry. */
+    send: (fp: string, body: string) => Promise<{
+        entry: ApiEntry;
+        receipt: {
+            id: string;
+            seq?: number;
+            status: string;
+        };
+    }>;
+    typing: (fp: string, on: boolean) => Promise<{
+        ok: true;
+    }>;
+    presence: (fps: readonly string[]) => Promise<{
+        online: Record<string, boolean>;
+    }>;
+    /** The owner instructs their alter (an owner user/message + a woken turn in the alter session). */
+    instruct: (text: string) => Promise<{
+        sessionId: string;
+        messageId: string;
+        state: ApiAlterState | null;
+    }>;
+    /** The alter's latest state (null = no session yet). */
+    sessionLatest: () => Promise<{
+        state: ApiAlterState | null;
+    }>;
+    /** The alter transcript (last `limit` items). */
+    sessionHistory: (limit?: number) => Promise<ApiHistory>;
+    /** Pending drafts (all, or one friend's). */
+    drafts: (fp?: string) => Promise<{
+        drafts: ApiDraft[];
+    }>;
+    /** Decide a draft: approve (optionally edited), reject, or send it back to the alter with feedback. */
+    decideDraft: (id: string, decision: {
+        action: "approve";
+        body?: string;
+    } | {
+        action: "reject";
+    } | {
+        action: "revise";
+        feedback: string;
+    }) => Promise<{
+        ok: true;
+        draft: ApiDraft;
+        entry?: ApiEntry;
+    }>;
+    /** Note / protocol override (peer) and reply tier (plugin) of a friend; `tier: ''` = back to the default. */
+    friendSet: (fp: string, patch: {
+        note?: string;
+        protocol?: string;
+        tier?: ReplyTier | "";
+    }) => Promise<{
+        friend: ApiFriend;
+    }>;
+    friendCard: (fp: string) => Promise<{
+        fp: string;
+        name: string;
+        uri: string;
+    }>;
+    protocolGet: () => Promise<{
+        text: string;
+        path: string;
+        exists: boolean;
+    }>;
+    protocolSet: (text: string) => Promise<{
+        ok: true;
+        text: string;
+        path: string;
+    }>;
+};
+export type NetworkEventFrame = {
+    kind: 'message';
+    message: {
+        id: string;
+        from: string;
+        name: string;
+        body: string;
+        ts: number;
+        seq?: number;
+        type?: string;
+        auto?: true;
+        artifactName?: string;
+    };
+}
+/** An outbound entry was archived (the alter sent, a draft was approved, or the debug direct send): `fp` is the friend. */
+ | {
+    kind: 'outbound';
+    fp: string;
+    entry: ApiEntry;
+} | {
+    kind: 'typing';
+    fp: string;
+    on: boolean;
+} | {
+    kind: 'friend_request';
+    request: ApiPending;
+} | {
+    kind: 'friend_accept';
+    friend: ApiFriend;
+} | {
+    kind: 'presence';
+    fp: string;
+    online: boolean;
+} | {
+    kind: 'status';
+    status: ApiStatus;
+}
+/** The alter's state changed (a turn, a note, a send …). */
+ | {
+    kind: 'alter';
+    state: ApiAlterState;
+}
+/** A pending draft was stored or decided. */
+ | {
+    kind: 'draft';
+    action: 'added' | 'removed';
+    draft: ApiDraft;
+    decision?: 'approved' | 'rejected' | 'revise';
+};
+export interface NetworkStoreSnapshot {
+    readonly state: ApiState | undefined;
+    readonly loading: boolean;
+    readonly error: string | undefined;
+    /** fp → typing flag (live, from SSE). */
+    readonly typing: Readonly<Record<string, boolean>>;
+    readonly status: ApiStatus | undefined;
+    /** Bumps on every SSE frame so lists can refetch. */
+    readonly revision: number;
+    /**
+     * Friends / pending / drafts as folded from the last `/state` answer plus
+     * the SSE frames since (optimistic; replaced by the next refetch). The
+     * sidebar badge, the page's middle column and the toast read this, not
+     * `state` directly.
+     */
+    readonly inbox: InboxState;
+}
+/**
+ * One store per browser page: `refresh()` pulls `/state`, `connect()` keeps the
+ * SSE stream open (typing, friend events, backend status) while someone
+ * subscribes. Components read it through `useSyncExternalStore`.
+ */
+export declare class NetworkStore {
+    private snapshot;
+    private readonly listeners;
+    private readonly mailListeners;
+    private readonly frameListeners;
+    private source;
+    private refreshTimer;
+    private inflight;
+    getSnapshot: () => NetworkStoreSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Subscribe to new-mail notices (one per inbound `message` frame). The
+     * caller decides whether to show a cue (e.g. only when that thread is not
+     * on screen). Independent of the snapshot subscription; does not open the
+     * SSE stream by itself.
+     */
+    onMail: (listener: (notice: MailNotice) => void) => (() => void);
+    /** Subscribe to every SSE frame as it arrives (the page's stores fold `message` / `outbound` / `alter` / `draft`). */
+    onFrame: (listener: (frame: NetworkEventFrame) => void) => (() => void);
+    /** Fold a `presence` answer (fp -> online) into the friend rows. */
+    applyPresence: (online: Readonly<Record<string, boolean>>) => void;
+    /** Fold an outbound entry we just archived ourselves (preview / time of the friend row). */
+    applyOutbound: (fp: string, entry: ApiEntry) => void;
+    private set;
+    /** The owner read a friend's conversation: zero its unread locally and tell the host. */
+    markRead: (fp: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    /** Debounced refresh after SSE frames that change lists. */
+    private scheduleRefresh;
+    private connect;
+    private disconnect;
+}
+export declare const networkStore: NetworkStore;

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

@@ -0,0 +1,57 @@
+/**
+ * Pure inbox state: the friend list as the browser sees it (from
+ * `/soulmirror/api/state`) folded with the live SSE frames (`message`,
+ * `outbound`, `presence`, `typing`, `friend_accept`, `friend_request`,
+ * `draft`) so the sidebar badge, the page's middle column and the new-mail
+ * cue update instantly — the authoritative `/state` refetch that follows a
+ * frame replaces the optimistic fold. No React, no DOM: unit-tested under
+ * node (test/inbox-state.test.ts).
+ */
+import type { ApiDraft, ApiFriend, ApiPending, ApiState, NetworkEventFrame } from './api.ts';
+export interface InboxFriend extends ApiFriend {
+}
+/** The slice of the network state the inbox surfaces read. */
+export interface InboxState {
+    readonly friends: readonly InboxFriend[];
+    readonly pending: readonly ApiPending[];
+    /** Pending drafts of the alter (P4), oldest first. */
+    readonly drafts: readonly ApiDraft[];
+    /** The alter session id (host), when known. */
+    readonly alterSessionId: string | undefined;
+    /** fp → typing flag (live, never persisted). */
+    readonly typing: Readonly<Record<string, boolean>>;
+}
+/** What the new-mail cue needs: who wrote, what, and the alter session id (the toast is suppressed while it is on screen). */
+export interface MailNotice {
+    readonly id: string;
+    readonly fp: string;
+    readonly name: string;
+    readonly body: string;
+    readonly ts: number;
+    readonly sessionId: string | undefined;
+}
+export declare const EMPTY_INBOX: InboxState;
+/** Unread total over all friends (the sidebar badge number). */
+export declare function unreadTotal(friends: readonly Pick<InboxFriend, 'unread'>[]): number;
+/** Friends sorted for the inbox: unread first, then by last message time (desc), then by name. */
+export declare function sortInbox(friends: readonly InboxFriend[]): InboxFriend[];
+/** Pending drafts for one friend, oldest first. */
+export declare function draftsFor(state: Pick<InboxState, 'drafts'>, fp: string): ApiDraft[];
+/** Replace the folded state with a fresh `/state` answer (keeps the live typing flags and, for rows without `online`, the last known presence). */
+export declare function fromApiState(previous: InboxState, state: ApiState): InboxState;
+/**
+ * Fold one SSE frame into the state. Returns the next state and, for
+ * `message` frames, the notice the new-mail cue should show.
+ */
+export declare function applyFrame(state: InboxState, frame: NetworkEventFrame): {
+    state: InboxState;
+    notice?: MailNotice;
+};
+/** The owner read a conversation: zero its unread count locally (the host/peer cursor moves in parallel). */
+export declare function markReadLocal(state: InboxState, fp: string): InboxState;
+/** Should the new-mail cue fire? Only while the alter session is not the one on screen. */
+export declare function shouldNotify(notice: MailNotice, currentSessionId: string | undefined): boolean;
+/** Compact relative time for the inbox row: "now", "5m", "3h", "2d", else a short date. */
+export declare function formatAge(ts: number | undefined, now?: number): string;
+/** One-line preview of a message body for the inbox row. */
+export declare function previewOf(body: string | undefined, max?: number): string;

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

@@ -0,0 +1,30 @@
+/**
+ * soulnet-dsh browser half (served as
+ * /plugins/soulnet-dsh/client.js).
+ *
+ * Registers: zh/en dictionaries, the `a2a-message` Conversation Node
+ * Definition + keyed Chat renderer (inbound mail bubbles / plugin notes in
+ * the native alter session), the "SoulMirror" `conversation.view` tab (opens
+ * the page), the `sidebar.footer.action` entry (SoulMirror button + unread
+ * badge → toggles the page), two `shell.overlay` entries (`soulmirror-page`:
+ * the full page — the pinned "My alter" chat, the friend list and the
+ * read-only friend threads, right of dsh's sidebar; `soulmirror-inbox`: the
+ * new-mail toast), the `settings.section` "SoulMirror network", the
+ * `settings.onboarding` identity step, and the client side of the slash
+ * commands (`/friends` and `/soulmirror` popups open the page). The P3
+ * composer takeover of friend sessions is gone with the friend sessions
+ * (P4): the alter session keeps dsh's native composer. All cross-plugin
+ * collaboration goes through cordis services (`ctx.slots`, `ctx.locale`,
+ * `ctx.conversationEvents`, `ctx.sessions`, `ctx.settingsScope`,
+ * `ctx.commandUi`); the only value imports are react, ui-primitives and this
+ * package's own files (bundle purity).
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+export type { A2AChatData } from './a2a-node.ts';
+export type { SoulmirrorKey } from './locales.ts';
+export type { InboxState, MailNotice } from './inbox-state.ts';
+export type { ThreadEntry, ThreadState } from './page-state.ts';
+export declare const inject: string[];
+/** Whether a session cwd is the SoulMirror workspace (`<home>/a2a`, e.g. `~/.soulnet/a2a`). */
+export declare function isSoulmirrorCwd(cwd: string | undefined): boolean;
+export declare function apply(ctx: ClientContext): void;