dsh-point

Readme

# dsh-point

Point checkpoints and ancestry-aware session continuation for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

[简体中文](./README.zh-CN.md)

`dsh-point` gives a DSH workspace an immutable Point history without loading all prior sessions into every new context. Point is the only history unit: save a Point, continue from a Point, and let the agent read an authorized ancestor Point only when needed.

## Features

- `/point-stash [title]` saves complete participant-visible events since the previous Point.
- A Web workspace view renders the Point parent DAG, node details, and an explicit **Continue from this Point** action.
- Continue creates or reuses a deterministic DSH Session and carries Point ancestry without copying historical events into context.
- `point_read(point_id)` lets the model read original events from an ancestor Point; unrelated Points are rejected.
- Crash recovery reconciles the local cursor against immutable Point metadata instead of creating duplicate Points.
- Compaction records are excluded, while the original visible transcript, content blocks, source metadata, and paired tool calls/results are preserved.

## Requirements

- Node.js 22.19 or newer
- DeepSeek Harness 0.1.0-rc.6
- The [`point`](https://github.com/guix4ever/point) CLI available on `PATH`

Install Point first if needed:

```bash
python3 -m pip install "git+https://github.com/guix4ever/point.git"
```

## Install

Add the plugin to the DSH Web profile:

```bash
dsh plugin --profile web add dsh-point
```

Restart DSH after installation. The package contributes both the Host plugin and its Web client bundle through `cordis.patch.yml`.

## Use

Save the current completed work:

```text
/point-stash explain the change briefly
```

Open the **Points** tab in the DSH conversation view to inspect the current workspace DAG. Selecting a node is read-only; press **Continue from this Point** to open its deterministic continuation Session.

The continuation receives only the selected Point ancestry. If historical detail is relevant, the model can call:

```text
point_read(point_id)
```

Only Point ids in that continuation's ancestry are accepted.

## Integrity and failure policy

The save boundary waits for agent idle, flushes DSH persistence, and advances its cursor only after `point stash` succeeds. Projection fails closed on non-contiguous events, open turns, incomplete assistant chunks, duplicate or missing tool identities, dangling calls, and empty visible Points.

The browser cannot choose a filesystem path, Point binary, or shell argument. Workspace path and agent preset are derived by the Host from the addressed DSH Session.

## Development

```bash
npm ci
npm run typecheck
npm test
npm pack --dry-run
```

Maintained sources are TypeScript in `src/` and `client-src/`. Runtime entry points are built into `lib/` and committed so Git installation does not require a local build step.

## Current scope

- The client module targets DSH Web, the client platform currently exposed by DSH. Host behavior is reusable by other entry points.
- The DAG deliberately uses a small horizontally scrollable layout rather than a graph framework, pan/zoom, clustering, or a second history abstraction.
- Automated coverage includes the real Point CLI, crash reconciliation, ancestry authorization, Host restart idempotence, and a real DSH Web/Chromium acceptance run. A paid live-model invocation is not required for this release.

## License

MIT