dsh-loop-engine-allinone 0.0.0-stage → 0.4.1

package/lib/types/client/turn-status.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Per-engine styling for the chat turn-status line (the "深度求索中..." row).
+ *
+ * That row is rendered from inside the harness's ChatView and its words belong
+ * to ui-chat: the row is not a slot, and ui-chat owns the `chat` locale
+ * namespace (a second `locale.register` for the same namespace throws), so a
+ * plugin cannot change the text. What it CAN do is restyle the element, and
+ * that is all this module does — it paints an engine-specific glyph and color
+ * onto the row while the session on screen runs a hosted engine, and leaves the
+ * stock look alone otherwise. On the 0.2.0 line it also takes the harness's own
+ * indicator out of that row ({@link RUNNING_ICON}): that generation draws a
+ * DeepSeek whale there, and a hosted engine turning under a DeepSeek mark is
+ * exactly what this row must not say.
+ *
+ * WHICH engine it paints is the SESSION ON SCREEN's, not the settings default.
+ * {@link reflectTurnStatusEngine} is driven from the per-session engine cache
+ * (`./session-engine.ts`) — the same authoritative answer the header chip and
+ * the composer render from, the plugin's own Remote read off the session's
+ * durable log — and it is driven by the ONE hook those two surfaces share
+ * (`./use-session-engine.ts`). So this row cannot disagree with the two surfaces
+ * beside it; while it was keyed off the settings store it did, and painted
+ * Claude Code's glyph onto every session's row whenever claude-code was the
+ * default, a session running pi included.
+ *
+ * The reflection's SUBJECT is still a document-level attribute rather than the
+ * row's own element: the sheet has to reach a class the harness hashes (see
+ * {@link ROW_SELECTORS}), which takes an attribute selector on an ancestor,
+ * and the row offers no session-scoped hook for a plugin to hang it on — the one
+ * attribute this module does put on a row ({@link LIVE_ATTR}) claims no session,
+ * it says "the turn in flight is this one" and is re-derived every time the rows
+ * change. A document-level attribute has exactly ONE owner at a time, though —
+ * and on this page the WRITERS outnumber the reader: the chip and the composer of every
+ * session that has been rendered carry an answer, the session the user has just
+ * left included, and the cache publishes a session's answer regardless of what is
+ * on screen. So "whoever reflected last" is not "the session on screen", and an
+ * implementation that read it as one shipped the bug this guard ends: a
+ * background session's answer — or the late answer of the session the user just
+ * left — painted ITS engine onto the row of the session on screen, and a session
+ * running pi showed Kimi's moon.
+ *
+ * The owner is therefore DECLARED, not inferred: a reflection names the session
+ * it speaks for and writes only while that session is the row's focus
+ * ({@link focusTurnStatusSession}); a reflection whose subject is not the focused
+ * session is a NO-OP, so only the session on screen can paint and only it can
+ * un-paint. The chip and the composer of one session reflect the same value (the
+ * write is idempotent); the focus is withdrawn by
+ * {@link blurTurnStatusSession}, which acts only while the focus is still the
+ * departing session's (React runs a departing component's cleanup in no
+ * guaranteed order against an arriving one's, so an unconditional withdrawal
+ * would un-focus the session that just took over); and the attribute itself is
+ * never withdrawn on unmount: the sibling surface of the same session still
+ * paints by it, and a leftover attribute is inert on a page whose turn-status row
+ * is not rendered.
+ *
+ * The paint is gated TWICE, and both gates are needed on the 0.1.7 line — the
+ * 0.2.0 line needs neither of them, for the reason given below.
+ *
+ * First, on the session being MID-TURN, through a second document-level
+ * attribute ({@link RUNNING_ATTR}, written from the same reflection). On the
+ * 0.1.5 line the row only exists while a turn is in flight, so the engine
+ * attribute alone was enough; on the 0.1.7 line that same button stays on screen
+ * after the turn ends, as the collapsed summary that reads "用时 4秒" — an
+ * engine-only gate leaves the glyph and the sweep animating on a finished turn,
+ * which is not what the live line means. The gate is a surface's own answer
+ * (`session.running`, which every session-scoped seat receives), so a surface
+ * that cannot answer passes nothing and leaves it alone rather than guessing.
+ *
+ * Second, and this is the one a session-level gate cannot express: on the
+ * 0.1.7 line EVERY turn's row stays on screen, so while turn N runs, turns
+ * 1..N-1 are still there. A session-wide gate turns the whole sheet on for all
+ * of them — the finished rows would wear the glyph again for as long as any
+ * later turn ran. So the live row is MARKED, and the row selector is gated on
+ * the mark (see {@link LIVE_ATTR}, {@link markLiveRow} and
+ * {@link ROW_SELECTORS}): "the last row in the document" is the turn in flight,
+ * because the rows are rendered in turn order and only the newest one can still
+ * be running. The two gates answer different questions — "is a turn in flight
+ * for this session" and "is this row the one it belongs to" — and neither alone
+ * is enough.
+ *
+ * The 0.2.0 line needs NEITHER gate, because it moved the live row out of the
+ * turn-process button. There the running indicator is the harness's own node —
+ * `RunningStatus`, a `[data-chat-running]` div mounted only while the session
+ * runs — and `TurnProcessNodeView` renders nothing at all until its turn closes,
+ * so a turn-process button is now always a settled summary. The third sheet
+ * ({@link sheetForRunning}) is therefore gated on the engine attribute alone,
+ * and the per-row mark is not merely unnecessary there but WRONG:
+ * {@link markLiveRow} stamps nothing while such a node is on screen, because the
+ * last turn-process button on that page is a finished turn's summary — exactly
+ * the row the mark exists to leave alone.
+ *
+ * Three facts about the harness markup make that safe and specific:
+ *   - the row has one stable handle per harness generation — an
+ *     `[hash]_turnStatus` class suffix on the 0.1.5 line, the
+ *     `data-turn-process` button on the 0.1.7 line (whose text is a `<span>`
+ *     whose hashed class ends `_label`), and the harness's own
+ *     `data-chat-running` attribute on the 0.2.0 line — so each generation gets
+ *     its own copy of the sheet ({@link ROW_SELECTORS}, {@link RUNNING_ROW}) and
+ *     the one the running app renders matches while the others stay inert;
+ *   - its colours paint through custom properties — the 0.1.x rows through the
+ *     `--dsw-static-deepseek-*` gradient pair, 0.2.0's through the
+ *     `--dsw-alias-label-deep-diving*` pair it resolves its own text colour and
+ *     shimmer tint from — so recoloring is a variable override rather than a
+ *     fight over `background` and `background-clip` or over the harness's own
+ *     animation;
+ *   - the glyph rides a `::before` pseudo-element, so the row's real text node
+ *     — and the status it announces — is untouched.
+ *
+ * This sheet deliberately keeps the 0.1.x rows animating even when the OS
+ * reports `prefers-reduced-motion: reduce` (see the re-asserted sweep below):
+ * the deployment's Windows images ship with client-area animation off, which
+ * otherwise freezes every indicator here — the sweep and the glyph alike. On the
+ * 0.2.0 line the harness runs its own shimmer and honours that preference
+ * itself, so the plugin neither re-declares it nor overrides it there; only the
+ * glyph keeps animating. In-process sessions keep the stock reduced-motion
+ * behaviour on every line.
+ *
+ * @module dsh-loop-engine-allinone/client/turn-status
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { LoopEngineId, HostedEngineId } from '../agent-preset-ids.ts';
+/**
+ * One engine's paint: the colours, the glyph and the animation that drives it.
+ *
+ * Exported for the coverage test, which asserts that EVERY hosted engine has an
+ * entry here. Without that assertion a new engine silently keeps the row
+ * unpainted — and because the 0.2.0 sheet hides the harness's own whale on any
+ * `data-loop-engine` value, "unpainted" does not fall back to the DeepSeek
+ * brand, it falls back to nothing at all.
+ */
+export interface EnginePaint {
+    /** The text's own colour — and the glyph's, where the glyph is not an emoji. */
+    readonly colour: string;
+    /** The lighter tint the sweep (0.1.x gradient, 0.2.0 overlay) travels in. */
+    readonly tint: string;
+    /** The glyph itself, unquoted; the glyph rule adds the `content` quoting. */
+    readonly glyph: string;
+    /** Further declarations the glyph rule carries after `color`, in order. */
+    readonly extras: readonly string[];
+    /** The `animation` shorthand driving the glyph; its `@keyframes` is below. */
+    readonly animation: string;
+}
+/**
+ * Every hosted engine's paint, in the order the sheets emit it.
+ *
+ * This is the one place an engine's identity on the row lives. The pair is the
+ * same on every generation — a base colour and the lighter tint its sweep
+ * travels in — and only the custom properties it is written to change, so a
+ * sheet is this table emitted through that generation's selectors and variables
+ * rather than a second copy of the engine roster.
+ */
+export declare const ENGINE_PAINT: ReadonlyArray<readonly [HostedEngineId, EnginePaint]>;
+/**
+ * Reflect the engine of the session ON SCREEN; `undefined` restores the stock
+ * row.
+ *
+ * The caller names the session it speaks for, and that is the row's SUBJECT: a
+ * reflection paints its session's engine only while that session is the focused
+ * one ({@link focusTurnStatusSession}), and is a NO-OP otherwise — the whole
+ * guard, and the reason the attribute can no longer be taken over by a session
+ * the user is not looking at. The subject is an explicit argument rather than
+ * ambient state, so a caller cannot reflect without saying whose engine it is,
+ * and cannot say "whoever, I don't know".
+ *
+ * `in-process` is the harness's own row, and `undefined` is every answer that
+ * names no engine at all: a session the host reports as `legacy` (it ran a
+ * hosted engine, the id never said which) or `unset`, a session whose first
+ * answer has not landed yet, and an answer dropped in preparation for a re-read.
+ * None of them paints — naming an engine for an unknown one is the misreport
+ * this module was fixed for — so each clears the attribute. The clear is as
+ * authoritative as the paint: a session that takes the focus with no answer yet
+ * takes the previous session's paint off with it.
+ *
+ * The write is idempotent and never a withdrawal: the chip and the composer of
+ * one session both come through here with the same value, and unmounting never
+ * clears the attribute, because the sibling surface of the same session is still
+ * on screen painting through it.
+ *
+ * The MID-TURN gate is written from here as well, but only by a surface that can
+ * answer it (`running` given): the sheet is gated on both, because the 0.1.7 row
+ * outlives its turn, and a surface with no answer must leave the gate as the
+ * surface that has one left it rather than guess.
+ *
+ * The NO-OP covers the late reflection as well — the one from the session the
+ * user has just left, whose own answer landing after the switch used to paint
+ * over the session that replaced it.
+ * @param sessionId - the session this reflection speaks for, or undefined for a
+ *   page with no session at all (the new-session page, which has no turn-status
+ *   row): such a page has nothing to say about the row, so nothing is written and
+ *   nothing is withdrawn — it leaves the row it found alone.
+ * @param engine - the engine that session runs, when it is known.
+ * @param running - whether that session is mid-turn, when the surface knows;
+ *   omitted by a surface with no answer, which leaves the gate alone.
+ */
+export declare function reflectTurnStatusEngine(sessionId: string | undefined, engine: LoopEngineId | undefined, running?: boolean): void;
+/**
+ * Declare which session's surfaces are on screen — the row's one subject.
+ *
+ * Only the focused session may paint ({@link reflectTurnStatusEngine}), which is
+ * what keeps the row on the session the user is looking at: the alternative,
+ * "whoever writes last owns the row", was the bug this guard ends, because the
+ * chip and the composer of EVERY session that has been rendered write here, and
+ * a session's answer can land after the user has left it.
+ *
+ * The caller is the component that renders that session: only a component knows
+ * which session is the one on screen, and the hook both of that session's
+ * surfaces share (`./use-session-engine.ts`) is the only place that declares it.
+ * @param sessionId - the session whose surfaces are now on screen.
+ */
+export declare function focusTurnStatusSession(sessionId: string): void;
+/**
+ * Withdraw the focus — but only while it is still this session's.
+ *
+ * The guard is the point: React offers no ordering guarantee between a departing
+ * component's cleanup and an arriving one's, so an unconditional withdrawal would
+ * let the session the user has just left un-focus the session that replaced it
+ * and silence the row. A session that is no longer the focus has nothing to
+ * withdraw; unmounting also never clears the attribute itself, which the sibling
+ * surface of the same session (and, for a session that is still on screen, the
+ * next focus) still paints by.
+ * @param sessionId - the session whose surface is going away.
+ */
+export declare function blurTurnStatusSession(sessionId: string): void;
+/**
+ * Install the per-engine turn-status stylesheet for the lifetime of `ctx`.
+ *
+ * This is the sheet and nothing else: which engine it selects is written by
+ * {@link reflectTurnStatusEngine}, driven from the session on screen's own
+ * authoritative answer (`./session-engine.ts`), through the hook the chip and
+ * the composer share (`./use-session-engine.ts`) — not from the settings
+ * default.
+ * @param ctx - the client root context.
+ */
+export declare function installTurnStatusStyles(ctx: ClientContext): void;
+//# sourceMappingURL=turn-status.d.ts.map

package/lib/types/client/use-session-engine.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The React binding over the plugin's per-session engine cache.
+ *
+ * Separated from `./session-engine.ts` on purpose: the cache, the contribution,
+ * and the switcher are plain logic with no React import, so they are exercised
+ * in node (`tests/session-engine-cache.spec.ts`) — this file is the only part of
+ * the read path that needs a component to render.
+ *
+ * It is also the ONE driver of the chat turn-status row
+ * (`./turn-status.ts`): the row is painted through a document-level attribute,
+ * and a component is the only place that knows whether the session it renders is
+ * the one on screen. The cache cannot know that — it answers for every session a
+ * surface has watched — so a reflection made from there could be (and was) taken
+ * over by a background session. Here the chip and the composer of the session on
+ * screen declare that session as the row's subject while they are mounted, with
+ * the focus guard inside `reflectTurnStatusEngine`, and the reflection follows
+ * the cache's answer so a switch repaints the row.
+ *
+ * @module dsh-loop-engine-allinone/client/use-session-engine
+ */
+import { type SessionEngineReport } from '../agent-preset-ids.ts';
+import type { SessionEngineCache } from './session-engine.ts';
+/**
+ * Follow one session's engine report in a component, and — because a component
+ * is what knows whether this session is the one on screen — drive the chat
+ * turn-status row from it.
+ *
+ * The value is read from the cache DURING render, so a session switch can never
+ * paint the previous session's engine: only the re-render is deferred, and only
+ * until the host answers. The reflection runs in an effect rather than during
+ * render (it writes to the document), and re-runs when the ANSWER changes — not
+ * just when the session id does — so the row follows a switch: the picker's
+ * `invalidate` drops the cached answer, the cache re-asks, the hook's watcher
+ * bumps, the engine changes, and the attribute lands on the engine the session
+ * now runs.
+ *
+ * Only the ACTUAL engine reaches the row. A recorded engine that differs from it
+ * is one whose switch never took over (its release did not complete), so the row
+ * keeps painting what is really running — the same rule the chip and the composer
+ * follow when they name an engine; they merely also carry the marker
+ * ({@link SessionEngineReport}).
+ *
+ * The value is read from the cache DURING render, so a session switch can never
+ * paint the previous session's engine: only the re-render is deferred, and only
+ * until the host answers. This effect is also the trigger that re-reads the
+ * session: it runs when the session on screen CHANGES (a mount, a switch, or the
+ * same session opened again), and the subscription it installs re-reads the
+ * session on its first watch (`SessionEngineCache.watch` → `refresh`), so a
+ * session the user comes back to cannot keep rendering a report this page took
+ * before — coming back is not what moves the session (a switch is performed on
+ * the host, and the one that has to release the session reloads this page), but
+ * it is long enough for the answer to be old.
+ * Re-renders of the same session do not re-run this effect, so nothing here asks
+ * again while the session stays on screen.
+ *
+ * One effect does the whole thing, so the three steps cannot come apart: declare
+ * this session as the row's subject (`focusTurnStatusSession`), reflect its
+ * engine and its mid-turn gate by that declaration (`reflectTurnStatusEngine`),
+ * and release the declaration when this surface goes away
+ * (`blurTurnStatusSession`, which withdraws it only while it is still this
+ * session's).
+ *
+ * `running` is the session's own live state (`session.running`, from the
+ * session-scoped standard kit) and it is part of the effect's key: the 0.1.7 row
+ * stays on screen after the turn ends, so the paint has to come off when the turn
+ * does — a surface that does not know the state passes nothing and leaves the
+ * gate alone.
+ * @param cache - the cache the plugin mounted.
+ * @param sessionId - the session to follow, or undefined off a session scope.
+ * @param running - whether that session is mid-turn, when the surface knows.
+ * @returns the engine report, or undefined while it is unknown.
+ */
+export declare function useEngineOfSession(cache: SessionEngineCache, sessionId: string | undefined, running?: boolean): SessionEngineReport | undefined;
+//# sourceMappingURL=use-session-engine.d.ts.map

package/lib/types/commands.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Claude Code slash-command bridge.
+ *
+ * The dsh `commands` runtime executes a registered command locally — the line
+ * is consumed and never reaches the model — so a command whose real processing
+ * lives inside the Claude Code CLI must forward the raw line back to the
+ * engine. The definitions here do exactly that: the handler delivers
+ * `/<name> [args]` to the receiving agent as a plain user message, and the CLI
+ * then expands it natively (built-ins and custom `.claude/commands/*.md`).
+ * Registering the built-ins keeps them visible in the dsh web slash menu;
+ * unregistered `/lines` pass through as user text, but the menu would hide the
+ * engine's command surface.
+ *
+ * User-level custom slash commands (`~/.claude/commands/*.md`) are discovered
+ * and registered the same way, so they appear in the menu AND reach the CLI.
+ * Project-level `.claude/commands/` files are left to the CLI entirely: they
+ * are cwd-dependent, and a global dsh registration would collide across
+ * projects.
+ *
+ * The built-in list is limited to commands the CLI actually recognizes in SDK
+ * mode (verified against Claude Code 2.1.220 by driving real SDK queries):
+ * unknown ones are not forwarded to the model at all — the CLI answers
+ * `Unknown command: /name` — but registering one would still advertise a
+ * command that does not exist. Note that some recognized commands report
+ * `isn't available in this environment` outside the interactive TUI; that
+ * report is the engine's own answer and travels back as an assistant message.
+ *
+ * @module dsh-loop-engine-allinone/commands
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+/** Minimal shape of a DSH command definition (avoiding a direct peer dep on @deepseek-ai/dsh-commands). */
+export interface CommandDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly input?: {
+        readonly hint: string;
+        readonly images?: boolean;
+    };
+    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;
+}
+/** Invocation delivered to one registered command handler. */
+export interface CommandInvocation {
+    readonly commandId: string;
+    /** The receiving agent; forwarding handlers deliver the raw line back to it. */
+    readonly agent: {
+        readonly followup: (input: UserMessage) => void;
+    };
+    /** Exact text following the command name, including separator whitespace. */
+    readonly rawInput: string;
+    readonly signal: AbortSignal;
+}
+/** Settled result of one command handler. */
+export interface CommandResult {
+    readonly kind: 'success' | 'error';
+    readonly text?: string;
+}
+/**
+ * Build the forwarding handler for one Claude Code slash command: it
+ * re-delivers the full `/<name> [args]` line to the receiving agent as a
+ * plain user message, where the CLI expands it. `rawInput` already carries the
+ * separator whitespace and any arguments.
+ * @param name - the command name without the leading slash.
+ * @returns the command handler.
+ */
+export declare function forwardClaudeCodeCommand(name: string): (invocation: CommandInvocation) => CommandResult;
+/** Claude Code's built-in slash commands. */
+export declare const CLAUDE_CODE_COMMANDS: readonly CommandDefinition[];
+/**
+ * Discover the user-level custom slash commands from `~/.claude/commands/*.md`
+ * and build forwarding definitions for them. The scan is synchronous so the
+ * agent-creation path can register the commands before the agent is published;
+ * files without a usable name or description, and names already taken by the
+ * built-ins, are skipped.
+ * @returns forwarding definitions, sorted by file name.
+ */
+export declare function discoverUserSlashCommands(): CommandDefinition[];
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/compat.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Runtime harness-generation probe. One released build must serve the 0.1.5
+ * line (`0.1.5-rc.1` … `0.1.5-rc.3`, all sharing the OLD settings API) and the
+ * 0.1.7 line (`0.1.7-rc.1`), which rewrote the settings host and client and
+ * turned the agent-creation announcement async. The differences are not
+ * version strings but API SHAPES, so the switch is a structural probe of the
+ * imported module rather than a semver parse: `@deepseek-ai/dsh-settings`
+ * exported a named `SettingsProvider` class on the 0.1.5 line, and the 0.1.7
+ * rewrite deleted it in favour of `SettingsForms` plus per-entry volatile
+ * Config fields.
+ *
+ * The probe resolves to whichever `@deepseek-ai/dsh-settings` the running
+ * profile actually provides. It is host-side only: the browser bundle must not
+ * import host packages, so `src/client/*` never imports this module.
+ *
+ * @module dsh-loop-engine-allinone/compat
+ */
+/**
+ * Whether the running harness predates the profile-backed settings rewrite
+ * (the 0.1.5 line). `true` selects the legacy settings host/client, the
+ * synchronous agent-creation announcement, and the legacy tool-result message
+ * introspection.
+ */
+export declare const LEGACY_HARNESS: boolean;
+//# sourceMappingURL=compat.d.ts.map