dsh-asa-agent — Asa inside DeepSeek Harness

Asa's research pipeline, a full Asa agent turn, and Asa's health stats inside a DSH session — three MCP tools and a doctor, bridged from one local endpoint.

dsh-asa-agent is a DeepSeek Harness plugin bundle. It mounts the host's @deepseek-ai/dsh-mcp-client (transport: streamable-http) against the MCP server Asa's gateway already serves at POST /mcp, and adds one native tool that tells you whether that bridge is healthy.

Status — v0.1.0, not yet installed. This documentation set was written against Asa 0.1.0 and the DSH desktop profile as of 2026-10-24. The plugin has not been installed into a live profile yet, so the quickstart below is the install procedure, not a report of a completed run. Every step that needs your approval says so explicitly.

What you get

Tool	Type	What it does
mcp__asa__asa_research	bridged MCP tool	Runs Asa's recursive research pipeline on a topic: plan → web search → fetch → ingest into the Vectorless RAG knowledge base → analyze with confidence → synthesize a cited report. Returns the report path and run stats. Can take minutes.
mcp__asa__asa_message	bridged MCP tool	Sends a message to Asa and returns its reply. Pass session_id to continue a conversation. Accepts up to 10 attachments.
mcp__asa__asa_status	bridged MCP tool	Asa health and memory statistics, including whether Docker is reachable.
asa_doctor	native DSH tool	Probes the configured gateway and reports reachability, the tools it discovered, and hints for fixing a failure.

In plain terms: DSH gains three tools that are Asa, and one tool that tells you why the other three aren't answering.

The first three names come from DSH's MCP naming rule, mcp__<serverName>__<rawName>. Asa's server is named asa and its tools are already named asa_research, asa_message, asa_status — so the names read asa twice. That is correct, not a typo. Change serverName in the plugin config and the prefix follows it.

In plain terms: the tool name is "the MCP namespace" + "the tool's own name", and both happen to be called asa.

Why three tools and not fifteen

An earlier planning document for this integration proposed a new stdio MCP server with roughly fifteen tools (asa.recall, asa.record, asa.audit, asa.sleep, asa.forget, asa.kb.*, asa.skills.*, company.*, asa.ask, asa.message.send). That server does not exist. None of those tools are on Asa's MCP endpoint today.

What exists is Asa's gateway MCP server — Streamable HTTP, stateless JSON mode, exactly three tools — and this plugin bridges it without adding a second server in the middle. The invented surface is tracked as roadmap below and is labelled not implemented.

In plain terms: the docs describe the three tools that work, and file the fifteen that don't under "not built yet" instead of pretending.

Quickstart (about 5 minutes)

Path conventions: <asa-repo> is the path to your Asa checkout and <plugin-dir> is the path to this repository as checked out on your machine. They are placeholders, not real directories — substitute your own absolute paths.

You need: a local Asa checkout, a DSH desktop profile, and a free terminal. Asa's own README lists Node 22+ and Python 3.12+ as its prerequisites.

1. Start Asa's gateway

In a terminal you can leave running:

cd <asa-repo>
npm run setup
npm run dev:gateway

npm run setup is first-run only and is idempotent — skip it on later runs. npm run dev:gateway blocks, serving the gateway on http://localhost:8787; leave it running and use a second terminal for the next command.

In plain terms: Asa is the server here. Nothing works until it is running.

2. Check it is up

In a second terminal:

Invoke-RestMethod http://127.0.0.1:8787/api/health

You should see ok : True, name : asa and version : 0.1.0. /api/health is an unauthenticated route on loopback — a useful smoke check before you involve DSH at all.

In plain terms: this asks Asa "are you alive?" in a way that needs no token and no MCP client.

3. Install the plugin bundle — this needs your approval

Plugin installation goes through the harness, not a shell npm install into the profile. In DSH, install the bundle with the plugin_manager tool's install_bundle action, passing the plugin directory as the target:

{
  "action": "install_bundle",
  "target": "<plugin-dir>"
}

This block is not a shell command — it is the argument object for a plugin_manager tool call, shown so you can see the exact target path.

macOS and Windows surface a plugin-installation approval prompt; you have to accept it. If the result names a pendingBuilds entry, that install script needs its own explicit approval before it runs. Neither step is unattended.

In plain terms: DSH asks you "may I install this?" and you have to say yes. Nothing installs silently.

4. Verify the bridge

In a DSH session, call mcp__asa__asa_status — no arguments — and then run asa_doctor, which also takes none. The argument object is the same for both:

{}

The first call proves the bridge carries traffic; the second proves it is pointed at the right place and tells you what to fix if it isn't.

In plain terms: one call asks Asa for its stats, the other asks the plugin whether the wiring is sound.

What success looks like

asa_status returns JSON text shaped like this:

{
  "docker": true,
  "kb": { "documents": 42 },
  "mind": { "...": "memory statistics" }
}

The keys come from Asa: docker is a boolean from its Docker probe, and kb / mind are its knowledge-base and cognitive-memory statistics. asa_doctor reports reachability, the tools it discovered, and fix hints instead.

In plain terms: a healthy answer shows Docker's state plus Asa's memory counters; a broken one points you at the next step.

Configuration at a glance

All eight keys are optional. Defaults shown:

Key	Default	Why you'd change it
url	ASA_MCP_URL env, else loopback using ASA_GATEWAY_PORT (default 8787)	Asa runs on another port or another machine.
serverName	asa	You already bridge another server named asa.
token	(unset)	Asa is remote, so the pairing token is required.
mcp	true	Keep asa_doctor but skip the MCP bridge.
primer	true	You don't want a system-prompt section about Asa.
toolCallTimeoutMs	600000	Research takes longer than 10 minutes on your machine.
failOnStartupError	false	You want harness startup to fail loudly when Asa is down.
doctorTimeoutMs	15000	The probe times out on a slow machine.

Override any of these in your profile's patch layer under id: dsh-asa-agent. Note that a patch row's config is replaced wholesale, not deep-merged, so restate every key you want to keep.

In plain terms: you can point this at a different Asa, give it a token, or turn a piece off — and every default is chosen so that doing nothing still works on a stock local Asa.

Security in one paragraph

If the gateway is on loopback, Asa's own auth lets the call through without a token — that is Asa's design, not a plugin weakness, and it is why the default URL is 127.0.0.1. Point the plugin at a remote Asa and you must supply the pairing token. asa_message does not call a read-only API: it runs a full Asa agent turn, so its blast radius is Asa's own tool surface (workspace reads and writes, sandbox execution, web fetches). Before exposing anything beyond localhost, know that the plugin adds no transport security of its own: over plain http:// your pairing token and every tool payload are readable on the network.

In plain terms: on the same machine, Asa trusts you without a password. The message tool is a whole agent, not a lookup.

Troubleshooting quick hits

• No mcp__asa__* tools in the session — the bundle isn't installed or enabled, or the bridge failed at startup. Run asa_doctor; if that tool is missing too, the plugin itself isn't loaded.

• asa_doctor says unreachable — Asa's gateway isn't running, or url points somewhere else. Start it with npm run dev:gateway.

• 401 "pairing required" — url points at a non-loopback host (a LAN IP, for example) without a token. Use 127.0.0.1 or set token.

• A call seems to hang for minutes — asa_research legitimately takes minutes; toolCallTimeoutMs defaults to ten. If a call parks close to ten minutes and comes back without doing anything, Asa stopped on its own ask_user consent prompt and there was nobody in the Asa window to answer it: the turn resumes as "not confirmed". Answer the prompt in Asa's UI, or set Asa's ASA_ASK_TIMEOUT_MS lower so unanswerable prompts fail fast.

In plain terms: almost every failure is either "Asa isn't running" or "the URL is wrong" — check those two first.

Documentation

This README is the complete public guide: install, configuration, security and the failures people actually hit. A longer reference set — architecture walkthrough, exhaustive tool reference, deployment and consent-hazard notes — is maintained privately and is not part of this repository.

Roadmap — not implemented

Nothing in this table exists as an Asa MCP tool today. It is the surface the earlier planning document proposed; treat it as a wish list, not an API.

Proposed	Layer	Status
asa.recall, asa.record, asa.audit, asa.sleep, asa.forget	cognitive memory loop	not implemented
asa.kb.query, asa.kb.ingest, asa.kb.list	knowledge base	not implemented
asa.skills.list, asa.skills.read	skills	not implemented
company.recall, company.remember	company brain	not implemented
asa.ask, asa.message.send	bounded Q&A loop, fire-and-forget inbox	not implemented
asa.spawn, asa.run	full autonomous loop	not implemented
stdio transport (spawned per session)	transport	not implemented — v0.1.0 is Streamable HTTP only

For context: Asa's MCP surface shrank before this plugin existed. Its repo's own check (npm run check:mcp) asserts that asa_recall, asa_ingest and asa_sandbox_run are absent from the tool list. A roadmap entry that reintroduces them is a design proposal, not a restoration.

In plain terms: the memory and knowledge-base tools people expected are not there — Asa removed some of them on purpose, and the rest were never built.

License

Plugin code: MIT — see LICENSE, © Memkist. Asa itself is a separate local product; it is not redistributed here and is not covered by that MIT grant.

In plain terms: you can reuse this plugin's code freely; that says nothing about the Asa application you connect it to.

---

Tested against: plugin 0.1.0 · Asa 0.1.0 · DSH desktop profile · 2026-10-24. This line records the versions these docs were written against; the plugin is not yet installed, so it is not a claim that every step above was executed end to end.