soulnet-dsh 0.1.0

package/lib/types/alter-state.d.ts

@@ -0,0 +1,185 @@
+/**
+ * What the owner needs to know about their alter, folded from the alter
+ * session's durable event log (P3, reshaped in P4 for ONE alter session) —
+ * pure, unit-tested in test/alter-state.test.ts:
+ *
+ *   - `triggerOf(events)`: what woke the CURRENT turn — the owner (a
+ *     `user/message` with `source.kind === 'user'`), mail from a friend (the
+ *     relay `user/message` the sessions plugin delivers; the trigger carries
+ *     that friend's fingerprint / name), an auto-flagged mail, or unknown.
+ *     `soulmirror_send_message` reads this to decide send-now vs draft
+ *     (src/policy.ts `sendGate`); the persona variables resolve the per-turn
+ *     friend context from it.
+ *   - `latestFromEvents(events)`: the alter's latest state — its latest words
+ *     to the owner (last assistant text), the last owner instruction, the
+ *     last `soulmirror_send_message` call and its outcome (sent / draft
+ *     queued / refused), and how the last turn ended.
+ *   - `chatFromEvents(events)`: the transcript the SoulMirror page renders
+ *     for "My alter": owner messages, the alter's replies, inbound mail from
+ *     friends (with the friend context), what the alter sent / queued, the
+ *     plugin's notes (draft decisions) and failed turns.
+ *
+ * The fold reads plain event envelopes (`{ type, seq, time, data }`) so it
+ * needs no dsh value import; `Session.events` satisfies the shape.
+ */
+import type { TurnTrigger } from './policy.ts';
+import { type A2ANoteKind } from './events.ts';
+export interface EventLike {
+    readonly type: string;
+    readonly seq: number;
+    readonly time: number;
+    readonly data: unknown;
+}
+export interface AlterNote {
+    readonly text: string;
+    readonly ts: number;
+    readonly seq: number;
+    readonly turn: number;
+}
+export interface AlterInstruction {
+    readonly text: string;
+    readonly ts: number;
+    readonly seq: number;
+}
+/** Outcome of a `soulmirror_send_message` call as the tool reported it. */
+export type SendOutcome = 'sent' | 'draft-queued' | 'refused' | 'failed';
+export interface AlterSend {
+    readonly body: string;
+    readonly fingerprint?: string;
+    readonly ts: number;
+    /** Undefined while the tool result is pending. */
+    readonly outcome?: SendOutcome;
+    /** The gate reason the tool reported (`owner-initiated`, `draft-tier`, …). */
+    readonly gate?: string;
+    /** Draft id when the outcome is `draft-queued`. */
+    readonly draftId?: string;
+    /** Error / refusal text when not sent. */
+    readonly detail?: string;
+}
+export interface AlterTurn {
+    readonly turn: number;
+    readonly reason: string;
+    readonly failed: boolean;
+    readonly ts: number;
+    readonly message?: string;
+    /** The turn is still open (no `turn/end` yet). */
+    readonly open: boolean;
+}
+export interface AlterLatest {
+    /** The last owner instruction in the log. */
+    readonly instruction?: AlterInstruction;
+    /** The alter's latest words to the owner (last assistant text). */
+    readonly note?: AlterNote;
+    /** The last `soulmirror_send_message` call. */
+    readonly sent?: AlterSend;
+    /** The latest turn (open or closed). */
+    readonly turn?: AlterTurn;
+    /** What woke the latest turn. */
+    readonly trigger: TurnTrigger;
+    /** Number of events folded (the page uses it as a change marker). */
+    readonly seq: number;
+}
+export declare const EMPTY_LATEST: AlterLatest;
+/** Concatenate the text blocks of a message's content. */
+export declare function textOf(content: unknown): string;
+/** The relay `a2a` block of a user/message, when the source is ours. */
+export declare function relayMetaOf(data: unknown): {
+    fp: string;
+    id: string;
+    ts: number;
+    name: string;
+    auto: boolean;
+    type?: string;
+    note?: A2ANoteKind;
+    draftId?: string;
+} | undefined;
+/** Classify one `user/message` by its source: owner / inbound / inbound-auto / note (ours, not mail) / other. */
+export declare function classifyUserMessage(data: unknown): 'owner' | 'inbound' | 'inbound-auto' | 'note' | 'other';
+/**
+ * What woke the current (latest) turn: the first attributable `user/message`
+ * after the last `turn/start`. No turn, or only tool results / injected
+ * context / plugin notes in it → `unknown`.
+ */
+export declare function triggerOf(events: readonly EventLike[]): TurnTrigger;
+/** Fold the whole log (or a suffix of it) into the latest alter state. */
+export declare function latestFromEvents(events: readonly EventLike[]): AlterLatest;
+export type AlterChatItem = 
+/** The owner spoke (page composer or dsh's input bar); `revise` when it was the page's "let the alter revise" feedback on a draft. */
+{
+    readonly kind: 'owner';
+    readonly key: string;
+    readonly ts: number;
+    readonly text: string;
+    readonly revise?: {
+        readonly name: string;
+        readonly fp: string;
+    };
+}
+/** The alter answered the owner (assistant text). */
+ | {
+    readonly kind: 'alter';
+    readonly key: string;
+    readonly ts: number;
+    readonly text: string;
+    readonly turn: number;
+}
+/** Mail from a friend reached the alter (relayed into the session). */
+ | {
+    readonly kind: 'inbound';
+    readonly key: string;
+    readonly ts: number;
+    readonly fp: string;
+    readonly name: string;
+    readonly id: string;
+    readonly body: string;
+    readonly auto: boolean;
+    readonly type?: string;
+}
+/** The alter called `soulmirror_send_message`. */
+ | {
+    readonly kind: 'send';
+    readonly key: string;
+    readonly ts: number;
+    readonly fp: string;
+    readonly body: string;
+    readonly outcome?: SendOutcome;
+    readonly gate?: string;
+    readonly draftId?: string;
+    readonly detail?: string;
+    readonly auto: boolean;
+}
+/** The plugin's own note (the owner decided a draft). */
+ | {
+    readonly kind: 'note';
+    readonly key: string;
+    readonly ts: number;
+    readonly note: A2ANoteKind;
+    readonly fp: string;
+    readonly text: string;
+    readonly draftId?: string;
+}
+/** A turn ended without completing (no model, provider error, cancelled …). */
+ | {
+    readonly kind: 'turn-failed';
+    readonly key: string;
+    readonly ts: number;
+    readonly turn: number;
+    readonly reason: string;
+    readonly message?: string;
+};
+export interface AlterChat {
+    readonly items: readonly AlterChatItem[];
+    /** A turn is open (its `turn/end` has not been logged). */
+    readonly running: boolean;
+    /** Change marker (last seq + 1). */
+    readonly seq: number;
+}
+export declare const EMPTY_CHAT: AlterChat;
+/** The owner instruction the sessions plugin writes for "let the alter revise" (name, fp, feedback). */
+export declare const REVISE_INSTRUCTION: RegExp;
+/** Strip the host's model-facing preamble (first line) so the bubble shows the mail body only. */
+export declare function bodyOfRelayText(text: string): string;
+/** Fold the alter session log into the transcript the page renders. */
+export declare function chatFromEvents(events: readonly EventLike[]): AlterChat;
+/** Event types that change what the folds answer (the sessions plugin broadcasts on these). */
+export declare const ALTER_EVENT_TYPES: ReadonlySet<string>;

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

@@ -0,0 +1,52 @@
+/**
+ * Browser-facing HTTP API of the host half, mounted on dsh's web server
+ * (`ctx.webServer.register`, prefix `/soulmirror/api/`). The client bundle
+ * uses it for everything the SoulMirror page / settings / onboarding need
+ * that is not a session event: identity, card, friends, pending requests,
+ * read cursors, the conversation archive, presence, the debug direct send,
+ * the owner → alter channel (P4: `alter.instruct {text}`, `session.latest`,
+ * `session.history`), pending drafts (`drafts.list`, `drafts.decide`),
+ * per-friend settings (`friends.set` with tier / protocol override), the
+ * global diplomacy protocol (`protocol.get` / `protocol.set`), and a
+ * Server-Sent-Events stream of live events (inbound mail, outbound archive,
+ * typing, friend requests, presence, backend status, `alter` = the alter's
+ * state changed, `draft` = a draft was stored / decided).
+ *
+ * Why not dsh's Typert remotes: those are generated build artifacts selected
+ * by the web app at build time; an out-of-repo plugin cannot add one (see
+ * dsh-api-remotes README "capability set is fixed by explicit build-time
+ * value imports"). Why not `ctx.sessionProjections` for typing: projections
+ * are pure folds over COMMITTED session events and typing must not be logged
+ * (SPIKE.md §1), so there is no event to fold. This route is the plugin's own
+ * channel; it is served by the same loopback web server as `/api`.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import { type NetworkClient, type NetworkEvent } from '../network/types.ts';
+import type { AlterSessions, SessionsEvent } from '../sessions/index.ts';
+import type { SoulmirrorSettings } from '../settings.ts';
+export declare const API_PREFIX = "/soulmirror/api/";
+/**
+ * What the SSE stream carries: every NetworkEvent of the backend plus the
+ * sessions plugin's own frames (`outbound`, `alter`, `draft`).
+ */
+export type ApiFrame = NetworkEvent | SessionsEvent;
+export interface ApiOptions {
+    readonly client: NetworkClient;
+    readonly home: string;
+    readonly settingsNamespace: string;
+    /** Resolved lazily: the sessions plugin may mount after the network plugin. */
+    readonly sessions: () => AlterSessions | undefined;
+    /** Live settings (the alter fields apply without restart). */
+    readonly settings: () => SoulmirrorSettings;
+    readonly log: (level: 'info' | 'warn' | 'error', message: string) => void;
+}
+export interface ApiHandler {
+    (req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** Push one frame to every SSE client (the sessions plugin's events are forwarded through this). */
+    broadcast(frame: ApiFrame): void;
+    dispose(): void;
+}
+export declare function createApiHandler(options: ApiOptions): ApiHandler;
+/** Mount the API on `ctx.webServer` when (and for as long as) that service exists. */
+export declare function mountApi(ctx: Context, options: ApiOptions): void;

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

@@ -0,0 +1,4 @@
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+export type A2ANodeProps = PropsRuntime<'conversation.chat.node', 'a2a-message'> & PropsLocale<typeof NS>;
+export declare function A2ANode({ node, t }: A2ANodeProps): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import type { Translate } from './Inbox.tsx';
+export interface AlterPaneProps {
+    t: Translate;
+    /** Open the alter's dsh session (closes the page). */
+    onOpenSession: (sessionId: string) => void;
+    /** Jump to a friend's read-only thread. */
+    onGoFriend: (fp: string) => void;
+}
+export declare function AlterPane({ t, onOpenSession, onGoFriend }: AlterPaneProps): import("react").JSX.Element;

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

@@ -0,0 +1,13 @@
+import type { Translate } from './Inbox.tsx';
+import { type InboxFriend } from './inbox-state.ts';
+export interface ChatPaneProps {
+    t: Translate;
+    friend: InboxFriend;
+    /** Whether the page is visible (mark-read only then). */
+    visible: boolean;
+    /** Open the friend's dsh session (resolves fp → session id first) and close the page. */
+    onOpenSession: (fp: string) => void;
+    /** Debug setting: offer "Send as myself" (direct send through the peer). */
+    directSend: boolean;
+}
+export declare function ChatPane({ t, friend, visible, onOpenSession, directSend }: ChatPaneProps): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+import type { ApiDraft } from './api.ts';
+import type { Translate } from './Inbox.tsx';
+export declare function reasonLabel(t: Translate, reason: string): string;
+export declare function DraftCard({ draft, t, showTarget, onGoFriend }: {
+    draft: ApiDraft;
+    t: Translate;
+    /** Name the target in the head (the alter chat lists drafts to every friend). */
+    showTarget?: boolean;
+    /** Jump to the friend's read-only thread. */
+    onGoFriend?: (fp: string) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,20 @@
+import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+import type { SoulmirrorSettingsValues } from './SettingsSection.tsx';
+export interface FriendMatch {
+    readonly sessionId: string;
+    readonly friendName: string;
+    /** `preset`: the session composes `soulmirror-chat`; `map`: the host's fp → session map names it. */
+    readonly reason: 'preset' | 'map';
+}
+export interface FriendComposerInjected {
+    /** Bound settings scope of the `soulmirror` namespace (reads `directSend` live). */
+    scope: SettingsScope<SoulmirrorSettingsValues>;
+}
+export type FriendComposerProps = PropsRuntime<'conversation.composer'> & {
+    matched: FriendMatch;
+} & InjectFace<FriendComposerInjected> & PropsLocale<typeof NS>;
+export type FriendSelector = (owner: ComposerChainProps) => FriendMatch | null;
+export declare function FriendComposer({ matched, scope, t }: FriendComposerProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import type { Translate } from './Inbox.tsx';
+export interface FriendListProps {
+    t: Translate;
+    /** `ALTER_KEY` or the selected friend's fingerprint. */
+    selected: string;
+    onSelect: (key: string) => void;
+    /** A pending request was accepted: the new friend's fp. */
+    onAccepted?: (fp: string) => void;
+    /** Close the page (back to dsh). */
+    onClose: () => void;
+}
+export declare function FriendList({ t, selected, onSelect, onAccepted, onClose }: FriendListProps): import("react").JSX.Element;

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

@@ -0,0 +1,13 @@
+import type { Translate } from './Inbox.tsx';
+import { type InboxFriend } from './inbox-state.ts';
+export interface FriendPaneProps {
+    t: Translate;
+    friend: InboxFriend;
+    /** Whether the page is visible (mark-read only then). */
+    visible: boolean;
+    /** Jump to "My alter". */
+    onGoAlter: () => void;
+    /** Debug setting: offer the direct-send row (bypasses the alter). */
+    directSend: boolean;
+}
+export declare function FriendPane({ t, friend, visible, onGoAlter, directSend }: FriendPaneProps): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+export type Translate = PropsLocale<typeof NS>['t'];
+export interface InboxProps {
+    t: Translate;
+    /** A friend row was clicked (or a request accepted): open the SoulMirror page on that friend. */
+    onOpenFriend: (fp: string) => void;
+}
+export declare function Inbox({ t, onOpenFriend }: InboxProps): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+export interface InboxOverlayInjected {
+    /** The session currently on screen (ctx.sessions.list current), for the new-mail cue. */
+    currentSessionId: () => string | undefined;
+}
+export type InboxOverlayProps = InboxOverlayInjected & PropsLocale<typeof NS>;
+export declare function InboxOverlay({ currentSessionId, t }: InboxOverlayProps): import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+export type OnboardingProps = PropsRuntime<'settings.onboarding'> & PropsLocale<typeof NS>;
+export declare function SoulmirrorOnboarding({ complete, openSection, t }: OnboardingProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,29 @@
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import { type ReplyTier } from './api.ts';
+import type { NS } from './locales.ts';
+type SettingsSectionProps = PropsRuntime<'settings.section'>;
+export interface SoulmirrorSettingsValues {
+    relay?: string;
+    displayName?: string;
+    backend?: string;
+    peerBinary?: string;
+    home?: string;
+    defaultTier?: ReplyTier;
+    autoReplyPerHour?: number;
+    directSend?: boolean;
+}
+export interface SoulmirrorSettingsInjected {
+    /** Select a session as current (ctx.sessions.open) — used for "Open the alter session in dsh". */
+    openSession: (id: string) => void;
+    /** Bound settings scope of the `soulmirror` namespace. */
+    scope: SettingsScope<SoulmirrorSettingsValues>;
+}
+export type SoulmirrorSettingsProps = SettingsSectionProps & InjectFace<SoulmirrorSettingsInjected> & PropsLocale<typeof NS>;
+export declare function CardBlock({ cardUri, home, t }: {
+    cardUri: string;
+    home: string;
+    t: SoulmirrorSettingsProps['t'];
+}): import("react").JSX.Element;
+export declare function SoulmirrorSettingsSection({ openSession, scope, t }: SoulmirrorSettingsProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,9 @@
+import type { SidebarFooterActionOwnerProps } from '@deepseek-ai/dsh-client-ui-sidebar/client';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+export type SidebarEntryProps = SidebarFooterActionOwnerProps & PropsLocale<typeof NS>;
+/** The SoulMirror glyph: a mirror (rounded frame) with a reflected spark. */
+export declare function SoulMirrorIcon({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+export declare function SidebarEntry({ wide, t }: SidebarEntryProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+import type { SoulmirrorSettingsValues } from './SettingsSection.tsx';
+export interface SoulmirrorPageInjected {
+    /** Select a session as current (ctx.sessions.open). */
+    openSession: (sessionId: string) => void;
+    /** Bound settings scope of the `soulmirror` namespace (the page reads the debug `directSend` toggle live). */
+    scope: SettingsScope<SoulmirrorSettingsValues>;
+}
+export type SoulmirrorPageProps = SoulmirrorPageInjected & PropsLocale<typeof NS>;
+export declare function SoulmirrorPage({ openSession, scope, t }: SoulmirrorPageProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,5 @@
+import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+export type SoulmirrorViewProps = ConvViewProps & PropsLocale<typeof NS>;
+export declare function SoulmirrorView({ sessionId, t }: SoulmirrorViewProps): import("react").JSX.Element;

package/lib/types/client/a2a-node.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Conversation Node Definition for SoulMirror relayed rows in the NATIVE dsh
+ * view of the alter session.
+ *
+ * The host writes each inbound A2A message as a `user/message` whose source is
+ * `{ kind:'plugin', plugin:'soulmirror', form:'relay', senderSessionId, a2a:{…} }`
+ * (see ../sessions/index.ts and SPIKE.md §1) — and, since P4, its own NOTES
+ * (the owner decided a draft) with the same source plus `a2a.note`. This
+ * definition folds exactly those events into `a2a-message` chat nodes that
+ * ./A2ANode.tsx paints as a bubble (mail) or a system line (note).
+ * ui-conversation's own `input-message` definition also renders the same
+ * event as a collapsed "Context injection · soulmirror" row; shadowing that
+ * row (keyed `context` renderer at priority -1) is still open.
+ */
+import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-runtime/client';
+import type { A2AMessageData, A2ASourceMeta } from '../events.ts';
+/** Renderer payload: the message plus the seq of the event that produced the node. */
+export interface A2AChatData extends A2AMessageData {
+    readonly seq: number;
+    readonly type?: string;
+}
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+    interface ChatNodeDataMap {
+        'a2a-message': A2AChatData;
+    }
+}
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+    interface ConversationStepDataMap {
+        'a2a-message': A2AChatData;
+    }
+}
+interface RelaySource {
+    kind?: unknown;
+    plugin?: unknown;
+    form?: unknown;
+    senderSessionId?: unknown;
+    a2a?: Partial<A2ASourceMeta>;
+}
+/** Whether a `user/message` source is a SoulMirror relayed row (mail or note). */
+export declare function isSoulmirrorRelaySource(source: unknown): source is RelaySource & {
+    a2a?: Partial<A2ASourceMeta>;
+};
+/** Strip the host's model-facing preamble (first line) so the bubble shows the mail body only. */
+export declare function bodyOfRelayText(text: string): string;
+export declare const a2aRelayDefinition: ConversationNodeDefinition<A2AChatData>;
+export {};

package/lib/types/client/alter-ui.d.ts

@@ -0,0 +1,35 @@
+import { type ReplyTier } from './api.ts';
+import type { Translate } from './Inbox.tsx';
+export declare const TIERS: readonly ReplyTier[];
+export declare function tierLabel(t: Translate, tier: ReplyTier): string;
+export declare function tierShort(t: Translate, tier: ReplyTier): string;
+export declare function TierPill({ tier, t }: {
+    tier: ReplyTier;
+    t: Translate;
+}): import("react").JSX.Element;
+export declare function TierSelect({ value, defaultTier, onChange, t, disabled, id }: {
+    /** Stored tier; undefined = the global default applies. */
+    value: ReplyTier | undefined;
+    defaultTier: ReplyTier;
+    onChange: (tier: ReplyTier | undefined) => void;
+    t: Translate;
+    disabled?: boolean;
+    id?: string;
+}): import("react").JSX.Element;
+/** Per-friend alter settings: reply tier + protocol override (friend pane, above the action bar). */
+export declare function FriendSettingsPanel({ fp, name, tier, tierExplicit, protocol, defaultTier, perHour, t, onClose }: {
+    fp: string;
+    name: string;
+    tier: ReplyTier | undefined;
+    tierExplicit: boolean;
+    protocol: string | undefined;
+    defaultTier: ReplyTier;
+    perHour: number;
+    t: Translate;
+    onClose?: () => void;
+}): import("react").JSX.Element;
+/** The global diplomacy protocol editor (protocol.md), used by the friend list and the settings section. */
+export declare function ProtocolEditor({ t, compact }: {
+    t: Translate;
+    compact?: boolean;
+}): import("react").JSX.Element;