runwarden 0.1.0 → 0.3.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
@@ -247,6 +247,14 @@ real model provider), see [examples/durable](examples/durable/README.md).
247
247
  parks in `awaiting_approval` instead of failing. Your app resolves it
248
248
  with `approveInvocation` or `rejectInvocation`. Approval reruns the
249
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.
250
258
 
251
259
  All of it lives in four tables in the `agent_runtime` schema:
252
260
 
@@ -336,6 +344,33 @@ The end of a quickstart run prints that trail. A typical run:
336
344
  tool_call_audit invocation=<id> tool=billing__refund status=succeeded idempotency_key=<prefix>...
337
345
  ```
338
346
 
347
+ ## Run IDs
348
+
349
+ Every attempt of an invocation carries a run ID. It fences the attempt's
350
+ lease, travels to MCP servers as the `X-Runwarden-Run-Id` header, and is
351
+ stamped on policy decisions and tool call audits, so your own logs and
352
+ systems can correlate with Runwarden's records.
353
+
354
+ Who generates it depends on how the invocation runs:
355
+
356
+ - **Direct execution** (`invoke()` on a runtime without a database):
357
+ pass `runId` in the invocation input to use your own ID verbatim. This
358
+ is the seam for hosts that register their own run IDs, such as a
359
+ worker that resolves each attempt in its own tables. When omitted, a
360
+ random UUID is generated per invocation.
361
+ - **Durable execution** (a database plus `runWorker`): attempts are
362
+ fenced, so every attempt needs a fresh ID and a caller-supplied `runId`
363
+ is rejected instead of being silently ignored. To control the format,
364
+ pass `generateRunId` to `defineRuntime`; the worker calls it each time
365
+ it goes to claim work and uses the returned value for the attempt it
366
+ takes (a claim that finds no work discards the value unused, so the
367
+ factory must be cheap and safe to call often). The worker checks that
368
+ each value is a UUID (the run ID is stored in a Postgres `uuid`
369
+ column) and fails loudly on anything else. Returning a unique value
370
+ on every call is the factory's contract: a duplicate that is still in
371
+ use violates the unique index on active run IDs and fails that claim,
372
+ and attempt fencing assumes run IDs are never reused.
373
+
339
374
  ## Limitations
340
375
 
341
376
  - **Not for massive throughput:** Runwarden targets indie and solo scale:
package/dist/index.d.ts CHANGED
@@ -48,6 +48,7 @@ export declare class AgentRuntimeError extends Error {
48
48
  interface InvocationInput {
49
49
  scope: string;
50
50
  prompt: string;
51
+ runId?: string;
51
52
  conversationId?: string;
52
53
  orderingKey?: string;
53
54
  context?: Record<string, unknown>;
@@ -78,6 +79,7 @@ interface InvocationRecord extends InvocationInput {
78
79
  createdAt: Date;
79
80
  completedAt?: Date;
80
81
  }
82
+ type InvocationSettledListener = (invocation: InvocationRecord) => void | Promise<void>;
81
83
  interface NeutralMessage {
82
84
  role: 'user' | 'assistant' | 'system';
83
85
  content: string;
@@ -1139,6 +1141,8 @@ declare const RUNTIME_INTERNALS: unique symbol;
1139
1141
  interface RuntimeInternals {
1140
1142
  onPolicyDecision(listener: (decision: PolicyDecision) => void): () => void;
1141
1143
  onToolCallAudit?: (listener: (event: ToolCallAuditEvent) => Promise<void>) => () => void;
1144
+ notifyInvocationSettled?: (invocation: InvocationRecord) => Promise<void>;
1145
+ generateRunId?: () => string;
1142
1146
  }
1143
1147
  interface DefineRuntimeOptions {
1144
1148
  db?: DatabaseHandle;
@@ -1153,6 +1157,8 @@ interface DefineRuntimeOptions {
1153
1157
  onMetrics?: (metrics: RuntimeMetrics) => void;
1154
1158
  onPolicyDecision?: (decision: PolicyDecision) => void;
1155
1159
  onToolCallAudit?: ToolCallAuditSink;
1160
+ onInvocationSettled?: InvocationSettledListener;
1161
+ generateRunId?: () => string;
1156
1162
  }
1157
1163
  interface InvokeOptions {
1158
1164
  waitTimeoutMs?: number;
@@ -1229,4 +1235,4 @@ export declare class FakeAgentRuntime implements AgentRuntime {
1229
1235
  export declare const RUNTIME_NAME = "runwarden";
1230
1236
  export declare const RUN_ID_HEADER = "X-Runwarden-Run-Id";
1231
1237
  export declare const ERROR_CATEGORY_META_KEY = "runwarden/error-category";
1232
- export type { AgentRuntime, AgentRuntimeErrorKind, ApprovalActionOptions, DatabaseHandle, DefineRuntimeOptions, HistoryLoader, InitOptions, InitResult, InvocationInput, InvocationRecord, InvocationResult, InvocationStatus, InvokeOptions, McpServerConfig, McpToolClient, McpToolSession, NativeMcpClientConfig, NeutralMessage, OpenAiCompatibleModelConfig, PendingToolCall, PolicyDecision, PolicyDecisionKind, PolicyRule, RunWorkerOptions, Runtime, RuntimeInvocationInput, RuntimeMetrics, RuntimePolicies, SystemPromptLoader, ToolCallAuditEvent, ToolCallAuditSink, ToolDefinition, WorkerHandle };
1238
+ export type { AgentRuntime, AgentRuntimeErrorKind, ApprovalActionOptions, DatabaseHandle, DefineRuntimeOptions, HistoryLoader, InitOptions, InitResult, InvocationInput, InvocationRecord, InvocationResult, InvocationSettledListener, InvocationStatus, InvokeOptions, McpServerConfig, McpToolClient, McpToolSession, NativeMcpClientConfig, NeutralMessage, OpenAiCompatibleModelConfig, PendingToolCall, PolicyDecision, PolicyDecisionKind, PolicyRule, RunWorkerOptions, Runtime, RuntimeInvocationInput, RuntimeMetrics, RuntimePolicies, SystemPromptLoader, ToolCallAuditEvent, ToolCallAuditSink, ToolDefinition, WorkerHandle };
package/dist/index.js CHANGED
@@ -112,7 +112,8 @@ async function getInvocationRowById(db, id) {
112
112
  return raw ? mapRow(raw) : void 0;
113
113
  }
114
114
  async function claimInvocations(db, workerId, options) {
115
- return (await db.execute(sql`
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");
116
+ const result = await db.execute(sql`
116
117
  with exhausted as (
117
118
  update agent_runtime.invocations
118
119
  set status = 'failed',
@@ -122,7 +123,7 @@ async function claimInvocations(db, workerId, options) {
122
123
  ${CLEAR_CLAIM}
123
124
  where status = 'running' and lease_expires_at < now()
124
125
  and attempt_count >= max_attempts
125
- returning id
126
+ returning *
126
127
  ), candidate as (
127
128
  select inv.id
128
129
  from agent_runtime.invocations inv
@@ -151,22 +152,34 @@ async function claimInvocations(db, workerId, options) {
151
152
  order by inv.created_at asc, inv.id asc
152
153
  for update skip locked
153
154
  limit ${options.maxBatchSize}
155
+ ), claimed as (
156
+ update agent_runtime.invocations inv
157
+ set status = 'running',
158
+ attempt_count = inv.attempt_count + 1,
159
+ claimed_at = now(),
160
+ claimed_by = ${workerId},
161
+ lease_heartbeat_at = now(),
162
+ lease_expires_at = now() + (${options.leaseTimeoutMs} * interval '1 millisecond'),
163
+ started_at = coalesce(inv.started_at, now()),
164
+ active_run_id = coalesce(${options.runId ?? null}::uuid, gen_random_uuid()),
165
+ active_run_registered_at = now(),
166
+ updated_at = now()
167
+ from candidate
168
+ where inv.id = candidate.id
169
+ returning inv.*
154
170
  )
155
- update agent_runtime.invocations inv
156
- set status = 'running',
157
- attempt_count = inv.attempt_count + 1,
158
- claimed_at = now(),
159
- claimed_by = ${workerId},
160
- lease_heartbeat_at = now(),
161
- lease_expires_at = now() + (${options.leaseTimeoutMs} * interval '1 millisecond'),
162
- started_at = coalesce(inv.started_at, now()),
163
- active_run_id = gen_random_uuid(),
164
- active_run_registered_at = now(),
165
- updated_at = now()
166
- from candidate
167
- where inv.id = candidate.id
168
- returning inv.*
169
- `)).rows.map(mapRow);
171
+ select 'claimed' as transition, claimed.* from claimed
172
+ union all
173
+ select 'exhausted' as transition, exhausted.* from exhausted
174
+ `);
175
+ const claimed = [];
176
+ const exhausted = [];
177
+ for (const raw of result.rows) if (raw.transition === "exhausted") exhausted.push(mapRow(raw));
178
+ else claimed.push(mapRow(raw));
179
+ return {
180
+ claimed,
181
+ exhausted
182
+ };
170
183
  }
171
184
  async function heartbeatInvocation(db, id, workerId, runId, leaseTimeoutMs) {
172
185
  return (await db.execute(sql`
@@ -945,6 +958,9 @@ const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
945
958
  function dbRequired(operation) {
946
959
  return new AgentRuntimeError("failure", `${operation} requires a database: pass createDb() as defineRuntime({ db })`, { code: "db_required" });
947
960
  }
961
+ function callerRunIdRejected() {
962
+ 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" });
963
+ }
948
964
  function defineRuntime(options) {
949
965
  const model = options.model ?? (options.provider ? openAiCompatible(options.provider) : void 0);
950
966
  if (!model) throw new Error("defineRuntime requires either `model` or `provider`");
@@ -971,6 +987,11 @@ function defineRuntime(options) {
971
987
  }
972
988
  });
973
989
  const db = options.db;
990
+ async function notifyInvocationSettled(invocation) {
991
+ try {
992
+ await options.onInvocationSettled?.(invocation);
993
+ } catch {}
994
+ }
974
995
  async function waitForInvocation(invocationId, opts) {
975
996
  if (!db) throw dbRequired("waitForInvocation");
976
997
  const deadline = Date.now() + (opts?.waitTimeoutMs ?? 3e5);
@@ -1005,6 +1026,7 @@ function defineRuntime(options) {
1005
1026
  }
1006
1027
  }
1007
1028
  async function durableInvoke(input, opts) {
1029
+ if (input.runId !== void 0) throw callerRunIdRejected();
1008
1030
  const { invocationId } = await enqueueInvocation(db.db, input);
1009
1031
  return waitForInvocation(invocationId, opts);
1010
1032
  }
@@ -1019,17 +1041,20 @@ function defineRuntime(options) {
1019
1041
  code: "invocation_not_awaiting_approval",
1020
1042
  invocationId: id
1021
1043
  });
1022
- return toRecord(result.row);
1044
+ const record = toRecord(result.row);
1045
+ if (resolution === "rejected") await notifyInvocationSettled(record);
1046
+ return record;
1023
1047
  }
1024
1048
  return {
1025
1049
  engine,
1026
1050
  invoke: db ? durableInvoke : (input) => engine.invoke({
1027
1051
  ...input,
1028
1052
  invocationId: randomUUID(),
1029
- runId: randomUUID()
1053
+ runId: input.runId ?? randomUUID()
1030
1054
  }),
1031
1055
  enqueue: async (input) => {
1032
1056
  if (!db) throw dbRequired("enqueue");
1057
+ if (input.runId !== void 0) throw callerRunIdRejected();
1033
1058
  return enqueueInvocation(db.db, input);
1034
1059
  },
1035
1060
  getInvocation: async (id) => {
@@ -1056,7 +1081,9 @@ function defineRuntime(options) {
1056
1081
  return () => {
1057
1082
  auditListeners.delete(listener);
1058
1083
  };
1059
- }
1084
+ },
1085
+ notifyInvocationSettled,
1086
+ generateRunId: options.generateRunId
1060
1087
  }
1061
1088
  };
1062
1089
  }
@@ -1147,7 +1174,28 @@ function runWorker(options) {
1147
1174
  const db = options.db.db;
1148
1175
  const internals = options.runtime[RUNTIME_INTERNALS];
1149
1176
  let stopped = false;
1150
- async function executeOne(row) {
1177
+ function guardLease(row) {
1178
+ let lost = false;
1179
+ async function beat() {
1180
+ try {
1181
+ const owned = await heartbeatInvocation(db, row.id, workerId, row.activeRunId, leaseTimeoutMs);
1182
+ if (!owned) lost = true;
1183
+ return owned && !lost;
1184
+ } catch {
1185
+ return false;
1186
+ }
1187
+ }
1188
+ const interval = setInterval(() => void beat(), heartbeatIntervalMs);
1189
+ interval.unref?.();
1190
+ return {
1191
+ beat,
1192
+ get isLost() {
1193
+ return lost;
1194
+ },
1195
+ stop: () => clearInterval(interval)
1196
+ };
1197
+ }
1198
+ async function executeOne(row, lease) {
1151
1199
  const record = toRecord(row);
1152
1200
  const auditWrites = [];
1153
1201
  let auditError;
@@ -1179,13 +1227,6 @@ function runWorker(options) {
1179
1227
  if (!await completeToolCallAudit(db, auditId, event.phase, event.errorCode, event.runId, event.dispatchId)) throw new Error("Tool audit completion lost its dispatch claim");
1180
1228
  auditIds.delete(event.dispatchId);
1181
1229
  });
1182
- let leaseLost = false;
1183
- const heartbeat = setInterval(() => {
1184
- heartbeatInvocation(db, row.id, workerId, row.activeRunId, leaseTimeoutMs).then((ok) => {
1185
- if (!ok) leaseLost = true;
1186
- }).catch(() => void 0);
1187
- }, heartbeatIntervalMs);
1188
- heartbeat.unref?.();
1189
1230
  try {
1190
1231
  let result;
1191
1232
  try {
@@ -1201,18 +1242,30 @@ function runWorker(options) {
1201
1242
  await Promise.all(auditWrites);
1202
1243
  if (auditError) throw new AgentRuntimeError("failure", "Policy audit persistence failed", { code: "audit_persistence_failed" }, { cause: auditError });
1203
1244
  }
1204
- if (leaseLost) return;
1245
+ if (lease.isLost) return;
1205
1246
  if (await markInvocationSucceeded(db, row.id, workerId, row.activeRunId, {
1206
1247
  resultText: result.text,
1207
1248
  provider: result.provider,
1208
1249
  model: result.model
1209
- })) await options.onSucceeded?.({
1210
- ...record,
1211
- status: "succeeded",
1212
- resultText: result.text
1213
- }, result);
1250
+ })) {
1251
+ const settledRecord = await getInvocationRowById(db, String(row.id)).then((settledRow) => settledRow ? toRecord(settledRow) : {
1252
+ ...record,
1253
+ status: "succeeded",
1254
+ resultText: result.text
1255
+ }, () => ({
1256
+ ...record,
1257
+ status: "succeeded",
1258
+ resultText: result.text
1259
+ }));
1260
+ await internals?.notifyInvocationSettled?.(settledRecord);
1261
+ await options.onSucceeded?.({
1262
+ ...record,
1263
+ status: "succeeded",
1264
+ resultText: result.text
1265
+ }, result);
1266
+ }
1214
1267
  } catch (error) {
1215
- if (leaseLost) return;
1268
+ if (lease.isLost) return;
1216
1269
  const agentError = toAgentError(error);
1217
1270
  if (errorCode(agentError) === "approval_required") {
1218
1271
  const pendingToolCall = pendingFromError(agentError);
@@ -1224,34 +1277,49 @@ function runWorker(options) {
1224
1277
  code: errorCode(agentError),
1225
1278
  message: agentError.message
1226
1279
  }, retryDelayMs);
1227
- if (updated?.status === "failed") await options.onFailed?.(toRecord(updated), agentError);
1228
- } finally {
1229
- clearInterval(heartbeat);
1280
+ if (updated?.status === "failed") {
1281
+ await internals?.notifyInvocationSettled?.(toRecord(updated));
1282
+ await options.onFailed?.(toRecord(updated), agentError);
1283
+ }
1230
1284
  }
1231
1285
  }
1232
1286
  const loop = (async () => {
1233
1287
  while (!stopped) {
1288
+ let claimRunId;
1289
+ if (internals?.generateRunId) {
1290
+ claimRunId = internals.generateRunId();
1291
+ 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}`);
1292
+ }
1234
1293
  let claimed = [];
1235
1294
  try {
1236
- claimed = await claimInvocations(db, workerId, {
1237
- leaseTimeoutMs,
1238
- maxBatchSize: 1
1239
- });
1240
- } catch {
1241
- await sleep(pollIdleMs);
1242
- continue;
1243
- }
1244
- if (claimed.length === 0) {
1245
- await sleep(pollIdleMs);
1246
- continue;
1247
- }
1248
- for (const row of claimed) {
1249
- if (stopped) break;
1250
- await executeOne(row);
1295
+ try {
1296
+ const result = await claimInvocations(db, workerId, {
1297
+ leaseTimeoutMs,
1298
+ maxBatchSize: 1,
1299
+ runId: claimRunId
1300
+ });
1301
+ claimed = result.claimed.map((row) => ({
1302
+ row,
1303
+ lease: guardLease(row)
1304
+ }));
1305
+ for (const exhaustedRow of result.exhausted) await internals?.notifyInvocationSettled?.(toRecord(exhaustedRow));
1306
+ } catch {
1307
+ await sleep(pollIdleMs);
1308
+ continue;
1309
+ }
1310
+ for (const { row, lease } of claimed) {
1311
+ if (stopped) break;
1312
+ if (!await lease.beat()) continue;
1313
+ if (stopped) break;
1314
+ await executeOne(row, lease);
1315
+ }
1316
+ } finally {
1317
+ for (const { lease } of claimed) lease.stop();
1251
1318
  }
1252
- await sleep(pollActiveMs);
1319
+ await sleep(claimed.length === 0 ? pollIdleMs : pollActiveMs);
1253
1320
  }
1254
1321
  })();
1322
+ loop.catch(() => {});
1255
1323
  return { async stop() {
1256
1324
  stopped = true;
1257
1325
  await loop;
package/package.json CHANGED
@@ -90,7 +90,7 @@
90
90
  "url": "git+https://github.com/happyeric77/runwarden.git"
91
91
  },
92
92
  "scripts": {
93
- "build": "tsdown",
93
+ "build": "tsdown --config-loader tsx",
94
94
  "demo": "tsx examples/governed-invocation.ts",
95
95
  "format": "prettier --write '**/*.{ts,json,md}'",
96
96
  "format:check": "prettier --check '**/*.{ts,json,md}'",
@@ -103,5 +103,5 @@
103
103
  "sideEffects": false,
104
104
  "type": "module",
105
105
  "types": "./dist/index.d.ts",
106
- "version": "0.1.0"
106
+ "version": "0.3.0"
107
107
  }