dsh-continuum
Agents are temporary. The project is continuous.
dsh-continuum is a production-grade marketplace plugin for DeepSeek Harness (DSH). It provides persistent project memory, context-safe agent handoffs, checkpointing, evidence tracking, and long-running task continuity across ephemeral LLM agent sessions.
The Problem: Ephemeral Agent Amnesia
In multi-agent and long-running workflows, individual agent processes are inherently temporary:
- Context windows fill up, forcing context wipes or aggressive summarization.
- Subagents die or time out, losing critical reasoning, rejected hypotheses, and uncommitted findings.
- Successive agents repeat expensive literature/codebase research or regress already-solved bugs.
- Uncoordinated agents overwrite each other's work or self-verify incomplete implementations.
dsh-continuum turns DeepSeek Harness from a stateless prompt runner into a resilient, state-preserving software engineering environment.
Key Capabilities
graph TD
subgraph DSH_Runtime["DeepSeek Harness Runtime"]
Agent["Ephemeral Agent Session"]
Prompt["Prompt Section (order: 200)"]
Tools["7 First-Party Tools"]
end
subgraph Continuum["dsh-continuum Core Engine"]
OCC["Optimistic Concurrency (OCC)"]
Leases["Renewable Task Leases"]
SoD["Separation of Duty (4-Eyes)"]
ContextEng["10-Tier Context Budgeter"]
Lock["Liveness File Lock (PID check)"]
end
subgraph Storage[".continuum/ Storage Layer"]
Log["events.jsonl (Append-Only)"]
Snap["checkpoints/ (Snapshots)"]
Arts["artifacts/ (Large Spilled Outputs >10KB)"]
Backup["Backup & Restore (.continuum-backup)"]
end
Agent -->|Invokes| Tools
Tools --> OCC
OCC --> Lock
Lock --> Log
Log --> Snap
Log --> Arts
Snap --> ContextEng
ContextEng -->|Injects Context Pack| Prompt
- Deterministic Event Sourcing (
events.jsonl):
Every state change (project creation, task claim, finding, decision, evidence, verification) is modeled as an immutable, strictly monotonically sequenced event. System state is derived deterministically by replaying the event log.
- Crash Resilience & Partial Line Recovery:
If a host process dies mid-write (SIGKILL or power loss), Continuum automatically detects incomplete trailing JSON fragments, safely truncates to the last committed event, and continues operations without data loss.
- Liveness-Checked Cooperative Locking:
Serializes concurrent process writes using cooperative lockfiles with defensive PID existence validation (
process.kill(pid, 0)). Stale locks from terminated processes are safely broken without dangerous arbitrary timeouts.
- Optimistic Concurrency Control (OCC):
Entity updates enforce strict version matching (
expectedVersion). Concurrent writes with stale assumptions are rejected with typed VersionConflictError rather than silently overwriting state.
- Strict Mutation Idempotency:
Retrying a network-dropped or replayed tool call with identical
idempotencyKey returns the cached result without duplicating side effects. Accidental key collisions across different actions trigger an immediate IdempotencyMismatchError.
- Renewable Execution Leases:
Tasks claimed by agents issue time-bound leases (e.g., 10 minutes). If an agent crashes or abandons a task without renewing its lease, Continuum's lease reconciler automatically releases the task back to
ready with an incremented attempt counter.
- Four-Eyes Separation of Duty:
Configurable task verification policies (
independent, dual, redteam) mathematically forbid the agent who implemented a task from self-verifying it.
- Deterministic 10-Tier Context Budgeting:
Builds token-capped system prompt sections using strict priority ranking (active task $\to$ North Star $\to$ blocker conflicts $\to$ key findings $\to$ recent handoffs). Large outputs (>10KB) are automatically spilled to disk artifacts to protect prompt budgets.
- Untrusted Content Encapsulation:
External web scrapes, user inputs, and finding contents are sanitized and sealed in strict
<continuum:untrusted-finding> boundaries to prevent prompt breakout attacks.
- Cryptographic Backup & Verified Restore:
Exports the entire project into a self-contained
.continuum-backup archive with SHA-256 integrity verification.
Installation
Install into your DeepSeek Harness project:
pnpm add dsh-continuum
# or
npm install dsh-continuum
DeepSeek Harness Configuration (cordis.patch.yml)
Add dsh-continuum to your Cordis configuration file:
plugins:
dsh-continuum:
storageMode: workspace # 'workspace' (.continuum/) | 'home' (~/.continuum/) | 'custom'
autoInjectContext: true
maxContextPackTokens: 8000
defaultLeaseTtlMinutes: 10
The 7 First-Party Continuum Tools
dsh-continuum exposes 7 first-party tools defined using @deepseek-ai/dsh-tools:
| Tool | Action Options | Description |
|---|
continuum_project | init, get, status, history, export | Initializes projects, updates North Star requirements, and exports backup bundles. |
continuum_task | create, claim, renew_lease, submit, verify, reopen, get | Manages task lifecycle, leases, deliverables, and 4-eyes verification. |
continuum_memory | record_finding, record_decision, ask_question, raise_conflict, attach_evidence, get | Records facts, architectural choices (with supersession), conflicts, and evidence. |
continuum_checkpoint | create, list | Captures named milestone snapshots for fast replay and rollback. |
continuum_handoff | create, get_latest | Transfers state cleanly from one agent role to another with context notes. |
continuum_context | render | Inspects or re-renders the active token-budgeted Context Pack. |
continuum_status | check | Diagnostics, lock status, lease expirations, and event log health. |
Concurrency & Actor Safety
- Authenticated Principal Enforcement: Actor identities (
id, role) are derived securely from exec.agent.id and runtime context; caller JSON cannot spoof principal IDs.
- Tool Concurrency Annotations: Safe read actions (
get, history, render, check) are declared isConcurrencySafe: true, while mutating operations are serialized.
Programmatic API Usage
You can also use Continuum directly in standalone Node.js / TypeScript code:
import { ContinuumEngine, FileSystemStorageBackend, StorageResolver } from 'dsh-continuum'
// 1. Initialize storage backend
const resolver = new StorageResolver({ mode: 'workspace' })
const storage = new FileSystemStorageBackend(resolver)
const engine = new ContinuumEngine(storage)
// 2. Initialize project & North Star
await engine.initProject('proj-alpha', 'Project Alpha', 'Core Engine', {
id: 'agent-orchestrator',
role: 'orchestrator'
})
await engine.setNorthStar(
'Build resilient distributed consensus',
['Linearizable reads', 'Crash recovery'],
{ id: 'agent-orchestrator', role: 'orchestrator' }
)
// 3. Create task with independent verification policy
const task = await engine.createTask({
title: 'Implement WAL Appender',
description: 'Write write-ahead log with fsync flush barrier',
acceptanceCriteria: ['Pass crash fault tests'],
verificationPolicy: 'independent' // Four-eyes principle
}, {
actor: { id: 'agent-orchestrator', role: 'orchestrator' }
})
// 4. Implementer claims task (lease issued)
const claim = await engine.claimTask(task.data.id, {
actor: { id: 'agent-implementer', role: 'implementer' }
})
console.log('Claimed task with lease:', claim.data.leaseId)
Task State Machine
Tasks strictly adhere to the following transition graph:
┌──────────┐
│ queued │
└────┬─────┘
│
┌────▼─────┐
│ ready │◄───────────────────────┐
└────┬─────┘ │
│ claimTask │
┌────▼─────┐ │
│ claimed │ │
└────┬─────┘ │
│ startTask │ (rejection / lease expired)
┌────▼─────┐ │
│ running │ │
└────┬─────┘ │
│ submitTask │
┌────▼─────┐ │
│submitted │ │
└────┬─────┘ │
│ verifyTask │
├───────────────┐ │
│ (passed) │ (rejected) │
┌────▼───────┐ ┌────┴────────┐ │
│ completed │ │ rejected ├─────┘
└────────────┘ └─────────────┘
Quality & Verification
dsh-continuum is thoroughly tested against the actual DeepSeek Harness runtime and Node.js 24:
- 14 Test Suites, 31 Automated Tests: 100% passing across unit, property, integration, and E2E tiers.
- Property-Based Invariant Testing (
fast-check): Verified sequence monotonicity, deterministic replay, and snapshot-tail equivalence across 100 randomized event streams.
- Zero Third-Party Code Bleed: Fully Permissive MIT License. Verified complete conceptual independence from non-permissive academic skills.
Run the test suite:
pnpm test
Inspect the full verification trace in docs/VERIFICATION.md and the end-to-end multi-agent scenario in docs/E2E-DEMO.md.
License
MIT License. See LICENSE and NOTICE.md for details.
