Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.
DSH packaged-app reconnaissance
Source: /Applications/DeepSeek Harness.app/Contents/Resources/app.asar (read-only; version 0.2.0-rc.2, dsh/desktop-runtime.json → hostProtocolVersion: 4, node 24.18.1, platform darwin/arm64).
Method: asar header parsed (dataOffset = align4(16 + uint32@12)), 288 @deepseek-ai/* packages extracted to /tmp/dsh-recon/, READMEs + lib/*.js + lib/*.css read and grepped. Every claim below cites a package/file. "not discoverable" = not present in the packaged code.
1. Runtime topology
One CLI, layered "profiles", one web surface. dsh is "the sole supported Node application launcher: profiles are ordered stacks of plugin-bundle patch layers" (dsh/README.md). Profiles live under $DSH_HOME/profiles/<name> ($DSH_HOME else ~/.dsh — lib/main.js:25 DSH_HOME_DIR_NAME = ".dsh", dsh-home-paths). Layer order: bundle patches in dsh.profile.bundles order → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch overlays. Shipped bundles: dsh-base, dsh-web-app, dsh-headless, dsh-sdk-app, dsh-sdk-minimal, dsh-acp-app. The desktop profile name is reserved for Electron and rejected by the npm CLI.
| Surface | Entry | Notes |
|---|---|---|
| Web | dsh web / dsh --profile web |
dsh-web-app/lib/startup.js: flags --host <host>, --port <port> (0 = OS-assigned), --trusted-host <authority...>, --no-open. --host 0.0.0.0 is a usage error: "it would expose remote code execution to the network; use 127.0.0.1 instead". |
| Desktop | Electron lib/main.js |
Spawns a child Node process, does not embed the host. |
| Headless / SDK / ACP | dsh --profile headless|sdk|sdk-minimal|acp |
Same plugin kernel, no browser. |
Host: HTTP server
dsh-host-webserver is a plain node:http server that "knows no harness concepts and serves no files". Config {host: 127.0.0.1 | 0.0.0.0, port: 3000, compression: 'gzip'} (README example uses port 3000; port: 0 → OS-assigned, read back via ctx.webServer.port). Matching: exact table → longest prefix → single fallback handler; register(route) / registerUpgrade(route); duplicate path throws. Index rendering = two layers: collectIndexInjections() gathers structured IndexInjection rows (one webserver/index-inject emit per call), then applyIndexTaps(html) raw transforms. No TLS/auth/origin policy of its own — route owners enforce theirs. Shipped web bundle uses gzip level 1 with a 1024-byte threshold.
Frontend: the built web shell
@deepseek-ai/dsh-web-frontend — package description: "Web application entry: vite build over the @deepseek-ai/dsh-client-web shell library; dist/ served by apps/cli's dsh web" (repo apps/web). Contents: dist/index.html (825 B, <div id="root">, KaTeX fonts under dist/assets/fonts/), assets/index-5SrrfWpU.js (633 KB), assets/vendor-CCJJTK99.js (740 KB), assets/index-BPHePDI_.css (76 KB), assets/vendor-BNsW4eBh.css (29 KB).
Served by dsh-host-frontend-static, which claims the fallback seat: root/configured index render index.html through ctx.webServer.renderIndex; other existing files served with MIME; unknown extension → application/octet-stream; traversal → 403; missing → empty 404 (no silent SPA fallback); non-GET/HEAD → 405. It injects <base href="./"> ahead of every injected row. Index access needs ctx.connection.authorizeIndex: a valid process token gets 303 + persistent browser cookie, a valid cookie serves the index, everything else gets the Connection-owned 401. Static assets stay public.
window.__DSH_BOOT__
Composed by dsh-client-modules (host half): it "scans the host Loader's entries for packages declaring dsh.client, composes the window.__DSH_BOOT__ entry graph … in module-graph order, serves one-or-more-plugin combo scripts …, contributes the registration facade, application preloads, bootstrap scripts, and graph to the webserver's index injection table". The graph is emitted as one injection row:
{ kind: "global", name: "__DSH_BOOT__", value: graph }
which dsh-host-webserver/lib/index.js renders verbatim as
<script>globalThis["__DSH_BOOT__"] = {…}</script> (placed in <head>, < escaped to \u003c). Companion rows: script-preload for application-phase batches, script-src for bootstrap-phase batches, and a raw script row carrying the module-loader queue. The browser bundle then reads it: await globalThis.__DSH_BOOT_READY__?.promise; const o = n.__ModuleLoader__; const s = globalThis.__DSH_TRANSPORT__; this.modules = o.create({ boot: n.__DSH_BOOT__, staticModules: rM(), ...s?.loadBundle && { loadBundle: s.loadBundle } }) (dsh-web-frontend/dist/assets/index-5SrrfWpU.js).
Client plugin model (slots + /plugins)
- A browser plugin declares
dsh.clientin itspackage.json(platform: 'web', exports./client, optionaldsh.client.external). Host bundles are served under/plugins;<id>/clientand bare id resolve to the same exports. Boot scripts register factories; module bodies run lazily at first materialization. Failed combo → one retry, then per-row one-resource combo (≤3 requests per missing row). - Shared baseline module table
PLATFORM_MODULES(React, Cordis, static UI libraries) is frozen by the shell; onlydsh.client.externalentries may resolve elsewhere. Rejects malformed requests, missing suppliers, self-requests, sync cycles. - UI composition is typed slots:
dsh-client-ui-slotsprovidessingle/list/keyed/chainslots plus Component Factories. "Declaring a slot is claiming it" — the only entry allowed to render a key is its declarer; registering into an undeclared slot throws at load.ChainSelectelects by ascendingpriority, ties by registration order. The React implementation and install contract live indsh-client-ui-renderer("after the complete client plugin roster settles, the boot kernel callsctx…"). - Live updates:
dsh-client-hmr"keeps open Web pages in sync with the Host plugin graph and reloads rebuilt browser bundles"; ordinary enable/disable needs no page reload. Thedsh-client-connectionpackage carries browser→Host Remote calls, exact Fetch responses and "connection generations" over the/apibridge (dsh-api-gatewayowns the two-sided RPC endpoint andREMOTE_STREAM_MUX_PATHwebsocket mux).
Desktop boot chain
app.asar/lib/main.js → spawn(node, ["--expose-internals", …, "<runtimeDir>/node_modules/@deepseek-ai/dsh-desktop-host/lib/index.js", runtimeDir, projectDir, primaryRuntime, pnpm, nodeBin], {stdio: [ignore, pipe, pipe, ipc]}). The child (@deepseek-ai/dsh-desktop-host, "Private Node-mode host process for the Electron desktop application", mounts dsh-host-webserver, dsh-agent, dsh-client-connection, dsh-jobs, dsh-schedule, dsh-workspace, dsh-skill-office, dsh-deepseek-account) replies over IPC {type:'ready', url, injections}; main then window.loadURL(<that url>). Other IPC events: platform-session, shutdown-complete, fatal, plus a request/response control channel. Preloads shipped: preload-app.cjs, preload-mandatory.cjs, preload-platform-account.cjs, preload-update-dialog.cjs, preload-welcome.cjs; separate renderer documents for welcome / mandatory-update / update-dialog. The preload sets html[data-platform='darwin'] (macOS) and data-windows-titlebar (Windows); these switch frame geometry.
URL announcement: dsh web: <authenticatedUrl> (LAN: …), DSH_WEB_URL is exported to the model's shell env, and webRuntime service + web-app plugin add the "You are interacting with the user through the DeepSeek Harness Web GUI at " system-prompt section.
Ports: config example 3000; --port 0 for ephemeral; Electron takes whatever the desktop-host reports; loopback host is hardcoded 127.0.0.1 for the canonical URL (LOOPBACK_HOST).
2. Client package map
Shell / sidebar / layout
| Package | Responsibility | UI region |
|---|---|---|
dsh-client-ui-layout |
Three-column AppFrame, edge-column widths, ctx.layout.selectPanel/toggleSidebar/openRightbar/closeRightbar, theme presenter |
whole frame |
dsh-client-ui-renderer |
Mounts the assembled client GUI, React slot renderer + install contract | app root |
dsh-client-ui-slots |
Slot/factory registry (React-free) | infra |
dsh-client-ui-sidebar |
Brand mark+name, New Session, sidebar.panellist global entries, collapse/rail, bottom-pinned Settings |
left column |
dsh-client-ui-workspace |
Workspace + Session catalog: grouped/flat lists, add/rename/reorder/search/fork/archive/delete, row hover menus | left column body |
dsh-client-ui-sidebar-right |
Right dock: one surface per session, two presentations (docked/fullscreen), expand button, rightbar controller |
right column |
dsh-client-ui-sidebar-files |
Workspace file tree with watched auto-refresh | right tab |
dsh-client-ui-sidebar-terminal |
Shell picker + persistent terminals, rename, recovery | right tab |
dsh-client-ui-sidebar-browser |
HTTP(S) browsing: iframe+managed history (web) / <webview> (desktop) |
right tab |
dsh-client-ui-sidebar-documentpreview |
File preview + renderer choice (Markdown/code/PDF/HTML/images/sheets) | right tab |
dsh-client-ui-theme |
light/dark/system, content font size 10–22 px, token stylesheets | global presentation |
dsh-client-ui-brand-official |
Swaps DSH mark+name into the sidebar for an official build |
sidebar brand |
dsh-client-ui-open-in-app |
Session-header split button: open cwd in remembered app |
header |
Conversation / chat
| Package | Responsibility | UI region |
|---|---|---|
dsh-client-ui-conversation |
Target-neutral assembly: event/view registries, per-session bindings, input state, image URL cache, composer shell | center |
dsh-client-ui-chat |
The Chat target: recorded-conversation rendering, historical images, scroll restore, "work details" modes | center |
dsh-client-ui-trajectory |
Turn-aware ledger + timing overview + record inspector | center (tab) |
dsh-client-ui-tool |
Renders every tool call, dispatched by conversation.tool-call key |
inside chat |
dsh-client-ui-primitives |
Controls, icons, overlays, Markdown/TeX, terminal, read, diff, search, web, JSON renderers | everywhere |
dsh-client-ui-attachment |
Draft rail under composer, full-viewport drop invitation, durable images, lightbox | composer + messages |
dsh-client-ui-commands |
/ command popups, client actions, host command input; /model, /permission popupSelect specs |
composer |
dsh-client-ui-input-trigger |
/ and @ grouped menu at caret (commands, files, sessions) with drill-down |
composer |
dsh-client-ui-reference |
@ completion ordering: files before sessions |
composer |
dsh-client-ui-message-feedback |
Like/Dislike in the assistant action strip + feedback dialog + /feedback |
message actions |
dsh-client-ui-approval |
Approval presentation; takes over the composer; Enter=allow, Escape=reject | composer takeover |
dsh-client-ui-user-questions |
Agent question panel beside the input: options, text, skip, batch submit | beside composer |
dsh-client-ui-plan |
Plan mode chip, plan review card, plan preview resource | composer + card |
dsh-client-ui-goal |
Durable goal + activation: edit/pause/resume/clear, /goal bubbles |
chat node |
dsh-client-ui-jobs |
Session background jobs: one header control, lifecycle/elapsed/progress, expandable output | header |
dsh-client-ui-deliverables |
Turn-end changed-files card, delivered-file cards, inline-code links into the sidebar | turn tail |
dsh-client-ui-skill |
/skill and /name skill invocation surface |
composer |
dsh-client-ui-model-selection |
/model popup + composer model control (provider-grouped, reasoning effort) |
composer |
dsh-client-ui-agent-preset |
Preset chooser + new-task default + Creator-mode authoring | hero / settings |
dsh-client-ui-permission-presets |
Preset picker for session (composer, /permission) vs future default (settings) |
composer + settings |
dsh-client-ui-subagent |
Browse descendant conversations, running state, tokens, active-turn duration | overlay/panel |
dsh-client-ui-workflow-run |
One durable workflow run per Chat node; phases → members | chat node |
dsh-client-ui-schedule |
Automation tasks page + right-sidebar task tab | overlay/tab |
dsh-client-ui-cordis |
Historical generated-plugin cards + process-local control panel | chat node |
dsh-client-ui-directory-picker-browse / -native |
In-app directory browser / OS chooser, filling ui-workspace directory-flow slots |
modal |
Settings
| Package | Responsibility |
|---|---|
dsh-client-ui-settings |
Transport+schema layer: ctx.configForms namespaces, atomic multi-field updates, concurrent-write protection, whileServed |
dsh-client-ui-settings-general |
The Settings shell: sidebar.settings occupant, navigation, modal panel, onboarding steps, connection pill, config-file action |
dsh-client-ui-settings-models |
Models page: API keys (write-only), per-provider model lists, hand-declared custom routes |
dsh-client-ui-settings-plugins |
"Built-in plugins" section shell owning the tab row (settings.plugins.tab) |
dsh-client-ui-settings-plugin-inventory |
Read-only "Plugin list" tab: agent presets (open) + collapsed global inventory + search |
dsh-client-ui-settings-account |
Account/login section (STRIP for Strata) |
dsh-client-ui-settings-shell / -agent-loop / -subagent / -web-search / -session-log |
Official plugin pages: Shell, Agent loop, Subagent, Web search, session-log upload |
dsh-client-ui-shortcuts |
"Keyboard shortcuts" dialog (Mod+/): search, recorder, restore defaults |
dsh-client-ui-plugin-manager |
Plugins sidebar entry: install/enable bundles, pnpm output, install-script approval |
Infra (non-visual)
dsh-client-store (React-free observables/snapshot stores, Immer updates, optional persistence), dsh-client-modules (boot graph + /plugins bundles), dsh-client-shortcuts (per-device keybinding registry/persistence), dsh-client-locale (en/zh + plugin locales), dsh-client-connection (Remote calls + connection generations), dsh-client-resources (dsh-resource:// addressing), dsh-client-file-upload (Blob/stream intake per Session), dsh-client-hmr.
3. Screen & navigation inventory
Left sidebar (dsh-client-ui-sidebar, -workspace)
Top→bottom: brand row (sidebar.brand.mark + sidebar.brand.name; fallback is the fish mark + localized common.brand.localBuild "local build"; a complete build stacks a version[-commit][-dirty] badge from DSH_CLIENT_VERSION / DSH_CLIENT_COMMIT_HASH / DSH_CLIENT_GIT_DIRTY) → New Session button (label session.new.label = "New session"; effective binding shown as trailing grey text on hover/focus) → global panel entries (sidebar.panellist; "The shipped composition registers no example panel", labels still present: "Global panels") → workspace/session list → bottom-pinned Settings.
Sidebar labels: "New Session", "Open sidebar", "Collapse sidebar", "Settings", "Global panels".
Session list (ui-workspace copy): "Search session names", "Filter sessions", "Group by", "Order by", "Last updated", "Show archived" / "Archived only" / "All conversations (show archived)", "Hide archived", "No sessions yet", "No matching sessions", "No archived sessions yet", "Archived sessions cannot be opened. Unarchive it to view.", "Selecting or adding a workspace", "Loading workspaces…". Row hover buttons + row menu: Rename session, Fork session ("Could not fork the session. Try again."), Archive session, Pin session ("Pin failed. Try again later."), "Plan awaiting review" badge. Subagent-origin sessions are hidden; pending interactions show warning dots.
Collapse: 264–420 px (default 280), 56 px rail, auto-collapse below 1024 px, macOS desktop hides the column entirely and mounts reopen/New-Session controls into the frame's shell.leading seat beside the traffic lights. Scrollbars are pointer affordances: thumb transparent when the pointer is outside the column, drawn for 2 s after it leaves.
Conversation header (top bar)
conversation.session.header with leading / actions / corner / lineage / utilities slots. Known occupants: open-in-app split button (workspace.openLocal, "Open requested", "Opening containing folder…"), jobs control ("Background jobs"), context-occupancy ring + percentage ("the button stays hidden until context usage and capacity are available"), right-sidebar expand button, more-actions menu (contains Download session log, dsh-session-log-export), subagent/workflow lineage chips, the View tab bar (Chat / Trajectory, hidden when fewer than two views are available).
Settings dialog
Opened from the sidebar's bottom control or the Settings command (desktop Mod+,, web Mod+Alt+,); a modal panel using the frame's overlay inset with ≥24 px viewport margin; navigation scrolls independently of content; exactly one onboarding step mounts at a time.
Sections = settings.section contributions. Observed: General, Models, Account, Plugins ("Built-in plugins"), Keyboard shortcuts (entry labeled "Edit shortcuts", "follows Coding Tools"). The Plugins section owns a tab row: Plugin list (read-only; agent presets open, global inventory collapsed, "Search plugins"), plus the Official group pages Shell, Agent loop, Subagent, Web search, Session log.
General contains: Coding Tools switch (ui-settings.enabled, default true), Appearance row (from ui-theme), Current version at the bottom, Open configuration file (loopback browser only, host-confirmed), Upload Session Log when using the official model API, and rows registered into settings.general.item.
Shell page copy: "Command timeout (ms)", "Output cap per stream (bytes)", "Overridden" badge, "Reset to default", "Nothing is written until Save".
Models page copy: "Add model provider", "Custom model API", "API protocol", "Base URL", "API key", "Display name", "Context window", "Add model", "Delete model", "A capacity must be a number, optionally suffixed K or M.", "Context window must be a positive count, like 131072, 256K, or 1M.", "Anthropic Messages", "Configured — enter a new value to replace", "Customized model catalog".
Overlays / modals
| Overlay | Evidence |
|---|---|
| Generic modal (mask + card) | Modal.module.css: fixed inset 0, z-index: 1000, padding: max(24px, var(--dsh-frame-overlay-top, 24px)) 24px, dialog width: min(380px, 100%), mask uses --dsw-mask-blur + --dsw-alias-bg-mask-1 |
| Menus | Menu / MenuSurface / MenuGroup modules; menu surface fill --dsw-menu-surface-fill: #f8f9fa94 |
| Keyboard shortcuts dialog | 480×600 CSS px card, header + search fixed, internally scrolling list, inline recorder, "Restore All Defaults" footer with override count |
| Approval | composer takeover; "Waiting for approval", "Approval details", "Allow once"; Enter allows, Escape rejects |
| Ask-user question panel | "Ask question", "Waiting until you answer", "Type your answer", "Take time", "Skip", "Dismiss all questions" |
| Directory picker | "Select Workspace Directory" browse dialog (list/navigate/create) or the native OS chooser |
| Plugin manager | install guide, pnpm output panel, "Install scripts need permission" dialog, "Allow these scripts and retry" |
| Risk confirmation | RiskConfirmation.module.css; "I understand the risks and want to continue" (Full access / Auto review) |
| Image lightbox | ImageLightbox.module.css, "Close original image preview" |
| Toasts / hover cards / tooltips | Toast.module.css, HoverCard.module.css (--dsw-hovercard-bg: #2C2C2E), Tooltip.module.css |
| Plan review card | "Plan review", "View full plan", "Open plan in sidebar", "Request changes" |
| Update dialogs (desktop only) | renderer/update-dialog.html, renderer/mandatory-update.html |
Keyboard shortcuts (defaults read from registration code)
| Keys (desktop / web) | Action | Source |
|---|---|---|
Mod+N / Mod+Alt+N |
New session (session.new, aliases "new session", "new chat") |
ui-workspace |
Mod+K / Mod+Alt+K |
Search sessions (session.search) |
ui-workspace |
Mod+O / Mod+Alt+O |
Add workspace / open folder (workspace.add) |
ui-workspace |
Mod+Alt+G |
Rename session (session.rename) |
ui-workspace |
Mod+Alt+F / Mod+Shift+F |
Fork session (session.fork) |
ui-workspace |
Mod+Shift+A / Mod+Alt+A |
Archive session (session.archive) |
ui-workspace |
Mod+B / Mod+Alt+B |
Toggle left sidebar (shell.overlay, label "Toggle left sidebar") |
ui-layout |
Mod+Alt+B / Mod+Shift+B |
Toggle right sidebar float/fullscreen | ui-sidebar-right |
Mod+, / Mod+Alt+, |
Open/close Settings (settings.open) |
ui-settings-general |
Mod+/ |
Open/close Keyboard shortcuts (settings.general.item) |
ui-shortcuts |
Mod+P / Mod+Alt+P |
Files sidebar | ui-sidebar-files |
| `Ctrl+`` | Terminal | ui-sidebar-terminal |
Mod+T / Mod+Alt+T |
Browser tab in right sidebar | ui-sidebar-browser |
Mod+Alt+O / Mod+Shift+O |
Open workspace in app (workspace.openLocal) |
ui-open-in-app |
Enter |
Send/approve; Shift+Enter newline; Mod+Enter steers all queued messages |
ui-conversation |
Escape |
Stop response (response.stop); also closes top dialog / stops menu |
ui-conversation |
double Escape |
Host stopSequenceMs setting, default 500 ms, range 1…2,147,483,646 |
dsh-client-shortcuts |
Mod+2 / arrows / Enter |
segmented-tab & menu navigation | ui-conversation, ui-shortcuts |
Binding rules: each command declares defaults per profile desktop:{macos,windows,linux} and web:{macos,windows,linux}; an omitted profile is unbound. Web persists overrides in origin-local localStorage key dsh.keybindings.v1; Desktop in userData/keybindings.json (v1 → v2 adds optional secondCode). Only overrides are stored; null clears a binding; Restore All affects the current profile only. Effective bindings take priority over native actions, editors, terminals and embedded pages.
Command palette
There is no command palette. The nearest equivalents are (a) the / slash popup — dsh-client-ui-commands + ui-input-trigger, grouped commands / files / sessions with drill-down and a "Loading options…" state, and "a command line is never silently downgraded to a plain prompt"; (b) the searchable Keyboard shortcuts dialog (Mod+/) which lists every registered command, its English alias and its key, matching "an ordered subsequence within one label, English alias, or key combination, ignoring case"; (c) the /model popup for model+effort selection.
4. Conversation / chat UX mechanics
Assembly. ui-conversation consumes SessionEventLikeEntry feeds (outer type = durable vs client-only transient; inner event = {type, seq, time, data}), with match/start/update Definitions, Turn/Step location, and Group Definitions that own segmentation. Views are pluggable targets; Chat and Trajectory are the shipped ones (conversation.view). "With Coding Tools off, the shell hides only Trajectory; other plugin-contributed Views remain available."
| Mechanic | Behaviour | Evidence |
|---|---|---|
| Message list | Turn/step-grouped timeline with incremental append/prepend, replacement-window rebuilds, "Click to load earlier history" / "Load earlier history…", "Back to bottom", restored scroll position | ui-conversation, ui-chat, ui-trajectory |
| Streaming | Assistant deltas arrive as transient assistant/live-chunk entries; settlement removes transient matches and applies one durable entry; text renders token-by-token; stop is response.stop (Escape) |
ui-conversation |
| Reasoning / thinking | "Deep diving" + shimmer tokens (--dsw-alias-label-deep-diving, -shimmer), "Analyzing the request", disclosure rows; work-details modes: settings.transcript.{compact,standard,detailed,verbose} and settings.performance.{compact,detailed} |
ui-chat, ui-theme, slot keys |
| Tool calls | One renderer per conversation.tool-call key via ui-tool; strings: "Called tools" / "Calling tools", "Execution requested", "Result cap reached.", "Content truncated", "Collapse output", "Command failed", "Collapse diff", "Inspect call", "Edited files" / "Editing files" |
ui-tool, ui-chat |
| Approvals | The approval plugin takes over the composer and publishes the pending request through ctx.uiSession; approval.allow = Enter, approval.reject = Escape; copy: "Waiting for approval", "Approval details", "Allow once"; one pending-request lock shared by keyboard and pointer |
ui-approval |
| Permissions | Presets Read Only, Workspace Write, Full access, Auto review; session-scoped pickers in the composer and /permission, future-session default in General settings; "Enable Full access?", "I understand the risks and want to continue" |
ui-permission-presets |
| Edit / retry / branch | Assistant action strip (conversation.chat.assistant-actions), "Branch into a new conversation", "Available only on the last message of a completed turn", copy actions, "Cancel editing" |
ui-chat, ui-conversation |
| Feedback | Like/Dislike pair in the finalized assistant strip; both open a dialog collecting a category + optional description; /feedback decoration; toasts on ack/failure |
ui-message-feedback |
| Composer | One Lexical editor per Session (DraftEditorRuntime / DraftEditor), attachments as an ordered draft rail + full-viewport drop invitation, @ references (files before sessions, @"path with spaces"), / commands claimed/highlighted while only arguments change, IME-safe hints, Cmd/Ctrl+Enter steers all queued messages |
ui-conversation, ui-attachment, ui-reference, ui-input-trigger |
| Attachments | Browser stores a Blob / exact bytes / ReadableStream per Session and gets an opaque receipt for a later prompt; durable images render in Chat, Trajectory and Tool results with a lightbox | dsh-client-file-upload, ui-attachment |
| Context / token metering | Context-occupancy ring + percentage below the input card, opening a token breakdown panel; session stats add "Avg time to first token (TTFT)", "Cache hit", "Cache write", "Cached input", decode wall time; compaction: "Compacting context…", "Context compacted", "Compaction summary unavailable", /compact |
ui-conversation, dsh-session-stats, dsh-compaction |
| Session titles | First eligible human message → title, with optional async LLM generator (dsh-session-title-llm, -first-prompt-llm), explicit user rename, session.untitled fallback |
dsh-session-title* |
| Session list / persistence | Append-only JSONL per session with checksummed Zstandard frames (raw lines when compression off), versioned format generations v0→v4 with migrations, projection cache for history lists/stats/goals, FTS5 search | dsh-session-persistence-jsonl, dsh-session-format*, dsh-session-projection*, dsh-session-query-sqlite |
| Plan mode | Enter with /plan, leave with the composer chip ("Plan mode on — click to turn off (/plan off)"), submitted plan becomes a review card ("Plan review", "View full plan", "Request changes"), plan preview is a sidebar resource ("Plan · Markdown") |
ui-plan, ui-sidebar-right |
| Goals | Durable objective across resume/fork/restart plus process-local activation; states "Ongoing Goal", "Paused Goal", "Blocked Goal", "Inactive Goal"; actions Edit / Pause / Resume / Clear / Save goal; /goal runs render as "Command input" bubbles; dsh-goal-round-driver auto-continues while idle and rounds remain |
ui-goal, dsh-goal, dsh-goal-round-driver |
| Jobs | One header control for the session's background jobs with lifecycle, elapsed time and progress; live and settled-with-output jobs expand; collapsing stops the stream; "Confirm stop", "Click again to confirm", "no exit code" | ui-jobs, dsh-jobs-local |
| Deliverables | Turn-end changed-files card with host line counts, each opening the turn's review tab in that file; explicit delivered-file cards; inline-code references in closing prose become links; split/unified diff, "Enable line wrap", "Binary file; changes cannot be shown", "File too large; changes cannot be shown" | ui-deliverables |
| User questions | Agent question card beside the chat input: choose options, enter text, skip, submit one answer batch; timeout/abort copy ("ask_user_question timed out before the user answered") | ui-user-questions |
| Trajectory | Turn-aware ledger (User/Assistant/Tool/Subtool/compaction), turn+step boundaries, record inspector for tokens, duration, input, output, timing, images, attachment summaries, "Drag to resize. Double-click to reset." | ui-trajectory |
| Subagents / workflows | Descendant browsing with running state, token usage, active-turn duration; completed one-shot conversations open read-only; workflow runs render as Chat nodes with phases→members | ui-subagent, ui-workflow-run (both STRIP for Strata) |
5. Settings model
Host side (dsh-settings). "Edit fields that plugins declare with .settings…" Forms expose only volatile fields from active, uniquely addressed profile entries; ordinary configuration stays editable through Cordis configuration files. Composition:
- id: settings
name: '@deepseek-ai/dsh-settings'
On first start after the Loader settles, a legacy harness-home settings.yaml is imported once — each section is written into the entry of the same id (ui-developer-tools → ui-settings, ui-onboarding → ui-settings-general, shell → the platform shell executor entry) — then renamed to settings.yaml.imported. Reset restores the value beneath the profile override (including schema defaults); home patches and command-line overlays take precedence and a form write they would override is refused. Each form reports autoGenerate (default on) for schema-driven pages — "no shipped client does so yet". A plugin with its own page registers configure({ auto: false }, ctx.fiber) inside an optional ctx.inject(['settings'], …) child from apply.
Schema & persistence. Declared by plugins with schemastery (z.object({...})) — e.g. dsh-web-app config {openBrowser, printUrl, surfaceContext, trustedHosts}, dsh-host-webserver {host, port, compression}, dsh-llm-pi-ai {providers: {...}}. Values live in the composed Cordis tree: bundle patch → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch overlays. Credentials never enter the settings document — they go through dsh-credentials and appear to the UI only as write-only descriptions ("Stored outside the settings file. Leave blank to keep the current key.").
Client side (dsh-client-ui-settings). One settings.describe reader per browser; feature adapters get a per-entry handle:
ctx.configForms.get(entryId)→ snapshot{ value, base, user, revision, writable, persistence }and one write queue shared by every editor of that entry.set/unsetsubmit one operation;mutatesubmits one atomic operation list; staged editors pass the revision they read, and conflicts preserve drafts.ctx.configForms.whileServed(namespaces, register)registers a page only while the host actually serves one of its namespaces ("A deployment that never composed the owner therefore shows no trace of the page").- Validation is two-stage: browser validates against the serialized Config schema, the host validates the complete configuration including non-serializable checks.
Pane contributions (slots). settings.section (a page), settings.plugins.tab (a tab inside Built-in plugins), settings.onboarding (one mounted step at a time), settings.general.item (a row inside General), settings.links.*, settings.header, settings.launcher, plus named surfaces settings.models, settings.account, settings.plugins, settings.pluginInventory, settings.shell, settings.agentLoop, settings.subagent, settings.webSearch, settings.sessionLog, settings.theme, settings.permission, settings.transcript.*, settings.performance.*.
Namespaces seen in the wild: ui-theme (theme + content font size, persisted by the local provider into $DSH_HOME/cordis.patch.yml; remote Web keeps it browser-local), ui-settings (ui-settings.enabled Coding Tools switch), subagent, subagent-model-selection, shell, plus keybindings which are not settings at all (they live in localStorage / userData/keybindings.json). There is no versioned settings-migration system for the settings document itself (only session-format migrations exist); "not discoverable" for a settings schema version field.
6. Design language
All values quoted from dsh-client-ui-theme/lib/client.js (embedded stylesheet bundle: base.css, design-platform.css, corner-shape.css, focus.css, onboarding.css, scrollbar.css, gradient-shadow-text.css, shiki.css) and the CSS-module files under dsh-client-ui-primitives/lib/.
Token layering. Three tiers: --dsw-static-* (raw palette) → --dsw-alias-* (semantic) → --dsw-specific-*, plus --dsh-* (app/layout), --dsl-* (markdown/terminal blocks), --ds-* (motion/fonts). 483 distinct --dsw/--dsh/--ds/--dsl/--shiki tokens are defined in the bundle.
Palette (light / dark are two blocks: body{…} and body[data-ds-dark-theme]{…}). Neutrals are "neutral-bluish": --dsw-static-neutral-bluish-00:#fff, -50:#f9fafb, -75:#f1f3f5, -100:#ebeef2, -150:#e9ecf2, -200:#e1e5ee, -300:#cfd3d6, -400:#adb2b8, -500:#979da6, -600:#81858c, -700:#61666b, -750:#43454a, -800:#353638, -850:#2c2c2e, -875:#232324, -900:#1b1b1c, -950:#151517, -1000:#0f1115. Brand/accent: --dsw-static-deepseek-500:#4176e6 (light) / #4176e6 also --dsw-alias-brand-primary-new-colorprimary-new-color:#4176e6; deepseek ramp -50:#edf3fe, -100:#e4edfd, -200:#d3e2ff, -300:#b7c8fe, -400:#7aaaff, -450:#5686fe, -500:#4176e6, -600:#4868b2, -800:#34415b, -900:#283142. State: green -400:#4ed17e / -500:#22c55e / -900:#233c2c; amber -400:#f7ad31 / -500:#f59e0b; red -400:#f25a5a / -500:#ef4444 / -600:#ec1313; blue -400:#60a5fa / -450:#4d93f8 / -500:#3b82f6 / -600:#2563eb / -900:#0e3074 / -950:#172554.
Surfaces: --dsw-alias-bg-base = neutral-bluish-00 (light) / neutral-bluish-950 (dark); bg-layer-1/2/3 = neutral-bluish-00 (light); masks --dsw-alias-bg-mask-1/2/3 = #0000003d / #0000001f / #0000007a (drop mask #ffffffb3); skeleton #0000000a. Text: --dsw-alias-label-primary = neutral-bluish-1000 / (dark) inverted; -secondary = -700; -tertiary = -600; -caption = -400; -dimmed = -200; -primary-foreground = -00. Borders: --dsw-alias-border-l1:#0000000a, -l2:#0000001a, -l2-darkmode-thin:#0000001a, -l3:#0000001f, -l4:#00000029. Sidebar: --dsw-specific-sidebar-fill: var(--dsw-static-neutral-bluish-50), nav hover -75, active -100, active accent deepseek-100. Tooltip --dsw-alias-tooltip-bg: neutral-bluish-850; toast -800 with -00 label; menu surface #f8f9fa94; hover card #2C2C2E. Diff: added #e6f4e7 / gutter #edf7ed / marker #01a241; deleted #fce6e2 / #fdece9 / #ba2723; --dsw-alias-code-diff-added: green-500-a08 (#22c55e14), deleted red-600-a08 (#ec131314). Shiki token colors are inlined (e.g. --shiki-token-string:#8ce99a, --shiki-token-punctuation:#ced4da, --shiki-token-link:#74c0fc).
Theme mechanism. html { color-scheme } + body[data-ds-dark-theme] attribute; theme ids light / dark / system (THEME_PREFERENCES = ["light","dark","system"]); third-party themes register alias-layer overrides. Content font size is a variable: --dsh-content-font-size (setting range 10–22 px, Only affects conversation content), with --dsh-content-font-delta: calc(var(--dsh-content-font-size,14px) - 14px) driving markdown line-height and secondary size.
Typography.
- UI:
--dsw-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Helvetica Neue", Helvetica, Arial, sans-serif - Brand:
--dsw-font-family-brand: "Montserrat", var(--dsw-font-family)(withbrand-font.cssinui-theme/lib/styles/) - Code:
--ds-font-family-code: "SF Mono", "JetBrains Mono", "Fira Code", Consolas, "Liberation Mono", Menlo, Courier, "PingFang SC", "Microsoft YaHei" - Composite steps:
--dsw-font-base-16: 16px/24px var(--dsw-font-family)(weight 400),--dsw-font-base-strong-16: 500 16px/24px,--dsw-font-l-20: 500 20px/28px,--dsw-font-m-18: 500 16px/28px,--dsw-font-markdown-base: 400 var(--dsh-content-font-size,14px)/calc(24px + var(--dsh-content-font-delta)), markdown strong 600, italic variant,--dsw-font-markdown-code-block: 11px/19px var(--ds-font-family-code); block banner11px/18px. - Component sizes: buttons
font-size: 14px; line-height: 22px; padding: 0 14px; height: 36px(.md) and12px/18px; padding: 0 10px; height: 28px; radius sm(.sm); sidebar--dsh-sidebar-inline-padding: 12px.
Radii / shape. --dsw-radius-xs:4px, -sm:8px, -md:12px, -lg:16px, -xl:20px, -panel:28px. Windows content corner --dsh-windows-content-radius:16px ("only the content area's top-left corner has a 16px radius; the other corners and the internal divider remain square"). Progressive enhancement: @supports (corner-shape:superellipse(1.5)){ :root{--dsw-corner-shape:superellipse(1.5)} *,:before,:after{corner-shape:var(--dsw-corner-shape)} }.
Elevation / shadows. --dsw-shadow-lv1: 0 2px 4px 0 #0000000d, -lv1-blur: 0 4px 12px 0 #00000005, -lv2: 0 4px 12px 0 #00000005, 0 2px 8px 0 #0000000a, -lv3: 0 0 1px 0 #0003, 0 0 4px 0 #00000005, 0 12px 32px 0 #00000014; composed elevations --dsw-elevation-stroke: 0 0 0 .5px var(--dsw-elevation-stroke-color), -soft: stroke, 0 4px 16px 0 #00000008, 0 0 24px 0 #00000008, -panel: stroke, 0 3px 8px 0 #00000008, 0 0 16px 0 #00000005, -prominent: stroke, 0 3px 8px 0 #0000000a, 0 0 20px 0 #0000000d. Borders are hairlines: 0.5px solid var(--dsw-alias-border-l3) on outlined buttons; --dsw-alias-border-l2-darkmode-thin exists precisely so dark mode can thin a stroke.
Motion. --ds-ease-in-out: cubic-bezier(.4, 0, .2, 1); durations --ds-transition-duration: .2s, -fast: .1s, -slow: .3s. Reconnection loader dots advance every 500 ms and an attempt stays visible ≥ 800 ms; the Connected pill fades out over 150 ms; "Dragging has no transition delay"; discrete open/close sets data-animating so the track and the occupant's slide share one duration/easing; fullscreen presentation suppresses transitions; reduced-motion disables sidebar transitions.
Layout metrics.
| Metric | Value | Source |
|---|---|---|
| Sidebar width | clamp 264–420 px, default 280 px, rail 56 px, auto-collapse below 1024 px | ui-layout/lib/client.js (clampWidth(sidebar, 264, 420), sidebar: 280, SIDEBAR_AUTO_COLLAPSE = 1024) |
| Right panel | first open 45 % of frame (RIGHTBAR_DEFAULT_RATIO = .45), capped 70 % (RIGHTBAR_MAX_RATIO = .7), floor 300 px, centre protected at 400 px |
ui-layout |
| Frame clearances | --dsh-frame-top-clearance: 48px, --dsh-frame-overlay-top: calc(var(--dsh-frame-top-clearance) + 20px), --dsh-frame-leading-clearance: 160px, --dsh-frame-chrome-top: var(--dsh-windows-titlebar-height) |
ui-layout |
| Chat content | --dsh-chat-content-width: min(calc(100% - 32px), 920px), user column clamp(680px, …); other literal caps found in the client bundles: max-width: 960px, 843px, 760px, 720px |
ui-conversation, ui-chat |
| Composer | --dsh-composer-card-max-width: calc(var(--dsh-chat-content-width) + 32px) (≈952 px), --dsh-composer-text-max-height: 336px, --dsh-composer-dock-inset: 8px, --dsh-composer-side-clearance: 16px (8 px narrow), --dsh-composer-stack-gap: 6px |
ui-conversation |
| Scrollbars | --dsh-scrollbar-width: 5px | 6px | 9px, session list --dsh-session-list-scrollbar-width: 5px |
primitives / ui-workspace |
| Modal | full-viewport layer z-index: 1000, padding max(24px, var(--dsh-frame-overlay-top,24px)) 24px, dialog min(380px,100%), gap 20px |
Modal.module.css |
| Shortcut dialog | 480 × 600 CSS px; rows 42 px high; settings-control grey key blocks | ui-shortcuts README |
| z-index ladder (observed values) | 0,1,2,5,10,11,15,100,1000,1004,1100 | grep over all CSS/JS |
| macOS chrome | 52 px top strip in the expanded sidebar; caption icon buttons = 16 px glyphs in 28 px circular controls; --dsh-windows-menu-start: 84px collapsed / 48 px expanded |
ui-sidebar README |
| Focus | focus.css (298 B) defines the ring; automatic entry/return focus deliberately omits outlines while Tab/directional navigation keeps visible indicators |
ui-theme, ui-shortcuts |
Icons / assets. No icon-font or third-party icon package: hand-written inline SVGs, named exports like IconPanelLeftOutlineRegular, IconNewChatOutlineRegular (ui-sidebar/lib/client.js). Product mark assets: a fish mark slot + wordmark; ui-brand-official swaps in the DeepSeek Harness mark for an official build; the conversation hero always uses the animated fish. Frontend ships favicon.svg / favicon-dark.svg, manifest.webmanifest, and KaTeX woff/woff2/ttf subsets.
7. Strip list vs keep list
| Capability | Verdict | Why / replacement |
|---|---|---|
Profile/bundle boot model (dsh.profile.bundles + patch layers, $DSH_HOME/cordis.patch.yml) |
KEEP | It is the extension spine; Strata needs one strata profile, not a cloud account. Simplify to 2–3 bundles. |
Slot/factory client composition (ui-slots + ui-renderer) |
KEEP | Lets Models / Engine / Serving / Monitor be separate panes without touching the shell. This is the single most reusable idea in the codebase. |
dsh.client + /plugins + __DSH_BOOT__ boot graph |
KEEP | Free plugin discovery and lazy bundles; Strata can serve one prebuilt graph. |
Web-first host (host-webserver + host-frontend-static + web-app flags) |
KEEP | Exactly Strata's deployment shape; keep --host/--port/--no-open and the loopback default, add an explicit LAN opt-in later. |
| Electron desktop shell | DEFER | Large surface (updater, welcome, mandatory-update, platform login, tray). Strata is web-first; ship strata serve and let the browser be the app. |
| Sign-in / accounts / DeepSeek cloud API | STRIP | Remove dsh-llm-deepseek*, dsh-api-account-controller, ui-settings-account, dsh-deepseek-account. Replace with the local engine as the only provider. |
| Session-log upload + OTel telemetry + product analytics | STRIP | Remove dsh-session-log-deepseek, dsh-session-telemetry*, dsh-host-product-telemetry-otel, dsh-client-product-analytics, ui-settings-session-log. Strata's Monitor dashboard replaces the visibility need locally. |
| Subagents / workflows / agent teams / schedules | STRIP | Remove dsh-subagent*, ui-subagent, ui-workflow-run, dsh-experimental-agent-team*, dsh-schedule, ui-schedule. A single local model cannot serve parallel agents usefully. |
Provider abstraction ctx.llm + chunk protocol (finish, BlockAssembler) |
KEEP | This is the seam Strata plugs the local engine into; keeping it means the loop, titles and compaction all work unchanged. |
dsh-llm-pi-ai "custom route" config (api: openai-completions, baseURL, models[]) |
KEEP (repurpose) | It already reaches llama.cpp/MLX-style servers. Strata's Engine/Models tabs should write this config shape. |
Settings model (ctx.settings forms + configForms handles + revision-checked writes) |
KEEP | Schema-driven panes, atomic updates, conflict protection — exactly what Engine tuning needs (beginner/expert). |
Credentials seam (dsh-credentials) |
DEFER | A local engine needs no API key; keep the seam for remote fallback but ship without a secrets UI. |
| Permission presets (Read Only / Workspace Write / Full access / Auto review) + approvals | KEEP | Local models still write files; the Enter/Escape approval takeover is cheap and high-trust. Drop "Auto review" (it is an LLM call). |
Capability gating (ui-settings.enabled Coding Tools switch) |
KEEP | Free simple/expert mode switch for Strata; extend it to gate Engine-expert controls. |
| Context metering + session stats + Trajectory | KEEP (adapt) | Essential for small local context windows; Trajectory's token/timing inspector becomes the Monitor foundation. |
Compaction (/compact, dsh-compaction-basic) |
KEEP | Non-negotiable with 8–32 k local contexts; keep /compact and the "Compacting context…" affordances. |
Artifacts/office skills, libreoffice-kit, PTC runtime, MCP, web search/fetch |
DEFER | Large optional trees; keep the skill loader (dsh-skill-filesystem, /skill) and drop the bundled office/search plugins initially. |
| HMR of client plugins | DEFER | Nice for plugin authors; adds a websocket path. Keep the boot graph, enable HMR behind a dev flag. |
| Session persistence (JSONL + zstd frames + format migrations + FTS5 search) | KEEP (simplify) | Durable sessions are the product; keep append-only JSONL, one format version, and FTS-less listing at first. |
| Command palette | ADD (gap) | DSH has none; Strata should add one — the registry (ctx.shortcuts catalog with labels, aliases, keys) already exists to populate it. |
| OpenAI-compatible serving (Serving tab + request log) | ADD (net-new) | Nothing in the packaged code serves /v1/* outbound; only pi-ai consumes it. Build the server + log. |
| First-run hardware onboarding wizard | ADD (net-new) | The onboarding ledger (settings.onboarding, sequential, one step mounted) is the ready-made container. |
| Engine tuning beginner/expert | ADD | Render as a settings.section page plus a Start-page card; reuse the staged-draft + Save + "Overridden" pattern from ui-settings-shell. |
| Monitor dashboard | ADD | Reuse dsh-session-stats (turns/steps/TTFT/decode), context-occupancy ring, and the Trajectory timing overview as the data layer. |
8. Local-engine integration points
Where the provider abstraction lives
dsh-llm is the only supported path into a model: "Any composition that calls a model provider — an agent loop, a session-title generator, a compaction summarizer — streams its requests through this service. Mount it together with at least one provider adapter; the service itself has no configuration and no provider wire code." Adapters: dsh-llm-deepseek (own Messages transport + capabilities), dsh-llm-deepseek-api-key / -account (auth + model discovery), dsh-llm-pi-ai (routes through @earendil-works/pi-ai — "design-verification twin of dsh-llm-deepseek"), dsh-llm-retry (retries at the agent's failed-step extension point), dsh-deepseek-llm-api-extensions (provider-specific top-level request fields).
Interface (from dsh-llm/README.md):
for await (const chunk of ctx.llm.stream({
provider: 'deepseek-official',
model: 'deepseek-v4-flash',
messages: [{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }],
})) { /* block-start, text-delta, …, usage, finish */ }
ctx.llm.listProviders()→ registered routes in registration order; duplicate route registration failsDUPLICATE_ADAPTER.ctx.llm.listModels()is required for GUI selection ("The GUI requires catalog membership for selection and submission"; base returns an empty list).- Resolution: per-model context window, output default, reasoning efforts, input modalities, system-prompt update mode (
'in-history'when any-positionsystemmessage is effective);normalizeModelInforejects anything else withINVALID_MODEL_INFO. - Reasoning effort is validated against the exact model before any provider I/O; an adapter output cap is materialized when the request omits one.
- Every stream ends in exactly one terminal
finishchunk:{kind:'error', failure}or{kind:'aborted', failure}. Stable failure codes:NO_ADAPTER,MISSING_CREDENTIAL,INVALID_CREDENTIAL,AUTH,RATE_LIMIT,CONTEXT_WINDOW_EXCEEDED,QUOTA,ACCOUNT_QUOTA,DISCOVERY_FAILED,IMAGE_OFFLOAD_REQUIRED. "Consumers route on the code, never on message text." - Compaction of the stream:
BlockAssembler/AssistantStreamAccumulator, timestamps + token boundaries preserved in one durable attempt settlement.
Wire protocol actually spoken
dsh-llm-pi-ai → @earendil-works/pi-ai → OpenAI Chat Completions via the openai SDK client:
dsh/node_modules/@earendil-works/pi-ai/dist/api/openai-completions.js:557
return new OpenAI({ apiKey, baseURL: model.baseUrl, dangerouslyAllowBrowser: true, defaultHeaders: headers … })
…
const { data: openaiStream, response } = await retryProviderRequest(
() => client.chat.completions.create(params, requestOptions).withResponse(), …)
Request shaping observed in the same file: params.stream_options = { include_usage: true } (line 582), params.max_completion_tokens = options.maxTokens (592), reasoning/thinking compatibility switches thinkingFormat ∈ zai | qwen | qwen-chat-template | chat-template | baseten | deepseek | openrouter | ant-ling | together | string-thinking (619–712), instruction role model.reasoning && compat.supportsDeveloperRole ? "developer" : "system" (896).
Stream parsing (same file): choice.delta.tool_calls[] → { id, function.name, function.arguments } accumulated with partialArgs and re-parsed per delta via parseStreamingJson (425–455); reasoning read from ["reasoning_content","reasoning","reasoning_text"], first non-empty wins — the comment names llama.cpp explicitly: "Some endpoints return reasoning in reasoning_content (llama.cpp), or reasoning (other openai compatible endpoints)" (395–399). Usage mapping (1167–1183): reads usage.cached_tokens (Kimi-style top-level) as well as the OpenAI nested form, and completion_tokens_details.reasoning_tokens; "OpenAI completion_tokens already includes reasoning_tokens" — i.e. it does not double-count.
Model discovery (dsh-llm-pi-ai/lib/index.js:2130–2180): OpenAI protocols list at GET {baseURL}/models with bearer auth; Anthropic Messages at {root}/v1/models with x-api-key + anthropic-version. Response capped at 4 MiB; reads data[] and "the enriched models map some compatible gateways expose"; any other protocol reports it cannot be interrogated so the UI falls back to hand-entry.
Tool-call format
Tools are declared with JSON-schema-style { name, description, parameters } (pi-ai passes an OpenAI tools array; a comment notes tools must be present "when messages include tool_calls or tool role messages" — line 22, needed by LiteLLM/Anthropic proxies). Calls come back as streaming tool_calls deltas (id → name → partial arguments). Results are returned as role: "tool" messages correlated by tool_call_id, with assistant replay metadata kept on the durable messages. DSH-side, dsh-system-prompt supplies "one ordered system prompt and the available tool schemas for each model step"; workspace guidance comes from dsh-agent-instructions (user-global + project AGENTS.md); history pressure is handled by dsh-compaction (/compact) plus dsh-compaction-image-offload.
Model-selection flow
- Adapters register routes and advertise models; configured-provider adapters declare a settings namespace so "configuration surfaces can activate dormant providers and edit connection facts without a restart".
dsh-agent-default-modelanswers exactly one question for fresh agents —currentSelection()→{provider, model, reasoningEffort?};saveSelection()persists it via the config editor (a no-op without one). Config shape:{ provider: required, model: required, reasoningEffort?: optional }.- Selection UI:
/modelpopup and the composer's model control both show "the same provider-grouped choices, and the selected model determines the available effort names and default" (dsh-client-ui-model-selection); page copy "Select the model for this conversation", "Model and reasoning effort", "This model provides no reasoning effort levels." - The chosen selection enters the session and each request names
provider+model+ optionalreasoningEffort; capability resolution (context window, output cap, modalities, reasoning efforts) happens inctx.llmbefore I/O. dsh-client-ui-settings-modelsis where a human declares a route by hand: "Add model provider", "Custom model API", "API protocol", "Base URL", "API key", "Display name", "Context window", "Add model".
Checklist: what an OpenAI-compatible local server must satisfy for Strata
| Requirement | Detail | Why (from DSH code) |
|---|---|---|
POST {baseURL}/chat/completions |
OpenAI Chat Completions schema; model, messages[], tools[], max_tokens/max_completion_tokens, stream: true |
openai-completions.js:557 uses the openai SDK with baseURL |
GET {baseURL}/models |
{"data":[{"id":…,"name"?,"context_window"?,"max_tokens"?}]}; extra models map tolerated; ≤4 MiB |
pi-ai discovery LISTABLE_PROTOCOLS |
| SSE streaming | text/event-stream, one JSON object per data: line, terminating data: [DONE] |
pi-ai reads openaiStream async-iterable |
stream_options.include_usage |
Must honor it and emit a final chunk carrying usage |
params.stream_options = { include_usage: true } |
| Usage fields | usage.prompt_tokens, usage.completion_tokens, usage.total_tokens, optional prompt_tokens_details.cached_tokens and completion_tokens_details.reasoning_tokens; completion_tokens must already include reasoning tokens |
usage mapping 1167–1183 |
| Tool-call deltas | choices[0].delta.tool_calls[] with index, id, type:"function", function.name, function.arguments fragments (concatenated, JSON parsed incrementally) |
ensureToolCallBlock + partialArgs |
| Reasoning channel | Emit thinking text in reasoning_content (llama.cpp convention) — reasoning and reasoning_text also accepted, first non-empty wins |
395–399 |
| Tool-call correlation | Accept role:"tool" messages with tool_call_id, and tolerate tools being present even when only tool history exists |
line 22 comment |
| Error shape | HTTP error + JSON body the adapter can classify into AUTH / RATE_LIMIT / CONTEXT_WINDOW_EXCEEDED / QUOTA; never rely on message text |
failure-code contract |
| Capability metadata | Local model must know its own context window; otherwise defaultContextWindow: 262,144 / defaultMaxTokens: 32,768 fallbacks apply, which are far too large for local models — Strata must set these per model |
dsh-llm-pi-ai config table |
| Shims likely needed | (a) reasoning vs reasoning_content choice, (b) effort mapping into chat-template thinking flags, (c) prompt-cache fields (openai-prompt-cache.js) are OpenAI-specific, (d) image content parts must be plain base64 data URLs, (e) systemPromptUpdate: 'in-history' only if the engine honors mid-history system messages |
adapter compat switches |
| Config entry Strata should write | providers.local: { displayName: "Local", api: "openai-completions", baseURL: "http://127.0.0.1:8080/v1", models: [{ id, name, contextWindow, maxTokens, reasoningEfforts }] } |
dsh-llm-pi-ai provider dictionary |
Not discoverable in the packaged code: an outbound OpenAI-compatible serving endpoint (nothing registers /v1/chat/completions as a route; dsh-host-webserver consumers are file/UI routes only), any GPU/hardware detection, any engine-process supervision (llama.cpp/MLX lifecycle), and any request-log store. All four are net-new Strata surfaces.
Appendix — evidence shortcuts
- Host/boot:
dsh/README.md,dsh-base/README.md,dsh-web-app/{README.md,lib/startup.js,lib/index.js},dsh-host-webserver/README.md+lib/index.js,dsh-host-frontend-static/README.md,dsh-client-modules/README.md+lib/index.js,dsh-desktop-host/{package.json,lib/cli.js},lib/main.js:3656-3730,dsh-web-frontend/{package.json,dist/index.html,dist/assets/index-5SrrfWpU.js}. - IA/strings: per-package
lib/client.jsliterals (e.g.ui-workspace,ui-settings-*,ui-shortcuts,ui-chat,ui-conversation,ui-trajectory,ui-deliverables), plus the slot-key census (231 keys) gathered acrossdsh-client-*/lib/client.js. - Design tokens:
dsh-client-ui-theme/lib/client.js(embeddeddesign-platform.css+ friends),dsh-client-ui-primitives/lib/*.module.css,dsh-web-frontend/dist/assets/*.css. - Engine:
dsh-llm/README.md,dsh-llm-pi-ai/{README.md,lib/index.js},dsh-agent-default-model/README.md,dsh-settings/README.md,@earendil-works/pi-ai/dist/api/openai-completions.js.