deepseek-harness/examples/desktop/docs/upstream-ledger.md

Upstream ledger

Findings that need a fix in deepseek-harness upstream (not in this repo), kept here so we don't lose them when we ship the desktop demo. Each entry is a promise to file — either an RFC (via docs/upstream-rfc-pack/) or a narrower PR. What lives in this repo is the local workaround; what lives upstream is the proper fix.

Format per entry:

• Symptom — what a user sees today.
• Root cause — file:line pins into the upstream repo (path relative to packages/… in deepseek-harness-dev/ or the corresponding org path in deepseek-ai/deepseek-harness).
• Local workaround — what we did in this repo to keep the demo honest, and how to spot the workaround at review time.
• Upstream fix (needed) — the shape of the correct change.

---

L-1 Runtime should emit the presented view for tool results, not the raw execute() meta

Symptom. On the default profile (stdio-deepseek), the file-diff card never renders after an fs.edit / fs.write. The tool executes, the result box appears, but the visual diff (which is the headline for the "files visualization" story) is missing. Same latent risk for the terminal card on bash.

Root cause. Two layers in upstream never meet:

• packages/fs/tool-fs/src/edit.ts:92-96 — execute() returns { content, meta: { diffs } }. There is no card field on this meta.
• packages/fs/tool-fs/src/edit.ts:111-116 — presentResult() is where the display view ({ card: 'diff', title, diffs }) is authored. This is a display-time callback.
• packages/core/agent-loop/src/loop.ts:584-594 — the runtime persists the raw execute() meta verbatim on the tool/result event. presentResult() is never invoked; nothing on the wire ever gains a card discriminant.
• packages/core/tools/src/index.ts:787-790 — the tool-registry side of the same seam; presentResult() is declared in the tool descriptor but has no runtime call site.

The desktop renderer's tool/result dispatch (this repo's src/renderer/renderer.js:4744) primarily routes by view.card === 'diff' | 'terminal' | 'widget'. With no card on the wire, all fs meta falls through to the raw-text fallback branch.

Local workaround. src/renderer/renderer.js:4744 now has a fs-family fallback: when view.card is absent, view.diffs is an array, and the tool name is fs-family (fs.edit / fs.write / fs.read, or the short-form aliases), it synthesises { card: 'diff', title, diffs } and renders through the same path. See test/renderer-diff-card-fallback.test.js

• test/fixtures/fs-edit-wire-shape.json (the fixture is the real wire shape captured on lane-showcase 2026-07-18 during the 12/12 verify).

Spot the workaround in code review by the viewLooksLikeDiff / isFsFamilyTool locals in the tool/result case, and by the fixture JSON's _note header.

Upstream fix (needed). Either

• Make agent-loop invoke presentResult(args, result) on tool/result emit and put the returned view onto the wire under data.meta, replacing (or supplementing) the raw execute() meta; OR
• Expose the tool registry to the shell so a shell-side dispatcher can call presentResult after receiving the raw meta.

Either shape is a small RFC (see docs/upstream-rfc-pack/ template). The tool-side contract (presentResult returning ToolResultView) already exists — this is a wiring gap, not a design decision.

Once upstream lands the fix, the fallback becomes dead code but stays in place (the shape test still passes via the primary card:'diff' branch), so there's no coupling between land order.

---

L-2 Runtime should emit semantic trace signals (loop / redundant / plan-*)

Symptom. A researcher watching a session can't see at a glance where the interesting things happened: the agent got stuck in a tool-call loop, called the same tool with the same args twice within a few turns, mid-turn rewrote its plan, or restarted after a tool error. These are the first four things a debugger wants highlighted, and today the trace tri-view

• main assistant flow show every step at equal visual weight. The Tree column has an ✗ glyph for tool errors — that's the only pre-existing signal.

Root cause. The runtime wire has no dedicated "signal" event type. All diagnostic annotations that today's UI could show — loop detection, redundant-call detection, plan updates, plan restarts, ordinary tool errors raised to signal status — are inferable from the flat event stream but not themselves emitted. Concretely:

• packages/core/agent-loop/src/loop.ts — the loop sees every tool/call and every tool/result but never emits a trace/signal derived from them.
• packages/core/tools/src/index.ts — tool descriptors don't declare loop/retry guardrails that could feed a signal emission.
• packages/core/planner/ (or the equivalent — grep for plan in deepseek-harness-dev/packages/core/) — plan updates are internal state, not observable on the wire.

The desktop renderer therefore has no signal to render.

Local workaround. New src/renderer/trace-signal-detect.js is a heuristic detector run over meta.cachedEvents. It emits five signal kinds:

• loop-detected — ≥ N consecutive same-tool + same-args-prefix calls (N=3)
• redundant-call — same (name, args-prefix) reappearing within an 8-seq window with at least one different call in between
• plan-update — assistant/message text matching "new/revised/updated plan", "here's the plan", or a two-line numbered-list intro
• plan-restart — same tool re-invoked after a tool/result ok:false
• tool-error — surfaced from the already-visible ok:false result, but also stamped on the matching call seq so the Graph node (which absorbs the result into the call) has a place to hang the badge

Signals are then rendered as:

• Timeline bars: colored dots to the left of each affected row (.trace-timeline-signal-badge in style.css)
• Graph nodes: outer ring around the node (.trace-graph-signal-ring, highest-priority signal wins the color)
• Assistant turn container: a chip row above the body (.turn-signal-chip-row / .turn-signal-chip), one chip per signal kind observed in that turn, clicking a chip auto-opens the trace drawer

The detector already special-cases wire-emitted signals: any event whose type === 'trace/signal' is passed through verbatim (marked source: 'wire') and the heuristic scan skips seqs already covered by wire signals. This means the shape is forward-compatible: once upstream lands the fix, the runtime's signals win and the heuristic scan becomes dead code without requiring a renderer change.

Spot the workaround in code review by:

• src/renderer/trace-signal-detect.js — the entire file
• src/renderer/trace-timeline.js — the options.signals badge loop (around the "Signal badges" comment)
• src/renderer/trace-graph.js — the "Signal ring" block inside renderGraph's node loop
• src/renderer/trace-tri-view.js — the _computeSignals(records) call passing a bySeq map to both Timeline and Graph
• src/renderer/renderer.js — applyTurnSignalChips(sessionId, section) called at the end of finishTurnContainer
• src/renderer/style.css — the .trace-timeline-signal-badge / .trace-graph-signal-ring / .turn-signal-chip* blocks at the tail

Upstream fix (needed). Emit trace/signal events from the runtime with this shape:

{
  type: 'trace/signal',
  seq: <number>,          // seq the signal decorates (often the tool/call seq)
  time: <number>,
  data: {
    signal: 'loop-detected'|'redundant-call'|'plan-update'|'plan-restart'|'tool-error',
    // signal-specific fields; the renderer uses these for tooltip content:
    name?: string,        // for tool-family signals: which tool
    argsKey?: string,     // 80-char args prefix
    run?: number,         // loop-detected: number of consecutive matches
    priorSeqs?: number[], // loop-detected: earlier calls in the run
    priorSeq?: number,    // redundant-call / plan-restart pointer
    priorErrorSeq?: number,
    snippet?: string,     // plan-update: first 80 chars of the plan text
    error?: string,       // tool-error
  }
}

Suggested seams (grep upstream to confirm exact packages/… paths — the comments below cite the same file family as L-1):

1. Loop/redundant detection — add a small ring buffer of recent tool/call (name, argsKey) pairs inside agent-loop's emit path. When the buffer trips the threshold, emit trace/signal before the offending tool/call reaches the wire so the signal precedes the call in seq order. Threshold defaults (loopN=3, window=8) can be config-flagged.
2. Plan updates — plumbed from the planner / plan-summary side. Ideal shape: a plan/updated event upstream, with trace-signal derived from it. If the planner state is internal, at minimum emit the "assistant drafted a new plan" fact when it happens (the heuristic detector proves the text is recoverable, but the wire truth is upstream).
3. Plan restarts / tool errors — pair tool/result ok:false with the next same-tool tool/call and emit the paired signal at emit time.

The detector-side dedup already covers the "signal already came from the wire" case, so upstream can ship these one at a time without a big-bang change: each signal kind lands, its heuristic branch becomes dead code, and eventually trace-signal-detect.js reduces to a pass-through for the wire signals.

Once all five signal kinds land upstream, the renderer-side detector becomes pure pass-through (roughly 20 lines) — a small doc-only PR at that point removes the heuristic scan entirely. Until then, the tri-view tabs read as "here's what the runtime is showing you" (wire signals) and "here's what the shell inferred" (heuristic, tooltipped as such).

---

L-4 Runtime should expose a models/list RPC (shell-side static mirror is workaround)

Symptom. The shell has no wire-level way to ask the runtime "which (adapter × model) pairs are actually registered right now?". A researcher who wires up a new adapter or ships a plugin that calls ctx.llm.registerAdapter(...) at boot has no way to see that model in the composer dropdown without also editing shell code. Picking a model the runtime doesn't know about falls through to a NO_ADAPTER error, which the shell recovers from with a "switch profile" affordance — but the up-front list is a static mirror maintained by hand.

Root cause. No models/list (or equivalent) RPC on the wire. The runtime knows its own adapter/model registry — that's what routes each llm/call to the right adapter — but it never exposes that registry to the shell. The shell therefore has to guess, and today "guess" means "copy the yml into a JS map".

Local workaround.

• src/main/profiles.js:230 — PROFILE_MODELS is a static map, profile name → array of supported model ids, one entry per row in config/*.yml.
• src/main/profiles.js:246 — modelsFor(name) is the accessor exported to main.js.
• src/main/main.js:280 — the profiles:models IPC handler snapshots the whole map to the renderer at handshake / profile-switch time.
• src/renderer/renderer.js:4048 — renderComposerModel(currentModel) uses the mirror to filter the composer dropdown; if the runtime later reports NO_ADAPTER we fall back to the "switch profile" affordance.
• test/model-profile-guard.test.js — parses every config/*.yml models: field and asserts the yml matches PROFILE_MODELS line by line, so any yml drift trips the test.

Spot the workaround in code review by the PROFILE_MODELS literal at src/main/profiles.js:230 and by the guard test — both exist purely because the runtime never told us.

The workaround is intentionally strict: hand-maintained maps drift, so the guard test locks yml ↔ map. It does not cover runtime-time registerAdapter calls; those still surface only as NO_ADAPTER-then-recover.

Upstream fix (needed). Expose a models/list RPC on the wire:

Method: models/list
Params: none
Result: {
  models: [
    { id: string, adapter: string, capabilities?: { streaming, thinking, ... } }
  ]
}

Consumer migration in this shell once the RPC lands:

• Add a runtime:list-models IPC and call it once at handshake plus on every profile switch.
• Downgrade PROFILE_MODELS to a fallback used only when the RPC is unavailable (e.g. older runtime).
• Keep test/model-profile-guard.test.js — its job becomes narrower (yml ↔ fallback consistency), still worth having for older-runtime users.

Precedent in ledger. Same shape as L-1 (presentResult wire), L-2 (trace semantic signals), L-3 (artifact blob snapshot): the shell paints over an information gap the runtime should own, and the fix is a small wire addition that lets the workaround retire.

Reference. PR #374 review comment by @ZiyaZhang — https://github.com/deepseek-harness/deepseek-harness/pull/374#issuecomment-5016306211