Skip to main content

dsh-plugins/mock

44Stars4Forks1Issues0Watchers

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.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
Python
License
MIT
Branch
main
dsh-plugindsh-plugin-marketdsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add dsh-mock

Run 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 name dsh-mock (mock/package.json:2-4), one of the sub-packages under the Ephemeral-AI-Lab/dsh-plugins monorepo. This wiki focuses on the capabilities corresponding to the mock path.

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 /mock slash 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.
  • run subcommand: Write tool({"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).
  • replay subcommand: Read pre-arranged scripts from local files and replay step by step (src/parser.ts:111-132), with optional --overwrite-wait-time-ms N to override all explicit waits in the script (src/converter.ts:134-160).
  • Supports two replay source formats: canonical dsh-mock-script JSON 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 mockStatus projection (src/projection.ts:34-57); deactivation or abort writes it as cancelled, recognized as expired on next session resume.

Technical Implementation

  • Language: TypeScript (tsconfig.json:3-21 strict mode, target ES2024 / NodeNext)
  • Key Dependencies:
    • @deepseek-ai/dsh-llm (>=0.1.0-rc.5): Extend LlmAdapter to register internal mock route
    • @deepseek-ai/commands (>=0.1.0-rc.6): Use ctx.commands.register to register /mock
    • @deepseek-ai/cordis (>=4.0.0): Host plugin framework, listen to agent/pre-step / agent/request / agent/error / agent/disposed events
    • @deepseek-ai/dsh-session-projection (>=0.1.0-rc.6): Register mockStatus projection to fold state to client
    • @deepseek-ai/dsh-client-ui-slots + @deepseek-ai/dsh-client-ui-conversation + @deepseek-ai/dsh-client-runtime: Inject MockStatusDock into conversation.input.dock slot
    • react (>=18.2.0): Status row is a React component
    • zod (^4.4.3): Projection schema strict validation
  • Architecture Pattern: Cordis plugin, cordis.patch.yml disables directory-picker and injects mock into host plugin directory (cordis.patch.yml:1-9). apply(ctx) registers a MockAdapter for provider:'mock', then registers /mock command and intercepts /mock … text via agent/pre-step hook to submit as plan; adapter internally produces StreamChunk step 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 is mock/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

DependencyMinimum VersionDescription
@deepseek-ai/cordis>=4.0.0peerDependencies, host plugin framework
@deepseek-ai/dsh-llm>=0.1.0-rc.5peerDependencies, required for registering LLM adapter
@deepseek-ai/dsh-commands>=0.1.0-rc.6peerDependencies, required for registering /mock command
@deepseek-ai/dsh-agent>=0.1.0-rc.6devDependencies, holds Agent instance at runtime
@deepseek-ai/dsh-session + @deepseek-ai/dsh-session-projection>=0.1.0-rc.6peerDependencies, 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-slotseach >=0.1.0-rc.6peerDependencies, package.json:27-35 lists these four under dsh.client.inject, missing any will cause Web dock to fail loading
react>=18.2.0peerDependencies, status row component runtime
zod^4.4.3devDependencies, projection schema validation
PlatformDSH Webpackage.json:28 explicitly declares dsh.client.platform: "web", not declared for CLI/desktop
Node.jsNot declaredNo engines field in package.json; @types/node ^22.20.0 in devDependencies
Native modulesNoneOnly 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 / ParameterLocationTypeDescriptionDefault
/mock run <tool({...})> or /mock run [a({...}),b({...})]Input boxOne or parallel group of tool callsInline trigger; multiple tools must be in [ ] (src/parser.ts:80-100)None
/mock replay <path>Input boxAbsolute path or path relative to session working directoryRead 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 commandNon-negative integerOverride 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 extract session.jsonl first (src/replay-input.ts:3-17).
  • replay mode explicitly rejects nested/subagent tools: When tool name matches regex (?:^|[-_])(nested|subagent|agent[-_]spawn|spawn[-_]agent)(?:$|[-_]), it directly throws UNSUPPORTED_NESTED_TOOL (src/index.ts:370-375).
  • Inline /mock run doesn't support wait steps—wait syntax 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 by MockScriptError(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/call events will appear but the host side will report "unknown tool"—mock itself won't "fabricate" tools out of thin air.

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](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.

← Back to plugin directory