Provides a "Fake LLM" channel for DeepSeek Harness: uses scripts to make agents skip real model calls and instead trigger preset tool invocations based on JSON/JSONL playbooks, for offline testing, teaching demos, and CI regression.
- Language
- Python
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add dsh-mockRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin Ephemeral-AI-Lab/dsh-plugins/mock for me: review the repository at https://github.com/Ephemeral-AI-Lab/dsh-plugins first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
The repository sub-path corresponding to the landing page is
mock, npm package namedsh-mock(mock/package.json:2-4), one of the sub-packages under theEphemeral-AI-Lab/dsh-pluginsmonorepo. This wiki focuses on the capabilities corresponding to themockpath.
One-line Positioning
Register a "fake LLM" channel for DeepSeek Harness, allowing agents to trigger preset tool calls according to your script without calling real models, used for offline reproduction, automated testing, and teaching demonstrations.
Core Capabilities
- Register internal-only provider/model
mock/mock(src/index.ts:132): Used by AgentLoop to replace "LLM output" with pre-arranged "tool call flow"; the real model selector doesn't display it. - Provide
/mockslash command (src/index.ts:133-145): The command handler simply puts the entire line back into the session inbox as a user message, letting the normal AgentLoop execute it—no host logic bypassed. runsubcommand: Writetool({"k":"v"})in the input box to trigger a single tool call, or write[a({...}),b({...})]to trigger a group of parallel calls (src/parser.ts:71-108).replaysubcommand: Read pre-arranged scripts from local files and replay step by step (src/parser.ts:111-132), with optional--overwrite-wait-time-ms Nto override all explicit waits in the script (src/converter.ts:134-160).- Supports two replay source formats: canonical
dsh-mock-scriptJSON and native DSH JSONL session logs, auto-detected and converted (src/converter.ts:172-251,src/index.ts:341-360). - Push status to host UI in real-time: Render a compact Mock status dock above the conversation input, showing current step, total steps, and whether waiting for tool receipt (
src/client/index.ts:19-26,src/client/MockStatusRow.tsx:90-92). - Status exposed via
mockStatusprojection (src/projection.ts:34-57); deactivation or abort writes it ascancelled, recognized as expired on next session resume.
Technical Implementation
- Language: TypeScript (
tsconfig.json:3-21strict mode, targetES2024/NodeNext) - Key Dependencies:
@deepseek-ai/dsh-llm(>=0.1.0-rc.5): ExtendLlmAdapterto register internalmockroute@deepseek-ai/commands(>=0.1.0-rc.6): Usectx.commands.registerto register/mock@deepseek-ai/cordis(>=4.0.0): Host plugin framework, listen toagent/pre-step/agent/request/agent/error/agent/disposedevents@deepseek-ai/dsh-session-projection(>=0.1.0-rc.6): RegistermockStatusprojection to fold state to client@deepseek-ai/dsh-client-ui-slots+@deepseek-ai/dsh-client-ui-conversation+@deepseek-ai/dsh-client-runtime: Inject MockStatusDock intoconversation.input.dockslotreact(>=18.2.0): Status row is a React componentzod(^4.4.3): Projection schema strict validation
- Architecture Pattern: Cordis plugin,
cordis.patch.ymldisablesdirectory-pickerand injectsmockinto host plugin directory (cordis.patch.yml:1-9).apply(ctx)registers aMockAdapterforprovider:'mock', then registers/mockcommand and intercepts/mock …text viaagent/pre-stephook to submit as plan; adapter internally producesStreamChunkstep by step according to compiled script, executed normally by host AgentLoop. - Entry File:
mock/src/index.ts(export name = 'mock',inject = ['llm','commands'],src/index.ts:29-30), client entry ismock/src/client/index.ts
Use Cases
When you need DSH agent to trigger tool calls according to a fixed script without consuming real model quota—for example, replaying a DSH JSONL recording as a regression test case, demonstrating agent-tool interaction flow to newcomers, or running an end-to-end verification in an offline environment for CI—all can use this plugin; as long as you can write a canonical JSON or use existing session logs, /mock replay one line can replay everything.
Prerequisites and Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
@deepseek-ai/cordis | >=4.0.0 | peerDependencies, host plugin framework |
@deepseek-ai/dsh-llm | >=0.1.0-rc.5 | peerDependencies, required for registering LLM adapter |
@deepseek-ai/dsh-commands | >=0.1.0-rc.6 | peerDependencies, required for registering /mock command |
@deepseek-ai/dsh-agent | >=0.1.0-rc.6 | devDependencies, holds Agent instance at runtime |
@deepseek-ai/dsh-session + @deepseek-ai/dsh-session-projection | >=0.1.0-rc.6 | peerDependencies, write mock/status events and expose projection |
@deepseek-ai/dsh-client-runtime + @deepseek-ai/dsh-client-locale + @deepseek-ai/dsh-client-ui-conversation + @deepseek-ai/dsh-client-ui-slots | each >=0.1.0-rc.6 | peerDependencies, package.json:27-35 lists these four under dsh.client.inject, missing any will cause Web dock to fail loading |
react | >=18.2.0 | peerDependencies, status row component runtime |
zod | ^4.4.3 | devDependencies, projection schema validation |
| Platform | DSH Web | package.json:28 explicitly declares dsh.client.platform: "web", not declared for CLI/desktop |
| Node.js | Not declared | No engines field in package.json; @types/node ^22.20.0 in devDependencies |
| Native modules | None | Only pure JS packages, no node-gyp build items |
Installation
dsh plugin --profile web add github:Ephemeral-AI-Lab/dsh-plugins/mock
Configuration
This plugin requires no additional configuration. It doesn't read any environment variables or ctx.config, and has no config file; the only "configuration surface" is determined by /mock command arguments:
| Command / Parameter | Location | Type | Description | Default |
|---|---|---|---|---|
/mock run <tool({...})> or /mock run [a({...}),b({...})] | Input box | One or parallel group of tool calls | Inline trigger; multiple tools must be in [ ] (src/parser.ts:80-100) | None |
/mock replay <path> | Input box | Absolute path or path relative to session working directory | Read script and replay step by step; relative path requires session's current header.cwd to be set (src/index.ts:362-368) | None |
--overwrite-wait-time-ms <N> | End of replay command | Non-negative integer | Override milliseconds for all explicit wait steps in script (src/converter.ts:134-148) | If not passed, keep original values from script |
FAQ
Q: After installation, can I directly select "mock" from the model dropdown?
A: No. The mock route is intentionally hidden from the externally exposed model directory (README.md:21-28); regular model selectors won't list it; the only way to activate it is via slash commands like /mock run or /mock replay.
Q: What's the difference between /mock run and /mock replay?
A: run is inline trigger—write tool({"k":"v"}) or [a({...}),b({...})] directly to let the agent execute immediately, used once and discarded in the session; replay reads from a local script file and replays a pre-arranged script step by step, suitable for fixed-scenario regression testing. Both internally use the same MockAdapter, differing only in script source (src/index.ts:312-339).
Q: What file formats does the replay script support?
A: Two types: (1) canonical dsh-mock-script JSON—{"type":"dsh-mock-script","version":1,"steps":[…]}, steps can be tool, parallel, or wait; (2) native DSH JSONL session logs—starting with {"type":"session"}, converter automatically folds out tool calls and assembles canonical script (src/converter.ts:172-251). ZIP archives passed directly will be explicitly rejected; you need to unzip and extract session.jsonl first (src/replay-input.ts:9-17).
Q: Will tool calls triggered by mock be recorded normally by the host?
A: Yes. MockAdapter only produces StreamChunk; tool lookup, parameter validation, authorization, execution, result writeback, and persistence all go through the host AgentLoop and ToolRuntime pipeline (src/mock-adapter.ts:89-95); the session event log shows regular entries like tool/call, tool/result, turn, etc.
Q: After a mock turn ends, will the next session automatically continue with the real model?
A: Yes. The agent/request hook records the real provider/model used in the previous session; after the mock turn completes, the next normal turn automatically restores it (src/index.ts:217-247), no manual switching needed.
Q: How to uninstall mock?
A: Use dsh plugin --profile web remove to remove the installation source. During effect cleanup, it calls adapter.dispose(), unregisters /mock command and llm adapter, and clears session-level state cache (src/index.ts:282-293).
Learning Curve
Advanced — Triggering a single call with /mock run tool({...}) is simple for beginners, but meaningful replay (writing canonical JSON or exporting JSONL) requires understanding DSH session event structure first; and you need to understand how the agent's internal provider/model switching mechanism works to troubleshoot when errors occur.
Known Issues and Limitations
- v1 is in unstable release: Commands, API, and UI of
[email protected]may change before stable version (README.md:3-5). - Directly passing ZIP packages as replay source will be rejected:
ReplayInputError(UNSUPPORTED_ARCHIVE)prompts to unzip and extractsession.jsonlfirst (src/replay-input.ts:3-17). replaymode explicitly rejects nested/subagent tools: When tool name matches regex(?:^|[-_])(nested|subagent|agent[-_]spawn|spawn[-_]agent)(?:$|[-_]), it directly throwsUNSUPPORTED_NESTED_TOOL(src/index.ts:370-375).- Inline
/mock rundoesn't supportwaitsteps—waitsyntax can only be used in canonical scripts (src/parser.ts:92,103). - Only declares
dsh.client.platform: "web"(package.json:28), CLI/desktop availability not explicitly clear in source. - Canonical script version is locked to
1; other versions will be rejected byMockScriptError(INVALID_SCRIPT)(src/converter.ts:84-85). - MockAdapter only produces chunks, doesn't execute: If the host's ToolRuntime doesn't recognize tool names in the replay script,
tool/callevents will appear but the host side will report "unknown tool"—mock itself won't "fabricate" tools out of thin air.
Small, focused plugins that make DeepSeek Harness more capable, expressive, and pleasant to use.
Quick start · Packages · Development · Documentation
🧠 Give your DSH sessions better tools, durable workflows, and a cleaner path from idea to execution.
⚡ Quick start
Published plugins install directly into a DSH profile with one command. The
examples below target the web profile; replace web with the profile you use.
🐚 Codex Terminal
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
🔐 Codex Coding Plan
Reuse an existing file-backed codex login from the DSH Models page:
dsh plugin --profile web add ./coding-plan/codex
# Grok Coding Plan models from the existing `grok login`
dsh plugin --profile web add ./coding-plan/grok
⏰ Loop
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
🧪 Mock — unstable
dsh-mock is published for early testing. Its commands, API, and UI may
change before a stable release.
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
🧭 Sessions
Inspect, create, read, and message DSH sessions with the current session tools:
# With the DSH CLI:
dsh plugin --profile web add [email protected]
# Without the `dsh` CLI:
npm install [email protected]
Restart DSH and create a new session after installing a plugin. If dsh is not
on your PATH, run the same command from a DeepSeek Harness source checkout with
pnpm dsh instead.
Direct npm installation downloads the package for use by your project. DSH profile installation is still required when you want DSH to load the plugin as part of a profile.
📦 Packages
| Package | Status | What it adds | Docs |
|---|---|---|---|
dsh-codex-coding-plan | 🧪 Local · 0.1.0 | Reuses a file-backed Codex ChatGPT login through the existing openai-codex pi-ai provider. | README |
dsh-grok-coding-plan | 🧪 Local · 0.1.0 | Reuses a file-backed Grok subscription login through the existing xai pi-ai provider. | README |
dsh-codex-terminal | ✅ Published · 0.1.3 | Codex-compatible exec_command and write_stdin tools with persistent command sessions. | README · npm |
dsh-loop | ✅ Published · 0.1.3 | Session-scoped recurring alarms, loop tools, slash commands, and a web UI. | README · npm |
dsh-mock | ⚠️ Unstable · ✅ Published · 0.1.0 | Deterministic mock model turns and replay commands routed through the real DSH AgentLoop and ToolRuntime. | README · SPEC · npm |
dsh-sessions | ✅ Published · 0.1.1 | Session discovery, bounded reads, creation, and delivery through session tools and /sessions. | README · SPEC · npm |
🐚 dsh-codex-terminal
Run shell commands like a Codex-style agent: start long-running processes, poll for output, and send input to persistent sessions. PTY transport is used by default with a configured pipe fallback when PTY allocation is unavailable.
⏰ dsh-loop
Create durable, session-local recurring prompts that can be managed through
agent tools, /loop commands, and the web UI. Loops resume with the session
and keep each alarm independent from the others.
🧪 dsh-mock
Exercise deterministic mock model turns through /mock run and /mock replay
while preserving the real DSH AgentLoop, ToolRuntime, policy, and event flow.
⚠️ Unstable: published as
[email protected]for early testing. The command, API, and UI surface may change before a stable release.
Install it into the DSH web profile with one command:
dsh plugin --profile web add [email protected]
🛠️ Development
Each plugin is independently installable and testable. For example:
cd loop
pnpm install
pnpm test
pnpm build
The source tree intentionally stays outside the DeepSeek Harness repository; DSH composes plugins through profile-scoped installation and patch layers.
📚 Documentation
- Codex Terminal documentation
- Coding Plan core
- Codex Coding Plan documentation
- Grok Coding Plan documentation
- Loop documentation
- Mock documentation
- Mock implementation specification
- Sessions documentation
- Sessions specification
- DeepSeek Harness
🤝 Contributing
Issues, ideas, and pull requests are welcome. Keep plugins focused, document their runtime contracts, and include tests for changes to tools, persistence, or UI behavior.
📄 License
Released under the MIT License.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/Ephemeral-AI-Lab/dsh-plugins/mock)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.