DS4Server/PLAN.md

DS4Server implementation plan

Bundle/application identifier: DS4Server.rfc1437.de

DS4Server is the native macOS Rust/Iced application counterpart to ../ds4. The reference implementation remains normative: ds4.c/ds4.h define model and session behavior, ds4_server.c defines the HTTP API, and ds4_agent.c defines local-agent behavior and tools. Parity means matching observable behavior and fixtures, not merely exposing similar controls. All planned execution targets one self-contained Mac.

Current state

• The macOS application shell, projects, session rename/pin/archive/delete, SQLite transcripts, model preferences and downloads, Stats dashboard, native Application/Edit/Window menu integration, development bundle, and shared lazy model lifecycle are implemented.
• DeepSeek V4 Flash runs through the Rust/Metal executor with full configured context, ratio-4 sparse attention, cold and resumed batched prefill, prefix continuation, durable KV checkpoints, cancellation, and idle unload.
• The configurable localhost endpoint implements all ds4_server.c routes, streaming and non-streaming envelopes, model aliases, CORS, tool replay and continuation, malformed DSML recovery, transient prefix-aware KV reuse, disconnect/queue cancellation, and shared model scheduling. The full automated C/Rust differential corpus remains open.
• Local sessions persist user, assistant, reasoning, and tool roles. The agent executes the complete ds4_agent.c starting tool set and reinjects the same model-specific tool contract when sessions are opened or continued.
• The remaining baseline gaps are long-running agent behavior and tool safety. SSD streaming, speculative decoding, steering, GLM 5.2 execution, and DeepSeek V4 Pro execution are not implemented in the Rust executor. Some related catalog, validation, and preference plumbing already exists but must not be treated as runtime support.

Delivery order

1. Next: long-running agent stability and remaining ds4_agent.c parity.
2. Tool hardening, approvals, and productive tool presentation.
3. Remaining DS4 execution technology, starting with SSD streaming, then speculative decoding and the other Metal/runtime parity work.
4. Additional model execution: GLM 5.2 and DeepSeek V4 Pro.
5. Product completion, exhaustive parity verification, and distribution.
6. Optional extensions: Dev Brain and A2UI.

1. Next — long-running agent stability and ds4_agent.c parity

Goal: a local agent session must be able to run long read/edit/test loops, cross the context limit repeatedly, survive interruption or relaunch, and continue with the same durable task state as ds4-agent.

Context compaction

• Port the reference soft trigger: compact before a user turn or tool continuation at 85% context use, or when at most 8192 tokens remain, with the free-token threshold capped to one eighth of small contexts.
• Port the hard trigger: before appending a tool result that would leave insufficient answer room, compact once and retry. If it still does not fit, return a bounded tool error that tells the model to request less output.
• Use the live model to generate an internal durable task-state summary. The prompt and generated summary are private compaction work, never ordinary user/assistant messages, and may not execute tools or retain thinking/DSML control markup.
• Preserve goals, constraints, files touched, commands and important results, decisions, known failures, and next steps. Prefer reloadable paths, ranges, and commands over copying bulky data into the summary.
• Rebuild the model context exactly as the reference does: current system/tool contract, durable summary, then a recent verbatim tail. Keep up to 10% of the configured context as the tail, capped at 50000 tokens, and align it to a user-turn boundary when possible.
• Generate at most the reference summary budget, stop at model control or tool markers, and never let the private compaction exchange become the reusable session prefix.

Durable transition and recovery

• Treat transcript replacement and the new KV checkpoint as one logical transition. Persist the compacted semantic transcript and checkpoint metadata only after the rebuilt prefix is valid.
• On cancellation, summary failure, prefill failure, or application exit, keep the previous durable transcript, invalidate any KV state contaminated by the private compaction prompt, and make the next turn rebuild safely.
• Reopen a compacted session with the same summary and recent verbatim turns. If its checkpoint is absent or incompatible, rebuild it from persisted messages without changing the visible conversation.
• Preserve relevant live tool state across compaction. In particular, append a compact observation for running shell jobs so the model can still inspect or stop them after the context rebuild.
• Add a user-visible action equivalent to /compact, plus the reference strip/rebuild behavior: discard a session KV payload without discarding its transcript, then rebuild on the next use.
• Bind checkpoint compatibility to the model identity, quantization, context, rendered transcript, and payload ABI. A model/configuration change must rebuild rather than reuse an invalid prefix.

Long-turn behavior

• Accept user input while an assistant/tool loop is active. Queue it visibly and inject it after the current tool result, before the next assistant continuation, matching ds4_agent.c instead of starting a competing turn.
• Preserve the reference rule that there is no arbitrary maximum tool-round count. Completion, Stop, context pressure, or a real error ends the loop.
• Match the reference date/time context injection and periodic system/tool prompt reminder so long or reopened sessions do not drift away from the tool contract.
• Keep Stop cooperative across summarization, compacted-prefix prefill, generation, and active tool work. A stop must always leave a transcript that can be reopened.

Presentation and verification

• Show explicit Compacting, rebuilding/prefill, queued-input, stopped, and failed states without blocking the Iced event loop. Keep the compacted summary inspectable without presenting the private prompt as user history.
• Add focused tests for soft and hard triggers, tail selection, tool-result retry, cancellation rollback, checkpoint invalidation, queued input between tool rounds, running-job preservation, and reopen after compaction.
• Add a reference fixture that runs a long tool loop through compaction, saves, relaunches, and continues without losing the active task.

Exit criterion: repeat the reference ds4-agent long-context scenarios, including compaction forced by a large tool result, stop during compaction, and restart after a successful compaction. The same task state, recent turns, tool contract, and running-job awareness must remain available.

2. Tool hardening and safety

Goal: make the existing tool set safe and clear enough for productive daily use without weakening its ability to inspect, edit, build, and test a project.

• Keep file tools strictly inside the selected project after canonicalization, including symlinks and nonexistent write targets. Boundary escapes are rejected, not approved as exceptions.
• Centralize tool approval. Reuse the existing visible-browser approval path for actions that require consent instead of adding tool-specific modal systems.
• Require confirmation before destructive shell commands or commands that affect state outside the project, elevate privileges, launch external apps, or create unrequested network side effects. Show the exact command and working directory; support Allow once and Deny. Do not persist broad trust silently.
• Define the shell environment deliberately so application credentials and unrelated secrets are not exposed accidentally. Preserve the minimum normal development environment needed for project commands.
• Render streamed tool calls as compact cards with their real lifecycle: parsing, awaiting approval, queued, running, completed, failed, or stopped. Show bounded parameters and results, provide copy/open actions where useful, and never display raw DSML as ordinary assistant prose.
• Keep background shell jobs cancellable and observable through app stop, session switches, compaction, and application shutdown. Retain bounded output files only as long as needed and report cleanup failures.
• Continue enforcing context-aware read/search/bash result limits. Oversized output must remain available through continuation or a file reference rather than being inserted wholesale into the prompt.
• Test project-boundary and symlink escapes, destructive-command approval, denial and cancellation, browser approval, output bounding, and session switching with a live job.

Exit criterion: use the agent for a real inspect/edit/test cycle while every side effect is visible, risky actions require consent, Stop works at every stage, and no file tool can escape the selected project.

3. DS4 execution technology parity

Goal: finish the model-independent Metal/runtime capabilities in ds4.c before adding larger model families. Every capability must be shared by local chat and the HTTP endpoint through the single process-wide model owner.

3.1 SSD streaming — first runtime priority

SSD streaming is the capacity prerequisite for larger models and therefore comes before GLM 5.2 and DeepSeek V4 Pro execution.

• Keep non-routed weights resident while loading routed MoE experts from the GGUF into a bounded in-memory cache on demand.
• Port DS4's automatic cache sizing from the recommended Metal working set, non-routed weights, KV/context requirements, graph scratch, and routed-prefill headroom. Preserve explicit expert-count and GiB-budget modes.
• Port cold start, hot-expert preload, explicit preload count, full resident layer policy, cache eviction, and the overlapped prefill/decode loading path.
• Keep inference correct under cache misses, short reads, cancellation, memory pressure, unload, and model replacement. A streaming failure must produce a bounded request error, not partial model state.
• Report resident bytes, cache capacity, hit/miss and load rates, SSD bytes and latency, preload progress, and memory-pressure decisions in Stats.
• First prove resident-versus-streaming token parity on DeepSeek V4 Flash. Keep the cache and I/O layer model-aware so later GLM/Pro milestones add policy and graph support rather than a second streaming subsystem.

3.2 Speculative decoding: legacy MTP and DSpark

• Load and validate the optional Flash legacy-MTP or DSpark support GGUF without treating either as a standalone model. Preserve exact support-kind and target compatibility checks.
• Port draft generation, confidence/margin pruning, target-model verification, accepted-prefix commit, rejected-suffix rollback/replay, cache counters, and cancellation boundaries. The target model always owns the output stream.
• Honor MTP draft depth/margin and DSpark confidence/strict settings. Match the reference rules for greedy, sampled, and quality modes rather than applying speculation where DS4 falls back to target-only decode.
• Match current DS4 compatibility between SSD streaming and DSpark; remove temporary Rust-only exclusions where the reference supports the combination.
• Expose accepted/drafted token counts, acceptance rate, verifier cost, and effective speedup in Stats. Do not call the feature complete merely because it produces correct tokens; it must also preserve checkpoints, tools, streaming responses, usage accounting, and Stop behavior.
• GLM's in-model MTP path belongs to the GLM milestone, but it should reuse the verifier/session machinery established here.

3.3 Remaining Metal execution controls

• Port directional steering files and exact FFN/attention application, including DS4 defaults, validation, zero-scale behavior, and checkpoint/model identity effects.
• Audit every accepted execution preference against the Rust executor. Power, prefill chunking, quality/exact kernels, warm weights, simulated memory, and expert profiling must either affect execution as DS4 defines or be disabled with a clear explanation; persisted no-op settings are not parity.
• Add hardware-backed token/activation fixtures for each mode and keep the ordinary resident Flash path unchanged when optional features are off.

3.4 Single-machine server batching

• Port DS4's resident multi-session batching and server scheduling only after the serialized path remains the correctness oracle. Preserve per-request cancellation, finish reasons, usage, and KV ownership while batching prefill or decode work.
• Keep all scheduling, model state, KV state, and request handling within the local process. Networked execution and non-Metal backends are outside the product scope.

Exit criterion: DeepSeek V4 Flash matches DS4 token output and lifecycle in resident, SSD-streamed, MTP, DSpark, steering, and batched-server configurations, with optional modes off producing the same baseline behavior as today.

4. Additional model execution

Start these only after the shared capacity and execution technology above is stable. Catalog entries, settings, tokenizer work, or GGUF validation alone do not make a model selectable for inference.

GLM 5.2

• Port the GLM DSA/MLA graph, dense-cache behavior, model-specific tensor and quantization paths, sampling defaults, reasoning controls, prompt rendering, and stop tokens.
• Use the already defined GLM tool syntax through the same durable local-agent loop and expose identical behavior through every HTTP route.
• Port GLM SSD streaming policy, resident full-layer selection, and the MTP block stored in the main GGUF. Respect GLM restrictions on power, prefill chunking, steering, and external support models.
• Validate resident and streamed token output against DS4 fixtures before the Model Manager advertises GLM as runnable.

DeepSeek V4 Pro

• Generalize the Flash graph only where Pro's dimensions, layers, routed experts, quantization layouts, or output path actually differ.
• Support resident and SSD-streamed single-machine configurations with explicit memory admission checks. Never begin a load that cannot leave room for the configured KV/context and graph working set.
• Match Pro prompt, sampling, checkpoint, HTTP, and agent behavior. Preserve the reference compatibility matrix for MTP/DSpark rather than assuming Flash support artifacts work with Pro.
• Validate supported single-file Q2/Q4 configurations against DS4 fixtures before advertising them as runnable.

Exit criterion: each advertised model passes the same local-agent, checkpoint, HTTP, SSD-capacity, cancellation, and deterministic token-output matrix as DeepSeek V4 Flash.

5. Product completion and verification

Reference parity and regression coverage

• Complete the automated black-box C/Rust corpus for Models, Messages, Chat Completions, Responses, Completions, and OPTIONS in streaming and non-streaming modes. Cover aliases/defaults, malformed input, context limits, tools, reasoning, cache reuse, disconnects, queueing, CORS, errors, usage, and finish reasons.
• Add every new agent/runtime/model capability to both local and endpoint regression coverage. HTTP conversations remain client-owned and may persist only opaque content-addressed KV entries, never application transcripts.
• Reuse DS4 prompt, sampling, KV, server, agent, and hardware fixtures. Keep formatting, Clippy, bundle, and unit tests as commit gates; run hardware matrices only where the required GGUF and machine are available.

macOS product and distribution

• Finish the remaining native menu and text behavior: functional File/View/Help actions, dynamic enabled state, undo/redo parity, and selectable/copyable transcript text.
• Finish session/model binding and recovery surfaces needed to explain why a checkpoint is reused or rebuilt. Keep archive as metadata-only and never delete project contents.
• Add production signing, hardened runtime, required entitlements, notarization, update delivery, and release automation. Preserve all upstream DwarfStar/llama.cpp notices for adapted code and kernels.

Exit criterion: a notarized build can be installed on a clean supported Mac, run the full local-agent and endpoint smoke matrix, restart into its previous sessions, and update without losing projects, transcripts, models, or KV data.

6. Optional future extensions

These are not DS4 baseline parity and must not delay the milestones above.

Dev Brain

• Let the user opt into one existing Obsidian vault through a native folder picker and persist a security-scoped bookmark for sandboxed restart access.
• Add one project-independent tool with bounded search, read, and create/append operations for Markdown notes. Return vault-relative citations and exclude .obsidian, hidden files, deletion, and arbitrary overwrite.
• Reuse the existing file/search implementation with a separate explicit vault boundary. No vault means no tool and no effect on ordinary sessions.

Exit criterion: store a memory in one project, restart, and retrieve it with a vault-relative citation from another project without granting broader disk access.

A2UI local-chat surfaces

• After the ordinary tool UI is stable, use ../bDS2 as the reference for typed cards, charts, forms, lists, metrics, mind maps, tables, and tabs.
• Validate and persist versioned structured payloads with their messages. Render with native Iced/SVG primitives; reject model-authored HTML, JavaScript, styles, file URLs, and arbitrary commands.
• Keep A2UI local-chat-only until a real endpoint client requires a compatible protocol. All mutating actions continue through the normal approval path.

Exit criterion: supported surfaces render accessibly, malformed payloads fall back safely, interactions are validated, and the same surfaces rehydrate after restart.