runwarden 0.2.0 → 0.4.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/README.md +42 -1
- package/dist/index.d.ts +8 -1
- package/dist/index.js +69 -16
- package/package.json +2 -14
package/README.md
CHANGED
|
@@ -196,6 +196,20 @@ a tool behind human approval, add
|
|
|
196
196
|
[full quickstart](examples/quickstart/README.md) walks through that flow
|
|
197
197
|
end to end.
|
|
198
198
|
|
|
199
|
+
For input-dependent approval, provide a synchronous predicate instead:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
policies: {
|
|
203
|
+
requireApproval: ({ toolName, input }) =>
|
|
204
|
+
toolName === 'billing__refund' &&
|
|
205
|
+
typeof input === 'object' && input !== null &&
|
|
206
|
+
'amount' in input && typeof input.amount === 'number' && input.amount > 50,
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
The predicate also receives `scope`. Return `true` to require approval; a
|
|
211
|
+
thrown error fails the invocation.
|
|
212
|
+
|
|
199
213
|
## The full quickstart (from the repo)
|
|
200
214
|
|
|
201
215
|
### Requirements
|
|
@@ -243,7 +257,7 @@ real model provider), see [examples/durable](examples/durable/README.md).
|
|
|
243
257
|
5. Every ruling lands in `policy_decisions`, a call's latest dispatch state
|
|
244
258
|
lands in `tool_call_audits`, and invocation state lands in `invocations`.
|
|
245
259
|
Tool audits are latest-state records, not a history of every attempt.
|
|
246
|
-
6. If a proposed call
|
|
260
|
+
6. If a proposed call requires approval under `requireApproval`, the invocation
|
|
247
261
|
parks in `awaiting_approval` instead of failing. Your app resolves it
|
|
248
262
|
with `approveInvocation` or `rejectInvocation`. Approval reruns the
|
|
249
263
|
whole invocation; rejection cancels it.
|
|
@@ -344,6 +358,33 @@ The end of a quickstart run prints that trail. A typical run:
|
|
|
344
358
|
tool_call_audit invocation=<id> tool=billing__refund status=succeeded idempotency_key=<prefix>...
|
|
345
359
|
```
|
|
346
360
|
|
|
361
|
+
## Run IDs
|
|
362
|
+
|
|
363
|
+
Every attempt of an invocation carries a run ID. It fences the attempt's
|
|
364
|
+
lease, travels to MCP servers as the `X-Runwarden-Run-Id` header, and is
|
|
365
|
+
stamped on policy decisions and tool call audits, so your own logs and
|
|
366
|
+
systems can correlate with Runwarden's records.
|
|
367
|
+
|
|
368
|
+
Who generates it depends on how the invocation runs:
|
|
369
|
+
|
|
370
|
+
- **Direct execution** (`invoke()` on a runtime without a database):
|
|
371
|
+
pass `runId` in the invocation input to use your own ID verbatim. This
|
|
372
|
+
is the seam for hosts that register their own run IDs, such as a
|
|
373
|
+
worker that resolves each attempt in its own tables. When omitted, a
|
|
374
|
+
random UUID is generated per invocation.
|
|
375
|
+
- **Durable execution** (a database plus `runWorker`): attempts are
|
|
376
|
+
fenced, so every attempt needs a fresh ID and a caller-supplied `runId`
|
|
377
|
+
is rejected instead of being silently ignored. To control the format,
|
|
378
|
+
pass `generateRunId` to `defineRuntime`; the worker calls it each time
|
|
379
|
+
it goes to claim work and uses the returned value for the attempt it
|
|
380
|
+
takes (a claim that finds no work discards the value unused, so the
|
|
381
|
+
factory must be cheap and safe to call often). The worker checks that
|
|
382
|
+
each value is a UUID (the run ID is stored in a Postgres `uuid`
|
|
383
|
+
column) and fails loudly on anything else. Returning a unique value
|
|
384
|
+
on every call is the factory's contract: a duplicate that is still in
|
|
385
|
+
use violates the unique index on active run IDs and fails that claim,
|
|
386
|
+
and attempt fencing assumes run IDs are never reused.
|
|
387
|
+
|
|
347
388
|
## Limitations
|
|
348
389
|
|
|
349
390
|
- **Not for massive throughput:** Runwarden targets indie and solo scale:
|
package/dist/index.d.ts
CHANGED
|
@@ -36,7 +36,11 @@ interface RuntimePolicies {
|
|
|
36
36
|
maxToolCallsPerInvocation?: number;
|
|
37
37
|
maxDurationMs?: number;
|
|
38
38
|
toolAllowlist?: string[] | ((scope: string) => string[] | undefined);
|
|
39
|
-
requireApproval?: string[]
|
|
39
|
+
requireApproval?: string[] | ((call: {
|
|
40
|
+
scope: string;
|
|
41
|
+
toolName: string;
|
|
42
|
+
input: unknown;
|
|
43
|
+
}) => boolean);
|
|
40
44
|
maxToolResultBytes?: number;
|
|
41
45
|
}
|
|
42
46
|
type AgentRuntimeErrorKind = 'timeout' | 'failure';
|
|
@@ -48,6 +52,7 @@ export declare class AgentRuntimeError extends Error {
|
|
|
48
52
|
interface InvocationInput {
|
|
49
53
|
scope: string;
|
|
50
54
|
prompt: string;
|
|
55
|
+
runId?: string;
|
|
51
56
|
conversationId?: string;
|
|
52
57
|
orderingKey?: string;
|
|
53
58
|
context?: Record<string, unknown>;
|
|
@@ -1141,6 +1146,7 @@ interface RuntimeInternals {
|
|
|
1141
1146
|
onPolicyDecision(listener: (decision: PolicyDecision) => void): () => void;
|
|
1142
1147
|
onToolCallAudit?: (listener: (event: ToolCallAuditEvent) => Promise<void>) => () => void;
|
|
1143
1148
|
notifyInvocationSettled?: (invocation: InvocationRecord) => Promise<void>;
|
|
1149
|
+
generateRunId?: () => string;
|
|
1144
1150
|
}
|
|
1145
1151
|
interface DefineRuntimeOptions {
|
|
1146
1152
|
db?: DatabaseHandle;
|
|
@@ -1156,6 +1162,7 @@ interface DefineRuntimeOptions {
|
|
|
1156
1162
|
onPolicyDecision?: (decision: PolicyDecision) => void;
|
|
1157
1163
|
onToolCallAudit?: ToolCallAuditSink;
|
|
1158
1164
|
onInvocationSettled?: InvocationSettledListener;
|
|
1165
|
+
generateRunId?: () => string;
|
|
1159
1166
|
}
|
|
1160
1167
|
interface InvokeOptions {
|
|
1161
1168
|
waitTimeoutMs?: number;
|
package/dist/index.js
CHANGED
|
@@ -112,6 +112,7 @@ async function getInvocationRowById(db, id) {
|
|
|
112
112
|
return raw ? mapRow(raw) : void 0;
|
|
113
113
|
}
|
|
114
114
|
async function claimInvocations(db, workerId, options) {
|
|
115
|
+
if (options.runId !== void 0 && options.maxBatchSize !== 1) throw new Error("ClaimOptions.runId requires maxBatchSize of 1: a single runId cannot identify multiple attempts");
|
|
115
116
|
const result = await db.execute(sql`
|
|
116
117
|
with exhausted as (
|
|
117
118
|
update agent_runtime.invocations
|
|
@@ -160,7 +161,7 @@ async function claimInvocations(db, workerId, options) {
|
|
|
160
161
|
lease_heartbeat_at = now(),
|
|
161
162
|
lease_expires_at = now() + (${options.leaseTimeoutMs} * interval '1 millisecond'),
|
|
162
163
|
started_at = coalesce(inv.started_at, now()),
|
|
163
|
-
active_run_id = gen_random_uuid(),
|
|
164
|
+
active_run_id = coalesce(${options.runId ?? null}::uuid, gen_random_uuid()),
|
|
164
165
|
active_run_registered_at = now(),
|
|
165
166
|
updated_at = now()
|
|
166
167
|
from candidate
|
|
@@ -467,7 +468,7 @@ var PolicyEngine = class {
|
|
|
467
468
|
reason: "The correction must call the same tool with corrected arguments."
|
|
468
469
|
};
|
|
469
470
|
}
|
|
470
|
-
const requiresApproval = this.
|
|
471
|
+
const requiresApproval = this.isApprovalRequired(input.scope, input.toolName, input.toolInput);
|
|
471
472
|
const matchesApproval = this.approvedToolCall !== void 0 && isSameToolCall(this.approvedToolCall, input.toolName, input.toolInput);
|
|
472
473
|
if (requiresApproval && !matchesApproval) {
|
|
473
474
|
this.pendingApproval ??= {
|
|
@@ -518,6 +519,17 @@ var PolicyEngine = class {
|
|
|
518
519
|
afterStep(toolCalls) {
|
|
519
520
|
if (this.terminal) return;
|
|
520
521
|
if (this.pendingCorrection) {
|
|
522
|
+
if (toolCalls.length === 0) {
|
|
523
|
+
if (this.pendingCorrection.correctionsUsed >= this.correctionBudget) this.exhaustCorrection(toolCalls);
|
|
524
|
+
else {
|
|
525
|
+
this.pendingCorrection.correctionsUsed += 1;
|
|
526
|
+
this.record({
|
|
527
|
+
rule: this.pendingCorrection.kind === "multi-call" ? "exactly_one" : "input_validation",
|
|
528
|
+
decision: "correction_issued"
|
|
529
|
+
});
|
|
530
|
+
}
|
|
531
|
+
return;
|
|
532
|
+
}
|
|
521
533
|
const only = toolCalls.length === 1 ? toolCalls[0] : void 0;
|
|
522
534
|
if (only && !only.invalid) {
|
|
523
535
|
this.pendingCorrection = void 0;
|
|
@@ -591,6 +603,14 @@ var PolicyEngine = class {
|
|
|
591
603
|
});
|
|
592
604
|
this.terminal = new AgentRuntimeError("failure", toolCalls.length === 0 ? "Provider did not return a corrected tool call" : toolCalls.length > 1 ? "Provider returned multiple tool calls" : "Provider returned invalid tool input", toolCalls.length > 1 ? { code: "multiple_tool_calls" } : void 0);
|
|
593
605
|
}
|
|
606
|
+
isApprovalRequired(scope, toolName, input) {
|
|
607
|
+
const policy = this.policies.requireApproval;
|
|
608
|
+
return typeof policy === "function" ? policy({
|
|
609
|
+
scope,
|
|
610
|
+
toolName,
|
|
611
|
+
input
|
|
612
|
+
}) : policy?.includes(toolName) ?? false;
|
|
613
|
+
}
|
|
594
614
|
record(decision) {
|
|
595
615
|
try {
|
|
596
616
|
this.hooks.onDecision?.(decision);
|
|
@@ -695,6 +715,7 @@ var AiSdkNativeRuntime = class {
|
|
|
695
715
|
correctionForInvalidCall: (call) => this.correctionFor(call),
|
|
696
716
|
approvedToolCall: input.approvedToolCall
|
|
697
717
|
});
|
|
718
|
+
let approvalError;
|
|
698
719
|
try {
|
|
699
720
|
const systemPrompt = this.options.loadSystemPrompt ? await this.options.loadSystemPrompt(input) : "";
|
|
700
721
|
const contextLoadedAt = this.now();
|
|
@@ -702,7 +723,7 @@ var AiSdkNativeRuntime = class {
|
|
|
702
723
|
const historyLoadedAt = this.now();
|
|
703
724
|
const baseInstructions = [systemPrompt, this.options.policies?.exactlyOneToolCallPerStep ?? true ? TOOL_EXECUTION_CONTRACT : ""].filter((part) => part.length > 0).join("\n\n");
|
|
704
725
|
const tools = this.createTools(input, startedAt, state, policy);
|
|
705
|
-
const
|
|
726
|
+
const agent = new ToolLoopAgent({
|
|
706
727
|
model: this.options.model,
|
|
707
728
|
tools,
|
|
708
729
|
instructions: baseInstructions,
|
|
@@ -715,21 +736,39 @@ var AiSdkNativeRuntime = class {
|
|
|
715
736
|
onLanguageModelCallEnd: (event) => {
|
|
716
737
|
state.currentProposalCount = event.content.filter((part) => part.type === "tool-call").length;
|
|
717
738
|
},
|
|
718
|
-
toolApproval: ({ toolCall }) =>
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
739
|
+
toolApproval: ({ toolCall }) => {
|
|
740
|
+
try {
|
|
741
|
+
return policy.approvalFor({
|
|
742
|
+
toolName: toolCall.toolName,
|
|
743
|
+
toolCallId: toolCall.toolCallId,
|
|
744
|
+
toolInput: toolCall.input,
|
|
745
|
+
proposalCount: state.currentProposalCount,
|
|
746
|
+
scope: input.scope
|
|
747
|
+
});
|
|
748
|
+
} catch (error) {
|
|
749
|
+
approvalError = { error };
|
|
750
|
+
throw error;
|
|
751
|
+
}
|
|
752
|
+
},
|
|
725
753
|
onStepEnd: (step) => {
|
|
726
754
|
policy.afterStep(step.toolCalls);
|
|
727
755
|
},
|
|
728
756
|
stopWhen: () => policy.terminalError != null
|
|
729
|
-
})
|
|
730
|
-
|
|
757
|
+
});
|
|
758
|
+
const messages = modelMessages(history, input);
|
|
759
|
+
let result = await agent.generate({
|
|
760
|
+
messages,
|
|
731
761
|
timeout: this.remaining(startedAt)
|
|
732
762
|
});
|
|
763
|
+
const steps = [...result.steps];
|
|
764
|
+
while (!policy.terminalError && policy.correctionInstruction()) {
|
|
765
|
+
messages.push(...result.response.messages);
|
|
766
|
+
result = await agent.generate({
|
|
767
|
+
messages,
|
|
768
|
+
timeout: this.remaining(startedAt)
|
|
769
|
+
});
|
|
770
|
+
steps.push(...result.steps);
|
|
771
|
+
}
|
|
733
772
|
if (policy.terminalError) throw policy.terminalError;
|
|
734
773
|
const text = result.text.trim();
|
|
735
774
|
const provider = normalizeProviderName(result.finalStep.model.provider);
|
|
@@ -744,7 +783,7 @@ var AiSdkNativeRuntime = class {
|
|
|
744
783
|
contextLoadMs: contextLoadedAt - startedAt,
|
|
745
784
|
historyLoadMs: historyLoadedAt - contextLoadedAt,
|
|
746
785
|
toolCallCount: state.toolCallCount,
|
|
747
|
-
...aggregateStepTimings(
|
|
786
|
+
...aggregateStepTimings(steps),
|
|
748
787
|
totalMs: completedAt - startedAt
|
|
749
788
|
});
|
|
750
789
|
return {
|
|
@@ -755,6 +794,7 @@ var AiSdkNativeRuntime = class {
|
|
|
755
794
|
model
|
|
756
795
|
};
|
|
757
796
|
} catch (error) {
|
|
797
|
+
if (approvalError) throw approvalError.error;
|
|
758
798
|
const runtimeError = findAgentRuntimeError(error);
|
|
759
799
|
if (runtimeError) throw runtimeError;
|
|
760
800
|
if (isTimeoutFailure(error)) throw new AgentRuntimeError("timeout", "Native runtime timed out");
|
|
@@ -957,6 +997,9 @@ const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
|
957
997
|
function dbRequired(operation) {
|
|
958
998
|
return new AgentRuntimeError("failure", `${operation} requires a database: pass createDb() as defineRuntime({ db })`, { code: "db_required" });
|
|
959
999
|
}
|
|
1000
|
+
function callerRunIdRejected() {
|
|
1001
|
+
return new AgentRuntimeError("failure", "InvocationInput.runId is only honored for direct execution without a database. Durable invocations mint a fresh runId per attempt; use defineRuntime({ generateRunId }) to control how those runIds are generated.", { code: "caller_run_id_in_durable_mode" });
|
|
1002
|
+
}
|
|
960
1003
|
function defineRuntime(options) {
|
|
961
1004
|
const model = options.model ?? (options.provider ? openAiCompatible(options.provider) : void 0);
|
|
962
1005
|
if (!model) throw new Error("defineRuntime requires either `model` or `provider`");
|
|
@@ -1022,6 +1065,7 @@ function defineRuntime(options) {
|
|
|
1022
1065
|
}
|
|
1023
1066
|
}
|
|
1024
1067
|
async function durableInvoke(input, opts) {
|
|
1068
|
+
if (input.runId !== void 0) throw callerRunIdRejected();
|
|
1025
1069
|
const { invocationId } = await enqueueInvocation(db.db, input);
|
|
1026
1070
|
return waitForInvocation(invocationId, opts);
|
|
1027
1071
|
}
|
|
@@ -1045,10 +1089,11 @@ function defineRuntime(options) {
|
|
|
1045
1089
|
invoke: db ? durableInvoke : (input) => engine.invoke({
|
|
1046
1090
|
...input,
|
|
1047
1091
|
invocationId: randomUUID(),
|
|
1048
|
-
runId: randomUUID()
|
|
1092
|
+
runId: input.runId ?? randomUUID()
|
|
1049
1093
|
}),
|
|
1050
1094
|
enqueue: async (input) => {
|
|
1051
1095
|
if (!db) throw dbRequired("enqueue");
|
|
1096
|
+
if (input.runId !== void 0) throw callerRunIdRejected();
|
|
1052
1097
|
return enqueueInvocation(db.db, input);
|
|
1053
1098
|
},
|
|
1054
1099
|
getInvocation: async (id) => {
|
|
@@ -1076,7 +1121,8 @@ function defineRuntime(options) {
|
|
|
1076
1121
|
auditListeners.delete(listener);
|
|
1077
1122
|
};
|
|
1078
1123
|
},
|
|
1079
|
-
notifyInvocationSettled
|
|
1124
|
+
notifyInvocationSettled,
|
|
1125
|
+
generateRunId: options.generateRunId
|
|
1080
1126
|
}
|
|
1081
1127
|
};
|
|
1082
1128
|
}
|
|
@@ -1278,12 +1324,18 @@ function runWorker(options) {
|
|
|
1278
1324
|
}
|
|
1279
1325
|
const loop = (async () => {
|
|
1280
1326
|
while (!stopped) {
|
|
1327
|
+
let claimRunId;
|
|
1328
|
+
if (internals?.generateRunId) {
|
|
1329
|
+
claimRunId = internals.generateRunId();
|
|
1330
|
+
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(claimRunId)) throw new Error(`generateRunId must return a UUID string, got: ${claimRunId}`);
|
|
1331
|
+
}
|
|
1281
1332
|
let claimed = [];
|
|
1282
1333
|
try {
|
|
1283
1334
|
try {
|
|
1284
1335
|
const result = await claimInvocations(db, workerId, {
|
|
1285
1336
|
leaseTimeoutMs,
|
|
1286
|
-
maxBatchSize: 1
|
|
1337
|
+
maxBatchSize: 1,
|
|
1338
|
+
runId: claimRunId
|
|
1287
1339
|
});
|
|
1288
1340
|
claimed = result.claimed.map((row) => ({
|
|
1289
1341
|
row,
|
|
@@ -1306,6 +1358,7 @@ function runWorker(options) {
|
|
|
1306
1358
|
await sleep(claimed.length === 0 ? pollIdleMs : pollActiveMs);
|
|
1307
1359
|
}
|
|
1308
1360
|
})();
|
|
1361
|
+
loop.catch(() => {});
|
|
1309
1362
|
return { async stop() {
|
|
1310
1363
|
stopped = true;
|
|
1311
1364
|
await loop;
|
package/package.json
CHANGED
|
@@ -57,18 +57,6 @@
|
|
|
57
57
|
"main": "./dist/index.js",
|
|
58
58
|
"name": "runwarden",
|
|
59
59
|
"packageManager": "pnpm@10.34.9",
|
|
60
|
-
"pnpm": {
|
|
61
|
-
"onlyBuiltDependencies": [
|
|
62
|
-
"@embedded-postgres/darwin-arm64",
|
|
63
|
-
"@embedded-postgres/darwin-x64",
|
|
64
|
-
"@embedded-postgres/linux-arm",
|
|
65
|
-
"@embedded-postgres/linux-arm64",
|
|
66
|
-
"@embedded-postgres/linux-ia32",
|
|
67
|
-
"@embedded-postgres/linux-ppc64",
|
|
68
|
-
"@embedded-postgres/linux-x64",
|
|
69
|
-
"@embedded-postgres/windows-x64"
|
|
70
|
-
]
|
|
71
|
-
},
|
|
72
60
|
"prettier": {
|
|
73
61
|
"importOrder": [
|
|
74
62
|
"<BUILTIN_MODULES>",
|
|
@@ -90,7 +78,7 @@
|
|
|
90
78
|
"url": "git+https://github.com/happyeric77/runwarden.git"
|
|
91
79
|
},
|
|
92
80
|
"scripts": {
|
|
93
|
-
"build": "tsdown",
|
|
81
|
+
"build": "tsdown --config-loader tsx",
|
|
94
82
|
"demo": "tsx examples/governed-invocation.ts",
|
|
95
83
|
"format": "prettier --write '**/*.{ts,json,md}'",
|
|
96
84
|
"format:check": "prettier --check '**/*.{ts,json,md}'",
|
|
@@ -103,5 +91,5 @@
|
|
|
103
91
|
"sideEffects": false,
|
|
104
92
|
"type": "module",
|
|
105
93
|
"types": "./dist/index.d.ts",
|
|
106
|
-
"version": "0.
|
|
94
|
+
"version": "0.4.0"
|
|
107
95
|
}
|