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 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 is listed in `requireApproval`, the invocation
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.policies.requireApproval?.includes(input.toolName);
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 result = await new ToolLoopAgent({
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 }) => policy.approvalFor({
719
- toolName: toolCall.toolName,
720
- toolCallId: toolCall.toolCallId,
721
- toolInput: toolCall.input,
722
- proposalCount: state.currentProposalCount,
723
- scope: input.scope
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
- }).generate({
730
- messages: modelMessages(history, input),
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(result.steps),
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.2.0"
94
+ "version": "0.4.0"
107
95
  }