runwarden 0.1.0 → 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/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
 
package/dist/index.d.ts CHANGED
@@ -78,6 +78,7 @@ interface InvocationRecord extends InvocationInput {
78
78
  createdAt: Date;
79
79
  completedAt?: Date;
80
80
  }
81
+ type InvocationSettledListener = (invocation: InvocationRecord) => void | Promise<void>;
81
82
  interface NeutralMessage {
82
83
  role: 'user' | 'assistant' | 'system';
83
84
  content: string;
@@ -1139,6 +1140,7 @@ declare const RUNTIME_INTERNALS: unique symbol;
1139
1140
  interface RuntimeInternals {
1140
1141
  onPolicyDecision(listener: (decision: PolicyDecision) => void): () => void;
1141
1142
  onToolCallAudit?: (listener: (event: ToolCallAuditEvent) => Promise<void>) => () => void;
1143
+ notifyInvocationSettled?: (invocation: InvocationRecord) => Promise<void>;
1142
1144
  }
1143
1145
  interface DefineRuntimeOptions {
1144
1146
  db?: DatabaseHandle;
@@ -1153,6 +1155,7 @@ interface DefineRuntimeOptions {
1153
1155
  onMetrics?: (metrics: RuntimeMetrics) => void;
1154
1156
  onPolicyDecision?: (decision: PolicyDecision) => void;
1155
1157
  onToolCallAudit?: ToolCallAuditSink;
1158
+ onInvocationSettled?: InvocationSettledListener;
1156
1159
  }
1157
1160
  interface InvokeOptions {
1158
1161
  waitTimeoutMs?: number;
@@ -1229,4 +1232,4 @@ export declare class FakeAgentRuntime implements AgentRuntime {
1229
1232
  export declare const RUNTIME_NAME = "runwarden";
1230
1233
  export declare const RUN_ID_HEADER = "X-Runwarden-Run-Id";
1231
1234
  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 };
1235
+ 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,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
- return (await db.execute(sql`
115
+ const result = await db.execute(sql`
116
116
  with exhausted as (
117
117
  update agent_runtime.invocations
118
118
  set status = 'failed',
@@ -122,7 +122,7 @@ async function claimInvocations(db, workerId, options) {
122
122
  ${CLEAR_CLAIM}
123
123
  where status = 'running' and lease_expires_at < now()
124
124
  and attempt_count >= max_attempts
125
- returning id
125
+ returning *
126
126
  ), candidate as (
127
127
  select inv.id
128
128
  from agent_runtime.invocations inv
@@ -151,22 +151,34 @@ async function claimInvocations(db, workerId, options) {
151
151
  order by inv.created_at asc, inv.id asc
152
152
  for update skip locked
153
153
  limit ${options.maxBatchSize}
154
+ ), claimed as (
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.*
154
169
  )
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);
170
+ select 'claimed' as transition, claimed.* from claimed
171
+ union all
172
+ select 'exhausted' as transition, exhausted.* from exhausted
173
+ `);
174
+ const claimed = [];
175
+ const exhausted = [];
176
+ for (const raw of result.rows) if (raw.transition === "exhausted") exhausted.push(mapRow(raw));
177
+ else claimed.push(mapRow(raw));
178
+ return {
179
+ claimed,
180
+ exhausted
181
+ };
170
182
  }
171
183
  async function heartbeatInvocation(db, id, workerId, runId, leaseTimeoutMs) {
172
184
  return (await db.execute(sql`
@@ -971,6 +983,11 @@ function defineRuntime(options) {
971
983
  }
972
984
  });
973
985
  const db = options.db;
986
+ async function notifyInvocationSettled(invocation) {
987
+ try {
988
+ await options.onInvocationSettled?.(invocation);
989
+ } catch {}
990
+ }
974
991
  async function waitForInvocation(invocationId, opts) {
975
992
  if (!db) throw dbRequired("waitForInvocation");
976
993
  const deadline = Date.now() + (opts?.waitTimeoutMs ?? 3e5);
@@ -1019,7 +1036,9 @@ function defineRuntime(options) {
1019
1036
  code: "invocation_not_awaiting_approval",
1020
1037
  invocationId: id
1021
1038
  });
1022
- return toRecord(result.row);
1039
+ const record = toRecord(result.row);
1040
+ if (resolution === "rejected") await notifyInvocationSettled(record);
1041
+ return record;
1023
1042
  }
1024
1043
  return {
1025
1044
  engine,
@@ -1056,7 +1075,8 @@ function defineRuntime(options) {
1056
1075
  return () => {
1057
1076
  auditListeners.delete(listener);
1058
1077
  };
1059
- }
1078
+ },
1079
+ notifyInvocationSettled
1060
1080
  }
1061
1081
  };
1062
1082
  }
@@ -1147,7 +1167,28 @@ function runWorker(options) {
1147
1167
  const db = options.db.db;
1148
1168
  const internals = options.runtime[RUNTIME_INTERNALS];
1149
1169
  let stopped = false;
1150
- async function executeOne(row) {
1170
+ function guardLease(row) {
1171
+ let lost = false;
1172
+ async function beat() {
1173
+ try {
1174
+ const owned = await heartbeatInvocation(db, row.id, workerId, row.activeRunId, leaseTimeoutMs);
1175
+ if (!owned) lost = true;
1176
+ return owned && !lost;
1177
+ } catch {
1178
+ return false;
1179
+ }
1180
+ }
1181
+ const interval = setInterval(() => void beat(), heartbeatIntervalMs);
1182
+ interval.unref?.();
1183
+ return {
1184
+ beat,
1185
+ get isLost() {
1186
+ return lost;
1187
+ },
1188
+ stop: () => clearInterval(interval)
1189
+ };
1190
+ }
1191
+ async function executeOne(row, lease) {
1151
1192
  const record = toRecord(row);
1152
1193
  const auditWrites = [];
1153
1194
  let auditError;
@@ -1179,13 +1220,6 @@ function runWorker(options) {
1179
1220
  if (!await completeToolCallAudit(db, auditId, event.phase, event.errorCode, event.runId, event.dispatchId)) throw new Error("Tool audit completion lost its dispatch claim");
1180
1221
  auditIds.delete(event.dispatchId);
1181
1222
  });
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
1223
  try {
1190
1224
  let result;
1191
1225
  try {
@@ -1201,18 +1235,30 @@ function runWorker(options) {
1201
1235
  await Promise.all(auditWrites);
1202
1236
  if (auditError) throw new AgentRuntimeError("failure", "Policy audit persistence failed", { code: "audit_persistence_failed" }, { cause: auditError });
1203
1237
  }
1204
- if (leaseLost) return;
1238
+ if (lease.isLost) return;
1205
1239
  if (await markInvocationSucceeded(db, row.id, workerId, row.activeRunId, {
1206
1240
  resultText: result.text,
1207
1241
  provider: result.provider,
1208
1242
  model: result.model
1209
- })) await options.onSucceeded?.({
1210
- ...record,
1211
- status: "succeeded",
1212
- resultText: result.text
1213
- }, result);
1243
+ })) {
1244
+ const settledRecord = await getInvocationRowById(db, String(row.id)).then((settledRow) => settledRow ? toRecord(settledRow) : {
1245
+ ...record,
1246
+ status: "succeeded",
1247
+ resultText: result.text
1248
+ }, () => ({
1249
+ ...record,
1250
+ status: "succeeded",
1251
+ resultText: result.text
1252
+ }));
1253
+ await internals?.notifyInvocationSettled?.(settledRecord);
1254
+ await options.onSucceeded?.({
1255
+ ...record,
1256
+ status: "succeeded",
1257
+ resultText: result.text
1258
+ }, result);
1259
+ }
1214
1260
  } catch (error) {
1215
- if (leaseLost) return;
1261
+ if (lease.isLost) return;
1216
1262
  const agentError = toAgentError(error);
1217
1263
  if (errorCode(agentError) === "approval_required") {
1218
1264
  const pendingToolCall = pendingFromError(agentError);
@@ -1224,32 +1270,40 @@ function runWorker(options) {
1224
1270
  code: errorCode(agentError),
1225
1271
  message: agentError.message
1226
1272
  }, retryDelayMs);
1227
- if (updated?.status === "failed") await options.onFailed?.(toRecord(updated), agentError);
1228
- } finally {
1229
- clearInterval(heartbeat);
1273
+ if (updated?.status === "failed") {
1274
+ await internals?.notifyInvocationSettled?.(toRecord(updated));
1275
+ await options.onFailed?.(toRecord(updated), agentError);
1276
+ }
1230
1277
  }
1231
1278
  }
1232
1279
  const loop = (async () => {
1233
1280
  while (!stopped) {
1234
1281
  let claimed = [];
1235
1282
  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);
1283
+ try {
1284
+ const result = await claimInvocations(db, workerId, {
1285
+ leaseTimeoutMs,
1286
+ maxBatchSize: 1
1287
+ });
1288
+ claimed = result.claimed.map((row) => ({
1289
+ row,
1290
+ lease: guardLease(row)
1291
+ }));
1292
+ for (const exhaustedRow of result.exhausted) await internals?.notifyInvocationSettled?.(toRecord(exhaustedRow));
1293
+ } catch {
1294
+ await sleep(pollIdleMs);
1295
+ continue;
1296
+ }
1297
+ for (const { row, lease } of claimed) {
1298
+ if (stopped) break;
1299
+ if (!await lease.beat()) continue;
1300
+ if (stopped) break;
1301
+ await executeOne(row, lease);
1302
+ }
1303
+ } finally {
1304
+ for (const { lease } of claimed) lease.stop();
1251
1305
  }
1252
- await sleep(pollActiveMs);
1306
+ await sleep(claimed.length === 0 ? pollIdleMs : pollActiveMs);
1253
1307
  }
1254
1308
  })();
1255
1309
  return { async stop() {
package/package.json CHANGED
@@ -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.2.0"
107
107
  }