dsh-plugins

Composable, config-driven plugins for DeepSeek Harness (dsh). Each package is a publishable dsh bundle: install only what an agent needs, configure it through Cordis, and keep dsh itself unpatched.
Packages
| Package | What it does | Primary seams |
|---|---|---|
@amaster.ai/dsh-a2a |
Serves dsh agents over the A2A protocol 1.0 (JSON-RPC + SSE, opt-in HTTP+JSON/REST and gRPC, with v0.3 compatibility): all eleven standard operations, tool approvals, opt-in native inbox execution; pluggable task-state stores (memory/filesystem/Redis/GCS + workspace archive) | ctx.agents, session/event, approval/request, own protocol listeners |
@amaster.ai/dsh-storage |
Mirrors the session event stream into MySQL/PostgreSQL/SQLite/SQL Server (ai_messages / ai_chat_histories) |
session/event tap (local persistence stays authoritative) |
@amaster.ai/dsh-langfuse |
Langfuse observability: one generation per LLM call (plus a nested llm-request span with the verbatim loop-built request), one span per tool call or hook run, one trace per turn; subagent child sessions nested under the parent's tree |
llm/stream, tools/pre-execute → tools/result, session/event (including hook/*), session/created + subagent/start/subagent/end |
@amaster.ai/dsh-telemetry |
Unified OTel tracing for Langfuse or Phoenix, including request context, hooks, subagents and A2A tasks | Shared llm/stream, tool, session, hook, subagent and A2A collector → backend adapter → shared OTLP/HTTP protobuf |
@amaster.ai/dsh-policy |
Declarative tool-call policy: config-driven allow/deny/ask rules (tool name, args pattern, per-segment shell command prefix/regex, priority) — Gemini CLI-style policy files as plain plugin config |
tools/pre-execute waterfall (ask rides dsh's approval seam) |
@amaster.ai/dsh-subagent-filesystem |
Discovers Markdown specialist roles through the caller's filesystem and delegates through native in-process subagents | ctx.fs, scoped ctx.tools / ctx.systemPrompt, agent/created, ctx.subagents |
Plugin previews
dsh-a2a![]() |
dsh-storage![]() |
dsh-langfuse![]() |
dsh-policy![]() |
dsh-subagent-filesystem![]() |
dsh-telemetry![]() |
Status
This is an early dsh-preview ecosystem. The plugin shapes, config schemas, and seam choices are in place; event-payload field names are marked TODO(verify) where dsh pre-release APIs may shift. Pin your dsh version and check those markers before production use.
Compatibility
| @amaster.ai/dsh-* | dsh | cordis | @a2a-js/sdk (dsh-a2a) |
|---|---|---|---|
| 0.1.x | `>=0.1.5-rc.1 | >=0.1.6-alpha.1 |
dsh is in developer preview and will break compatibility between releases. Plugins declare the oldest compatible dsh version as a fixed peer floor and every release records the tested dsh version in this matrix; the floor moves only when a plugin starts requiring a newer dsh API. Installs ride dsh plugin add, which is pnpm-only — pnpm's peer matching has no prerelease gate, so any newer dsh (alpha or stable) satisfies the floor without warnings. npm consumers are gated differently: npm never lets a prerelease satisfy a range unless the range names that release tuple with a prerelease comparator, so the peer ranges also name the 0.1.6, 0.1.7, 0.2.0, 0.2.1, and 0.2.2 prerelease tuples. Drop each union member once that line ships a final release.
dsh-a2a inbox execution additionally tests the unmodified official DSH 0.2.2-rc.1 npm runtime. Its agent peer floor is >=0.2.2-rc.1, for initial model selection through agent options and the scoped model-switch notice hook. Queueing uses Agent.send; no core patch is required.
dsh-a2a's optional Goal integration consumes @deepseek-ai/dsh-goal >=0.2.0-rc.2 || >=0.2.1-alpha.1 || >=0.2.2-rc.1 and preserves official Goal round validation (tested with the Goal service and round driver at 0.2.2-rc.1).
dsh-a2a's approval bridge has an optional @deepseek-ai/dsh-user-approval peer floor of >=0.1.6-alpha.2 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1 (tested at 0.2.2-rc.1).
dsh-a2a requires @deepseek-ai/dsh-session >=0.2.1-rc.5 || >=0.2.2-rc.1 for the owner-scoped SessionStore.flush durability barrier used by native inbox operations and checkpointed invalidations. Optional subagent streaming also consumes the session lifecycle offset to distinguish new children from restored sessions.
dsh-langfuse's optional image display uses @deepseek-ai/dsh-attachment >=0.2.0-rc.1 || >=0.2.2-rc.1 (tested at 0.2.2-rc.1); metadata-only tracing does not require an attachment backend.
dsh-subagent-filesystem requires @deepseek-ai/dsh-subagent >=0.2.1-rc.2 || >=0.2.2-rc.1 (tested at 0.2.2-rc.1) and the native in-process spawn provider. It supports foreground reports and continuable background children; Markdown definitions cannot override models, tools, or permissions.
dsh-telemetry tests the same dsh 0.2.2-rc.1 collector with OTel API 1.9.1, SDK/resources 2.10.0, and OTLP/HTTP protobuf exporter 0.221.0. It needs no Langfuse SDK. See its README for backend server/version limits, project configuration and migration; enable one collector per profile.
Install
Every package is a dsh bundle and ships a cordis.patch.yml. With the dsh CLI:
dsh plugin --profile my-agent add @amaster.ai/dsh-a2a @amaster.ai/dsh-storage @amaster.ai/dsh-langfuse
dsh --profile my-agent
For local development from this checkout, use a --patch overlay instead (no packaging needed):
# dev.patch.yml
- insert:
- id: langfuse
name: file:///absolute/path/to/dsh-plugins/packages/dsh-langfuse
dsh --profile my-agent --patch dev.patch.yml
Configuration
All plugins are disabled by default and configured through the standard dsh plugin config layer (Schemastery-validated, hot-reloaded). Example profile cordis.patch.yml snippet:
- insert:
- id: langfuse
name: '@amaster.ai/dsh-langfuse'
config:
enabled: true
publicKey: pk-lf-...
secretKey: sk-lf-...
baseUrl: https://cloud.langfuse.com
- 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
- id: a2a
name: '@amaster.ai/dsh-a2a'
config:
enabled: true
host: 127.0.0.1 # no auth built in — keep loopback or front with a proxy
port: 41241
cwd: /srv/agent-workspaces
taskStore: redis # memory | filesystem | redis | gcs — A2A task state only
filesystem:
root: /srv/dsh/a2a-tasks
redis:
url: redis://127.0.0.1:6379
gcs:
bucket: my-agent-archives
- id: policy
name: '@amaster.ai/dsh-policy'
config:
enabled: true
rules:
- tool: bash
decision: deny
commandPrefix: npm
priority: 200
message: 'npm is not allowed. Use bun instead.'
- tool: '*'
decision: allow
priority: 20
Data model
dsh-storage's relational shape matches the source project's ai_messages / ai_chat_histories tables, so existing data stays compatible (one deviation: no user_id column — tenancy rides on session_id). It requires Prisma 7 peer packages at runtime: @prisma/client plus the driver adapter for your database (@prisma/adapter-mariadb for MySQL, @prisma/adapter-pg for PostgreSQL, @prisma/adapter-libsql for SQLite, @prisma/adapter-mssql for SQL Server). The PrismaClient is pre-generated per provider and shipped in the package — no prisma generate step. 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
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 (derived from provider: sqlserver; SQL Server's ISJSON / JSON_VALUE still query the text as JSON).
ai_messages— user/model rows withthoughts,tokens,tool_calls,agent_id,metadataJSON columns and soft-delete; tool results update the matching model row'stool_calls.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 (the source project's metadata.id JSON-path lookup only works on PostgreSQL/MySQL). Session rows are matched by session_id and keep their cuid primary keys — the per-session serialization chain makes the find-then-write safe, and rows from the early scaffold (or the source project) are continued, never duplicated. Upgrade note: the early scaffold wrote messages with cuid keys; if you ran it, dedupe those by metadata.id before enabling this version.
Task updates use standard A2A streaming/subscriptions, snapshots, and optional official SDK Push Notifications. Enable pushNotifications: true to let clients register standard task webhooks.
Native inbox mode is opt-in and uses the official DSH APIs; it is tested with the unmodified 0.2.2-rc.1 npm runtime. See native inbox execution for queueing, steering, pause/recovery semantics and the runtime integration checks.
Opt into inbox: { enabled: true, shutdown: retain-pending } to retain unclaimed A2A steering and future turns across graceful host restarts. Retain both the session persistence and TaskStore storage; hosts still discover and wake eligible work. Explicit cancellation and context clearing remain terminal. See the shutdown contract.
A2A task snapshots are separate from the full conversation log: dsh-a2a ships pluggable TaskStore backends — in-memory (default), filesystem (private atomic JSON snapshots), Redis (task JSON + TTL), and GCS (gzipped task JSON). The snapshots retain A2A history and artifacts at task-state transitions; dsh-storage separately records the full conversation. Streamed text deltas stay in process until the next state change, so token-rate events never reach Redis or GCS. Redis and GCS keys are scoped to the A2A tenant and user; older unscoped records require migration or expiry.
Security
dsh ships no authentication or authorization. dsh-a2a binds 127.0.0.1 by default; if you expose it, put an authenticated reverse proxy in front and treat every agent as running with the host process's OS privileges. Multi-tenant deployments need per-tenant isolation (containers) on top.
Repository layout
packages/
├── dsh-a2a/ # A2A protocol server plugin
├── dsh-storage/ # session storage mirror plugin (+ prisma schema)
├── dsh-langfuse/ # Langfuse observability plugin
├── dsh-telemetry/ # Unified Langfuse/Phoenix tracing
└── dsh-policy/ # declarative tool-call policy plugin
Development
pnpm install
pnpm build # tsc per package
pnpm typecheck
pnpm test # vitest (packages with a test script)
pnpm test:performance # deterministic budgets + JSON results; no credentials
pnpm test:performance:network # real loopback HTTP/SSE/gRPC and attachment paths
pnpm test:performance:database # disposable SQLite benchmark
pnpm test:performance:combined # real A2A + storage + telemetry + policy, synthetic agent
The Performance workflow runs the Performance budgets check without model or backend credentials. It reuses focused unit-test modules with mocked backends, then benchmarks the real telemetry plugin/exporter against a loopback OTLP receiver in separate processes.
| Area | Workload and checks |
|---|---|
| Slow consumers | 100/10,000 frames in byte/object streams; bounded backlog and listener cleanup |
| Task discovery | 100/1,000 large Redis/GCS snapshots; bounded prefix reads, page-only hydration, recovery without full downloads, GCS concurrency |
| Subscriptions | 10/1,000 subscribers per context across eight contexts; shared checkpoints and disposal cleanup |
| Storage | Up to 1,024 tool results; bounded batching and cache lookups; a 512-message blocked burst alongside 16 other sessions; paginated SQL lookup/archive |
| Telemetry streams | Eight concurrent 256/16,384-chunk streams; bounded serialization/masking and unchanged delivery |
| Lifecycle | 32 plugin lifecycles with 32 sessions each; no leftover fake-clock timers or late event handling |
| Slow exporters | 1,000 LLM calls while exports stall; pinned OTel queue/batch limits, failure/timeout handling and unload completion |
| Large payloads | Up to 10,000 entries, 64-level JSON and split credentials; bounded traversal/bytes and preserved redaction on both adapters |
| Policy scale | 10/1,000 candidate rules and 1,000 shell substitutions; one argument serialization and one args check per candidate, preserving deny decisions |
| Protocol load | 64 requests each over HTTP, SSE and gRPC at concurrency 1/16/64; first-frame/request percentiles, throughput and event-loop delay; 32 concurrent subscription cancellations plus running-executor cancellation over SSE/gRPC |
| Attachments/media | 24 MiB real chunked download, 64 MiB cap refusal and cancellation without leftover files; 128 images sharing a 4 MiB read budget, including ignored-read cancellation |
| Real databases | 1,000/5,000 rows, oldest tool-call lookup, query plans, 32 concurrent reads and archive verification on SQLite/PostgreSQL; PostgreSQL additionally saturates a two-connection fixture pool and the actual backend pool with 32 locked writes, and verifies a single row-lock wait leaves other reads available |
| Combined plugins | A2A alone versus A2A + Storage + Telemetry + Policy over real HTTP/SQLite/OTLP, with eight warmup tasks and 64 measured tasks at concurrency eight; verifies policy rejection, all 144 message rows and 72 exported generations |
performance-results.json records unit-test outcomes and durations.
performance-metrics.json compares disabled telemetry with content capture off/on
for both Phoenix and Langfuse. Each mode runs in a fresh Node process: 16 warmup
turns, then five samples of 64 turns with 128 chunks each. The report includes
startup, streaming, flush and shutdown time, CPU usage, turns/second, sampled heap,
post-GC retained heap growth, process peak RSS and ratios against disabled mode.
The receiver runs outside the measured worker, so its CPU is excluded.
The workflow also uploads performance-network.json, performance-media.json,
performance-database-sqlite.json, performance-combined.json and the transport
test report. The separate PostgreSQL job uploads performance-database-postgresql.json.
Combined-plugin CPU includes its co-located client/server/receiver; it is a total
fixture observation, unlike the isolated telemetry worker measurements.
SQLite runs in temporary WAL databases. PostgreSQL uses a disposable CI service;
local runs require an explicit loopback database named dsh_performance:
DSH_PERFORMANCE_DB_PROVIDER=postgresql \
DSH_PERFORMANCE_DB_URL=postgresql://postgres:performance-only@127.0.0.1:5432/dsh_performance \
pnpm test:performance:database
Performance reports are retained for seven days. Capacity and work limits fail the check; hardware-dependent timing/memory figures are observations without fixed thresholds. The agents and responses are synthetic, even in the real transport/database tests. Reports do not establish production capacity or leak freedom. Query plans are recorded rather than required to choose a particular index on a small fixture; MySQL/SQL Server performance, real image decoding and production-network behavior are not covered by these benchmarks.
Real-model performance is collected by the existing Integration workflow.
A CI-only llm/stream observer reuses the scenarios' existing calls, including
retries, tool rounds and subagents. Each scenario's E2E artifact includes
model-performance.json, with a summary in the job summary. The report groups by
requested model/provider and purpose, retaining each attempt's outcome, stream
duration, first-token latency, input/cache/output/reasoning token counts and
observed output rate. No extra model requests are made.
Times are measured at the dsh stream boundary, include consumer pacing and exclude profile startup and tool execution between calls. First-token detection includes non-empty text/reasoning and meaningful tool-call deltas. Output rate uses the provider's output-token count (reasoning is already included) divided by elapsed time from the first token to stream closure. Missing usage or token timestamps remain null; an early-cancelled scenario may have no observed calls. The observer records neither prompts, replies, arguments, headers, URLs nor credentials. These measurements are observations, without fixed gateway-latency thresholds.
Current limitations
All plugins are disabled by default; enable and configure each explicitly in the profile.
dsh-a2aretains no event replay for subscriptions:SubscribeToTaskopens with the current task snapshot and follows the live bus only. Resuming a dsh session after restart requires the optionalsessionPersistenceservice.dsh-a2aGCS store: workspace archiving (archiveWorkspace) shells out totarand is not wired to the task lifecycle yet.
License
MIT






No comments yet. Be the first to write one.