@agentwares/agentguard 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +69 -0
- package/README.md +69 -19
- package/dist/cli.js +417 -56
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +9 -1
- package/dist/index.js +819 -458
- package/dist/index.js.map +1 -1
- package/llms.txt +4 -0
- package/package.json +8 -3
- package/server.json +3 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
`@agentwares/agentguard`, the CLI and MCP proxy. A tag `agentguard-v<version>` publishes the
|
|
4
|
+
GitHub Release for a version with its section below as the notes.
|
|
5
|
+
|
|
6
|
+
## 0.1.6 — 2026-10-07
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
|
|
10
|
+
- **A working MCP server with no configuration.** Started with no `agentguard.yaml` and no
|
|
11
|
+
`--config` / `AGENTGUARD_CONFIG` (an install button, a registry install, the Dockerfile),
|
|
12
|
+
`agentguard proxy` no longer exits with `INVALID_POLICY`. It fronts no servers and serves three
|
|
13
|
+
read-only tools of its own: `agentguard_get_status` (policy, mode, upstreams, caps used and
|
|
14
|
+
remaining, kill switch, pending approvals), `agentguard_get_report` (what a run did, or would
|
|
15
|
+
have done in dry-run, and every call that was halted) and `agentguard_verify_audit_log` (the
|
|
16
|
+
hash chain). Each has a title, `readOnlyHint: true`, a strict input schema and a documented
|
|
17
|
+
output schema; errors carry `code`, `cause`, `fix` and `retryable`. That mode writes nothing to
|
|
18
|
+
the directory it was started in. A policy with no upstreams serves the same three tools; with
|
|
19
|
+
upstreams configured the agent sees only the upstreams' tools, as before. A policy file that was
|
|
20
|
+
named and is missing is still an error.
|
|
21
|
+
- **Claude Code plugin marketplace** at the repo root:
|
|
22
|
+
`/plugin marketplace add agentwares/agentguard`, then `/plugin install agentguard@agentwares`.
|
|
23
|
+
`/agentguard:init` runs `init` and explains the policy it wrote; `/agentguard:report` explains a
|
|
24
|
+
run.
|
|
25
|
+
- **Gemini CLI extension** at the repo root:
|
|
26
|
+
`gemini extensions install https://github.com/agentwares/agentguard`, with the same two
|
|
27
|
+
commands.
|
|
28
|
+
- **`init` and `connect` read Gemini CLI's `.gemini/settings.json`** (and `~/.gemini/settings.json`
|
|
29
|
+
with `--client`). Gemini's `httpUrl` is read as Streamable HTTP, and `connect` writes `httpUrl`
|
|
30
|
+
there, because Gemini dials `url` as SSE.
|
|
31
|
+
- **A root `Dockerfile`**: `docker run -i --rm agentguard` serves the tools above over stdio;
|
|
32
|
+
`proxy --config /app/demo/agentguard.yaml` puts the bundled fake CRM behind the proxy.
|
|
33
|
+
- **Install links** for Cursor and VS Code in the README.
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- The README's example of the config `init` writes showed the unscoped package name, which does
|
|
38
|
+
not exist on npm; `init` itself has written `@agentwares/agentguard` since 0.1.4.
|
|
39
|
+
- README links to the permission-diff Action pointed at a path that exists only in the private
|
|
40
|
+
monorepo.
|
|
41
|
+
|
|
42
|
+
## 0.1.5 — 2026-09-11
|
|
43
|
+
|
|
44
|
+
- The 0.1.4 package was published with `workspace:^` dependency ranges and could not be installed.
|
|
45
|
+
Republished with real versions.
|
|
46
|
+
|
|
47
|
+
## 0.1.4 — 2026-09-11
|
|
48
|
+
|
|
49
|
+
- The MCP config `init` writes now starts `npx -y @agentwares/agentguard proxy`. It named the
|
|
50
|
+
unscoped `agentguard`, which does not exist on npm, so the proxy never started.
|
|
51
|
+
|
|
52
|
+
## 0.1.3 — 2026-09-07
|
|
53
|
+
|
|
54
|
+
- `agentguard connect <key>` points an MCP client at a hosted agentguard proxy.
|
|
55
|
+
- A spend cap that could fail open fails closed.
|
|
56
|
+
|
|
57
|
+
## 0.1.2 — 2026-09-07
|
|
58
|
+
|
|
59
|
+
- Absolute README links, so they work on npmjs.com.
|
|
60
|
+
|
|
61
|
+
## 0.1.1 — 2026-09-07
|
|
62
|
+
|
|
63
|
+
- Package links point at the public repository.
|
|
64
|
+
|
|
65
|
+
## 0.1.0 — 2026-09-02
|
|
66
|
+
|
|
67
|
+
- First release: the MCP policy proxy (stdio and Streamable HTTP, several upstreams), dry-run
|
|
68
|
+
writes with mutation diffs, spend and blast-radius caps, approvals, a kill switch, scoped agent
|
|
69
|
+
keys, a loop breaker and a hash-chained audit log.
|
package/README.md
CHANGED
|
@@ -52,14 +52,14 @@ npx @agentwares/agentguard init --client ~/Library/Application\ Support/Claude/c
|
|
|
52
52
|
npx @agentwares/agentguard init --undo # restore the backup
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
`init` writes `agentguard.yaml` next to
|
|
55
|
+
`init` finds `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `mcp.json` and `.gemini/settings.json` in the project (user-level files only with `--client`), writes `agentguard.yaml` next to them, backs the config up (`*.agentguard-backup`), and replaces its servers with one entry:
|
|
56
56
|
|
|
57
57
|
```json
|
|
58
58
|
{
|
|
59
59
|
"mcpServers": {
|
|
60
60
|
"agentguard": {
|
|
61
61
|
"command": "npx",
|
|
62
|
-
"args": ["-y", "agentguard", "proxy", "--config", "/abs/path/agentguard.yaml"]
|
|
62
|
+
"args": ["-y", "@agentwares/agentguard", "proxy", "--config", "/abs/path/agentguard.yaml"]
|
|
63
63
|
}
|
|
64
64
|
}
|
|
65
65
|
}
|
|
@@ -67,7 +67,57 @@ npx @agentwares/agentguard init --undo # restore the b
|
|
|
67
67
|
|
|
68
68
|
Tools keep their names (prefixed `<upstream>__` only on collision). Your MCP client sees one server; agentguard connects to all of them and holds their credentials.
|
|
69
69
|
|
|
70
|
-
|
|
70
|
+
### From your agent or editor
|
|
71
|
+
|
|
72
|
+
The same `init`, from where you already work:
|
|
73
|
+
|
|
74
|
+
- **Claude Code** (and Copilot CLI, which reads the same marketplace file):
|
|
75
|
+
`/plugin marketplace add agentwares/agentguard`, then `/plugin install agentguard@agentwares`.
|
|
76
|
+
`/agentguard:init` runs `init` and explains the policy it wrote; `/agentguard:report` explains
|
|
77
|
+
what a run did or would have done.
|
|
78
|
+
- **Gemini CLI**: `gemini extensions install https://github.com/agentwares/agentguard`, then
|
|
79
|
+
`/agentguard:init` and `/agentguard:report`. `init` reads `.gemini/settings.json`; Gemini's
|
|
80
|
+
`httpUrl` servers are proxied as Streamable HTTP (SSE-only `url` servers are not supported).
|
|
81
|
+
- **Cursor and VS Code**: one click adds agentguard as an MCP server
|
|
82
|
+
(`npx -y @agentwares/agentguard proxy`):
|
|
83
|
+
|
|
84
|
+
[](https://cursor.com/link/mcp/install?name=agentguard&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhZ2VudHdhcmVzL2FnZW50Z3VhcmQiLCJwcm94eSJdfQ%3D%3D)
|
|
85
|
+
[](https://vscode.dev/redirect/mcp/install?name=agentguard&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40agentwares%2Fagentguard%22%2C%22proxy%22%5D%7D)
|
|
86
|
+
|
|
87
|
+
The buttons open `cursor://anysphere.cursor-deeplink/mcp/install?name=agentguard&config=…` and
|
|
88
|
+
`vscode:mcp/install?{…}`; GitHub does not render those schemes as links, so the buttons go
|
|
89
|
+
through `cursor.com/link` and `vscode.dev/redirect`. Where the editor starts it next to an
|
|
90
|
+
`agentguard.yaml`, that server guards what the policy lists. Anywhere else it fronts nothing
|
|
91
|
+
and serves the three read-only tools below, the first of which tells you to run `init` in the
|
|
92
|
+
project. `init` then writes the project-level entry that does the guarding.
|
|
93
|
+
|
|
94
|
+
### Started with no policy file
|
|
95
|
+
|
|
96
|
+
Spawned with no arguments at all (what an install from the MCP registry does), `agentguard`
|
|
97
|
+
serves the stdio proxy and reads `AGENTGUARD_CONFIG` or `./agentguard.yaml`; in a terminal it
|
|
98
|
+
prints the help instead. If neither names a file that exists, it does not exit: it fronts no
|
|
99
|
+
servers, writes nothing, and serves three read-only tools of its own, each with a title,
|
|
100
|
+
`readOnlyHint: true` and a strict schema:
|
|
101
|
+
|
|
102
|
+
| Tool | Answers |
|
|
103
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| `agentguard_get_status` | which policy file it loaded or looked for, mode, upstreams, caps used and remaining, kill switch, pending approvals, and the next step |
|
|
105
|
+
| `agentguard_get_report` | what a run did, or would have done in dry-run, and every call that was halted (`run_id` optional) |
|
|
106
|
+
| `agentguard_verify_audit_log` | whether the hash-chained audit log verifies, its entry count and head hash |
|
|
107
|
+
|
|
108
|
+
A policy with no `upstreams:` serves the same three. Once upstreams are configured the agent sees
|
|
109
|
+
only their tools, exactly as before. A file named with `--config` or `AGENTGUARD_CONFIG` that does
|
|
110
|
+
not exist is still an error.
|
|
111
|
+
|
|
112
|
+
### Docker
|
|
113
|
+
|
|
114
|
+
The repo's `Dockerfile` builds the CLI from source and serves it over stdio:
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
docker build -t agentguard .
|
|
118
|
+
docker run -i --rm agentguard # no policy: the three tools above
|
|
119
|
+
docker run -i --rm agentguard proxy --config /app/demo/agentguard.yaml # a fake CRM behind the proxy, dry-run
|
|
120
|
+
```
|
|
71
121
|
|
|
72
122
|
Prefer HTTP (several agents, scoped keys, Slack approve buttons)? `agentguard proxy --http --port 8788` and point clients at `http://127.0.0.1:8788/mcp` with an `X-Run-Id` header per run and `Authorization: Bearer agk_…` per agent.
|
|
73
123
|
|
|
@@ -139,20 +189,20 @@ Run identity: `X-Run-Id` header (HTTP) → `_meta.runId` on the call → session
|
|
|
139
189
|
|
|
140
190
|
## Commands
|
|
141
191
|
|
|
142
|
-
| Command | What it does
|
|
143
|
-
| ------------------------------------------------------------------------------------------------------------------------------- |
|
|
144
|
-
| `agentguard init [--client path] [--all] [--no-probe] [--mode enforce] [--undo]` | generate the policy, rewrite the client config (project-level by default)
|
|
145
|
-
| `agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode m]` | run the proxy (stdio default)
|
|
146
|
-
| `agentguard report [--run id \| --all] [--json]` | what this run did / would have destroyed / spent; where it was halted; chain status
|
|
147
|
-
| `agentguard diff [--run id]` | mutation diff of faked writes
|
|
148
|
-
| `agentguard verify [audit.jsonl]` | recompute the hash chain; exit 1 on the first break
|
|
149
|
-
| `agentguard status [--run id]` | counters vs caps, kill state, pending approvals, running HTTP proxy
|
|
150
|
-
| `agentguard tools [--json]` | every exposed tool with class, verb, upstream and the reason
|
|
151
|
-
| `agentguard kill [reason]` / `agentguard resume` | halt everything now / clear it
|
|
152
|
-
| `agentguard approvals [--all]` / `approve <id>` / `deny <id> [--note …]` | the approval queue
|
|
153
|
-
| `agentguard key create <agent> [--allow p]… [--deny p] [--writes n] [--spend n] [--mode m]` / `key list` / `key revoke <agent>` | scoped credentials
|
|
154
|
-
| `agentguard connect <key> [--write] [--client path] [--all] [--url base]` | point this machine's MCP client at a hosted proxy (paid tiers); prints the config, `--write` merges it in
|
|
155
|
-
| `agentguard permission-diff [--base ref] [--head ref] [--fail-on-widen]` | which config changes widen agent permissions (also a [GitHub Action](https://github.com/agentwares/agentguard/tree/main/
|
|
192
|
+
| Command | What it does |
|
|
193
|
+
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
194
|
+
| `agentguard init [--client path] [--all] [--no-probe] [--mode enforce] [--undo]` | generate the policy, rewrite the client config (project-level by default) |
|
|
195
|
+
| `agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode m]` | run the proxy (stdio default) |
|
|
196
|
+
| `agentguard report [--run id \| --all] [--json]` | what this run did / would have destroyed / spent; where it was halted; chain status |
|
|
197
|
+
| `agentguard diff [--run id]` | mutation diff of faked writes |
|
|
198
|
+
| `agentguard verify [audit.jsonl]` | recompute the hash chain; exit 1 on the first break |
|
|
199
|
+
| `agentguard status [--run id]` | counters vs caps, kill state, pending approvals, running HTTP proxy |
|
|
200
|
+
| `agentguard tools [--json]` | every exposed tool with class, verb, upstream and the reason |
|
|
201
|
+
| `agentguard kill [reason]` / `agentguard resume` | halt everything now / clear it |
|
|
202
|
+
| `agentguard approvals [--all]` / `approve <id>` / `deny <id> [--note …]` | the approval queue |
|
|
203
|
+
| `agentguard key create <agent> [--allow p]… [--deny p] [--writes n] [--spend n] [--mode m]` / `key list` / `key revoke <agent>` | scoped credentials |
|
|
204
|
+
| `agentguard connect <key> [--write] [--client path] [--all] [--url base]` | point this machine's MCP client at a hosted proxy (paid tiers); prints the config, `--write` merges it in |
|
|
205
|
+
| `agentguard permission-diff [--base ref] [--head ref] [--fail-on-widen]` | which config changes widen agent permissions (also a [GitHub Action](https://github.com/agentwares/agentguard/tree/main/permission-diff)) |
|
|
156
206
|
|
|
157
207
|
### Hosted tiers
|
|
158
208
|
|
|
@@ -189,7 +239,7 @@ node dist/cli.js report && node dist/cli.js diff && node dist/cli.js verify
|
|
|
189
239
|
|
|
190
240
|
## Conformance and tests
|
|
191
241
|
|
|
192
|
-
`pnpm test` runs the CLI suite (
|
|
242
|
+
`pnpm test` runs the CLI suite (52 tests; 68 more in `agentguard-core`, 11 in the SDK): the engine over InMemoryTransport, the spawned stdio proxy (with and without a policy file), the Streamable HTTP proxy with `X-Run-Id`, scoped keys and control endpoints, `init` against real configs, and a recorded-fixture replay (`fixtures/recorded/crm-session.json`; re-record with `RECORD_FIXTURES=1`). `pnpm conformance` runs the official `@modelcontextprotocol/conformance` server suite against the proxy with a sample server behind it (tools, resources, prompts, completions, logging, progress, sampling and elicitation are relayed).
|
|
193
243
|
|
|
194
244
|
## Limits (honest)
|
|
195
245
|
|
|
@@ -203,4 +253,4 @@ node dist/cli.js report && node dist/cli.js diff && node dist/cli.js verify
|
|
|
203
253
|
|
|
204
254
|
- [`@agentwares/agentguard-sdk`](https://github.com/agentwares/agentguard/tree/main/packages/agentguard-sdk#readme) — the same engine for OpenAI Agents SDK / LangChain / plain functions, plus the guarded `fetch` for LLM spend.
|
|
205
255
|
- [`@agentwares/agentguard-core`](https://github.com/agentwares/agentguard/tree/main/packages/agentguard-core#readme) — the Web-standard policy engine (bring your own stores).
|
|
206
|
-
- [permission-diff GitHub Action](https://github.com/agentwares/agentguard/tree/main/
|
|
256
|
+
- [permission-diff GitHub Action](https://github.com/agentwares/agentguard/tree/main/permission-diff) — comments on PRs that widen `agentguard.yaml`, `.claude/settings.json` or `mcp.json`.
|