DeepSeek Harness
Connect a DeepSeek Harness profile to a Libra repository with the development bridge bundle
DeepSeek Harness
DeepSeek Harness (DSH) connects to a Libra repository through the profile bundle @libra-tools/dsh-bundle. Harness keeps the agent loop, session history, and approval policy. Libra keeps repository state. The bundle is the client between them: it starts libra agent bridge --stdio and speaks JSON-RPC 2.0, one object per line.
This is not external-agent hook capture. Do not use libra agent add, libra agent enable, or a provider hook to attach Harness. Those commands are documented in Use Agent Capture. The bridge is also not libra agent mcp --stdio. The bridge command itself is summarized under libra agent bridge --stdio in libra agent.
What is not released
The steps below install a development build, not a published package.
npm latest for @libra-tools/dsh-bundle is 0.1.0. That release does not guarantee the bridge behavior, Plugins form, or Memory switches described here. The development tree is 0.2.0 and cannot be installed with npm (do not run npm install of @0.2.0 or any other 0.2.0 spec). Clone the repository and build the local tarball as described below.
| Piece | Use this | Do not assume |
|---|---|---|
| Bundle | @libra-tools/dsh-bundle 0.2.0 built from libra-tools/deepseek-harness-libra-plugin |
npm latest 0.1.0 is the published package. It is not this tree, and there is no npm install command for 0.2.0. |
| Harness | DeepSeek Harness 0.2.2-rc.3 (engines.dsh ^0.2.2-rc.3, Node.js >= 24.9) |
The separate test:lifecycle script targets a historical DSH alpha and is not evidence for 0.2.2-rc.3. |
| Libra baseline | A libra binary that implements agent bridge --stdio and negotiates protocol major 1 |
Protocol 1.0 is the twenty-method baseline. It does not include Memory. |
| Memory 1.1 / 1.2 | Present in the unpublished Libra 0.30.207 development source checked for this page (Cargo.toml version 0.30.207: minor 1.1 adds memory.recall, minor 1.2 adds memory.episode.record) |
No published Libra release is claimed to include these methods. libra --version alone does not prove support. The plugin mounts Memory only when that process's initialize result lists the method. There is no signed compatibility receipt for this local Memory implementation. |
The conversation Memory changes used in local verification are uncommitted development changes, not a published Libra release. The published v0.30.210 bridge source advertises the protocol 1.0 baseline; it does not contain this conversation Memory module. Building a release or ordinary checkout therefore does not provide these methods. Inspect the bridge's negotiated methods and the source you build, and check the official releases for future availability. An older Bridge 1.2 development fixture (Libra 0.21.25) describes a different, compiler-backed Memory path that called a model and stored a structured note. The locally tested 0.30.207 store does not do that.
Build the bundle
Clone libra-tools/deepseek-harness-libra-plugin and build the self-contained tarball in that checkout. Do not install 0.2.0 from npm. The repository root and packages/bundle are not install targets by themselves.
pnpm install --frozen-lockfile
pnpm build
pnpm pack:bundle -- --destination ./artifacts
dsh plugin --profile <profile> add ./artifacts/libra-tools-dsh-bundle-0.2.0.tgz
pnpm check (lint, typecheck, unit tests, and build) is the fuller local gate before you pack. It is not a live Libra integration test. Packing needs pnpm build first; pack:bundle writes libra-tools-dsh-bundle-0.2.0.tgz.
Replace <profile> with the Harness profile you actually run (the development notes use names such as headless). Confirm the installed entry with:
dsh --profile <profile> --dump-config
The Cordis entry name is libra.
Configure the binary and repository
Set both locations. Prefer an absolute libraExecutable so PATH cannot select a different libra. repositoryRoot must be a Libra worktree (libra init). If you leave the repository empty, the plugin uses LIBRA_REPO or the host process's current directory, which can differ from the Harness session workspace.
{
"libraExecutable": "/absolute/path/to/libra",
"repositoryRoot": "/absolute/path/to/libra-repository"
}
LIBRA_BINARY is the environment fallback for the executable. The model cannot supply either path.
In the Harness GUI, open Plugins, then this bundle (Libra bridge). The form edits the same deployment fields:
| Form label | Config key | Notes |
|---|---|---|
| Libra binary | libraExecutable |
Absolute path, relative path, or a name on PATH. Empty falls back to LIBRA_BINARY; the plugin remains inactive only if neither supplies a usable binary. |
| Repository root | repositoryRoot |
Initialized worktree. |
| Outbox directory | outboxRoot |
Optional. Empty uses $DSH_HOME/libra/outbox, outside the repository. |
| Inject repository context on the first turn | injectContext |
Default on. One bounded libra_context snapshot, then the model can call the tool. |
| Workspace lease (ms) | workspaceLeaseTtlMs |
Default 30000. The bundle renews at half the TTL. |
| Memory token budget | memoryTokenBudget |
0 omits the budget; the locally tested Memory store uses a 2,000-byte default. A positive value is sent to the bridge. That store caps it at 16,384 UTF-8 bytes, including the prefix; despite the field name, this is a byte bound, not an exact model-token count. The plugin does not trim the returned section after checking its hash. |
If that screen says settings are unavailable, put libraExecutable in the bundle configuration instead.
Save, then reload the plugin after changing the binary or the repository. A bridge that is already running refuses the new target (Libra executable or repository changed; reload the plugin before continuing) so an existing session is not moved to another repository. The save confirmation may say the next bridge request picks up the change; a refusal still means reload. Changes to the outbox directory, context injection, and episode capture require a plugin reload. With the same binary and repository, the memory budget is read on the next recall and the lease TTL is refreshed on bridge requests. Unloading tries to drain bridge work before closing the bridge; on timeout, unacknowledged outbox events are retained. Live Harness sessions are not closed.
The bundle does not replace the built-in changed-files card or a general memory plugin such as dsh-mnemon. Those can stay enabled. Libra's injected section uses source kind libra-memory or libra-context.
Protocol negotiation
The child is always libra agent bridge --stdio. Stdout is protocol frames only; diagnostics go to stderr.
The development bundle requests protocol 1.2 (major 1, minor 2) from its bundled receiver fixture. The compatible baseline is 1.0; a major mismatch fails closed before other methods run. The server answers with its negotiated protocol, limits, methods, and source. On the locally tested 0.30.207 development source the negotiated minor is capped at 2:
| Negotiated minor | Methods the bridge will advertise and accept |
|---|---|
| 0 (1.0 baseline) | The original 20 methods only |
| 1 | Those 20, plus memory.recall |
| 2 | Those 21, plus memory.episode.record |
A method from a higher minor is rejected on that connection until initialize succeeds at that minor. A 1.0 peer that calls memory.recall does not get Memory. The plugin logs bridge does not advertise memory.recall; Memory module not mounted and continues with tools, context, leases, and the outbox.
Frame cap is 256 KiB. The client bounds the handshake. Later requests use the server deadline and still end if the child exits or the plugin closes the bridge.
Tools
These Harness tools map to bridge methods. There is no wildcard. Write and restore stay denied until Harness approval. Session identity comes from the calling session; the model cannot pass actor, repository_root, session_id, or operation_id.
| Tool | Method | Risk |
|---|---|---|
libra_context |
context.get |
read, allowed |
libra_status |
status.get |
read, allowed |
libra_diff |
diff.get |
read, allowed |
libra_history_search |
history.search |
read, allowed |
libra_checkpoint |
checkpoint.list |
read, allowed |
libra_checkpoint_show |
checkpoint.show |
read, allowed |
libra_checkpoint_create |
checkpoint.create |
write, needs approval |
libra_commit |
commit.create |
write, needs approval |
libra_review |
review.run |
write, needs approval |
libra_restore_checkpoint |
checkpoint.restore |
restore, needs approval |
Each result is one object: { schema_version, operation_id, status, data?, error?, warnings? }. Bridge and transport failures use status: "error". They are not an empty success.
Conversation memory
Memory is optional and off until you opt in on the repository. The bridge reads the repository-local key on every call. A global value or an environment variable does not enable it. Only the exact string true counts. Revoking it takes effect on the next memory request without restarting the process. While it is off, recall returns an empty delivery, recording is refused, and the memory database is not created.
libra config set --local bridge.conversationMemory true
libra config get --local --show-scope --default false bridge.conversationMemory
You also need a binary that negotiated memory.recall (and memory.episode.record if you want capture). Advertising the method is not the same as opting in.
Capture has a second switch, captureMemoryEpisodes, default false. It is not on the Plugins form above. Set it on the bundle entry and reload:
{
"libraExecutable": "/absolute/path/to/libra",
"repositoryRoot": "/absolute/path/to/libra-repository",
"captureMemoryEpisodes": true
}
Both switches must be on. After a successful turn the plugin sends the accepted user query and the final assistant text, with the session id and turn number. Failed, aborted, blocked, and truncated turns are skipped. Tool traces, reasoning blocks, later steering, and historical replay are not captured. There is no durable capture retry queue. A settled Harness flush means capture finished or failed observably, not that a row exists.
memoryModel (default deepseek-chat) is forwarded only for an older compiler-backed bridge. The 0.30.207 local store does not call a model and does not write a structured note or a selection receipt. You do not need a model API key for that store.
What the 0.30.207 store actually does
Checked in that development source, not in a release build:
- Records live in a private SQLite file,
memory.sqlite3, under the repository's.libra/conversation-memory/directory. The bridge does not accept a repository path or a filesystem path from the caller. - The store holds at most 1,000 episodes. When full, new records are rejected rather than automatically evicting older ones. A repeated session and turn is idempotent only when the redacted text matches.
- Before insert, text passes Libra's log redaction helper. That is best-effort pattern redaction. It does not guarantee removal of every secret, personal identifier, or other sensitive string.
- Recall is lexical, not semantic. It tokenizes the query into at most 16 terms (ASCII words of at least two characters, plus CJK bigrams and single CJK characters) and returns records when any term is a case-insensitive substring of the redacted goal or response. Newest rows come first. Matching rows from other sessions in the same repository can be returned. Synonyms and embeddings are not used. A query with no searchable term returns an empty delivery.
- The prompt section is prefixed as untrusted conversation data, not as instructions. The wrapper is not a prompt-injection filter and does not replace Harness approval policy. The response includes a SHA-256 of the exact UTF-8 section.
- A session id is an idempotency key, not a credential. The trust boundary is the local stdio process and the OS user who can read the repository.
The plugin truncates a goal at 4096 UTF-8 bytes and a response at 16384 bytes on a character boundary, adds a truncation marker, and logs only the session, turn, field, and original size. A truncated row is not a full transcript. The bridge itself rejects over-limit goal or response text from a direct caller.
Roll back
Do these independently. None of them erases data by itself.
-
Stop new capture: set
captureMemoryEpisodestofalseand reload the plugin. -
Stop recall and recording in this repository. Either value works because only exact
trueis enabled:libra config set --local bridge.conversationMemory falseOr remove the local key:
libra config unset --local bridge.conversationMemory -
Stop the bridge: disable or remove
@libra-tools/dsh-bundleon the Plugins page. Alternatively, clearlibraExecutableand removeLIBRA_BINARYfrom the Harness process environment, then reload the plugin. A blank setting alone is not enough if the environment variable points to a usable executable.
Disabling the plugin does not delete $DSH_HOME/libra/outbox or .libra/conversation-memory/. The bridge has no delete method for one episode. Logical deletion still would not guarantee that SQLite journals, filesystem snapshots, or backups dropped the bytes. If you remove the private directory yourself, do it only after the bridge process for that repository has exited, and treat copies outside the directory as still present. Do not delete .libra/ as a whole; that is the repository metadata store, not just Memory.
To return to the published bundle, remove this development tarball from the profile and install only an artifact whose version you have actually published. Do not point libraExecutable at a release binary and expect memory.recall unless that binary's handshake lists it.
Troubleshooting
| Symptom | What it means | What to do |
|---|---|---|
No libra process; log says the plugin is inactive |
No usable libraExecutable / LIBRA_BINARY, or the path is not an executable file |
Set an absolute path to the development binary and reload. A release binary on PATH is not a substitute. |
repositoryRoot is not a directory or not available |
The configured root is missing, or it is not a directory | Create the worktree with libra init, or set repositoryRoot to that absolute path. |
| Tools work, but Memory never appears | Handshake did not advertise memory.recall (typical for protocol 1.0) |
Confirm you are running the 0.30.207 development binary, then reload so initialize runs again. Check the negotiated methods list, not the version string alone. |
Memory methods are advertised, recall is always empty, and no conversation-memory directory appears |
Repository opt-in is off, or the query has no lexical term | Run libra config get --local --show-scope --default false bridge.conversationMemory; confirm the local value is true. An unscoped get can return a global value that the bridge ignores. |
| Capture flag is true but nothing is stored | Opt-in is off, the turn did not succeed, or the bridge never negotiated memory.episode.record |
Both switches, a successful turn, and minor 1.2 are required. A flush warning is not a stored row. |
Libra executable or repository changed; reload the plugin |
Binary or repository was edited while the bridge was up | Reload the plugin. Do not expect the open session to follow the new path. |
| Write or restore tool returns denied | Harness approval has not allowed it | Approve the call in Harness. Denial is not a bridge outage. |
status: "error" on a tool |
Bridge or transport failure | Read error. Do not retry a restore or commit until you know whether it was applied. |
| Settings form cannot be saved | This profile has no settings service | Edit the bundle configuration directly, including absolute libraExecutable. |
Pattern checks on the outbox and on Memory can miss secrets. Treat both stores as sensitive local data.