dsh-her 0.0.1 → 0.1.0

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

@@ -0,0 +1,163 @@
+/**
+ * HTTP endpoints for the "她" page, on DSH's own authenticated `/api` channel
+ * (`ctx.connection.fetch`), so every request has already passed DSH's browser
+ * authentication before it gets here.
+ *
+ * Every endpoint is POST with a JSON body and answers `{ ok: true, … }` or
+ * `{ ok: false, message }`. The page polls `/state`; changes answer with the
+ * fresh state, so the page never shows something the brain does not have.
+ */
+import type { Character } from '../core/index.ts';
+import type { LookView, PackSummary, WindowMode } from '../protocol/index.ts';
+import type { Fact, Episode } from '../memory/store.ts';
+import type { ReportLine } from './import-status.ts';
+import type { LookProject, WorkshopCard } from '../core/workshop.ts';
+import type { ProjectStatus } from './workshop.ts';
+import type { InstallState } from './body-install.ts';
+export declare const API_BASE = "/api/dsh-her";
+export interface StateView {
+    platform: string;
+    character: Character;
+    /** The model she uses now; `chosen` = picked on the "她" page (else the config's or DSH's default). */
+    model: {
+        provider: string;
+        model: string;
+        effort?: string;
+        chosen: boolean;
+    } | null;
+    /** status: listening (local recognition); speaking: her cloud voice. */
+    voice: {
+        status: string;
+        speaking: {
+            status: string;
+            service: string;
+            error?: string;
+        };
+        id: string;
+        speed: number;
+    };
+    body: {
+        connected: boolean;
+        /** A body process is running (it may still be connecting). */
+        running: boolean;
+        /** There is a body to start (the development one, or the installed app). */
+        canStart: boolean;
+        /** The installed body app: installing, updating, a newer version waiting for a restart. */
+        install: InstallState;
+        info?: {
+            kind: string;
+            version: string;
+            os: string;
+        };
+        pack?: PackSummary;
+        packs: PackSummary[];
+        activePack?: string;
+        mode?: WindowMode;
+        /** The look on screen, with its scenes (when a look rather than a single pack is chosen). */
+        look?: LookView;
+        /** The body's screens (logical size, scale), for advice on sizes. */
+        screens?: Array<{
+            w: number;
+            h: number;
+            scale: number;
+        }>;
+    };
+    import: {
+        state: 'idle' | 'picking' | 'running' | 'done' | 'failed';
+        done: number;
+        total: number;
+        step: string;
+        lines: ReportLine[];
+    };
+    heard?: {
+        text: string;
+        at: number;
+    };
+    memory: {
+        facts: Fact[];
+        episodes: Episode[];
+        diary: string[];
+        lastDigestDay: string | null;
+    };
+}
+export interface ApiRuntime {
+    state(): StateView;
+    saveCharacter(patch: Partial<Character>): Character;
+    expandPersona(input: {
+        name: string;
+        idea: string;
+        callYou: string;
+        pronoun: string;
+    }): Promise<string>;
+    tryPersona(input: {
+        name: string;
+        persona: string;
+        callYou: string;
+        pronoun: string;
+        history: Array<{
+            who: 'you' | 'her';
+            text: string;
+        }>;
+        message: string;
+    }): Promise<string>;
+    previewVoice(id: string, speed: number, text: string): Promise<{
+        audio: string;
+        format: 'wav' | 'mp3';
+        durationMs: number;
+    }>;
+    startBody(): string;
+    /** Download and install the body app (or a newer one); progress shows in the state. */
+    installBody(): void;
+    /** Stop the running body and start it again (to use a newly installed version). */
+    restartBody(): Promise<void>;
+    setMode(mode: WindowMode): void;
+    pickPack(): void;
+    usePack(packId: string): void;
+    setLook(change: {
+        auto?: boolean;
+        locked?: boolean;
+        go?: string;
+        on?: Record<string, boolean>;
+    }): void;
+    /** 形象工坊: projects in the materials folder; create, save, open, frame a scene, import. */
+    workshopList(): Array<{
+        project: LookProject;
+        status: ProjectStatus;
+    }>;
+    workshopNew(name: string): {
+        project: LookProject;
+        status: ProjectStatus;
+    };
+    workshopSave(project: unknown): {
+        project: LookProject;
+        status: ProjectStatus;
+    };
+    /** Copy a project to a folder the user picks on the body (undefined: cancelled). */
+    workshopExport(id: string, media: boolean): Promise<{
+        dir: string;
+        files: number;
+    } | undefined>;
+    /** Bring in a project folder (or its 形象.json) the user picks on the body. */
+    workshopImportProject(): Promise<{
+        project: LookProject;
+        status: ProjectStatus;
+    } | undefined>;
+    workshopExamples(): Array<{
+        card: WorkshopCard;
+        file: string;
+        label: string;
+        ready: boolean;
+    }>;
+    workshopOpen(id: string): void;
+    workshopFrame(id: string, sceneId: string): void;
+    workshopImport(id: string): void;
+    memoryRemove(ids: string[]): number;
+    memoryConfirm(ids: string[]): number;
+    digest(): Promise<string>;
+    exportMemory(): string;
+}
+type Body = Record<string, unknown>;
+type Handler = (body: Body) => Promise<Record<string, unknown>>;
+export declare function apiHandlers(rt: ApiRuntime): Record<string, Handler>;
+export declare function handle(handler: Handler, request: Request): Promise<Response>;
+export {};

package/lib/types/dsh/body-install.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The installed body: downloaded from the release (body/scripts/package.mjs
+ * makes it), checked, unpacked into `<home>/body/<version>/`, and kept up to
+ * date. The release has `body-latest.json`:
+ *
+ *   { "format": "dsh-her-body@1", "version": "0.1.0",
+ *     "assets": { "darwin-arm64": { "file": "dsh-her-body-0.1.0-darwin-arm64.zip", "size": …, "sha256": "…" } } }
+ *
+ * `<home>/body/current.json` says which version is installed. A download
+ * that does not match its SHA-256 is thrown away; the previous version stays
+ * until the new one is in place, and one older version is kept to go back to.
+ */
+import type { LaunchPlan } from './body-launcher.ts';
+export declare const MANIFEST = "body-latest.json";
+export interface BodyAsset {
+    file: string;
+    size: number;
+    sha256: string;
+}
+export interface BodyManifest {
+    format: 'dsh-her-body@1';
+    version: string;
+    assets: Record<string, BodyAsset>;
+}
+export interface Installed {
+    version: string;
+    /** The app (macOS: dsh-her.app) inside `<home>/body/<version>/`. */
+    app: string;
+    installedAt: string;
+}
+/** What the "她" page shows about the installed body. */
+export interface InstallState {
+    state: 'idle' | 'checking' | 'downloading' | 'installing' | 'failed';
+    installed?: string;
+    /** The newest version in the release, when checked. */
+    latest?: string;
+    /** A newer version is installed but the running body is still the old one. */
+    restart?: boolean;
+    done?: number;
+    total?: number;
+    error?: string;
+    /** This install runs the development body from the repository instead. */
+    dev: boolean;
+}
+/** This computer's asset key in the manifest. */
+export declare const platformKey: (platform?: NodeJS.Platform, arch?: NodeJS.Architecture) => string;
+/** -1, 0, 1: "0.1.0-dev.0" < "0.1.0" < "0.1.1" < "0.2.0". */
+export declare function compareVersions(a: string, b: string): number;
+export declare function validateManifest(value: unknown): BodyManifest;
+export declare function installedBody(home: string): Installed | undefined;
+/** How to start the installed body. */
+export declare function installedPlan(home: string): LaunchPlan | undefined;
+export declare function fetchManifest(base: string): Promise<BodyManifest>;
+/**
+ * Download this computer's asset of `manifest`, check it, unpack it next to
+ * the installed version and make it current. Progress in bytes.
+ */
+export declare function install(home: string, base: string, manifest: BodyManifest, onProgress: (done: number, total: number) => void): Promise<Installed>;

package/lib/types/dsh/body-launcher.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Start the body app when no body is connected: the development body (the
+ * repository's `body/` next to this package, built with `npm run build`
+ * there) when there is one, else the installed app (body-install.ts).
+ *
+ * The Electron binary is found through `node_modules/electron/path.txt`, not
+ * `require('electron')`: inside the DSH desktop app that require returns
+ * Electron's API instead of the binary path. The body is detached so it
+ * outlives DSH (she sleeps until DSH is back), and ELECTRON_RUN_AS_NODE is
+ * removed or the body would start as plain Node.
+ */
+export interface LaunchPlan {
+    binary: string;
+    args: string[];
+    cwd: string;
+}
+/** The development body next to this package, if it is built. */
+export declare function findDevBody(packageRoot?: string): LaunchPlan | {
+    missing: string;
+};
+/** A body that is running but not connected yet (still backing off) has its pid in `<home>/body.json`. */
+export declare function bodyRunning(home: string): boolean;
+export declare function launchBody(plan: LaunchPlan, env: {
+    url: string;
+    token: string;
+    home: string;
+    pack: string;
+}): number | undefined;

package/lib/types/dsh/config.d.ts

@@ -0,0 +1,34 @@
+import Schema from '@deepseek-ai/schemastery';
+import type { VoiceConfig } from '../voice/voice.ts';
+export interface HerConfig {
+    /** Where dsh-her keeps characters, packs, models and the discovery file, outside DSH. `~` expands. */
+    home: string;
+    character: {
+        /** Stable id; her session and memory are keyed by it. */
+        id: string;
+        name: string;
+        persona: string;
+    };
+    /** Model route for her session; both empty = DSH's current default model. A fast, non-reasoning model keeps her quick to answer. */
+    provider: string;
+    model: string;
+    /** Reasoning effort for her model route; empty = the route's default. Lower answers sooner. */
+    reasoningEffort: string;
+    /** Preferred port of the body protocol server (the next free one is used if taken). */
+    port: number;
+    body: {
+        /** auto: start the body app when DSH starts and no body is connected; off: never. */
+        launch: 'auto' | 'off';
+        /** Appearance pack directory passed to the body; empty = the body's default. */
+        pack: string;
+        /** Where the body app is downloaded from: the release's address, ending with the folder that has body-latest.json. */
+        releases: string;
+        /** Start the development body in the repository when there is one (off: behave like a release install). */
+        useDev: boolean;
+    };
+    voice: VoiceConfig & {
+        /** How the body listens: one utterance per shortcut press, or all the time. */
+        mic: 'push-to-talk' | 'always';
+    };
+}
+export declare const Config: Schema<HerConfig>;

package/lib/types/dsh/her-session.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Her own session in DSH ("她 · <name>"): one ordinary persisted session per
+ * character. Created once, resumed after every restart; its id is kept under
+ * the dsh-her home, not in DSH. The creation follows dsh-vael's SelfSession.
+ *
+ * Inside her agent's scoped context she gets her own system prompt (DSH's
+ * coding-agent prompt and runtime chatter are replaced) and a listener on her
+ * live assistant stream, which turns text deltas into speakable sentences.
+ * Reasoning and tool-call deltas are never spoken.
+ *
+ * Her prompt is rebuilt at every model request, so its performance section
+ * always matches the body that is connected and what she remembers is current.
+ * Her tools: `play_action` (a longer performance by the body) and `remember`,
+ * `recall`, `forget` (her memory).
+ */
+import { type Character } from '../core/index.ts';
+import type { MemoryProvider } from '../memory/store.ts';
+export interface ModelRoute {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+interface UserMessageLike {
+    id: string;
+    role: 'user';
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    source: {
+        kind: string;
+        [key: string]: unknown;
+    };
+}
+interface AgentLike {
+    readonly session: {
+        readonly id: string;
+    };
+    followup(message: UserMessageLike): void;
+    /** Context for the next model request, without starting a turn. */
+    inject(message: UserMessageLike): void;
+    cancel(cause?: unknown): void;
+    whenIdle(): Promise<void>;
+}
+interface AgentHandleLike {
+    readonly agent: AgentLike;
+    dispose(): Promise<void>;
+}
+/** One live publication of her assistant stream (`agent/assistant-stream`). */
+export type StreamFrame = {
+    type: 'start';
+    attemptId: string;
+    turn: number;
+    step: number;
+} | {
+    type: 'chunk';
+    attemptId: string;
+    index: number;
+    time: number;
+    chunk: {
+        type: string;
+        text?: string;
+    };
+} | {
+    type: 'end';
+    attemptId: string;
+    index: number;
+    outcome: {
+        kind: string;
+    };
+};
+export interface ScopedContext {
+    tools: {
+        register(definition: unknown): () => void;
+        /** Tool schemas as a scope sees them; no scope = the global surface. */
+        schemas(scope?: unknown): Array<{
+            name: string;
+        }>;
+        /** Hide global tools from the calling agent scope (scoped registrations stay visible). */
+        restrict(filter: {
+            allow?: readonly string[];
+            deny?: readonly string[];
+        }): () => void;
+    };
+    systemPrompt?: {
+        section(definition: {
+            name: string;
+            order: number;
+            text: string | (() => string);
+            complete?: boolean;
+            interpolate?: boolean;
+        }): unknown;
+        suppressRuntimeContext?(): unknown;
+    };
+    on(event: 'agent/assistant-stream', listener: (payload: {
+        frame: StreamFrame;
+    }) => void): () => void;
+}
+export interface DshServices {
+    agents: {
+        create(options: {
+            sessionId: string;
+            meta?: {
+                cwd?: string;
+            };
+            agentOptions?: ModelRoute;
+            setup?: (agentCtx: ScopedContext) => void | Promise<void>;
+        }): Promise<AgentHandleLike>;
+        resume(options: {
+            resumeSessionId: string;
+            agentOptions?: ModelRoute;
+            setup?: (agentCtx: ScopedContext) => void | Promise<void>;
+        }): Promise<AgentHandleLike>;
+    };
+    agentDefaultModel?: {
+        currentSelection(): {
+            provider: string;
+            model: string;
+        } | undefined;
+    };
+    workspaceRegistry?: {
+        create(path: string, title?: string): Promise<{
+            attachSession(id: string): Promise<void>;
+        }>;
+    };
+    sessionTitle?: {
+        rename(session: unknown, title: string): void;
+    };
+    sessionQuery?: {
+        readSession(id: string): Promise<{
+            events: Array<{
+                seq: number;
+                type: string;
+                data: unknown;
+            }>;
+        }>;
+    };
+}
+/**
+ * What her stream produces, per reply: one `start`, any number of `sentence`s,
+ * one `end`. `replyId` is unique across turns.
+ */
+export interface ReplyEvents {
+    start(replyId: string): void;
+    sentence(replyId: string, text: string): void;
+    end(replyId: string, outcome: string): void;
+}
+export interface HerSessionDeps {
+    cid: string;
+    /** Who she is right now (the "她" page can change it at any time). */
+    character: () => Pick<Character, 'name' | 'persona' | 'callYou' | 'pronoun'>;
+    /** The performance section for the connected body (empty without one). */
+    performance: () => string;
+    /** Have the body perform an action; resolves when it is done. */
+    playAction: (action: string) => Promise<{
+        ok: boolean;
+        reason?: string;
+        transcript?: string;
+    }>;
+    /** "关于对方" for her prompt, from memory. */
+    aboutYou: () => string;
+    memory: MemoryProvider;
+    /** dsh-her home for this character: session.json and her room live here. */
+    dir: string;
+    route: ModelRoute | undefined;
+    services: () => DshServices | undefined;
+    logger: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+    events: ReplyEvents;
+}
+export declare class HerSession {
+    private handle;
+    private opening;
+    private readonly splitter;
+    /** Set by interrupt(): the rest of the current reply is not spoken. */
+    private dropping;
+    /** The reply being streamed, unique across turns. */
+    private replyId;
+    private readonly deps;
+    constructor(deps: HerSessionDeps);
+    get title(): string;
+    get sessionId(): string | undefined;
+    /** Her live agent: reuse, resume the recorded session, or create it the first time. */
+    ensure(): Promise<AgentHandleLike>;
+    /** Send what you said (typed or recognized) as a new turn. */
+    say(text: string, via: 'voice' | 'text' | 'command'): Promise<AgentLike>;
+    /** Tell her something for her next turn without making her answer (what was heard of a cut-off reply, …). */
+    note(text: string): Promise<void>;
+    /** Stop the reply in progress (barge-in). DSH keeps the delivered prefix marked `interrupted`. */
+    interrupt(): void;
+    dispose(): Promise<void>;
+    private recordFile;
+    private recorded;
+    private open;
+    private composeScope;
+    /**
+     * Her tools, in DSH's native tool shape (plain JSON Schema). Not through
+     * `defineTool`: a plugin linked from outside the profile cannot import
+     * dsh-tools, and an unconverted schema makes the model provider reject the
+     * whole request.
+     */
+    private safe;
+    private registerTools;
+    /**
+     * P1: she only keeps you company, so DSH's work tools (shell, files, web…)
+     * are hidden from her session. Their schemas would also cost thousands of
+     * tokens on every turn. Tools she gets later are registered in her own scope,
+     * which a restriction never hides.
+     */
+    private hideGlobalTools;
+    private onFrame;
+}
+export {};

package/lib/types/dsh/import-status.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where a pack import started from the "她" page stands. The import itself
+ * runs in the body (it reads your folder and has ffmpeg); the body reports
+ * progress and a report, which the page shows by polling the brain's state.
+ */
+export interface ReportLine {
+    level: 'ok' | 'warn' | 'error';
+    text: string;
+}
+export interface ImportStatus {
+    state: 'idle' | 'picking' | 'running' | 'done' | 'failed';
+    done: number;
+    total: number;
+    step: string;
+    lines: ReportLine[];
+}
+export declare const IDLE_IMPORT: ImportStatus;

package/lib/types/dsh/plugin.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The DSH shell: opens her session as soon as DSH's agent services are ready,
+ * serves the body protocol, starts the body, and exposes `/her`. Everything
+ * hangs off `ctx.effect`, so disabling or uninstalling the plugin closes her
+ * session handle and the server (the body stays up and waits, asleep).
+ *
+ * Every reply of her session, whoever prompted it (the body's input box or
+ * microphone, the DSH page, `/her`), goes to connected bodies as `speak.*`
+ * sentences, each with its synthesized audio (or, without a voice, timed by
+ * reading speed). Replies are live only: a body that connects later never gets
+ * earlier ones replayed.
+ *
+ * Listening: a body sends what you said as audio; it is recognized here and
+ * goes to her like typed text. When a body cuts her off (you started talking),
+ * it reports how far she got; her next turn is told what you actually heard.
+ *
+ * Performing: the connected body's pack decides what she can do. Her prompt
+ * lists it; inline tags in her reply become cues on the sentence they are in,
+ * and longer performances go through her `play_action` tool, which waits for
+ * the body's `act.done`.
+ *
+ * Memory: files under `<home>/characters/<cid>/memory/` (src/memory). She
+ * writes with `remember`, reads with `recall`, and her prompt carries what she
+ * knows about you, her last diary days and what has a date today or tomorrow.
+ * A minute after each talk, a short note picks out of the new turns what is
+ * worth keeping (as candidates), so it shows on the "她记得的事" page at once.
+ * Once a day (30 minutes after you last talked, or from 23:30) a digest reads
+ * the day back from her session and writes her diary page and candidates.
+ *
+ * Her replies are also logged with timings to `<home>/logs/stream.jsonl`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { HerConfig } from './config.ts';
+export declare function apply(ctx: Context, config: HerConfig): void;

package/lib/types/dsh/workshop.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 形象工坊 on disk: each project is a folder under `~/Documents/dsh-her 素材`
+ * (where the user can see it and drop files in), with
+ *
+ *   形象.json              the project (character card, scenes, clips)
+ *   参考图提示词.txt        how to make 参考图.png, her "ID photo"
+ *   参考图.png             (the user's) — also the desk pet's anchor
+ *   生成清单.md            every clip: first frame, file, prompt
+ *   MiniMax生成任务.md      the same, as a task for MiniMax Code (when that is the tool)
+ *   ComfyUI生成清单.json    the same, for a ComfyUI script (when that is the tool)
+ *   桌宠/提示词.txt         + the desk pet's clips
+ *   场景-卧室/提示词.txt     + 照片提示词.txt, plate.png, scene.json, crop.png, clips
+ *
+ * The prompts are rewritten on every save; the user's pictures and clips are
+ * never touched. Importing hands the folders to the body (same computer).
+ */
+import { type LookProject, type WorkshopCard } from '../core/workshop.ts';
+export declare const MATERIALS_DIR: string;
+export interface PartStatus {
+    /** 桌宠, or the scene's name. */
+    name: string;
+    folder: string;
+    /** Clips planned, and how many of them are in the folder. */
+    planned: number;
+    made: number;
+    /** The minimum (idle and two talks) is there. */
+    enough: boolean;
+    /** Scenes: the photo, and her region framed on it (scene.json and crop.png). */
+    photo?: boolean;
+    framed?: boolean;
+}
+export interface ProjectStatus {
+    dir: string;
+    reference: boolean;
+    parts: PartStatus[];
+    /** Something can be imported: at least one part has its minimum (and a scene its frame). */
+    importable: boolean;
+}
+/** Every project in the materials folder, newest first. */
+export declare function listProjects(root?: string): Array<{
+    project: LookProject;
+    status: ProjectStatus;
+}>;
+export declare function findProject(id: string, root?: string): {
+    project: LookProject;
+    dir: string;
+} | undefined;
+export declare function projectStatus(project: LookProject, dir: string): ProjectStatus;
+/**
+ * Write a project: its folder (made on first save, named after it), 形象.json
+ * and every prompt file. Pictures and clips already there stay as they are.
+ */
+export declare function saveProject(input: unknown, screen?: {
+    width: number;
+    height: number;
+}, root?: string): {
+    project: LookProject;
+    status: ProjectStatus;
+};
+/** Before importing: the desk pet's anchor is the reference picture. */
+export declare function prepareImport(project: LookProject, dir: string): void;
+/**
+ * Copy a project to another folder (`dest`/<its name>): its settings
+ * (形象.json, the prompts, scene.json), and with `media` its pictures and
+ * clips too. The copy can be imported anywhere with importProject.
+ */
+export declare function exportProject(id: string, dest: string, media: boolean, root?: string): {
+    dir: string;
+    files: number;
+};
+/**
+ * Bring a project in from elsewhere: a folder with 形象.json in it, or the
+ * 形象.json itself. It becomes a new project in the materials folder (a new
+ * id if one with its id is there already), with whatever pictures and clips
+ * came along; the prompts are written afresh.
+ */
+export declare function importProject(path: string, screen?: {
+    width: number;
+    height: number;
+}, root?: string): {
+    project: LookProject;
+    status: ProjectStatus;
+};
+/** Where examples are looked for: the user's own first, then the plugin's. */
+export declare function exampleDirs(home: string): string[];
+/** The file to serve for an example slot, if it has been put in place. */
+export declare function exampleFile(home: string, file: string): string | undefined;
+/** Every card's example slots and whether each is there yet. */
+export declare function examples(home: string): Array<{
+    card: WorkshopCard;
+    file: string;
+    label: string;
+    ready: boolean;
+}>;

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * dsh-her — a desktop companion for DSH.
+ *
+ * The brain lives here: her own DSH session, voice, memory, and the body
+ * protocol server. The body (the Electron desktop app) lives in `body/`.
+ * `src/core` never imports DSH; `src/dsh` is the only layer that does.
+ */
+export declare const name = "dsh-her";
+export declare const usage = "dsh-her: a desktop companion who lives on your real desktop, talks by voice and remembers you. /her talks to her.";
+export { Config, type HerConfig } from './dsh/config.ts';
+export { apply } from './dsh/plugin.ts';