# DS4Server

DS4Server is a native macOS application for running DwarfStar models as a local
coding agent and as a localhost inference server. The inference engine, model
lifecycle, agent loop, and application UI are implemented in Rust with Iced;
the Metal kernels and small native integration layers are adapted from
[DwarfStar (`ds4`)](https://github.com/antirez/ds4).

## Capabilities

- **Project-based coding chat.** Add local project folders, keep multiple
  persistent sessions per project, and rename, retitle, pin, archive, compact,
  rebuild, or delete sessions. Chats stream Markdown, reasoning, tool activity,
  context use, and generation speed.
- **Local coding tools.** The agent can read, search, list, write, and edit
  project files; run and monitor asynchronous shell commands; search Google;
  and visit rendered web pages. File access is confined to the project, output
  is bounded, and risky shell or visible-browser actions require approval.
- **Long-running sessions.** Transcripts and summaries are stored in SQLite.
  Automatic and manual context compaction preserve the complete visible chat,
  while durable KV checkpoints make follow-up turns and relaunches resumable.
- **Native Metal inference.** DeepSeek V4 Flash, DeepSeek V4 Pro, and GLM 5.2
  run through model-specific Rust/Metal executors with long-context prefill,
  sampling, cancellation, idle unload, and a bounded resident session pool.
  Supported acceleration includes SSD expert streaming, DeepSeek legacy MTP,
  DSpark, GLM MTP, directional steering, and model-specific memory admission.
- **Local HTTP APIs.** A configurable listener on `127.0.0.1:4000` exposes
  Models, Chat Completions, Completions, Anthropic Messages, and Responses APIs
  with streaming, tool calls, usage accounting, cancellation, and prefix-aware
  KV reuse. Endpoint conversations remain client-owned and are not added to
  project history.
- **Model and runtime management.** Model Manager downloads, resumes, verifies,
  and deletes supported GGUF artifacts with byte progress, speed, and ETA.
  Preferences cover generation, runtime, SSD, speculative decoding, steering,
  KV storage, the local endpoint, and idle unload. The Stats view reports model,
  cache, SSD, speculative, session, and HTTP activity.

Projects, sessions, and transcripts use SQLite. Settings use a compact YAML file
that contains only values changed from their defaults and can also be edited by
hand.

## A2UI widgets

DS4Server renders A2UI v1.0 surfaces with these widgets:

- **Content:** Markdown text, images (including avatars), icons, video and audio
  players, and dividers.
- **Layout:** rows, columns, lists, cards, modals, and tabs.
- **Controls:** buttons, text fields, checkboxes, sliders, date/time inputs, and
  choice pickers.
- **Research:** bar, line, area, stacked-bar, pie, and donut charts; tables,
  metrics, timelines, maps, mind maps, and forms.

Video posters render in the surface; video and audio playback uses native
macOS AVKit player windows with standard transport, volume, and fullscreen
controls.

The newest A2UI surface is pinned above the transcript in a default 50/50
workspace split. Dismissing it requires confirmation and records a durable
boundary in the chat database, so reopening the session restores only the
newest surface created after the last dismissal. Left and right arrow buttons
reconstruct earlier and later read-only surface epochs from the recorded A2UI
protocol calls; model updates remain routed only to the current surface.

### Live A2UI validation

With DS4Server running and its local endpoint enabled, run the opt-in model
validation suite with:

```sh
cargo run --release -- validate-a2ui
```

It sends natural-language chart, form, choice, and full-composition prompts
through the current A2UI tool description, then replays every returned protocol
message through the real catalog and component-graph validators. Use `--case
pie-natural`, `--case composed-basics`, `--attempts 3`, `--model MODEL_ID`, or
`--endpoint URL` to narrow or repeat runs. This slow, model-dependent suite is
intentionally separate from `cargo test`.

## Build and run

DS4Server targets macOS 13 or newer and requires Rust 1.97 plus
`cargo-packager` 0.11.8.

```sh
cargo install cargo-packager --locked --version 0.11.8
make bundle
open target/release/DS4Server.app
```

## Application data

```text
~/Library/Application Support/de.rfc1437.ds4server/data.sqlite3
~/Library/Application Support/de.rfc1437.ds4server/config.yaml
~/Library/Application Support/de.rfc1437.ds4server/kv-cache/
```

Deleting a project or session removes DS4Server metadata and its associated
checkpoint; it never deletes the referenced project directory. See
[PLAN.md](PLAN.md) for the remaining implementation work.

The adapted Metal and browser sources retain their upstream notices in
[`native/metal/LICENSE`](native/metal/LICENSE) and
[`native/web/LICENSE`](native/web/LICENSE).
