QuantumKuba/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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. Four-Eyes Separation of Duty: Configurable task verification policies (independent, dual, redteam) mathematically forbid the agent who implemented a task from self-verifying it.
8. 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.
9. 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.
10. 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

dsh plugin --profile web add dsh-continuum

(Or during local development: dsh plugin --profile web ln /path/to/dsh-continuum)

Web UI "Plugin Configuration" & settings.yaml

dsh-continuum integrates seamlessly with DeepSeek Harness's @deepseek-ai/dsh-settings service. You can configure it visually in the DSH Web UI under Plugin configuration, or in ~/.dsh/settings.yaml:

dsh-continuum:
  autoInjectContext: true        # Automatically inject Context Pack into system prompts
  maxContextPackTokens: 8000     # Maximum token budget for Context Pack
  defaultLeaseTtlMinutes: 10     # Task execution lease TTL before sweep
  storageMode: workspace         # 'workspace' (.continuum/) | 'home' (~/.continuum/) | 'custom'
  customStoragePath: ""          # Custom directory if storageMode is 'custom'

Changes made in the Web UI take effect immediately in real time without restarting the server.

Bundle Layer Stack (cordis.patch.yml)

The package includes cordis.patch.yml for automated profile layer patching:

# dsh bundle patch: inserts dsh-continuum into a profile's layer stack.
- insert:
    - id: dsh-continuum
      name: dsh-continuum
      config:
        storageMode: workspace
        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.