dsh-postgres

中文 · Architecture · Deployment

A community PostgreSQL session-persistence plugin for DeepSeek Harness. It implements the native SessionPersistence / SessionHandle contract, with namespace isolation and a connection pool that can be shared by many DSH roots.

Status: 0.1 alpha. Source is available here; this package has not been published to npm. Type checking and compilation do not establish runtime correctness. PostgreSQL integration, failure recovery, and full DSH host flows have not yet been verified. See limitations.

Scope

The plugin persists session headers, append-only native events, fork lineage, and inherited-event counts. Native events include conversation messages and tool calls/results. It does not replace DSH's UI, agent loop, or session behavior.

Data or concern	Owner
Native session headers and events	This plugin / PostgreSQL
Namespace selection and authorization	Authenticated host application
Workspace state, projection caches, settings	Existing DSH storage providers
Attachment bytes	Attachment provider / object storage
Accounts, billing, credentials	Host's existing services
In-flight model requests and live processes	Runtime, not the persistence plugin

Compatibility

Dependency	Initial target
Node.js	22.18+
@deepseek-ai/cordis	~4.0.5
@deepseek-ai/dsh-session	0.2.1-rc.3
@deepseek-ai/dsh-session-persistence	0.2.1-rc.3
PostgreSQL	16+ deployment target; runtime verification pending

DSH packages are pinned deliberately: prerelease API versions are not interchangeable. latest on npm can point to an older DSH API. This package does not implement the older PersistenceCoordinator interface or migrate historical DSH session formats.

Build and install from source

git clone https://github.com/velobase/dsh-postgres.git
cd dsh-postgres
npm ci
npm run typecheck
npm run build
npm pack

Install the resulting velobase-dsh-postgres-0.1.0-alpha.1.tgz into the DSH host's package environment. Build output contains ESM JavaScript and TypeScript declarations. No registry publishing happens during build or packing.

Supply DSH_PG_URL through your shell or secret manager, then explicitly install the schema before starting the host:

node dist/migrate.js

DSH_PG_SCHEMA optionally changes the default dsh_postgres schema. The migration is transactional, serialized across deployers, and safe to repeat. Runtime initialization validates the schema version and never runs DDL.

Mount in a single-user host

The host must already provide ctx.sessions. Replace its existing sessionPersistence provider in the host composition; do not mount two providers for the same service.

import PgSessionPersistence from '@velobase/dsh-postgres'

ctx.plugin(PgSessionPersistence, {
  connectionString: process.env.DSH_PG_URL!,
  namespace: 'personal',
})

The default export is a native Cordis service plugin. Bundle/profile assembly remains the host's responsibility. Mounting the package in a specific desktop, CLI, or Web bundle requires that host's normal composition mechanism.

Share one pool across authenticated accounts

import { PostgresDatabase, createPostgresSessionPlugin } from '@velobase/dsh-postgres'

// Once per application process, before accepting requests.
const database = new PostgresDatabase({
  connection: { connectionString: process.env.DSH_PG_URL },
})
await database.ready() // Schema must already be migrated.
const SessionPlugin = createPostgresSessionPlugin(database)

// When composing an authenticated account's DSH root:
accountContext.plugin(SessionPlugin, { namespace: `account:${authenticatedAccount.id}` })

// Shutdown: dispose the account contexts first, then:
await database.close()

All data queries and writer leases use (namespace, session_id). A namespace is immutable for a service instance and must come from trusted host identity, not a browser-supplied tenant parameter. This is application-level isolation; there is no PostgreSQL RLS policy in this version.

No separate database, schema, pool, or server is required per user. Writer leases are renewed by one loop per shared database object. Idle write handles do not hold checked-out SQL connections.

An existing pg.Pool can be supplied as { pool } instead of { connection }. The caller retains ownership of that pool; database.close() does not end it. Do not close the shared database when an individual account disconnects.

Guarantees and failure semantics

• create commits the header immediately; empty sessions survive a restart.
• append commits a contiguous batch and its revision atomically, with synchronous_commit=on. Durability also depends on PostgreSQL/WAL configuration.
• flush drains native live-event writes and verifies current write ownership.
• Reads use a consistent MVCC snapshot from the primary database.
• Each write transaction checks the namespace, owner token, and lease expiry.
• Expired writers cannot revive themselves. A failed/uncertain write stops its handle; reopen to inspect the committed prefix before deciding how to recover.
• The default lease duration is 60 seconds, renewed every third of that period. After a crash, another process can claim the session once the lease expires. This is failure detection, not a limit on model execution time.
• Event payloads are stored as lossless JSON text. NUL characters and lone UTF-16 surrogates remain escaped; they are not removed to satisfy JSONB.

See architecture for transaction and resource boundaries.

Limitations

• No automated runtime test suite or database integration verification yet.
• No UI, HTTP API, account authentication, RLS, or untrusted-plugin sandbox.
• No import from JSONL or other PostgreSQL plugins, and no automatic log-format migration.
• No workspace/KV, search, projection-cache, credential, attachment, or spill backend.
• Moving session persistence alone does not make an entire DSH deployment disk-free.
• DSH's native list() returns all visible sessions. Public HTTP APIs should paginate separately; the plugin does not silently truncate native results.
• Full-log reads validate all events. Large-history performance is unmeasured.
• A stored conversation can be reopened after a restart; an in-flight tool or model request is not automatically resumed. Persistence leases do not fence external tool side effects.

Contributing and attribution

Read CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md. Keep commits focused and independently reviewable. The repository's dependency override and host obligations are documented in the deployment guide.

MIT licensed. The design builds on the public DeepSeek Harness and agentserver PostgreSQL implementations; see NOTICE for pinned source references and retained copyright notices. This is an independent community project.