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 +35 -0
- package/dist/index.d.ts +7 -1
- package/dist/index.js +122 -54
- package/package.json +2 -2
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
|
-
|
|
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
|
|
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
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 (
|
|
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
|
-
}))
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
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 (
|
|
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")
|
|
1228
|
-
|
|
1229
|
-
|
|
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
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
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.
|
|
106
|
+
"version": "0.3.0"
|
|
107
107
|
}
|