dsh-alfandega

dsh-alfandega

On-demand tool catalog for DeepSeek Harness.

A profile with many plugins and MCP servers sends hundreds of tool definitions on every request. Every definition costs schema tokens for every turn, and a tool list that large is well past the point where model accuracy starts to drop. dsh-alfandega adds one tool, achar_ferramenta ("find tool" in Portuguese), that finds the tool or skill missing from the agent schema by meaning and registers the found tool in the requesting agent's scope. The agent discovers the capability as content, when it needs it, instead of carrying every schema all the time.

Install

# 1. pnpm (needed by `dsh plugin`)
npm install -g pnpm

# 2. add the plugin to your `web` profile
npx @deepseek-ai/dsh plugin --profile web add github:songjongdevsecops/dsh-alfandega

If dsh is already installed globally, step 2 is:

dsh plugin --profile web add github:songjongdevsecops/dsh-alfandega

Restart the harness after installing: the bundle layer is read at boot.

npx @deepseek-ai/dsh web

Check that the line was loaded:

npx @deepseek-ai/dsh --profile web --dump-config | grep -A4 alfandega

Expected shape:

- id: alfandega
  name: dsh-alfandega
  config:
    colecao: ferramentas-bgem3-v1
    topK: 5
    buscaTimeoutMs: 20000

The package declares dsh.bundle.patch, so dsh plugin add appends dsh-alfandega to dsh.profile.bundles in the profile manifest. That line is the only activation.

Update and uninstall

# update: re-run the add command, then restart the harness
npx @deepseek-ai/dsh plugin --profile web add github:songjongdevsecops/dsh-alfandega

# uninstall, then restart
npx @deepseek-ai/dsh plugin --profile web remove dsh-alfandega

What the plugin does

the model needs a capability that is not in its schema
        │
        ▼
achar_ferramenta(consulta)                ← one tool, always in the schema
        │
        ├─ 1. optional vector search in a memsearch collection, by MEANING
        ├─ 2. completed by local lexical ranking (name > description > keyword)
        │
        ▼
returns the FULL schema as CONTENT (the prompt prefix is not rewritten)
and registers the tool in the scope of the agent that asked
        │
        ▼
the tool is callable from the NEXT request on — one cache re-warm, not one
per request

• One tool. achar_ferramenta({ consulta, quantas? }).
• One command. /alfandega <what you want to do>; /alfandega alone reports the catalog size and path.
• One hook. tools/change clears the in-memory catalog cache.
• No UI, no client bundle, no network service. client.js does not exist on purpose.

Registration is agent-scoped (exec.agent.ctx.tools.register), never global: the tool array of the prompt prefix is extended once, when the model asks, so the prompt cache survives.

Requirements

• Node.js ^22.19.0 || >=24.0.0 (the range DeepSeek Harness supports).
• pnpm on PATH; the harness manages profile plugins with it.
• DeepSeek Harness itself, e.g. npx @deepseek-ai/dsh web.
• memsearch is optional. With it, the first ranking stage is vector search over a collection whose item ids follow ferramenta-<name> / skill-<name>. Without it (or with the index busy/unavailable), the plugin falls back to local lexical ranking and says so in the result. Nothing breaks.

The catalog is generated on your machine

The package deliberately ships no catalog. A catalog is a dump of the tool and skill registry of one machine; shipping it would leak that machine's paths and internal descriptions, and it would be stale for everyone else.

On the first call (achar_ferramenta or /alfandega), if there is no catalog at the configured path, the plugin:

1. reads the live tool registry (tools.schemas()),
2. lists the skills visible to the calling agent,
3. writes the catalog to the configured path and answers from it.

Default path: ~/.dsh/alfandega/catalogo.json. If the directory is not writable, the plugin keeps the catalog in memory for the session and logs a warning instead of failing.

To refresh the catalog (for example after installing a new plugin), delete the file and call the tool again:

rm ~/.dsh/alfandega/catalogo.json

The search also merges what the calling agent already sees, so a tool that is in the schema never appears twice or gets registered again. The hook tools/change clears the in-memory cache, so a regenerated file is picked up without a restart.

Configuration

All keys live on the alfandega line of the profile patch. A patch replaces the whole config of the line, so restate every key you want to keep.

Profile patch example (~/.dsh/profiles/web/cordis.patch.yml):

- id: alfandega
  config:
    colecao: 'ferramentas-bgem3-v1'
    catalogo: '/home/you/.dsh/alfandega/catalogo.json'
    topK: 5
    buscaTimeoutMs: 20000

When developing the plugin from a directory, a catalogo.json next to index.js takes precedence over the home default; that is how a checkout can keep a pre-generated catalog while a package install generates its own.

Usage

Ask the agent for a capability it does not seem to have ("run a long command in the background", "search the web", "start a workflow"). It calls achar_ferramenta and receives the full schema of the match.

In the chat:

/alfandega list background jobs      # find and show the matching tool
/alfandega                           # catalog size, path and state

What a result looks like:

[alfandega] 1 de 42 itens para "list background jobs" (lexical + registro sob demanda).

FERRAMENTA job_list
  List background jobs started by this session
  parâmetros:
    { ... }

registradas agora no seu escopo: job_list. Elas ficam disponíveis a partir da
PRÓXIMA requisição.

Verification

From a clone of the repository:

node --test tests/

The suite covers the lexical ranking, vector-first ordering, scoped registration (never twice, never global), the frame-format JSON Schema, catalog read errors, catalog generation at the destination, and the package contract. It needs no harness install and no index; when @deepseek-ai/dsh-tools is resolvable (or DSH_TOOLS_ENTRY points at its entrypoint), it also validates the registered schema with the harness compiler.

To verify the install: check the dump-config line above, restart the harness, then run /alfandega web search. The first call reports catálogo gerado agora a partir do host.

Limits, stated

• The catalog is a snapshot. It is written on first use and does not update itself when a new tool appears. Delete the file to regenerate it. The tools/change hook only invalidates the in-memory cache.
• Registration is not instantaneous for the model. The tool becomes callable from the next request; in the current step the model already has the full schema as text, which is enough to decide.
• Vector search is an accelerator, not a requirement. Missing memsearch, missing collection, or a busy database means lexical ranking, which can order results worse but still returns them.
• Skills do not become tools. A found skill is returned with a pointer and is loaded through the harness skill tool, which owns the skill catalog.
• One tool, on purpose. The plugin does not add a second model-facing tool; the whole point is to keep the schema small.
• It only sees what the host registered. Tools and skills that the profile does not mount cannot be found.

Troubleshooting

• pnpm not found — npm install -g pnpm, then re-run the add command.
• Plugin installed but nothing appears — restart the harness; the bundle layer is read at boot.
• catálogo não existe em ...; o host não expôs ferramenta nem skill — the registry was empty when the plugin tried to generate the catalog. Check that the profile mounts its bundles, then call the tool again.
• Could not write the catalog — point DSH_ALFANDEGA_CATALOGO at a writable path; the session still works from memory.
• Results say lexical: motor ocupado — another process holds the memsearch database. The lexical ranking answers and the vector returns on the next call.
• Collection name warning — the convention is <subject>-<engine>-v1; the plugin warns but keeps working with the name you gave.

License

MIT