@crewhaus/target-batch-worker 0.3.2 → 0.4.2

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/dist/index.d.ts CHANGED
@@ -4,9 +4,11 @@
4
4
  * Codegen for the queue-worker target. Emits a single self-contained
5
5
  * daemon (`agent.ts`) that:
6
6
  *
7
- * 1. Constructs the configured queue adapter (in-memory only in v0;
8
- * SQS / Redis Streams / Postgres adapters stub out at the
9
- * `unsupported queue adapter` error).
7
+ * 1. Constructs the configured queue adapter. `in-memory` is the default
8
+ * and needs no environment; `sqs` / `redis-streams` / `postgres`
9
+ * resolve their connection details from the environment at boot
10
+ * (SQS_QUEUE_URL+AWS_REGION / REDIS_URL / DATABASE_URL — G06) and
11
+ * fail fast with the missing variable's name.
10
12
  * 2. Optionally seeds the in-memory adapter with `queue.seedJobs`
11
13
  * (test / smoke convenience).
12
14
  * 3. Boots a `queue-consumer` with the user's `agent` as the handler
@@ -14,12 +16,19 @@
14
16
  * the job input as the user message; the assistant's terminal text
15
17
  * is the cached result.
16
18
  * 4. Streams JSON events to stdout (`worker_start | job_start |
17
- * job_end | drain_start | drain_end | worker_stop`).
19
+ * job_end | drain_start | drain_end | worker_stop`). A successful
20
+ * `job_end` carries the handler's `result` (the assistant's terminal
21
+ * text) and `resultBytes`, so the run's observable output contains the
22
+ * work product and not just status — `CREWHAUS_BATCH_EMIT_RESULT=0`
23
+ * drops the payload and keeps `resultBytes`.
18
24
  * 5. Installs SIGTERM + SIGINT handlers that drain in-flight jobs
19
25
  * cleanly before exit.
20
26
  * 6. Runs the boot-time self-heal janitor (ops item 36) — session TTL
21
27
  * eviction + orphaned-tool_use report — at boot and hourly
22
28
  * (`CREWHAUS_JANITOR=0` / `CREWHAUS_JANITOR_INTERVAL_MS` to tune).
29
+ * 7. Builds the pending-approval store (G11) so a tool that resolves to
30
+ * `ask` PARKS for an out-of-band grant instead of collapsing to a deny
31
+ * on this surface, which has nobody to prompt.
23
32
  */
24
33
  import { CrewhausError } from "@crewhaus/errors";
25
34
  import { type Bundle, type EmitReadmeOptions, type IrBatchV0 } from "@crewhaus/ir";
package/dist/index.js CHANGED
@@ -4,9 +4,11 @@
4
4
  * Codegen for the queue-worker target. Emits a single self-contained
5
5
  * daemon (`agent.ts`) that:
6
6
  *
7
- * 1. Constructs the configured queue adapter (in-memory only in v0;
8
- * SQS / Redis Streams / Postgres adapters stub out at the
9
- * `unsupported queue adapter` error).
7
+ * 1. Constructs the configured queue adapter. `in-memory` is the default
8
+ * and needs no environment; `sqs` / `redis-streams` / `postgres`
9
+ * resolve their connection details from the environment at boot
10
+ * (SQS_QUEUE_URL+AWS_REGION / REDIS_URL / DATABASE_URL — G06) and
11
+ * fail fast with the missing variable's name.
10
12
  * 2. Optionally seeds the in-memory adapter with `queue.seedJobs`
11
13
  * (test / smoke convenience).
12
14
  * 3. Boots a `queue-consumer` with the user's `agent` as the handler
@@ -14,12 +16,19 @@
14
16
  * the job input as the user message; the assistant's terminal text
15
17
  * is the cached result.
16
18
  * 4. Streams JSON events to stdout (`worker_start | job_start |
17
- * job_end | drain_start | drain_end | worker_stop`).
19
+ * job_end | drain_start | drain_end | worker_stop`). A successful
20
+ * `job_end` carries the handler's `result` (the assistant's terminal
21
+ * text) and `resultBytes`, so the run's observable output contains the
22
+ * work product and not just status — `CREWHAUS_BATCH_EMIT_RESULT=0`
23
+ * drops the payload and keeps `resultBytes`.
18
24
  * 5. Installs SIGTERM + SIGINT handlers that drain in-flight jobs
19
25
  * cleanly before exit.
20
26
  * 6. Runs the boot-time self-heal janitor (ops item 36) — session TTL
21
27
  * eviction + orphaned-tool_use report — at boot and hourly
22
28
  * (`CREWHAUS_JANITOR=0` / `CREWHAUS_JANITOR_INTERVAL_MS` to tune).
29
+ * 7. Builds the pending-approval store (G11) so a tool that resolves to
30
+ * `ask` PARKS for an out-of-band grant instead of collapsing to a deny
31
+ * on this surface, which has nobody to prompt.
23
32
  */
24
33
  import { CrewhausError } from "@crewhaus/errors";
25
34
  import { escapeJsonString } from "@crewhaus/infra-utils";
@@ -106,6 +115,30 @@ function renderPermissionsField(ir) {
106
115
  }
107
116
  return `\n${lines.join("\n")}`;
108
117
  }
118
+ /**
119
+ * Loop contract 0.4 (G11) — the `askMode` + `approvals` fields. Unlike the
120
+ * CLI's `approvalRunOptions`, a bundle parses no `--ask-mode`, so the spec
121
+ * value is FIXED here at emit time. The store is built UNCONDITIONALLY,
122
+ * including under `"deny"` where it never parks, so runtime-core's denial
123
+ * diagnostic can honestly say `ask_mode: "deny"` instead of blaming absent
124
+ * plumbing (it branches on `approvals === undefined`).
125
+ *
126
+ * Deliberately SEPARATE from renderPermissionsField, which early-returns ""
127
+ * when the spec declares no `permissions:` block — precisely the case where
128
+ * parking matters most, since with no block every unmatched tool resolves to
129
+ * `ask`.
130
+ *
131
+ * CAVEAT unique to this shape: a park throws `RunFailedError`
132
+ * (`approval_pending`) out of the queue handler, so the queue-consumer sees a
133
+ * failed job and retries it per SPEC_MAX_RETRIES — the job can dead-letter
134
+ * before a human ever grants. The store keys on (toolName, inputHash), so a
135
+ * later re-delivery DOES find the grant and re-resolves pre-decided, but only
136
+ * while the retry budget lasts.
137
+ */
138
+ function renderApprovalFields(ir, indent) {
139
+ return (`\n${indent}askMode: ${escapeJsonString(ir.permissions.askMode ?? "pause")},` +
140
+ `\n${indent}approvals: { store: __approvals, surface: "batch" },`);
141
+ }
109
142
  /**
110
143
  * Adaptive model routing — render the `modelPool` runChatLoop field.
111
144
  * JSON.stringify safely quotes the validated pool object (mirroring
@@ -130,12 +163,247 @@ function taxonomyField(ir, indent) {
130
163
  return "";
131
164
  return `\n${indent}failureTaxonomy: ${JSON.stringify(taxonomy)},`;
132
165
  }
133
- export function emitBatchWorker(ir, opts = {}) {
134
- if (ir.queue.adapter !== "in-memory") {
135
- // v0 only ships the in-memory adapter; the others are stubs that
136
- // throw at runtime so the operator sees a clean diagnostic.
137
- // Codegen still succeeds — we emit the daemon, but boot fails.
166
+ /**
167
+ * Item 27 (Batch A extends it to this shape) — render the `budget`
168
+ * runChatLoop field. Empty when the spec omits it. Mirror: target-cli +
169
+ * target-channel-bot + target-managed render the same field. NOTE: the
170
+ * runtime meters cost per `runChatLoop` call, so on this shape the cap is a
171
+ * PER-JOB ceiling (every pulled job runs its own single-turn loop), not a
172
+ * worker-lifetime one.
173
+ */
174
+ function budgetField(ir, indent) {
175
+ if (ir.budget === undefined)
176
+ return "";
177
+ return `\n${indent}budget: ${JSON.stringify(ir.budget)},`;
178
+ }
179
+ /**
180
+ * Loop contract 0.4 (Batch A) — thread the top-level `limits:` ceilings into
181
+ * the per-job `runChatLoop` call as the runtime's individual top-level
182
+ * knobs, camelCase-mirroring the IR 1:1. Every knob is emitted only when
183
+ * declared — the runtime owns every default — so existing bundles stay
184
+ * byte-identical. Like `budget`, the time knobs (`deadlineMs` /
185
+ * `turnTimeoutMs`) bound ONE job's loop — size them against
186
+ * `queue.visibilityTimeoutMs`, not the worker's lifetime. `limits.crew`
187
+ * never reaches this shape (crew-only; the spec rejects it everywhere
188
+ * else). Mirror: target-cli + target-channel-bot + target-managed render
189
+ * the same fields.
190
+ */
191
+ function limitsFields(ir, indent) {
192
+ const limits = ir.limits;
193
+ if (limits === undefined)
194
+ return "";
195
+ const pieces = [];
196
+ if (limits.maxToolIterations !== undefined) {
197
+ pieces.push(`\n${indent}maxToolIterations: ${limits.maxToolIterations},`);
198
+ }
199
+ if (limits.maxConcurrentTools !== undefined) {
200
+ pieces.push(`\n${indent}maxConcurrentTools: ${limits.maxConcurrentTools},`);
201
+ }
202
+ if (limits.contextLimit !== undefined) {
203
+ pieces.push(`\n${indent}contextLimit: ${limits.contextLimit},`);
204
+ }
205
+ if (limits.deadlineMs !== undefined) {
206
+ pieces.push(`\n${indent}deadlineMs: ${limits.deadlineMs},`);
207
+ }
208
+ if (limits.turnTimeoutMs !== undefined) {
209
+ pieces.push(`\n${indent}turnTimeoutMs: ${limits.turnTimeoutMs},`);
138
210
  }
211
+ if (limits.modelCallTimeoutMs !== undefined) {
212
+ pieces.push(`\n${indent}modelCallTimeoutMs: ${limits.modelCallTimeoutMs},`);
213
+ }
214
+ if (limits.loopDetection !== undefined) {
215
+ pieces.push(`\n${indent}loopDetection: ${JSON.stringify(limits.loopDetection)},`);
216
+ }
217
+ return pieces.join("");
218
+ }
219
+ /**
220
+ * Section 9 / G05 (Batch A) — emit the `McpHost` boot block when the IR
221
+ * carries mcp_servers. Wire-once: the host boots once in `main()` (before
222
+ * the consumer starts) and registers every server's namespaced tools onto
223
+ * the shared `defaultCatalog`, so EVERY pulled job's `runChatLoop` carries
224
+ * them (`tools: defaultCatalog.list()` — no per-job reconnect). Mirror of
225
+ * target-channel-bot's renderMcpServers (keep in sync).
226
+ *
227
+ * 0.3.0 — env/header values are `IrSecretRef` objects; the UNRESOLVED
228
+ * config is embedded verbatim (so no secret value ever lands in the
229
+ * artifact) and `resolveMcpServerConfig` materialises it from the running
230
+ * process's environment at boot, failing fast with the variable's name
231
+ * when a referenced env var is unset.
232
+ *
233
+ * Empty `mcp_servers` returns empty strings so spec files without MCP get
234
+ * no MCP plumbing at all and prior bundles stay byte-identical.
235
+ */
236
+ function renderMcpServers(ir) {
237
+ const entries = Object.entries(ir.mcp_servers);
238
+ if (entries.length === 0) {
239
+ return { imports: [], bootBlock: "", cleanupBlock: "", hasAny: false };
240
+ }
241
+ const imports = [
242
+ `import { McpHost, resolveMcpServerConfig } from "@crewhaus/mcp-host";`,
243
+ `import { registerMcpServer } from "@crewhaus/tool-mcp";`,
244
+ ];
245
+ const addLines = entries
246
+ .map(([name, cfg]) => `mcpHost.addServer(${escapeJsonString(name)}, resolveMcpServerConfig(${JSON.stringify(cfg)}, { name: ${escapeJsonString(name)} }));`)
247
+ .join("\n");
248
+ const registerLines = entries
249
+ .map(([name]) => ` registerMcpServer(mcpHost, ${escapeJsonString(name)}, defaultCatalog, { onRegister: ({ fullName }) => process.stdout.write(\`[mcp] registered \${fullName}\\n\`) }),`)
250
+ .join("\n");
251
+ const bootBlock = [
252
+ "const mcpHost = new McpHost();",
253
+ addLines,
254
+ "await Promise.all([",
255
+ registerLines,
256
+ "]);",
257
+ ].join("\n");
258
+ return {
259
+ imports,
260
+ bootBlock,
261
+ cleanupBlock: "await mcpHost.disconnectAll();",
262
+ hasAny: true,
263
+ };
264
+ }
265
+ /**
266
+ * G06 — per-adapter queue construction. The adapter is fixed at CODEGEN
267
+ * time (`queue.adapter` in the spec), so the bundle carries only the
268
+ * selected backend's import + `buildQueue()` body. Non-in-memory backends
269
+ * resolve their connection details from the environment at boot via the
270
+ * emitted `requireQueueEnv` helper and throw ONLY when the selected
271
+ * backend's env is missing, naming the variable; everything past the env
272
+ * gate (SDK presence, credential chains) is `@crewhaus/queue-protocol`'s
273
+ * own boot contract. The identifier knobs each backend needs beyond its
274
+ * connection URL get worker-conventional defaults derived from the spec
275
+ * name, overridable by env.
276
+ *
277
+ * The in-memory body is emitted BYTE-IDENTICALLY to its pre-G06 text
278
+ * (including the now-historical unreachable `throw` arm) — the
279
+ * `pre-continuity` byte-restore pins in packages/compiler cover the
280
+ * in-memory batch bundle, and G06 must not disturb them.
281
+ */
282
+ function renderQueueBuild(ir) {
283
+ const seedJobsLit = JSON.stringify(ir.queue.seedJobs ?? []);
284
+ switch (ir.queue.adapter) {
285
+ case "in-memory":
286
+ return {
287
+ importLine: `import { createInMemoryQueue } from "@crewhaus/queue-protocol";`,
288
+ seedConst: `\nconst SPEC_SEED_JOBS: string[] = ${seedJobsLit};`,
289
+ buildFn: `function buildQueue(): ReturnType<typeof createInMemoryQueue<string>> {
290
+ if (SPEC_QUEUE_ADAPTER === "in-memory") {
291
+ return createInMemoryQueue<string>({ initialJobs: SPEC_SEED_JOBS });
292
+ }
293
+ throw new Error(
294
+ "[batch-worker] queue adapter \\"" + SPEC_QUEUE_ADAPTER +
295
+ "\\" is not implemented in v0 — only \\"in-memory\\" is supported. " +
296
+ "SQS / Redis Streams / Postgres adapters land in a follow-up.",
297
+ );
298
+ }`,
299
+ };
300
+ case "sqs":
301
+ return {
302
+ importLine: `import { createSqsAdapter, type QueueAdapter } from "@crewhaus/queue-protocol";`,
303
+ seedConst: "",
304
+ buildFn: `${REQUIRE_QUEUE_ENV_FN}
305
+
306
+ function buildQueue(): QueueAdapter<string> {
307
+ const queueUrl = requireQueueEnv("SQS_QUEUE_URL", "the queue's full https URL");
308
+ const region =
309
+ process.env["AWS_REGION"] ??
310
+ process.env["AWS_DEFAULT_REGION"] ??
311
+ requireQueueEnv("AWS_REGION", "the queue's AWS region, e.g. us-east-1");
312
+ // Credentials are optional here: absent, the SDK falls back to its own
313
+ // chain (env, profile, IAM instance role).
314
+ const accessKeyId = process.env["AWS_ACCESS_KEY_ID"];
315
+ const secretAccessKey = process.env["AWS_SECRET_ACCESS_KEY"];
316
+ return createSqsAdapter<string>({
317
+ queueUrl,
318
+ region,
319
+ ...(accessKeyId !== undefined ? { accessKeyId } : {}),
320
+ ...(secretAccessKey !== undefined ? { secretAccessKey } : {}),
321
+ });
322
+ }`,
323
+ };
324
+ case "redis-streams":
325
+ return {
326
+ importLine: `import { createRedisStreamsAdapter, type QueueAdapter } from "@crewhaus/queue-protocol";`,
327
+ seedConst: "",
328
+ buildFn: `${REQUIRE_QUEUE_ENV_FN}
329
+
330
+ function buildQueue(): QueueAdapter<string> {
331
+ // ioredis reads REDIS_URL when the client connects; the presence check
332
+ // here fails fast at boot with the variable's name instead of a hung
333
+ // first pull.
334
+ requireQueueEnv("REDIS_URL", "redis[s]://[user:pass@]host:port[/db]");
335
+ return createRedisStreamsAdapter<string>({
336
+ streamKey: process.env["REDIS_STREAM_KEY"] ?? \`crewhaus:\${SPEC_NAME}:jobs\`,
337
+ consumerGroup: process.env["REDIS_CONSUMER_GROUP"] ?? \`crewhaus:\${SPEC_NAME}:workers\`,
338
+ consumerName: process.env["REDIS_CONSUMER_NAME"] ?? \`worker-\${process.pid}\`,
339
+ });
340
+ }`,
341
+ };
342
+ case "postgres":
343
+ return {
344
+ importLine: `import { createPostgresAdapter, type QueueAdapter } from "@crewhaus/queue-protocol";`,
345
+ seedConst: "",
346
+ buildFn: `${REQUIRE_QUEUE_ENV_FN}
347
+
348
+ function buildQueue(): QueueAdapter<string> {
349
+ // pg reads DATABASE_URL when the pool connects; the presence check here
350
+ // fails fast at boot with the variable's name instead of a hung first
351
+ // pull.
352
+ requireQueueEnv("DATABASE_URL", "postgres://user:pass@host:port/db");
353
+ const deadLetterTable = process.env["CREWHAUS_JOBS_DLQ_TABLE"];
354
+ return createPostgresAdapter<string>({
355
+ tableName: process.env["CREWHAUS_JOBS_TABLE"] ?? "crewhaus_jobs",
356
+ ...(deadLetterTable !== undefined ? { deadLetterTable } : {}),
357
+ });
358
+ }`,
359
+ };
360
+ }
361
+ }
362
+ /**
363
+ * The env gate every non-in-memory `buildQueue()` opens with. Emitted (not
364
+ * imported) so the bundle stays self-contained; the message names the
365
+ * adapter, the variable, and its expected shape.
366
+ */
367
+ const REQUIRE_QUEUE_ENV_FN = `function requireQueueEnv(name: string, hint: string): string {
368
+ const v = process.env[name];
369
+ if (v === undefined || v === "") {
370
+ throw new Error(
371
+ \`[batch-worker] queue adapter "\${SPEC_QUEUE_ADAPTER}" requires the \${name} environment variable (\${hint}) — set it and restart the worker.\`,
372
+ );
373
+ }
374
+ return v;
375
+ }`;
376
+ /**
377
+ * Loop contract 0.4 (Batch F) — render the `IrSchedule` as a
378
+ * durable-execution `WakeSchedule` object literal (the IR MINUS
379
+ * `instructions`, which the worker enqueues as a job on each wake). Numeric
380
+ * fields are ms-normalized at lower time, so JSON.stringify is valid,
381
+ * byte-stable JS. Shared verbatim with target-channel-bot — keep in sync.
382
+ */
383
+ function wakeScheduleLiteral(schedule) {
384
+ const literal = schedule.kind === "cron"
385
+ ? {
386
+ kind: "cron",
387
+ cron: schedule.cron,
388
+ ...(schedule.timezone !== undefined ? { timezone: schedule.timezone } : {}),
389
+ ...(schedule.jitterMs !== undefined ? { jitterMs: schedule.jitterMs } : {}),
390
+ }
391
+ : {
392
+ kind: "interval",
393
+ everyMs: schedule.everyMs,
394
+ ...(schedule.jitterMs !== undefined ? { jitterMs: schedule.jitterMs } : {}),
395
+ };
396
+ return JSON.stringify(literal);
397
+ }
398
+ /** A one-line human description of a schedule for the boot log. Shared
399
+ * verbatim with target-channel-bot — keep in sync. */
400
+ function describeSchedule(schedule) {
401
+ const base = schedule.kind === "cron"
402
+ ? `cron "${schedule.cron}"${schedule.timezone !== undefined ? ` ${schedule.timezone}` : " UTC"}`
403
+ : `every ${schedule.everyMs}ms`;
404
+ return schedule.jitterMs !== undefined ? `${base} +/-${schedule.jitterMs}ms jitter` : base;
405
+ }
406
+ export function emitBatchWorker(ir, opts = {}) {
139
407
  const files = [{ path: "agent.ts", content: renderAgent(ir) }];
140
408
  // Item 42 — generated bundle README; default ON (`crewhaus compile
141
409
  // --no-readme` opts out).
@@ -152,28 +420,119 @@ function renderAgent(ir) {
152
420
  ? `\n// Spec-supplied tools registered at module load.\n${registrations.join("\n")}\n`
153
421
  : "";
154
422
  const permField = renderPermissionsField(ir);
155
- const seedJobsLit = JSON.stringify(ir.queue.seedJobs ?? []);
423
+ const queueBuild = renderQueueBuild(ir);
156
424
  const visRenewMs = ir.queue.visibilityRenewIntervalMs ?? Math.floor(ir.queue.visibilityTimeoutMs / 4);
157
425
  const hasRules = ir.permissions.rules.length > 0;
158
426
  const permImport = hasRules
159
427
  ? `import { BUILTIN_DEFAULT_RULES } from "@crewhaus/permission-engine";\n`
160
428
  : "";
429
+ const mcp = renderMcpServers(ir);
430
+ const mcpImportBlock = mcp.imports.length > 0 ? `${mcp.imports.join("\n")}\n` : "";
431
+ const mcpBoot = mcp.hasAny
432
+ ? ` // G05 — MCP servers, wired ONCE onto the shared defaultCatalog so every\n // pulled job's runChatLoop carries the namespaced tools.\n ${mcp.bootBlock.split("\n").join("\n ")}\n\n`
433
+ : "";
434
+ const mcpShutdownCleanup = mcp.hasAny ? `\n ${mcp.cleanupBlock}` : "";
435
+ const mcpIdleCleanup = mcp.hasAny ? `\n ${mcp.cleanupBlock}` : "";
436
+ // Loop contract 0.4 (Batch A) — spec-declared lifecycle hooks (`hooks:`).
437
+ // IrHook is HookDef-shaped by contract (the spec ↔ hooks-engine
438
+ // cross-check test pins the event vocabulary), so the literal threads
439
+ // straight into the per-job runChatLoop. Declaration order from the spec
440
+ // is preserved (hooks run in registration order). Absent/empty emits
441
+ // nothing so existing bundles stay byte-identical.
442
+ const specHooks = ir.hooks !== undefined && ir.hooks.length > 0 ? ir.hooks : undefined;
443
+ const hooksImport = specHooks !== undefined ? `import type { HookDef } from "@crewhaus/hooks-engine";\n` : "";
444
+ const hooksConst = specHooks !== undefined
445
+ ? `\n// Loop contract 0.4 — spec-declared lifecycle hooks (registration order preserved).\nconst SPEC_HOOKS: ReadonlyArray<HookDef> = ${JSON.stringify(specHooks)};`
446
+ : "";
447
+ const hooksField = specHooks !== undefined ? "\n hooks: SPEC_HOOKS," : "";
448
+ // The queue_idle fast-exit only exists on the in-memory adapter: its
449
+ // stats() are authoritative for "the queue is empty and nothing is in
450
+ // flight". SQS/Redis/Postgres stats cannot cheaply distinguish "empty
451
+ // right now" from "drained forever" (SQS pending, for one, is a
452
+ // CloudWatch metric), so those workers run until signaled.
453
+ // Loop contract 0.4 (Batch F) — a scheduled worker is a long-running cron
454
+ // daemon: it must NOT idle-exit between wakes, so a declared `schedule:`
455
+ // forces the keep-alive loop even for the in-memory adapter. Unscheduled
456
+ // specs keep the exact pre-Batch-F selection, so their bundles stay
457
+ // byte-identical.
458
+ const idleLoop = ir.queue.adapter === "in-memory" && ir.schedule === undefined
459
+ ? ` // For the hello-batch smoke: when the queue empties + no in-flight,
460
+ // emit a queue_idle event and exit so the smoke can assert on a
461
+ // clean shutdown without sending a signal. Production users will
462
+ // typically run forever and rely on signals.
463
+ const idleCheckMs = 200;
464
+ while (!stopping) {
465
+ await new Promise((r) => setTimeout(r, idleCheckMs));
466
+ const stats = await queue.stats();
467
+ if (stats.pending === 0 && stats.inFlight === 0 && consumer.inFlight() === 0) {
468
+ // Idle — check once more after a short delay to avoid racing with
469
+ // a job mid-pull.
470
+ await new Promise((r) => setTimeout(r, idleCheckMs));
471
+ const recheck = await queue.stats();
472
+ if (
473
+ recheck.pending === 0 &&
474
+ recheck.inFlight === 0 &&
475
+ consumer.inFlight() === 0
476
+ ) {
477
+ emit({ kind: "queue_idle", stats: recheck });
478
+ janitor.stop();
479
+ await consumer.drain();${mcpIdleCleanup}
480
+ emit({ kind: "worker_stop", stats: await queue.stats() });
481
+ return;
482
+ }
483
+ }
484
+ }`
485
+ : ` // Non-in-memory backend: no queue_idle fast-exit (the adapter's stats
486
+ // cannot prove the queue is drained) — the worker runs until SIGTERM /
487
+ // SIGINT drives the drain-and-stop path above.
488
+ const keepAliveMs = 200;
489
+ while (!stopping) {
490
+ await new Promise((r) => setTimeout(r, keepAliveMs));
491
+ }`;
161
492
  // v0.3.0 — continuity is spec-carried on this shape but not emit-wired in
162
493
  // 0.3.0 (only the five agent-loop shapes are). Surface it, 0.2.3-style.
163
494
  const continuityWarning = ir.continuity !== undefined
164
495
  ? "// note: continuity configured but ignored on batch in 0.3.0\n"
165
496
  : "";
497
+ // Loop contract 0.4 (Batch F, temporal contract / G84) — the `schedule:`
498
+ // wake loop. On each cron/interval wake the worker ENQUEUES a synthetic job
499
+ // (the schedule's `instructions`) so the running consumer pulls and
500
+ // processes it like any other — a scheduled job producer. All cron/interval
501
+ // + jitter arithmetic lives in durable-execution's `armSchedule`. Absent
502
+ // `schedule:` emits nothing, so unscheduled worker bundles stay
503
+ // byte-identical.
504
+ const scheduleImport = ir.schedule
505
+ ? `import { armSchedule } from "@crewhaus/durable-execution";\n`
506
+ : "";
507
+ const scheduleBoot = ir.schedule
508
+ ? `
509
+ // Loop contract 0.4 (Batch F) — schedule: wake loop (cron|interval + jitter)
510
+ const __scheduleInstructions = ${escapeJsonString(ir.schedule.instructions ?? "[scheduled wake]")};
511
+ let __scheduleTick = 0;
512
+ const __schedule = armSchedule(${wakeScheduleLiteral(ir.schedule)}, {
513
+ onWake: async () => {
514
+ __scheduleTick++;
515
+ const jobId = await queue.enqueue(__scheduleInstructions);
516
+ emit({ kind: "scheduled_wake", tick: __scheduleTick, jobId });
517
+ },
518
+ onError: (err) => emit({ kind: "scheduled_wake_error", error: (err as Error).message ?? String(err) }),
519
+ });
520
+ emit({ kind: "schedule_armed", schedule: ${escapeJsonString(describeSchedule(ir.schedule))} });
521
+ `
522
+ : "";
523
+ const scheduleShutdown = ir.schedule ? "\n __schedule.cancel();" : "";
166
524
  return `#!/usr/bin/env bun
167
525
  // Generated by crewhaus. DO NOT EDIT.
168
526
  // Source spec: ${escapeJsonString(ir.name)} (target: batch, ir version: ${ir.version})
169
- ${continuityWarning}import { createInMemoryQueue } from "@crewhaus/queue-protocol";
527
+ ${continuityWarning}${queueBuild.importLine}
170
528
  import { startConsumer } from "@crewhaus/queue-consumer";
171
529
  import { createInMemoryIdempotencyStore } from "@crewhaus/idempotency-keys";
172
530
  import { loadRetentionConfig } from "@crewhaus/data-retention-engine";
173
531
  import { createJanitor, runChatLoop } from "@crewhaus/runtime-core";
532
+ import { createPendingApprovalStore, resolveSessionRootDir } from "@crewhaus/runtime-core";
174
533
  import { createRunContext } from "@crewhaus/run-context";
175
534
  import { defaultCatalog } from "@crewhaus/tool-catalog";
176
- ${permImport}${importBlock}
535
+ ${permImport}${hooksImport}${scheduleImport}${mcpImportBlock}${importBlock}
177
536
 
178
537
  ${initLines}${registrationBlock}
179
538
  const SPEC_NAME = ${escapeJsonString(ir.name)};
@@ -184,23 +543,13 @@ const SPEC_VISIBILITY_TIMEOUT_MS = ${ir.queue.visibilityTimeoutMs};
184
543
  const SPEC_VISIBILITY_RENEW_MS = ${visRenewMs};
185
544
  const SPEC_MAX_RETRIES = ${ir.queue.maxRetries};
186
545
  const SPEC_CONCURRENCY = ${ir.concurrency};
187
- const SPEC_IDEMPOTENCY_WINDOW_MS = ${ir.idempotencyWindowMs};
188
- const SPEC_SEED_JOBS: string[] = ${seedJobsLit};
546
+ const SPEC_IDEMPOTENCY_WINDOW_MS = ${ir.idempotencyWindowMs};${queueBuild.seedConst}${hooksConst}
189
547
 
190
548
  function emit(event: Record<string, unknown>): void {
191
549
  process.stdout.write(\`\${JSON.stringify(event)}\\n\`);
192
550
  }
193
551
 
194
- function buildQueue(): ReturnType<typeof createInMemoryQueue<string>> {
195
- if (SPEC_QUEUE_ADAPTER === "in-memory") {
196
- return createInMemoryQueue<string>({ initialJobs: SPEC_SEED_JOBS });
197
- }
198
- throw new Error(
199
- "[batch-worker] queue adapter \\"" + SPEC_QUEUE_ADAPTER +
200
- "\\" is not implemented in v0 — only \\"in-memory\\" is supported. " +
201
- "SQS / Redis Streams / Postgres adapters land in a follow-up.",
202
- );
203
- }
552
+ ${queueBuild.buildFn}
204
553
 
205
554
  async function main(): Promise<void> {
206
555
  // Boot-time self-heal janitor (ops item 36): evicts expired sessions on a
@@ -236,7 +585,26 @@ async function main(): Promise<void> {
236
585
  janitor.start(Number(process.env["CREWHAUS_JANITOR_INTERVAL_MS"] ?? 3_600_000));
237
586
  }
238
587
 
588
+ ${mcpBoot} // G11 — a compiled bundle is NON-INTERACTIVE: a tool that lands on \`ask\`
589
+ // has nobody to prompt, so without this it collapsed to a deny. Rooted
590
+ // where the run's session files land, so parks live beside them (and
591
+ // inside a tenant's rebased root when one is active). No I/O until a park.
592
+ // A park fails the job, so it is retried per SPEC_MAX_RETRIES — an
593
+ // out-of-band grant lands on the same (toolName, inputHash) key and the
594
+ // next delivery within that budget proceeds.
595
+ const __approvalRoot = resolveSessionRootDir(undefined);
596
+ const __approvals = createPendingApprovalStore(
597
+ __approvalRoot !== undefined ? { rootDir: __approvalRoot } : {},
598
+ );
599
+
239
600
  const queue = buildQueue();
601
+ // Idempotency window (SPEC_IDEMPOTENCY_WINDOW_MS): caches each job's
602
+ // SUCCESSFUL result under its job id for the window, so a job that is
603
+ // re-delivered after already completing (a lost ack, a crash between
604
+ // handler and ack, an expired visibility lease, a competing consumer)
605
+ // is served from cache instead of paying for the model twice — that
606
+ // job_end reports \`fromCache: true\`. A clean run never re-delivers, so
607
+ // \`fromCache\` staying false throughout means nothing was duplicated.
240
608
  const idempotencyStore = createInMemoryIdempotencyStore<string>();
241
609
  emit({ kind: "worker_start", queueAdapter: SPEC_QUEUE_ADAPTER, concurrency: SPEC_CONCURRENCY });
242
610
 
@@ -255,7 +623,7 @@ async function main(): Promise<void> {
255
623
  seedMessages: [{ role: "user", content: input }],
256
624
  tools: defaultCatalog.list(),
257
625
  installSigintHandler: false,
258
- maxTokens: 1024,${permField}
626
+ maxTokens: ${ir.agent.maxTokens ?? 1024},${budgetField(ir, " ")}${limitsFields(ir, " ")}${hooksField}${permField}${renderApprovalFields(ir, " ")}
259
627
  });
260
628
  return reply.trim();
261
629
  },
@@ -268,7 +636,38 @@ async function main(): Promise<void> {
268
636
  observer: {
269
637
  onJobEnd: (job, outcome) => {
270
638
  if (outcome.kind === "ok") {
271
- emit({ kind: "job_end", jobId: job.id, attempt: job.attempt, status: "ok", fromCache: outcome.fromCache });
639
+ // The handler's return value IS the work product — a batch run
640
+ // whose stdout carried only status JSON had no observable result
641
+ // at all (replies were recoverable only from the session
642
+ // transcript). Emit it verbatim, plus its size so the line stays
643
+ // scannable. CREWHAUS_BATCH_EMIT_RESULT=0 suppresses the payload
644
+ // (large or sensitive results shipped to logs) while keeping
645
+ // resultBytes.
646
+ const includeResult = process.env["CREWHAUS_BATCH_EMIT_RESULT"] !== "0";
647
+ emit({
648
+ kind: "job_end",
649
+ jobId: job.id,
650
+ attempt: job.attempt,
651
+ status: "ok",
652
+ fromCache: outcome.fromCache,
653
+ resultBytes: Buffer.byteLength(outcome.value ?? "", "utf8"),
654
+ ...(includeResult ? { result: outcome.value } : {}),
655
+ });
656
+ } else if (outcome.kind === "deferred") {
657
+ // NOT a failure: the turn parked on a tool permission that needs a
658
+ // human. The job is neither ack'd nor dead-lettered — it returns to
659
+ // the queue after the defer window and the attempt does not count
660
+ // against maxRetries. Reported under its own status so an operator
661
+ // watching this stream can tell "waiting on someone" apart from
662
+ // "broken", and knows to run \`crewhaus approvals list\`.
663
+ emit({
664
+ kind: "job_end",
665
+ jobId: job.id,
666
+ attempt: job.attempt,
667
+ status: "awaiting_approval",
668
+ defers: outcome.defers,
669
+ error: (outcome.error as Error).message ?? String(outcome.error),
670
+ });
272
671
  } else {
273
672
  emit({
274
673
  kind: "job_end",
@@ -284,14 +683,14 @@ async function main(): Promise<void> {
284
683
  onDrainEnd: () => emit({ kind: "drain_end" }),
285
684
  },
286
685
  });
287
-
686
+ ${scheduleBoot}
288
687
  let stopping = false;
289
688
  const shutdown = async (signal: string): Promise<void> => {
290
689
  if (stopping) return;
291
690
  stopping = true;
292
- janitor.stop();
691
+ janitor.stop();${scheduleShutdown}
293
692
  emit({ kind: "shutdown_received", signal });
294
- await consumer.drain();
693
+ await consumer.drain();${mcpShutdownCleanup}
295
694
  const stats = await queue.stats();
296
695
  emit({ kind: "worker_stop", stats });
297
696
  process.exit(0);
@@ -299,32 +698,7 @@ async function main(): Promise<void> {
299
698
  process.on("SIGINT", () => void shutdown("SIGINT"));
300
699
  process.on("SIGTERM", () => void shutdown("SIGTERM"));
301
700
 
302
- // For the hello-batch smoke: when the queue empties + no in-flight,
303
- // emit a queue_idle event and exit so the smoke can assert on a
304
- // clean shutdown without sending a signal. Production users will
305
- // typically run forever and rely on signals.
306
- const idleCheckMs = 200;
307
- while (!stopping) {
308
- await new Promise((r) => setTimeout(r, idleCheckMs));
309
- const stats = await queue.stats();
310
- if (stats.pending === 0 && stats.inFlight === 0 && consumer.inFlight() === 0) {
311
- // Idle — check once more after a short delay to avoid racing with
312
- // a job mid-pull.
313
- await new Promise((r) => setTimeout(r, idleCheckMs));
314
- const recheck = await queue.stats();
315
- if (
316
- recheck.pending === 0 &&
317
- recheck.inFlight === 0 &&
318
- consumer.inFlight() === 0
319
- ) {
320
- emit({ kind: "queue_idle", stats: recheck });
321
- janitor.stop();
322
- await consumer.drain();
323
- emit({ kind: "worker_stop", stats: await queue.stats() });
324
- return;
325
- }
326
- }
327
- }
701
+ ${idleLoop}
328
702
  }
329
703
 
330
704
  main().catch((err) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/target-batch-worker",
3
- "version": "0.3.2",
3
+ "version": "0.4.2",
4
4
  "type": "module",
5
5
  "description": "Codegen for the BATCH target — emits a queue-consumer daemon (Section 23 BATCH)",
6
6
  "main": "dist/index.js",
@@ -15,9 +15,9 @@
15
15
  "test": "bun test src"
16
16
  },
17
17
  "dependencies": {
18
- "@crewhaus/errors": "0.3.2",
19
- "@crewhaus/infra-utils": "0.3.2",
20
- "@crewhaus/ir": "0.3.2"
18
+ "@crewhaus/errors": "0.4.2",
19
+ "@crewhaus/infra-utils": "0.4.2",
20
+ "@crewhaus/ir": "0.4.2"
21
21
  },
22
22
  "license": "Apache-2.0",
23
23
  "author": {