runwarden 0.0.0-stage → 0.2.0
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/LICENSE +21 -0
- package/README.md +402 -2
- package/assets/gate-overview.svg +80 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +21 -0
- package/dist/index.d.ts +1235 -0
- package/dist/index.js +1336 -0
- package/dist/init-Dm_qLwix.js +242 -0
- package/dist/rolldown-runtime-D8jQpDG7.js +12 -0
- package/migrations/0000_init.sql +84 -0
- package/migrations/meta/0000_snapshot.json +720 -0
- package/migrations/meta/_journal.json +13 -0
- package/package.json +105 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Eric Lee
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
|
|
20
|
+
OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,403 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Runwarden
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](LICENSE)
|
|
4
|
+

|
|
5
|
+

|
|
6
|
+

|
|
7
|
+
|
|
8
|
+
**Agents act. Policies decide. Postgres remembers.**
|
|
9
|
+
|
|
10
|
+
A lightweight, governed agent runtime for TypeScript: enforced tool-call
|
|
11
|
+
policy and a per-call audit trail, durable on your own Postgres.
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
<img width="900" alt="Runwarden policy gate: an agent proposes tool calls, Runwarden checks each one against policy, allowed calls execute through MCP tools, approval-gated calls are stopped, and every ruling is written to Postgres" src="assets/gate-overview.svg" />
|
|
16
|
+
|
|
17
|
+
Agent runs rarely fail by crashing. They fail by staying alive and doing
|
|
18
|
+
the wrong thing: picking the wrong tool, calling it twice, or reaching for
|
|
19
|
+
something sensitive nobody approved, while prompt-level rules ("never do
|
|
20
|
+
X") get quietly ignored by the model.
|
|
21
|
+
|
|
22
|
+
Runwarden puts the rules in the runtime instead of the prompt. You define
|
|
23
|
+
the runtime once (model, MCP tool servers, policies), and every tool call
|
|
24
|
+
the model proposes is checked against policy before it executes. Every
|
|
25
|
+
ruling is written to Postgres as an audit row. Underneath, invocations are
|
|
26
|
+
durable: queued in your database, claimed by workers under leases, retried
|
|
27
|
+
with backoff.
|
|
28
|
+
|
|
29
|
+
It is built for indie developers and solo founders putting agents in front
|
|
30
|
+
of real users: for the day your agent first does something wrong in front
|
|
31
|
+
of one of them.
|
|
32
|
+
|
|
33
|
+
DBOS gives you durable execution for workflows and functions. Runwarden's
|
|
34
|
+
headline is governing what an agent may do (enforced tool-call policy and
|
|
35
|
+
per-call audit), with durable execution as the substrate underneath.
|
|
36
|
+
|
|
37
|
+
## Features
|
|
38
|
+
|
|
39
|
+
- **Enforced tool-call policy**: exactly one tool call per model step, a
|
|
40
|
+
tool allowlist, and per-tool input validation, all checked in the runtime
|
|
41
|
+
between the model's proposal and execution. A violating call executes
|
|
42
|
+
nothing.
|
|
43
|
+
- **Correction loop**: a denied call returns a correction the model can
|
|
44
|
+
act on, within a bounded correction budget, instead of failing silently
|
|
45
|
+
or looping forever.
|
|
46
|
+
- **Approvals, in your database**: list a tool in `requireApproval` and
|
|
47
|
+
a proposal to call it parks the invocation in `awaiting_approval`,
|
|
48
|
+
with the proposed call stored on the row and the request recorded as
|
|
49
|
+
`approval_requested`. Your app lists and resolves pending approvals
|
|
50
|
+
through the library API. Approval reruns the whole invocation and
|
|
51
|
+
only the exact approved call passes; rejection cancels it. Nothing
|
|
52
|
+
sensitive executes unapproved.
|
|
53
|
+
- **Audit trail in Postgres**: invocations, policy decisions, and the latest
|
|
54
|
+
dispatch state of each tool-call identity are queryable with plain SQL in
|
|
55
|
+
`agent_runtime`. A call identity is its invocation, tool name, and canonical
|
|
56
|
+
JSON arguments. Its deterministic idempotency key is sent to the tool server;
|
|
57
|
+
that server must implement deduplication to protect side effects.
|
|
58
|
+
- **Durable execution**: invocations are claimed by workers under leases
|
|
59
|
+
with heartbeats, retried with backoff, and fenced so a stale worker
|
|
60
|
+
cannot overwrite a newer attempt. Delivery is at-least-once; idempotency
|
|
61
|
+
keys guard side effects.
|
|
62
|
+
- **MCP-first tools**: tools execute through MCP servers you run;
|
|
63
|
+
Runwarden governs, the server executes.
|
|
64
|
+
- **Your database**: `runwarden init` creates the schema in your own
|
|
65
|
+
Postgres. No hosted service, no separate state store.
|
|
66
|
+
|
|
67
|
+
## Getting Started
|
|
68
|
+
|
|
69
|
+
### Requirements
|
|
70
|
+
|
|
71
|
+
- Node.js 22 or newer
|
|
72
|
+
- Postgres (your own, or the Docker one-liner in the steps below)
|
|
73
|
+
- A model API key for any OpenAI-compatible endpoint
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
mkdir my-agent && cd my-agent
|
|
77
|
+
npm init -y
|
|
78
|
+
npm install runwarden @modelcontextprotocol/sdk zod
|
|
79
|
+
npm install -D tsx
|
|
80
|
+
|
|
81
|
+
docker run -d --name runwarden-pg -e POSTGRES_PASSWORD=password -e POSTGRES_DB=runwarden -p 5432:5432 postgres:17
|
|
82
|
+
export DATABASE_URL=postgres://postgres:password@localhost:5432/runwarden
|
|
83
|
+
export MODEL_API_KEY=<your key>
|
|
84
|
+
|
|
85
|
+
npx runwarden init
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
With pnpm, install with `pnpm add` instead and run the CLI as
|
|
89
|
+
`pnpm exec runwarden init`.
|
|
90
|
+
|
|
91
|
+
Save this as `main.ts`:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import { createServer } from 'node:http';
|
|
95
|
+
|
|
96
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
97
|
+
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
|
|
98
|
+
import { createDb, defineRuntime, runWorker } from 'runwarden';
|
|
99
|
+
import { z } from 'zod';
|
|
100
|
+
|
|
101
|
+
// A tiny MCP tool server with one tool. In your app this can be any
|
|
102
|
+
// MCP server; here it runs in-process so the example is self-contained.
|
|
103
|
+
function buildToolServer(): McpServer {
|
|
104
|
+
const server = new McpServer({ name: 'getting-started', version: '1' });
|
|
105
|
+
server.registerTool(
|
|
106
|
+
'notes__search',
|
|
107
|
+
{
|
|
108
|
+
description: 'Search the notes collection by keyword.',
|
|
109
|
+
inputSchema: { query: z.string() },
|
|
110
|
+
},
|
|
111
|
+
async ({ query }) => ({
|
|
112
|
+
content: [
|
|
113
|
+
{
|
|
114
|
+
type: 'text' as const,
|
|
115
|
+
text:
|
|
116
|
+
query.trim().toLowerCase() === 'roadmap'
|
|
117
|
+
? 'Roadmap note: "Ship the runtime first, add features later."'
|
|
118
|
+
: 'No matching note.',
|
|
119
|
+
},
|
|
120
|
+
],
|
|
121
|
+
}),
|
|
122
|
+
);
|
|
123
|
+
return server;
|
|
124
|
+
}
|
|
125
|
+
const httpServer = createServer(async (request, response) => {
|
|
126
|
+
const transport = new StreamableHTTPServerTransport({
|
|
127
|
+
sessionIdGenerator: undefined,
|
|
128
|
+
});
|
|
129
|
+
await buildToolServer().connect(transport);
|
|
130
|
+
await transport.handleRequest(request, response);
|
|
131
|
+
});
|
|
132
|
+
await new Promise<void>((resolve) =>
|
|
133
|
+
httpServer.listen(43121, '127.0.0.1', resolve),
|
|
134
|
+
);
|
|
135
|
+
|
|
136
|
+
const db = createDb(process.env.DATABASE_URL!);
|
|
137
|
+
const runtime = defineRuntime({
|
|
138
|
+
db,
|
|
139
|
+
provider: {
|
|
140
|
+
baseUrl: process.env.MODEL_BASE_URL ?? 'https://api.openai.com/v1',
|
|
141
|
+
apiKey: process.env.MODEL_API_KEY!,
|
|
142
|
+
model: process.env.MODEL_ID ?? 'gpt-4o-mini',
|
|
143
|
+
},
|
|
144
|
+
mcpServers: [
|
|
145
|
+
{
|
|
146
|
+
name: 'local',
|
|
147
|
+
url: 'http://127.0.0.1:43121/mcp',
|
|
148
|
+
tools: ['notes__search'],
|
|
149
|
+
},
|
|
150
|
+
],
|
|
151
|
+
tools: [
|
|
152
|
+
{
|
|
153
|
+
name: 'notes__search',
|
|
154
|
+
description: 'Search the notes collection by keyword.',
|
|
155
|
+
inputSchema: z.object({ query: z.string() }),
|
|
156
|
+
},
|
|
157
|
+
],
|
|
158
|
+
loadSystemPrompt: async () => 'You are a helpful assistant.',
|
|
159
|
+
loadHistory: async () => [],
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
const worker = runWorker({ runtime, db });
|
|
163
|
+
try {
|
|
164
|
+
const result = await runtime.invoke({
|
|
165
|
+
scope: 'getting-started',
|
|
166
|
+
prompt: 'Find the roadmap note and tell me what it says.',
|
|
167
|
+
});
|
|
168
|
+
console.log(`[app] ${result.text}`);
|
|
169
|
+
|
|
170
|
+
const audits = await db.pool.query(
|
|
171
|
+
'select tool_name, status from agent_runtime.tool_call_audits order by requested_at',
|
|
172
|
+
);
|
|
173
|
+
console.log('[audit]', JSON.stringify(audits.rows));
|
|
174
|
+
} finally {
|
|
175
|
+
await worker.stop();
|
|
176
|
+
await db.close();
|
|
177
|
+
httpServer.close();
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
```sh
|
|
182
|
+
npx tsx main.ts
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
You should see:
|
|
186
|
+
|
|
187
|
+
```text
|
|
188
|
+
[app] The roadmap note says: "Ship the runtime first, add features later."
|
|
189
|
+
[audit] [{"tool_name":"notes__search","status":"succeeded"}]
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The invocation ran in a durable worker, the tool call executed through
|
|
193
|
+
MCP under policy, and the audit row is already in your Postgres. To gate
|
|
194
|
+
a tool behind human approval, add
|
|
195
|
+
`policies: { requireApproval: ['your__tool'] }` to `defineRuntime`; the
|
|
196
|
+
[full quickstart](examples/quickstart/README.md) walks through that flow
|
|
197
|
+
end to end.
|
|
198
|
+
|
|
199
|
+
## The full quickstart (from the repo)
|
|
200
|
+
|
|
201
|
+
### Requirements
|
|
202
|
+
|
|
203
|
+
- Node.js 22 or newer
|
|
204
|
+
- pnpm 10
|
|
205
|
+
- Docker, to run Postgres for the example (or your own Postgres: set
|
|
206
|
+
`DATABASE_URL` and skip the compose step)
|
|
207
|
+
- A model API key for any OpenAI-compatible endpoint (or a local model
|
|
208
|
+
server; see the quickstart README)
|
|
209
|
+
|
|
210
|
+
```sh
|
|
211
|
+
git clone https://github.com/happyeric77/runwarden.git
|
|
212
|
+
cd runwarden
|
|
213
|
+
pnpm install
|
|
214
|
+
export MODEL_API_KEY=sk-... # any OpenAI-compatible endpoint
|
|
215
|
+
docker compose -f examples/quickstart/docker-compose.yml up -d --wait
|
|
216
|
+
pnpm quickstart
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
The quickstart runs the full story against a local MCP server with a
|
|
220
|
+
real model: a note lookup that executes through MCP, and a refund parked
|
|
221
|
+
by `requireApproval`, approved in the script, and rerun to completion.
|
|
222
|
+
It then prints both invocations and their policy decisions from Postgres. Occasionally the model responds with text instead of proposing
|
|
223
|
+
the refund tool; the example reports that nothing was intercepted rather than
|
|
224
|
+
claiming a blocked call. After approval, a text-only response does not prove a
|
|
225
|
+
refund executed; changed arguments park again without automatic approval. The
|
|
226
|
+
summary reports those outcomes from the audit rows. The [quickstart README](examples/quickstart/README.md)
|
|
227
|
+
walks through each step and what you should see.
|
|
228
|
+
|
|
229
|
+
For the production-shaped setup (separate app and worker processes and a
|
|
230
|
+
real model provider), see [examples/durable](examples/durable/README.md).
|
|
231
|
+
|
|
232
|
+
## How It Works
|
|
233
|
+
|
|
234
|
+
1. You describe the runtime once with `defineRuntime`: the model, the MCP
|
|
235
|
+
servers and tools it may use, and the policies that apply.
|
|
236
|
+
2. `invoke()` writes a durable invocation row to Postgres and waits for
|
|
237
|
+
the outcome; `enqueue()` returns immediately instead.
|
|
238
|
+
3. A worker started with `runWorker()` claims queued invocations under a
|
|
239
|
+
lease, heartbeating while it runs; expired leases are reclaimed.
|
|
240
|
+
4. At every model step, the proposed tool calls are checked against
|
|
241
|
+
policy (exactly-one, allowlist, input validation, `requireApproval`)
|
|
242
|
+
before anything executes through MCP.
|
|
243
|
+
5. Every ruling lands in `policy_decisions`, a call's latest dispatch state
|
|
244
|
+
lands in `tool_call_audits`, and invocation state lands in `invocations`.
|
|
245
|
+
Tool audits are latest-state records, not a history of every attempt.
|
|
246
|
+
6. If a proposed call is listed in `requireApproval`, the invocation
|
|
247
|
+
parks in `awaiting_approval` instead of failing. Your app resolves it
|
|
248
|
+
with `approveInvocation` or `rejectInvocation`. Approval reruns the
|
|
249
|
+
whole invocation; rejection cancels it.
|
|
250
|
+
7. When an invocation reaches a terminal state (succeeded, failed, or
|
|
251
|
+
cancelled), the optional `onInvocationSettled` callback from
|
|
252
|
+
`defineRuntime` fires with the final invocation record, so your app
|
|
253
|
+
can react: notify, chain the next step, or record the outcome. The
|
|
254
|
+
callback runs in the process that settled the invocation (the worker
|
|
255
|
+
for completions and final failures, the caller for rejections), after
|
|
256
|
+
the state is persisted. Callback errors are swallowed; they never
|
|
257
|
+
change the invocation's outcome.
|
|
258
|
+
|
|
259
|
+
All of it lives in four tables in the `agent_runtime` schema:
|
|
260
|
+
|
|
261
|
+
```mermaid
|
|
262
|
+
erDiagram
|
|
263
|
+
invocations ||--o{ policy_decisions : "rules on"
|
|
264
|
+
invocations ||--o{ tool_call_audits : "executes"
|
|
265
|
+
|
|
266
|
+
invocations {
|
|
267
|
+
bigint id PK
|
|
268
|
+
text scope
|
|
269
|
+
text conversation_id
|
|
270
|
+
text ordering_key
|
|
271
|
+
jsonb input
|
|
272
|
+
text result_text
|
|
273
|
+
text idempotency_key
|
|
274
|
+
invocation_status status "pending | running | awaiting_approval | succeeded | failed | cancelled"
|
|
275
|
+
int attempt_count
|
|
276
|
+
int max_attempts
|
|
277
|
+
timestamptz next_attempt_at
|
|
278
|
+
timestamptz claimed_at
|
|
279
|
+
text claimed_by
|
|
280
|
+
timestamptz lease_heartbeat_at
|
|
281
|
+
timestamptz lease_expires_at
|
|
282
|
+
uuid active_run_id
|
|
283
|
+
timestamptz active_run_registered_at
|
|
284
|
+
jsonb pending_tool_call
|
|
285
|
+
timestamptz started_at
|
|
286
|
+
timestamptz completed_at
|
|
287
|
+
timestamptz failed_at
|
|
288
|
+
text provider
|
|
289
|
+
text model
|
|
290
|
+
text last_error_code
|
|
291
|
+
text last_error_message
|
|
292
|
+
jsonb metadata
|
|
293
|
+
timestamptz created_at
|
|
294
|
+
timestamptz updated_at
|
|
295
|
+
}
|
|
296
|
+
tool_call_audits {
|
|
297
|
+
bigint id PK
|
|
298
|
+
bigint invocation_id FK
|
|
299
|
+
text scope
|
|
300
|
+
uuid run_id
|
|
301
|
+
text tool_name
|
|
302
|
+
text idempotency_key
|
|
303
|
+
tool_call_status status "started | succeeded | failed"
|
|
304
|
+
timestamptz requested_at
|
|
305
|
+
timestamptz completed_at
|
|
306
|
+
text error_code
|
|
307
|
+
jsonb request_snapshot
|
|
308
|
+
jsonb metadata
|
|
309
|
+
timestamptz created_at
|
|
310
|
+
}
|
|
311
|
+
policy_decisions {
|
|
312
|
+
bigint id PK
|
|
313
|
+
text scope
|
|
314
|
+
bigint invocation_id FK
|
|
315
|
+
uuid run_id
|
|
316
|
+
text tool_name
|
|
317
|
+
text rule
|
|
318
|
+
text decision
|
|
319
|
+
jsonb detail
|
|
320
|
+
timestamptz created_at
|
|
321
|
+
}
|
|
322
|
+
worker_leases {
|
|
323
|
+
text name PK
|
|
324
|
+
text holder_id
|
|
325
|
+
timestamptz acquired_at
|
|
326
|
+
timestamptz heartbeat_at
|
|
327
|
+
timestamptz expires_at
|
|
328
|
+
}
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
`worker_leases` stands alone on purpose. It is a named-lock table; each
|
|
332
|
+
invocation's lease state lives on the invocation row itself.
|
|
333
|
+
|
|
334
|
+
The end of a quickstart run prints that trail. A typical run:
|
|
335
|
+
|
|
336
|
+
```text
|
|
337
|
+
[audit] what landed in Postgres:
|
|
338
|
+
invocation <id>: status=succeeded attempts=1
|
|
339
|
+
invocation <id>: status=succeeded attempts=1
|
|
340
|
+
policy_decision invocation=<id> rule=require_approval decision=approval_requested tool=billing__refund
|
|
341
|
+
policy_decision invocation=<id> rule=require_approval decision=approved tool=billing__refund
|
|
342
|
+
policy_decision invocation=<id> rule=require_approval decision=allow tool=billing__refund
|
|
343
|
+
tool_call_audit invocation=<id> tool=notes__search status=succeeded idempotency_key=<prefix>...
|
|
344
|
+
tool_call_audit invocation=<id> tool=billing__refund status=succeeded idempotency_key=<prefix>...
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
## Limitations
|
|
348
|
+
|
|
349
|
+
- **Not for massive throughput:** Runwarden targets indie and solo scale:
|
|
350
|
+
agents in front of your users, not a high-volume job platform.
|
|
351
|
+
- **Single region:** one Postgres is the state store. There is no
|
|
352
|
+
multi-region story.
|
|
353
|
+
- **TypeScript only in v1:** the runtime, the policy surface, and the
|
|
354
|
+
examples are TypeScript on Node.js.
|
|
355
|
+
- **Invocation-level durability only:** a crashed or expired invocation
|
|
356
|
+
retries the whole run, at-least-once. There is no step-level
|
|
357
|
+
checkpointing and no multi-day workflow orchestration.
|
|
358
|
+
- **Approvals are API-only, and rerun the whole invocation:** there is
|
|
359
|
+
no approval inbox or UI; your app resolves pending approvals through
|
|
360
|
+
the library API. Approval does not resume mid-run. The invocation
|
|
361
|
+
reruns from the start, earlier tool calls can execute again, and
|
|
362
|
+
idempotency keys guard their side effects. That cost is the price of
|
|
363
|
+
invocation-level durability in v1.
|
|
364
|
+
- **Audit scope today:** tool audits are written as `started` before MCP
|
|
365
|
+
dispatch, then completed as `succeeded` or `failed`. A `started` row alone
|
|
366
|
+
does not prove execution; a policy-denied proposal emits no tool audit.
|
|
367
|
+
Repeated identical calls in one invocation reclaim the same row, including
|
|
368
|
+
retries and approval reruns. Reclaim replaces the run, request snapshot,
|
|
369
|
+
metadata, and timestamps, and clears the previous completion and error.
|
|
370
|
+
If the process then crashes, earlier success evidence is lost. This is a
|
|
371
|
+
deliberate latest-state tradeoff, not an append-only audit or a result cache.
|
|
372
|
+
Each dispatch has a separate fencing token in metadata; only that claim may
|
|
373
|
+
complete the row. Superseded completions fail with `audit_persistence_failed`,
|
|
374
|
+
including overlapping identical calls within one run. This does not undo
|
|
375
|
+
tool side effects or prevent duplicate execution at the tool server.
|
|
376
|
+
- **Audit hooks:** `defineRuntime()` plus `runWorker()` persists tool events
|
|
377
|
+
before calling `onToolCallAudit`. Observer exceptions are ignored, but the
|
|
378
|
+
observer is awaited and must finish promptly. Persistence failures stop the
|
|
379
|
+
invocation, taking precedence over a tool error. Custom engines without the
|
|
380
|
+
optional internal tool-audit subscription run without tool audit persistence;
|
|
381
|
+
direct in-process invocation has no worker persistence listener either.
|
|
382
|
+
- **Not hosted, not enterprise-grade:** a library you run yourself.
|
|
383
|
+
Isolation between your own workloads is a single `scope` string, not a
|
|
384
|
+
multi-tenant control plane.
|
|
385
|
+
|
|
386
|
+
## Development
|
|
387
|
+
|
|
388
|
+
Building requires Node.js 22.18+ on the 22.x line, 24.11+ on the 24.x line,
|
|
389
|
+
or 26+ to support tsdown and its declaration generator.
|
|
390
|
+
|
|
391
|
+
```sh
|
|
392
|
+
pnpm install
|
|
393
|
+
pnpm test # unit tests
|
|
394
|
+
pnpm test:integration # real Postgres via embedded-postgres
|
|
395
|
+
pnpm typecheck
|
|
396
|
+
pnpm format:check
|
|
397
|
+
pnpm build # compile src to dist (what npm publishes)
|
|
398
|
+
pnpm demo # in-process governed invocation, no database
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
## License
|
|
402
|
+
|
|
403
|
+
Runwarden is licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="640" viewBox="0 0 1240 640" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif">
|
|
2
|
+
|
|
3
|
+
<rect x="1" y="1" width="1238" height="638" rx="18" fill="#f8fafc" stroke="#e2e8f0"/>
|
|
4
|
+
|
|
5
|
+
<text x="165" y="52" text-anchor="middle" font-size="15" font-weight="700" letter-spacing="2" fill="#64748b">AGENTS ACT.</text>
|
|
6
|
+
<text x="620" y="52" text-anchor="middle" font-size="15" font-weight="700" letter-spacing="2" fill="#64748b">POLICIES DECIDE.</text>
|
|
7
|
+
<text x="1075" y="52" text-anchor="middle" font-size="15" font-weight="700" letter-spacing="2" fill="#64748b">TOOLS EXECUTE.</text>
|
|
8
|
+
|
|
9
|
+
<!-- Agent -->
|
|
10
|
+
<rect x="40" y="90" width="250" height="190" rx="14" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.5"/>
|
|
11
|
+
<text x="165" y="130" text-anchor="middle" font-size="20" font-weight="700" fill="#0f172a">Your agent</text>
|
|
12
|
+
<text x="165" y="152" text-anchor="middle" font-size="13" fill="#64748b">any model</text>
|
|
13
|
+
<rect x="60" y="172" width="210" height="34" rx="8" fill="#eef2ff" stroke="#c7d2fe"/>
|
|
14
|
+
<text x="165" y="194" text-anchor="middle" font-size="14" fill="#3730a3" font-family="ui-monospace, Menlo, Consolas, monospace">notes__search ×2</text>
|
|
15
|
+
<rect x="60" y="218" width="210" height="34" rx="8" fill="#fef2f2" stroke="#fecaca"/>
|
|
16
|
+
<text x="165" y="240" text-anchor="middle" font-size="14" fill="#991b1b" font-family="ui-monospace, Menlo, Consolas, monospace">billing__refund</text>
|
|
17
|
+
|
|
18
|
+
<!-- Gate -->
|
|
19
|
+
<rect x="420" y="80" width="400" height="230" rx="16" fill="#0f172a"/>
|
|
20
|
+
<text x="620" y="120" text-anchor="middle" font-size="22" font-weight="800" letter-spacing="3" fill="#ffffff">RUNWARDEN</text>
|
|
21
|
+
<text x="620" y="142" text-anchor="middle" font-size="13" fill="#94a3b8">every proposed call is checked before it runs</text>
|
|
22
|
+
<g font-size="15" fill="#e2e8f0">
|
|
23
|
+
<circle cx="462" cy="166" r="9" fill="none" stroke="#4ade80" stroke-width="2"/>
|
|
24
|
+
<text x="462" y="171" text-anchor="middle" font-size="11" fill="#4ade80">✓</text>
|
|
25
|
+
<text x="482" y="172">exactly-one call per step</text>
|
|
26
|
+
<circle cx="462" cy="198" r="9" fill="none" stroke="#4ade80" stroke-width="2"/>
|
|
27
|
+
<text x="462" y="203" text-anchor="middle" font-size="11" fill="#4ade80">✓</text>
|
|
28
|
+
<text x="482" y="204">tool allowlist</text>
|
|
29
|
+
<circle cx="462" cy="230" r="9" fill="none" stroke="#4ade80" stroke-width="2"/>
|
|
30
|
+
<text x="462" y="235" text-anchor="middle" font-size="11" fill="#4ade80">✓</text>
|
|
31
|
+
<text x="482" y="236">input validation</text>
|
|
32
|
+
<circle cx="462" cy="262" r="9" fill="none" stroke="#4ade80" stroke-width="2"/>
|
|
33
|
+
<text x="462" y="267" text-anchor="middle" font-size="11" fill="#4ade80">✓</text>
|
|
34
|
+
<text x="482" y="268">requireApproval list</text>
|
|
35
|
+
</g>
|
|
36
|
+
|
|
37
|
+
<!-- Tools -->
|
|
38
|
+
<rect x="950" y="90" width="250" height="190" rx="14" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.5"/>
|
|
39
|
+
<text x="1075" y="130" text-anchor="middle" font-size="20" font-weight="700" fill="#0f172a">Your MCP tools</text>
|
|
40
|
+
<text x="1075" y="152" text-anchor="middle" font-size="13" fill="#64748b">execution only</text>
|
|
41
|
+
<rect x="970" y="172" width="210" height="34" rx="8" fill="#f0fdf4" stroke="#bbf7d0"/>
|
|
42
|
+
<text x="1075" y="194" text-anchor="middle" font-size="14" fill="#166534" font-family="ui-monospace, Menlo, Consolas, monospace">notes__search ✓</text>
|
|
43
|
+
<rect x="970" y="218" width="210" height="34" rx="8" fill="#f8fafc" stroke="#e2e8f0"/>
|
|
44
|
+
<text x="1075" y="240" text-anchor="middle" font-size="14" fill="#94a3b8" font-family="ui-monospace, Menlo, Consolas, monospace">billing__refund ⊘</text>
|
|
45
|
+
|
|
46
|
+
<!-- Arrows -->
|
|
47
|
+
<line x1="292" y1="165" x2="405" y2="165" stroke="#334155" stroke-width="2.5"/>
|
|
48
|
+
<polygon points="420,165 405,158.5 405,171.5" fill="#334155"/>
|
|
49
|
+
<text x="354" y="150" text-anchor="middle" font-size="13" fill="#334155">proposes</text>
|
|
50
|
+
|
|
51
|
+
<line x1="822" y1="150" x2="935" y2="150" stroke="#16a34a" stroke-width="2.5"/>
|
|
52
|
+
<polygon points="950,150 935,143.5 935,156.5" fill="#16a34a"/>
|
|
53
|
+
<text x="884" y="135" text-anchor="middle" font-size="13" fill="#16a34a">allowed</text>
|
|
54
|
+
|
|
55
|
+
<line x1="822" y1="212" x2="866" y2="212" stroke="#dc2626" stroke-width="2.5" stroke-dasharray="6 4"/>
|
|
56
|
+
<polygon points="885,196 901,204 901,220 885,228 869,220 869,204" fill="#dc2626"/>
|
|
57
|
+
<text x="885" y="218" text-anchor="middle" font-size="13" font-weight="800" fill="#ffffff">!</text>
|
|
58
|
+
<text x="884" y="248" text-anchor="middle" font-size="12" fill="#b91c1c">approval-gated</text>
|
|
59
|
+
<text x="884" y="264" text-anchor="middle" font-size="12" fill="#b91c1c">stopped</text>
|
|
60
|
+
|
|
61
|
+
<path d="M 470 312 L 470 350 Q 470 364 456 364 L 178 364 Q 164 364 164 350 L 164 297" fill="none" stroke="#d97706" stroke-width="2.5"/>
|
|
62
|
+
<polygon points="164,282 157.5,297 170.5,297" fill="#d97706"/>
|
|
63
|
+
<text x="318" y="388" text-anchor="middle" font-size="13" fill="#b45309">denied → correction issued, model retries</text>
|
|
64
|
+
|
|
65
|
+
<line x1="620" y1="312" x2="620" y2="405" stroke="#334155" stroke-width="2.5"/>
|
|
66
|
+
<polygon points="620,420 613.5,405 626.5,405" fill="#334155"/>
|
|
67
|
+
<text x="634" y="362" font-size="13" fill="#334155">every ruling</text>
|
|
68
|
+
<path d="M 1075 282 L 1075 396 Q 1075 410 1061 410 L 774 410 Q 760 410 760 424 L 760 422" fill="none" stroke="#94a3b8" stroke-width="2" stroke-dasharray="5 4"/>
|
|
69
|
+
<polygon points="760,437 753.5,422 766.5,422" fill="#94a3b8"/>
|
|
70
|
+
<text x="1010" y="400" font-size="13" fill="#64748b">every execution</text>
|
|
71
|
+
|
|
72
|
+
<!-- Postgres -->
|
|
73
|
+
<path d="M 470 446 L 470 528 A 150 24 0 0 0 770 528 L 770 446" fill="#eff6ff" stroke="#93c5fd" stroke-width="1.5"/>
|
|
74
|
+
<ellipse cx="620" cy="446" rx="150" ry="24" fill="#dbeafe" stroke="#93c5fd" stroke-width="1.5"/>
|
|
75
|
+
<text x="620" y="480" text-anchor="middle" font-size="17" font-weight="700" fill="#1e3a8a">Postgres remembers.</text>
|
|
76
|
+
<text x="620" y="501" text-anchor="middle" font-size="12.5" fill="#334155" font-family="ui-monospace, Menlo, Consolas, monospace">invocations · policy_decisions</text>
|
|
77
|
+
<text x="620" y="519" text-anchor="middle" font-size="12.5" fill="#334155" font-family="ui-monospace, Menlo, Consolas, monospace">tool_call_audits · worker_leases</text>
|
|
78
|
+
|
|
79
|
+
<text x="620" y="606" text-anchor="middle" font-size="13" font-style="italic" fill="#64748b">Your database, your workers, your audit trail. No hosted control plane.</text>
|
|
80
|
+
</svg>
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { n as createDb, t as initDb } from "./init-Dm_qLwix.js";
|
|
3
|
+
// src/cli.ts
|
|
4
|
+
const [command] = process.argv.slice(2);
|
|
5
|
+
if (command !== "init") {
|
|
6
|
+
console.error("Usage: runwarden init");
|
|
7
|
+
process.exit(1);
|
|
8
|
+
}
|
|
9
|
+
const connectionString = process.env.DATABASE_URL;
|
|
10
|
+
if (!connectionString) {
|
|
11
|
+
console.error("DATABASE_URL is required");
|
|
12
|
+
process.exit(1);
|
|
13
|
+
}
|
|
14
|
+
const handle = createDb(connectionString);
|
|
15
|
+
try {
|
|
16
|
+
const result = await initDb(handle);
|
|
17
|
+
console.log(result.applied.length > 0 ? `Applied migrations: ${result.applied.join(", ")}` : "Database already up to date (no migrations applied).");
|
|
18
|
+
} finally {
|
|
19
|
+
await handle.close();
|
|
20
|
+
}
|
|
21
|
+
export {};
|