Skip to content

DESIGN.md

Latest commit

 

History

History
156 lines (123 loc) · 7.26 KB

DESIGN.md

File metadata and controls

156 lines (123 loc) · 7.26 KB
Raw

Design notes

This document explains how LOOPScope is built, which trade-offs the views make, and where to change things. The user-facing manual is README.md (Chinese) and README.en.md (English).

1. Package shape

LOOPScope is one DeepSeek Harness bundle with two faces:

package.json          dsh.bundle.patch + dsh.client.platform
cordis.patch.yml      one Host row: id=loopscope, name=dsh-loopscope
lib/host.js           Node loader entry (no-op plugin)
lib/client.js         browser artifact in the client-modules closure-factory format

The Host row exists only so the web client's module scanner discovers the package: dsh-client-modules enumerates live Loader entries whose package declares dsh.client, serves each exports["./client"] artifact, and composes window.__DSH_BOOT__. All behavior is in the browser bundle; there is no Host RPC, storage, or background work.

scripts/build.mjs produces the browser artifact:

  1. esbuild bundles src/client/index.ts as CommonJS with react and react/jsx-runtime external.

  2. the output is wrapped in

    window.__ModuleLoader__.load({ id: 'dsh-loopscope', factory: (require) => { ... } })

    which is exactly what the client loader expects (the injected require resolves the frozen platform module table).

  3. the build fails if the bundle requires anything besides those platform modules — the product's client packages may not runtime-import one another.

The plugin exports inject = ['slots', 'sessions', 'sidebarRightTabs', 'sidebarRight', 'locale']; Cordis waits for those services, so activation order is not a concern.

2. Data path

Session durable events (Host log)
  → client Session event window  (ctx.sessions.binding(id).eventSource)
  → buildModel(entries)          (src/client/model.ts)
  → views: duration bars / timeline / LOOP cards
  → bottom inspector            (selected element)

The model is a pure, memoized fold over the event window. It does not page history by itself; the panel offers “load earlier history” when the window reports hasMore.

Parsed event families and what they contribute:

Event Contribution
turn/start, turn/end turn boundaries and end reason
step/start, step/end one loop (one model request + its tools)
user/message the turn's prompt
system/message, developer/message prompt length, runtime injections (tool registry updates)
request/header dispatch time, route, tool roster, header reason
request/context context window, system-prompt update policy
assistant/message settlement time, usage, compact stream (first token, generation window)
assistant/attempt, llm/retry failed attempts and retry markers
tool/call, tool/result tool span, arguments, result, error
job/registered, job/settled precise async finish time
approval/asked, approval/decided approval gate wait
workspace/changes, deliverables/presented, team/task, team/member, subagent/catalog developer-signal badges attributed to the running loop

3. The three views and their trade-off

The same model is rendered three ways because no single chart answers both "when" and "what":

  • Duration bars (default). Each row starts at the left edge; length is the activity's duration relative to the P90 of settled activity. Rationale: an agent Session with 150 loops is minutes long and seconds-wide per bar; a true time axis turns every bar into a hairline in a narrow sidebar. P90 instead of max keeps one long approval or command from flattening the rest; outliers clamp.
  • Timeline. Real wall-clock positions with idle gaps over 4 s collapsed, so waiting cannot squeeze the work. Zoom and follow-latest are available.
  • LOOP. One card per loop: a four-phase SVG ring (context, decision, act, observe) sized by phase duration, with chips and tool chips that select elements. It answers "what did this iteration do and what did the model see" rather than "when". The ring gives context a minimum visible share because pre-dispatch preparation is usually milliseconds.

Selection is a plain value (src/client/selection.ts) so the inspector can be a pure lookup over the model: phase, conversation, tool, request, turn, approval.

4. LOOP phases

requestPhases() splits one loop:

  • context: step start → request header (preparation)
  • decision: header → first tool start or settlement (model call)
  • act: first tool start → last tool end
  • observe: max(last tool end, settlement) → step end

A loop without tools has a zero-length act; the ring skips zero-length arcs.

5. State and animation

  • The panel keeps only presentation state: selected element, collapsed turns, filter toggles, axis mode, zoom, follow, playback. Model data is derived.
  • Playback advances selection through loops on a 1.4 s interval. The interval is keyed on playing only and reads the latest loop list through a ref: a live Session rebuilds the model every second, and a dependency on the model would reset the timer forever.
  • Motion is CSS only: marching-ants connector, pulsing running nodes, a spinning ring marker, and a glow on the active card. prefers-reduced-motion disables the decorative animation.

6. Styling and i18n

  • Colors use the theme's semantic aliases (--dsw-alias-*) for surfaces, text and borders, so light/dark follow the GUI automatically.
  • The chart needs categorical colors the theme does not define; the fixed palette (tool families, loop phases) is chosen to stay legible on both bases. Tokens are CSS custom properties on the panel root, so changing the palette is a local edit (src/client/palette.ts + styles.ts).
  • Copy lives in src/client/locales.ts, registered through ctx.locale under the loopscope namespace with zh and en baselines; slots receive a bound t so a language switch updates without a reload.

7. Why data is read client-side

The alternative was a Host remote API that serializes trajectories. The client event window already contains every timeline fact, so a remote would add protocol surface, authorization, and latency without new information. Keeping the plugin read-only also means it cannot corrupt a Session.

8. Testing strategy

  • npm run check: evaluates lib/client.js against a fake module loader (artifact format, exported Cordis surface, platform-module boundary) and replays a real Session log or fixtures/sample-session.jsonl through the parser, asserting turns, loops, tokens, phases and signals.
  • npm run check:render: server-renders the panel (zh/en) and the LOOP view with ReactDOMServer, asserting the structural landmarks of both views.
  • End-to-end verification is done against a separate dsh web instance with Playwright (see the project history in the release notes); the repository's CI covers build + the two offline checks on Linux Node 20/22.

9. Extension points

  • New phase facts: extend LoopContextModel / RequestModel in model.ts, then render them in the inspector (panel.tsx).
  • New developer signals: extend signalFor() in model.ts; chips are rendered by loop.tsx.
  • New tool categories: extend TOOL_CATEGORIES and src/client/palette.ts.
  • New languages: add a dictionary in locales.ts and register it.