@amaster.ai/dsh-storage

Session storage mirror for DeepSeek Harness (dsh): projects the session/event stream into MySQL/PostgreSQL/SQLite/SQL Server (ai_messages / ai_chat_histories, same tables as the source project) without replacing dsh's local persistence — local files stay authoritative, this is a mirror.

Use it when a dsh profile needs durable, queryable session data in an existing relational database while preserving the runtime's local session store as the source of truth.

Install

dsh plugin --profile my-agent add @amaster.ai/dsh-storage

Runtime peers: @prisma/client (Prisma 7) plus the driver adapter for your database:

The PrismaClient is pre-generated per provider and shipped in the package — no prisma generate step for consumers.

Configuration

Disabled by default. Configure via the profile's cordis.patch.yml:

- insert:
    - id: storage-mirror
      name: '@amaster.ai/dsh-storage'
      config:
        enabled: true
        database:
          enabled: true
          provider: mysql   # mysql | postgresql | sqlite | sqlserver
          url: mysql://user:pass@host:3306/agent

Create or upgrade the tables with the shipped schema variant:

npx prisma db push --schema node_modules/@amaster.ai/dsh-storage/prisma/schema.mysql.prisma --url "mysql://user:pass@host:3306/agent"
# schema.postgresql.prisma / schema.sqlite.prisma / schema.sqlserver.prisma work the same way

Only message, tool-result, assistant-attempt, turn-end, title, and successful compaction events enter the mirror queue; unrelated lifecycle records do not trigger database reads or retries. Failed initialization retries share a one-second delay across sessions. Valid queued events wait through that delay, and session flush/unload still drain their ordered work. Database operation failures continue to be logged and swallowed; local DSH persistence remains authoritative.

Adjacent queued tool results for the same assistant row are merged before writing, with at most 32 events per batch and no debounce timer. Different messages and intervening mirrored events preserve queue order. Session flush, archive, disposal, and plugin unload seal and drain earlier batches. Full result rows are not kept in a new persistent cache. This reduces repeated reads/writes; the queue can still grow when incoming data outpaces the database.

Data model

• ai_messages — user and model rows, with thoughts, tokens, tool_calls, agent_id, metadata JSON columns and soft-delete. A tool/result updates the matching model row's tool_calls entry by call ID; it does not create a type=tool row.
• ai_chat_histories — per-session rollup (message count, total tokens, first/last message timestamps).

The logical message id rides in metadata.id; message rows use a deterministic hash of (session_id, message id) as their primary key, so re-projected events upsert in place rather than duplicate — on every connector. Session rows are matched by session_id and keep their cuid primary keys. One deviation from the source project: no user_id column — tenancy rides on session_id.

For user/message rows, content remains the text projection, while metadata.message retains the original user message as received, including source and ordered content blocks. Image/file blocks keep whatever attachment reference, path, URL, or inline data the incoming message actually contains; this mirror does not fetch or rewrite attachments. Re-projection writes the same raw message into the existing row.

The tool_calls array retains dsh's tool-call blocks (id, name, arguments); the matching entry gains the structured result block and, on failure, an error identity. Live call IDs are cached, and restored calls can resolve their message ID from the model surface: both paths read one message primary key. Older calls are searched in keyset pages of at most 100 ID/tool-call candidates, matched in the plugin and discarded before fetching the next page. Tool-result lookup SQL does not search JSON, join tables, or nest SELECT statements. Duplicate results update the same row and do not increment message counts. Existing historical type=tool rows are left intact.

When an assistant message contains dsh reasoning blocks, thoughts is an array of { content } entries in block order. If the adapter supplies a matching signature in the message's source.replayState.blocks, that entry also carries thoughtSignature. The full model source, including opaque replayState, is preserved in row metadata for lossless provider replay. The backend's readMessages() also accepts older { description } entries and JSON string thoughts, returning them as { content }. subject and a per-thought timestamp are not invented when the upstream message does not supply them.

SQL Server note: Prisma's sqlserver connector has no Json type, so its variant maps the JSON columns to text — the backend serializes them on write automatically (SQL Server's ISJSON / JSON_VALUE still query the text as JSON).

Mirroring is a no-throw seam: backend errors are logged with a [dsh-storage] prefix and never escape into the agent loop.

Successful native compaction/end events also write a utility_compressor message. Its content is the source-compatible Content[] JSON array of the complete surviving conversation: summary plus retained tail, with tool calls/results paired by ID. System prompts are excluded. The surface is captured at the event, before asynchronous database writes; failed/canceled compactions leave the previous snapshot intact. Snapshot rows do not increment the visible message count. Adjacent messages with the same role merge their ordered parts, since the legacy reader would otherwise skip the retained tail.

Consumers can resume from the latest active compression snapshot plus later message rows. Snapshots and newly mirrored rows include metadata.sessionCreatedAt and metadata.seq to distinguish resumed session generations and messages in the same database second. Older snapshots without this metadata retain their creation-time boundary. The mirror does not fetch attachments or invent usable paths/URLs from opaque attachment IDs. Attachments, developer updates, extension blocks and non-object tool arguments are preserved as labelled JSON data in text parts when legacy Content[] cannot represent them natively. Such snapshots preserve reference information, not attachment bytes or a complete native session/tool registry. Attachment bytes still need their existing durable storage. An unchanged legacy reader remains timestamp-based; it must consume the sequence metadata to distinguish later messages in the same database second.

Archive a session

When handling a session-clear request, call await ctx.get('dshStorage').archiveSession(sessionId) after stopping the live turn. It waits for queued mirror writes, then transactionally assigns all current, non-deleted ai_messages rows (history_id IS NULL) to a non-deleted ai_chat_histories row. The returned history ID can be used to query those rows directly from the database; a second call with no active messages returns null. A database failure rejects this explicit operation instead of reporting a successful clear.

Archived rollups stay queryable. The plugin recognizes an active rollup as a history row with no associated messages, so the next projected event creates a fresh rollup instead of overwriting the archived one. The caller owns stopping/replacing the dsh session surface and any A2A task state; this operation only archives the database mirror.

Compatibility

Pinned dsh/cordis versions live in the root compat matrix. Event payloads ride pre-release dsh APIs — check the TODO(verify) markers in src/ before upgrading dsh.

License

MIT