AGPA (Agent Player Achievements) for DeepSeek Harness — native achievement_* tools bridging the AGPA engine, plus automatic event tracking from dsh session events
The plugin will be installed here. Keep web if you are unsure.
npx -y @deepseek-ai/dsh plugin --profile web add github:eiainano/agpa-dsh-plugin#762acc1dbcc1b6cdcfe58ee6bb8f63f48fec66e8
Compatibility and provenance
Agpa Dsh Plugin is published as agpa-dsh-plugin and currently resolves to version 0.1.11. The Hub verifies its manifest and preserves the exact installation source for reproducible installs.
DSH compatibility
*
Runtime surfaces
any
Release source
github
Registry updated
Versions
0.1.11stable
Related plugins
Loading related plugins…
Related plugins
More verified plugins in integrations-communication.
Connects AGPA (Agent Player
Achievements) to DeepSeek Harness (dsh) as a Cordis plugin.
Design goal (maximum value per unit of code): the DSH side reimplements no
achievement logic. Every achievement_* tool is a thin shell that forwards its
arguments verbatim to the published AGPA MCP server (the agpa-mcp bin from
@eiainano/agpa). The AGPA engine, achievement definitions, profiles and the
~/.agent-achievements data store are therefore shared across Claude Code, DSH
and any other harness — so cross_agent achievements fire automatically.
Layers and files
Layer
File
Purpose
Entry (Cordis row)
src/index.ts + cordis.patch.yml
name='agpa', the patch id must match
Tool bridge
src/tools.ts
7 native achievement_* tool shells
MCP client
src/agpa-bridge.ts
Zero-runtime-dependency MCP-over-stdio (Node builtins only), lazily spawns one AGPA process
Auto-tracking
src/events.ts
Subscribes to dsh session/event, normalizes into CC-style payloads (source:'dsh')
Ingest subprocess
src/hook-runner.ts
Serially spawns short-lived agpa-hook auto processes, feeds them stdin
Model workflow manual
skills/agpa/SKILL.md
Teaches the model when to track / poll / announce unlocks
npm install --legacy-peer-deps # dev dependencies, for typechecking only
npm run typecheck # typecheck against the real @deepseek-ai/dsh-tools types
npm run build # tsc → lib/
npm run smoke:bridge # on-machine check of bridge ↔ AGPA MCP (read-only stats)
npm run install-skills # copy skills/agpa → ~/.agents/skills/agpa
npm pack # produce agpa-dsh-plugin-<version>.tgz
Installing into dsh
Published to npm as agpa-dsh-plugin.
# 1) add to a profile from the registry (a bundle layer; takes effect after restart)
dsh plugin --profile web add agpa-dsh-plugin
# 2) install the model workflow skill: the package ships skills/agpa, just copy it
# (when working from a git clone, use: npm run install-skills)
cp -r ~/.dsh/profiles/web/node_modules/agpa-dsh-plugin/skills/agpa ~/.agents/skills/
# 3) after restarting, check offline that the agpa row appears in the composed tree
dsh --profile web --dump-config | grep -A3 agpa
Local development (when editing the source):
npm run build && npm pack # prepack runs build automatically
dsh plugin --profile web add ./agpa-dsh-plugin-<version>.tgz
If the row appears but the tools do not, it is a code problem (check the dsh
logs); if the row never appears, it is a composition problem (the name did not
resolve, or files dropped cordis.patch.yml).
Environment variables
Variable
Purpose
AGPA_MCP_CMD
Override the AGPA MCP launch command (space-separated). Defaults to npx -y -p @eiainano/agpa@0.1.10 agpa-mcp. For local development, point it at tsx /path/to/agpa/src/main.ts
AGPA_AUTOTRACK=1
Enable automatic event tracking: one agpa-hook auto ingest process per normalized event
AGPA_HOOK_CMD
Override the ingest command (space-separated). Defaults to npx -y -p @eiainano/agpa@0.1.10 agpa-hook auto (works out of the box); for local development point it at tsx /path/to/agpa/src/cli/hook.ts auto
AGPA_DEBUG=1
Print AGPA MCP stderr plus every received event type ([agpa][ev]) and normalized payload ([agpa][autotrack])
DSH_AGENTS_HOME
Target skills root for install-skills (defaults to ~/.agents)
The bridge and ingest subprocesses always inject AGPA_TOOL_SOURCE=dsh, so
events are tagged with the correct tool source (stored as tool_source:"dsh",
coexisting with Claude Code's claude-code in the same store).
Status / roadmap
Phase 1 (this repo): 7 tool shells + MCP bridge (verified against the real AGPA engine — returns stats with tool_source=dsh) + SKILL
2026-09-09: verified end-to-end on a real dsh 0.1.2-rc.1: installed into both profiles with
dsh plugin --profile web|headless add <tgz>; a real headless task successfully called
achievement_stats, and the bridge returned real data from the shared store (75/212, level 6, 10,592 XP).
Phase 2 (this repo, 0.1.11 on npm): automatic event tracking, verified end-to-end
on a real machine and working out of the box.
events.ts subscribes to dsh session/event and normalizes tool/call + tool/result →
PostToolUse(Failure), and user/message (source.kind==='user') → UserPromptSubmit, into
CC-style payloads (source:'dsh'); each payload spawns one agpa-hook auto ingest process
(hook-runner.ts).
After a real headless run (Write/Bash), ~/.agent-achievements/profiles/neo/event.log gained
rows with tool_source:"dsh" — file.create / file.write / command.run / tool.complete
and friends.
Key gotcha found on the real machine: tool/result.data has no top-level callId
(only tool/call does); the call id needed for the ${turn}:${step}:${callId} correlation key
lives at result.data.message.source.callId (mirrored at content[].toolCallId). Event names
are always taken from the pinned dsh 0.1.2-rc.1 (session/event also broadcasts noise types
such as permission/preset and assistant/chunk, all of which are ignored).
AGPA 0.1.10 is published with the agpa-hook bin, so the plugin's default ingest command
npx -y -p @eiainano/agpa@0.1.10 agpa-hook auto works out of the box (verified with
AGPA_AUTOTRACK=1 alone). For local development you can still point AGPA_HOOK_CMD at a
checkout's tsx src/cli/hook.ts auto.
The ingest subprocess is spawned detached: a short-lived headless process exiting will not
SIGTERM an in-flight ingest (the first run has a cold-cache download and can be slow;
detaching guarantees no events are lost — long-lived web sessions were never affected).
Known caveats
dsh cannot start on this machine (fixed 2026-09-09, re-fixed 2026-09-15): the managed Node
runtime replaces its versioned prefix on upgrade (versions/22.22.2-2 →
versions/22.22.2-3), wiping any globals installed inside it. So dsh and pnpm no longer live
in that prefix — they live in the stable ~/.local/share/dsh-runtime. ~/.local/bin/dsh
reads the Node version dynamically from ~/.workbuddy/binaries/node/versions/current and puts
$DSH_HOME/bin (pnpm) plus that Node's bin on PATH. When installing a global package into
such a prefix you must invoke npm explicitly as
"$NODE" "$PREFIX/lib/node_modules/npm/bin/npm-cli.js" i -g <pkg> --prefix "$PREFIX",
otherwise the npm wrapper's shebang resolves to whatever node is on PATH.
Runtime resolution: an out-of-tree plugin's bare imports of @deepseek-ai/dsh-tools
(a value import) and @deepseek-ai/cordis (type-only) are mapped by the dsh host into the
in-box tree, and both resolve on 0.1.2-rc.1 (this plugin's defineTool value import is
verified by a real run).
DSH is a developer preview: cordis.patch.yml, the dsh field and event names can all
change between versions. package.json only declares @deepseek-ai/cordis as a peer (types
and closure injection are provided by dsh).
Event names are taken from the pinned version: the types this plugin subscribes to were
verified on the pinned 0.1.2-rc.1 (see Phase 2). If dsh is upgraded, check that version's
SessionEventMap first — do not copy the master docs.
The tool schemas use JSON-schema-style literals; AGPA does not currently do strict validation
of numeric ranges, and the descriptions state the allowed range.
If it will not install into a profile, first confirm that npm pack's files really includes
cordis.patch.yml.
npx
Phase 3: an optional dsh.client XP/achievement widget, or simply reusing the AGPA
dashboard (:3867).
