dsh-live-loop

Readme

<div align="center">

# dsh-live-loop

**Your agent wrote the page. Now let it prove that the page actually works.**

DeepSeek Harness frontend runtime verification for real local web applications.

[![CI](https://github.com/POWERRRRRRRR/dsh-live-loop/actions/workflows/ci.yml/badge.svg)](https://github.com/POWERRRRRRRR/dsh-live-loop/actions/workflows/ci.yml)
![DeepSeek Harness](https://img.shields.io/badge/DeepSeek_Harness-0.1.0--rc.7-4f46e5?style=flat-square)
![Node.js](https://img.shields.io/badge/Node.js-22.19_LTS_%7C_24%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)
[![License: MIT](https://img.shields.io/badge/License-MIT-111827?style=flat-square)](./LICENSE)

English | [简体中文](./README.zh.md)

[Quick start](#quick-start) · [Capabilities](#one-loop-not-another-browser-tool) · [Agent tools](#agent-tools) · [Security](#security-boundary) · [Evidence](./docs/RELEASE-EVIDENCE.md)

</div>

---

## Give the agent a feedback loop

Coding tools can edit a page and build it. That does not prove the page loaded, the interaction worked, the browser stayed error-free, or the result matched the reference.

**dsh-live-loop** gives an installed DeepSeek Harness Agent one coherent runtime loop:

```text
Understand → Edit → Detect → Run → Preview → Observe → Interact
→ Verify → Diagnose → Fix → Reload → Re-verify → Deliver with evidence
```

The plugin does not edit application code. DSH's normal coding tools remain responsible for that. Live Loop owns the dev-server lifecycle, isolated browser state, structured observation, interaction, verification, and durable evidence.

## See it inside DSH Web

<p align="center">
  <img src="./docs/assets/dsh-live-loop-preview.png" alt="dsh-live-loop running a verified page in the native DeepSeek Harness Web Live Preview panel" width="100%" />
</p>

<p align="center"><sub>Real DSH 0.1.0-rc.7 clean-profile run: managed Vite app, native Live Preview, stable DOM ref, page status 200, zero Console errors, zero critical Network failures, and a VERIFIED report. This is not a mockup.</sub></p>

## One loop, not another browser tool

| Detect | Run | Preview | Observe | Interact | Verify |
| --- | --- | --- | --- | --- | --- |
| Vite, React, Vue, Next.js, generic scripts, monorepos | DSH-owned process tree, health checks, safe port policy | Native DSH Web panel, viewports, iframe fallback | URL, title, DOM, Console, exceptions, Network | Stable refs, click, fill, type, press, scroll, history | Assertions, screenshots, visual diff, structured evidence |

What makes the plugin reusable is the system around the browser:

- structured target detection with explicit ambiguity instead of silently choosing the wrong app;
- argv-only execution through public DSH subprocess ownership, including bounded logs and cleanup;
- one isolated BrowserContext per DSH subject and Preview Session;
- bounded observation windows that work with HMR, WebSocket, SSE, and polling;
- DSH Attachment screenshots plus Reference / Current / Diff evidence;
- a strict four-state verdict that refuses to turn missing observation into a pass;
- a native DSH Web Live Preview, Verification Card, and Settings panel;
- failure diagnostics that tell the Agent what to fix before it verifies again.

## Compatibility

| Component | Supported |
| --- | --- |
| DeepSeek Harness | **exactly** `0.1.0-rc.7` |
| Node.js | `^22.19.0` or `>=24` |
| App package managers | npm, pnpm, Yarn; Bun detection is supported when Bun is on `PATH` |
| Browser runtime | installed Chrome, Edge, or Chromium |
| Tested app targets | Vite React, Vite Vue, Next.js, generic package script |

The DSH peer range is intentionally exact while the plugin ABI is release-candidate software. Do not run this plugin in a mixed rc.7/rc.8 dependency graph. Source installs use `--legacy-peer-deps` because several published rc.7 packages declare caret peer suggestions that npm otherwise tries to satisfy with rc.8; the committed lockfile itself contains no rc.8 package. See [Compatibility](./docs/COMPATIBILITY.md) for the verified seam and the published CLI resolution caveat.

## Install from GitHub

The repository includes prebuilt `lib/` artifacts so a Git checkout is inspectable and packageable without rebuilding DSH Web.

```bash
git clone https://github.com/POWERRRRRRRR/dsh-live-loop.git
cd dsh-live-loop
npm ci --legacy-peer-deps
npm run build
npm pack --ignore-scripts
dsh plugin --profile web add ./dsh-live-loop-1.0.0.tgz
```

Restart the `web` profile after installation because DSH resolves profile bundle membership at startup:

```bash
dsh --profile web --dump-config
dsh --profile web web
```

Run the final command from the workspace that contains the frontend you want the Agent to verify.

## Quick start

1. Open a DSH conversation in the frontend workspace.
2. Select the **Live Preview** conversation view.
3. Select **Detect**. If several targets or scripts are credible, choose one explicitly.
4. Select **Start**. Live Loop waits for a discovered URL and a successful HTTP health check.
5. Ask the Agent to modify the app and verify task-specific behavior.
6. Accept completion only with a fresh `VERIFIED` or justified `VERIFIED_WITH_WARNINGS` report and screenshot evidence.

Try this Agent request:

```text
Fix the form, start or reuse the detected app, fill the Name textbox with Ada,
press Enter, assert that “Hello, Ada!” appears, and do not finish until
live_loop_verify returns VERIFIED with screenshot evidence.
```

The intended failure loop is equally important:

```text
first verify: FAILED
→ inspect Console / Network / DOM / assertion / visual diff
→ edit the application
→ reload or let HMR apply
→ verify again: VERIFIED
→ deliver the report and evidence
```

## Agent tools

The model-facing API stays deliberately small and non-overlapping.

| Tool | Purpose |
| --- | --- |
| `live_loop_detect` | Return structured target and run-profile candidates. |
| `live_loop_server` | `start`, `stop`, `restart`, and `status` with bounded logs. |
| `live_loop_browser` | Navigate, reload, history, snapshot, stable-ref interactions, wait, screenshot, diagnostics, and viewport. |
| `live_loop_verify` | Run the high-level observation, interaction, assertion, screenshot, optional visual-diff, and report transaction. |

Every result has a stable structured value, concise model-readable text, an explicit error code when applicable, a next action, bounded output, and a warning that page-derived content is untrusted evidence.

## Truthful verification

A verification call establishes a fresh bounded observation window, loads or reloads the page, waits for DOM readiness plus network quiet, runs requested interactions and assertions, captures diagnostics and DOM state, persists a screenshot, optionally compares a reference, and writes a report.

| Status | Meaning |
| --- | --- |
| `VERIFIED` | Every requested check and required evidence completed without blocking diagnostics. |
| `VERIFIED_WITH_WARNINGS` | Required checks passed and all non-blocking warnings are explicit. |
| `FAILED` | The app was observed and a page, diagnostic, interaction, assertion, or visual requirement failed. |
| `UNVERIFIED` | Observation or evidence could not be completed, so no pass/fail claim is justified. |

`VERIFIED` is impossible when the browser is unavailable, the main document fails, stability times out, the observation boundary is unclear, an unignored Console error or critical Network failure exists, an interaction/assertion fails, a requested visual comparison is incomplete, or required screenshot evidence cannot be persisted.

Visual similarity is supporting evidence. It never overrides page loading, diagnostics, interactions, or assertions.

## Architecture

The Host is the single source of truth. The Web client never guesses process, browser, target, or verdict state.

```mermaid
flowchart LR
    Agent[DSH Agent] --> Tools[4 Agent tools]
    Web[DSH Web client] --> RPC[Public Connection RPC]
    Tools --> Host[LiveLoop Host service]
    RPC --> Host
    Host --> Detect[Target detector]
    Host --> Process[DSH subprocess manager]
    Host --> Browser[Isolated browser provider]
    Host --> Verify[Verification engine]
    Verify --> Evidence[DSH Attachments + reports]
    Web --> Preview[Live Preview + Tool View + Settings]
```

The package uses public rc.7 Extension Points: Cordis bundle patching, DSH service injection, `ctx.subprocess`, Attachments, System Prompt sections, Agent tools, lazy `dsh.client` loading, public slots, and loopback-scoped Connection RPC. It does not patch DSH Core, monkey-patch the Agent loop, or use a global-window shortcut to bypass Client Modules.

Read [Architecture](./docs/ARCHITECTURE.md) and [Decisions](./docs/DECISIONS.md) for the full provider, lifecycle, UI, and community-browser evaluation.

## Security boundary

This plugin starts workspace code, controls a browser, and stores evidence, so it fails closed at the important boundaries:

- canonical workspace confinement, including symlink and junction resolution;
- detected package scripts only, argv execution, no Agent-provided shell string;
- DSH permission, approval, subprocess ownership, cancellation, and process-tree cleanup;
- no arbitrary Agent-facing page JavaScript evaluation;
- loopback-only managed origins by default and explicit external-host allowlisting;
- redirect-hop checks, DNS/private-range denial, and cross-origin WebSocket blocking;
- cookie, storage, browser context, and Host operation isolation by subject/session;
- bounded logs, DOM, diagnostics, screenshots, reports, retention, and timeouts;
- best-effort credential redaction and no ordinary client setting for secrets;
- page DOM, text, Console, Network, and errors labeled as untrusted content.

The direct Live Preview preserves target CSP and `X-Frame-Options`. If framing is not valid, the UI marks the limitation and falls back to screenshots or **Open externally**; it does not turn DSH into an open proxy.

Read the implemented controls and residual constraints in [Security](./docs/SECURITY.md).

## How it differs

| Compared with | dsh-live-loop adds |
| --- | --- |
| Ordinary browser-control plugin | target detection, dev-server ownership, URL health, native Preview UI, strict observation windows, evidence retention, visual diff, and fix/re-verify guidance |
| Playwright or Cypress suite | installable Agent-time runtime verification without replacing the app's long-lived authored test suite |
| A successful build | proof from a real loaded page, interaction, diagnostics, assertions, and screenshot evidence |

The project independently implements its rc.7 Browser Provider. It incorporates publicly validated design lessons from [dsh-browser-playwright](https://github.com/ChenyuHeee/dsh-browser-playwright) and evaluates [dsh-plugin-browser](https://github.com/xu1132/dsh-plugin-browser), but does not copy either implementation. The compatibility and product-boundary decision is documented in [Decisions](./docs/DECISIONS.md).

## Release evidence

The current release was exercised against a clean DSH `0.1.0-rc.7` Profile and a real Vite app:

- packaged tarball installed into the clean Profile;
- DSH Web and the lazy Client Plugin loaded successfully;
- target detection, managed start, DOM snapshot, fill/press interaction, verification, attachment evidence, stop, and cleanup completed;
- page response `200`, Console errors `0`, critical Network failures `0`, final status `VERIFIED`.

The screenshot above and reproducible command/results ledger are in [Release evidence](./docs/RELEASE-EVIDENCE.md).

## Development

```bash
npm ci --legacy-peer-deps
npm run check
npm test
npm run test:e2e
npm run build
npm pack
```

`npm run test:e2e` launches real Vite React, Vite Vue, Next.js, generic/failure fixtures, Chromium, DSH's rc.7 local subprocess provider, and a failure → fix → re-verify story. `prepack` runs the complete check/test/browser/build release gate.

The repository intentionally commits prebuilt `lib/` output for community-plugin installation. If you change `src/`, run `npm run build` and include the matching generated output.

## Documentation

| Document | Contents |
| --- | --- |
| [Final product specification](./dsh-live-loop-product-spec.md) | unified product goal and acceptance boundary |
| [Architecture](./docs/ARCHITECTURE.md) | Host, Client, process, browser, verification, and evidence design |
| [Decisions](./docs/DECISIONS.md) | DSH seam research and community-provider decision |
| [Security](./docs/SECURITY.md) | implemented controls and residual constraints |
| [Compatibility](./docs/COMPATIBILITY.md) | exact DSH and runtime compatibility |
| [Release evidence](./docs/RELEASE-EVIDENCE.md) | real build, browser, package, and clean-Profile results |
| [Changelog](./CHANGELOG.md) | release history |

## Contributing

Issues, compatibility reports, fixtures, security improvements, and translations are welcome. Read [Contributing](./CONTRIBUTING.md) before opening a pull request.

To uninstall:

```bash
dsh plugin --profile web remove dsh-live-loop
```

Restart the Profile afterward. Uninstalling does not silently delete retained evidence.

## License and project status

[MIT](./LICENSE). This is an independent community project and is not an official DeepSeek AI release or endorsement.