@agentvalet/dsh

Readme

# @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

```bash
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:

```bash
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.