dsh-agentvalet

@agentvalet/dsh

Governed platform access for DeepSeek Harness agents: an agent calls Slack,
GitHub, Gmail, Stripe, or any other AgentValet-connected SaaS platform through
a broker that enforces the owner's grants and approval flow, with no API key
stored on the machine the agent runs on.

Install

dsh plugin --profile web add @agentvalet/dsh

This installs both plugins the bundle ships: av-identity (the agentvalet
service) and av-tools (the four tools below). Restart or reload the profile
after installing.

Connect

An installed but unconnected profile has no identity yet — calls report "not
connected" rather than failing obscurely. To connect it:

1. In the AgentValet dashboard, generate a single-use bootstrap token for a
   new agent.
2. Run the bundle's connect command:

AGENTVALET_BOOTSTRAP_TOKEN=<token> npx agentvalet-dsh-connect --profile web

--token <token> works too; the environment variable just keeps the token out
of your shell history. The command prints the new agent id and nothing else —
never the token, never the key. --help lists the rest of the flags.

Connecting is a command you run, not a tool the agent can call. An
enrolment tool would let an agent bootstrap its own identity with no human in
the loop, and the identity would stop attesting to a person's decision to
create it.

The command generates an RS256 keypair locally and sends only the public
key to AgentValet's /v1/agents/bind endpoint. The private key never leaves
the machine. It is written to $DSH_HOME/agentvalet/<profile>.json
(~/.dsh/agentvalet/... when DSH_HOME is unset) at mode 0600, and the
store refuses outright to write anywhere inside a git working tree.

Once bound, the agent shows up in the dashboard deny-by-default — it can
call nothing until the owner grants it specific platforms and scopes.

A bootstrap token is single-use. Re-running connect on an already-connected
profile is refused rather than silently replacing the identity, so one
agent's audit history can never be laundered into another's.

The routing instructions it writes

Connecting also writes a short routing block into $DSH_HOME/AGENTS.md — the
rule that platform calls go through AgentValet rather than around it. The block
sits between <!-- agentvalet:start --> and <!-- agentvalet:end --> fences:
anything else in that file is yours and is left untouched, and re-running
connect refreshes the region in place instead of appending a second copy.

It is written there because that is where dsh reads. The instruction loader
(@deepseek-ai/dsh-agent-instructions) reads $DSH_HOME/AGENTS.md and then
each directory from the project root down to the session cwd — it never scans
node_modules, so the AGENTS.md shipped inside this package reaches no
model. That copy is documentation for you to read or paste into a project root.

Note it follows $DSH_HOME, not --home: --home only relocates where the
identity is stored, and following it would put the file somewhere nothing reads.
If the write fails, connect says so and still reports the enrolment — by then
the single-use token is spent and the agent exists, so failing the whole command
over a markdown file would strand a real identity.

The block deliberately contains no agent id, owner id, or scope list. This file
lands in a home directory and gets copied into project roots and pasted into
issues; identity in it would leak through ordinary use.

Tools

Tool	Method	Notes
agentvalet_list_platforms	—	Lists platforms and scopes the owner has approved for this agent. Call this before any platform call — grants can change at any time.
agentvalet_read_platform	Always GET	Read from an approved platform.
agentvalet_write_platform	POST (default), PUT or PATCH	Create or update. May require owner approval.
agentvalet_delete_platform	Always DELETE	Usually requires owner approval.

Every tool takes the platform id and scope string exactly as returned by
agentvalet_list_platforms, plus an endpoint. All four resolve to
{ ok: true, data } on success or { ok: false, error } on failure — a
denial, a pending approval, or a suspended agent all come back as a plain
result the model can read and explain rather than as a thrown error. (That is
a guarantee about our own tool bodies. Argument validation happens in the
harness before our code runs, so a malformed call comes back in dsh's own
isError result shape instead.)

What this does NOT do

• No local policy engine. Every grant, scope, and approval decision is
  evaluated by AgentValet's proxy, not by anything running on this machine.
• No vault on disk beyond the agent's own signing key. There is no
  platform credential to steal locally — API keys for Slack, GitHub, and the
  rest live only at the broker, never on the agent's host.
• No sandboxing. This plugin governs which platform calls succeed; it
  is not a substitute for running the harness in a sandbox and pairs with
  one rather than replacing it.
• No sub-agent delegation and no attenuated scope re-issue. This bundle
  implements neither. It enforces the owner's grants for this one agent, and
  that is all it does.

Compatibility

Declared harness range: >=0.1.0-rc.5 <0.2.0. Verified against
@deepseek-ai/dsh@0.1.0-rc.7, @deepseek-ai/cordis@4.0.1, and
@deepseek-ai/dsh-tools@0.1.0-rc.7 — see VERIFICATION.md for what was and
was not confirmed against a real harness run.