@crewhaus/target-batch-worker 0.4.0 → 0.5.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/dist/index.d.ts CHANGED
@@ -16,12 +16,19 @@
16
16
  * the job input as the user message; the assistant's terminal text
17
17
  * is the cached result.
18
18
  * 4. Streams JSON events to stdout (`worker_start | job_start |
19
- * 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`.
20
24
  * 5. Installs SIGTERM + SIGINT handlers that drain in-flight jobs
21
25
  * cleanly before exit.
22
26
  * 6. Runs the boot-time self-heal janitor (ops item 36) — session TTL
23
27
  * eviction + orphaned-tool_use report — at boot and hourly
24
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.
25
32
  */
26
33
  import { CrewhausError } from "@crewhaus/errors";
27
34
  import { type Bundle, type EmitReadmeOptions, type IrBatchV0 } from "@crewhaus/ir";
package/dist/index.js CHANGED
@@ -16,14 +16,22 @@
16
16
  * the job input as the user message; the assistant's terminal text
17
17
  * is the cached result.
18
18
  * 4. Streams JSON events to stdout (`worker_start | job_start |
19
- * 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`.
20
24
  * 5. Installs SIGTERM + SIGINT handlers that drain in-flight jobs
21
25
  * cleanly before exit.
22
26
  * 6. Runs the boot-time self-heal janitor (ops item 36) — session TTL
23
27
  * eviction + orphaned-tool_use report — at boot and hourly
24
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.
25
32
  */
26
33
  import { CrewhausError } from "@crewhaus/errors";
34
+ import { renderControlDrain, renderControlImports, renderControlLane, renderControlPlaneBoot, renderControlStart, renderControlTimer, } from "@crewhaus/gateway-protocol/control-codegen";
27
35
  import { escapeJsonString } from "@crewhaus/infra-utils";
28
36
  import { renderBundleReadme, } from "@crewhaus/ir";
29
37
  export class TargetEmitError extends CrewhausError {
@@ -108,6 +116,30 @@ function renderPermissionsField(ir) {
108
116
  }
109
117
  return `\n${lines.join("\n")}`;
110
118
  }
119
+ /**
120
+ * Loop contract 0.4 (G11) — the `askMode` + `approvals` fields. Unlike the
121
+ * CLI's `approvalRunOptions`, a bundle parses no `--ask-mode`, so the spec
122
+ * value is FIXED here at emit time. The store is built UNCONDITIONALLY,
123
+ * including under `"deny"` where it never parks, so runtime-core's denial
124
+ * diagnostic can honestly say `ask_mode: "deny"` instead of blaming absent
125
+ * plumbing (it branches on `approvals === undefined`).
126
+ *
127
+ * Deliberately SEPARATE from renderPermissionsField, which early-returns ""
128
+ * when the spec declares no `permissions:` block — precisely the case where
129
+ * parking matters most, since with no block every unmatched tool resolves to
130
+ * `ask`.
131
+ *
132
+ * CAVEAT unique to this shape: a park throws `RunFailedError`
133
+ * (`approval_pending`) out of the queue handler, so the queue-consumer sees a
134
+ * failed job and retries it per SPEC_MAX_RETRIES — the job can dead-letter
135
+ * before a human ever grants. The store keys on (toolName, inputHash), so a
136
+ * later re-delivery DOES find the grant and re-resolves pre-decided, but only
137
+ * while the retry budget lasts.
138
+ */
139
+ function renderApprovalFields(ir, indent) {
140
+ return (`\n${indent}askMode: ${escapeJsonString(ir.permissions.askMode ?? "pause")},` +
141
+ `\n${indent}approvals: { store: __approvals, surface: "batch" },`);
142
+ }
111
143
  /**
112
144
  * Adaptive model routing — render the `modelPool` runChatLoop field.
113
145
  * JSON.stringify safely quotes the validated pool object (mirroring
@@ -471,18 +503,40 @@ function renderAgent(ir) {
471
503
  // `schedule:` emits nothing, so unscheduled worker bundles stay
472
504
  // byte-identical.
473
505
  const scheduleImport = ir.schedule
474
- ? `import { armSchedule } from "@crewhaus/durable-execution";\n`
506
+ ? `import { armSchedule, nextWakeDelayMs } from "@crewhaus/durable-execution";\n`
475
507
  : "";
508
+ // crewhaus.control.v1 — the wake body is a control LANE, so `POST
509
+ // /control/v1/wake {lane:"schedule"}` enqueues a job down the exact path the
510
+ // timer uses (and 409s while an enqueue is in flight). This shape is a
511
+ // PRODUCER: the wake enqueues a job and the consumer's handler mints its own
512
+ // session, so the lane never threads `__tick.sessionId` anywhere. It
513
+ // therefore declares `ownsSession: false` — the 202 answers with the enqueued
514
+ // `jobId` on the event stream rather than a session id that names nothing,
515
+ // and no orphan marker `.jsonl` is left where retention can never reach it.
476
516
  const scheduleBoot = ir.schedule
477
517
  ? `
478
518
  // Loop contract 0.4 (Batch F) — schedule: wake loop (cron|interval + jitter)
479
519
  const __scheduleInstructions = ${escapeJsonString(ir.schedule.instructions ?? "[scheduled wake]")};
520
+ const __scheduleSpec = ${wakeScheduleLiteral(ir.schedule)} as const;
480
521
  let __scheduleTick = 0;
481
- const __schedule = armSchedule(${wakeScheduleLiteral(ir.schedule)}, {
522
+ ${renderControlLane({
523
+ lane: "schedule",
524
+ varName: "__scheduleLane",
525
+ cadence: describeSchedule(ir.schedule),
526
+ nextDueAtExpr: "new Date(Date.now() + nextWakeDelayMs(__scheduleSpec, Date.now())).toISOString()",
527
+ indent: " ",
528
+ ownsSession: false,
529
+ body: `__scheduleTick++;
530
+ const jobId = await queue.enqueue(__scheduleInstructions);
531
+ emit({
532
+ kind: "scheduled_wake",
533
+ tick: __scheduleTick,
534
+ jobId,
535
+ ...(__tick.synthetic !== undefined ? { synthetic: true, reason: __tick.synthetic.reason, by: __tick.synthetic.by } : {}),
536
+ });`,
537
+ })} const __schedule = armSchedule(__scheduleSpec, {
482
538
  onWake: async () => {
483
- __scheduleTick++;
484
- const jobId = await queue.enqueue(__scheduleInstructions);
485
- emit({ kind: "scheduled_wake", tick: __scheduleTick, jobId });
539
+ await __scheduleLane.tick();
486
540
  },
487
541
  onError: (err) => emit({ kind: "scheduled_wake_error", error: (err as Error).message ?? String(err) }),
488
542
  });
@@ -490,14 +544,41 @@ function renderAgent(ir) {
490
544
  `
491
545
  : "";
492
546
  const scheduleShutdown = ir.schedule ? "\n __schedule.cancel();" : "";
547
+ // crewhaus.control.v1, from the shared gateway-protocol renderers. The batch
548
+ // worker has no public HTTP port, so control.v1 is its ONLY remote surface;
549
+ // it is also the shape whose drain semantics already existed (the consumer
550
+ // drains in-flight jobs on SIGTERM) — control.v1 just gives an operator a
551
+ // signal-free way to ask for it.
552
+ const controlPlaneBoot = renderControlPlaneBoot({
553
+ name: ir.name,
554
+ target: "batch",
555
+ indent: " ",
556
+ auditLogExpr: "__controlAudit",
557
+ });
558
+ const controlJanitorTimer = renderControlTimer({
559
+ indent: " ",
560
+ expr: '{ lane: "janitor", cadence: `every ${__janitorIntervalMs}ms`, ' +
561
+ '...(__janitorLastRunAt !== undefined ? { lastFiredAt: __janitorLastRunAt, lastOutcome: "ok" } : {}) }',
562
+ });
563
+ const controlDrain = renderControlDrain({
564
+ indent: " ",
565
+ body: `stopping = true;
566
+ janitor.stop();${ir.schedule ? "\n__schedule.cancel();" : ""}
567
+ emit({ kind: "drain_requested", via: "control.v1" });
568
+ await consumer.drain();${mcp.hasAny ? `\n${mcp.cleanupBlock}` : ""}
569
+ emit({ kind: "worker_stop", stats: await queue.stats() });`,
570
+ });
571
+ const controlStart = renderControlStart({ indent: " " });
493
572
  return `#!/usr/bin/env bun
494
573
  // Generated by crewhaus. DO NOT EDIT.
495
574
  // Source spec: ${escapeJsonString(ir.name)} (target: batch, ir version: ${ir.version})
496
575
  ${continuityWarning}${queueBuild.importLine}
497
- import { startConsumer } from "@crewhaus/queue-consumer";
576
+ import { openAuditLog } from "@crewhaus/audit-log";
577
+ ${renderControlImports()}import { startConsumer } from "@crewhaus/queue-consumer";
498
578
  import { createInMemoryIdempotencyStore } from "@crewhaus/idempotency-keys";
499
579
  import { loadRetentionConfig } from "@crewhaus/data-retention-engine";
500
580
  import { createJanitor, runChatLoop } from "@crewhaus/runtime-core";
581
+ import { createPendingApprovalStore, resolveSessionRootDir } from "@crewhaus/runtime-core";
501
582
  import { createRunContext } from "@crewhaus/run-context";
502
583
  import { defaultCatalog } from "@crewhaus/tool-catalog";
503
584
  ${permImport}${hooksImport}${scheduleImport}${mcpImportBlock}${importBlock}
@@ -520,6 +601,13 @@ function emit(event: Record<string, unknown>): void {
520
601
  ${queueBuild.buildFn}
521
602
 
522
603
  async function main(): Promise<void> {
604
+ // control.v1 — the harness-wide hash-chained audit log every control call
605
+ // appends a \`gateway_request\` record to. CREWHAUS_SECURITY_AUDIT=0 opts out.
606
+ const __controlAudit =
607
+ process.env["CREWHAUS_SECURITY_AUDIT"] === "0"
608
+ ? undefined
609
+ : await openAuditLog({ rootDir: \`\${process.cwd()}/.crewhaus/audit\` });
610
+ ${controlPlaneBoot}
523
611
  // Boot-time self-heal janitor (ops item 36): evicts expired sessions on a
524
612
  // schedule (TTL eviction otherwise only fires as a list() side-effect an
525
613
  // idle worker never triggers) and reports orphaned tool_use entries in
@@ -547,13 +635,37 @@ async function main(): Promise<void> {
547
635
  sessionTtlDays: retentionTtlDays,
548
636
  pinnedSessionIds: retentionPins,
549
637
  });
638
+ const __janitorIntervalMs = Number(process.env["CREWHAUS_JANITOR_INTERVAL_MS"] ?? 3_600_000);
639
+ let __janitorLastRunAt: string | undefined;
550
640
  if (process.env["CREWHAUS_JANITOR"] !== "0") {
551
641
  const janitorReport = await janitor.runOnce();
642
+ __janitorLastRunAt = new Date().toISOString();
643
+ __control.counters.janitorRuns++;
552
644
  process.stderr.write(\`[janitor] \${JSON.stringify(janitorReport.steps)}\\n\`);
553
- janitor.start(Number(process.env["CREWHAUS_JANITOR_INTERVAL_MS"] ?? 3_600_000));
645
+ janitor.start(__janitorIntervalMs);
554
646
  }
647
+ ${controlJanitorTimer}
555
648
 
556
- ${mcpBoot} const queue = buildQueue();
649
+ ${mcpBoot} // G11 — a compiled bundle is NON-INTERACTIVE: a tool that lands on \`ask\`
650
+ // has nobody to prompt, so without this it collapsed to a deny. Rooted
651
+ // where the run's session files land, so parks live beside them (and
652
+ // inside a tenant's rebased root when one is active). No I/O until a park.
653
+ // A park fails the job, so it is retried per SPEC_MAX_RETRIES — an
654
+ // out-of-band grant lands on the same (toolName, inputHash) key and the
655
+ // next delivery within that budget proceeds.
656
+ const __approvalRoot = resolveSessionRootDir(undefined);
657
+ const __approvals = createPendingApprovalStore(
658
+ __approvalRoot !== undefined ? { rootDir: __approvalRoot } : {},
659
+ );
660
+
661
+ const queue = buildQueue();
662
+ // Idempotency window (SPEC_IDEMPOTENCY_WINDOW_MS): caches each job's
663
+ // SUCCESSFUL result under its job id for the window, so a job that is
664
+ // re-delivered after already completing (a lost ack, a crash between
665
+ // handler and ack, an expired visibility lease, a competing consumer)
666
+ // is served from cache instead of paying for the model twice — that
667
+ // job_end reports \`fromCache: true\`. A clean run never re-delivers, so
668
+ // \`fromCache\` staying false throughout means nothing was duplicated.
557
669
  const idempotencyStore = createInMemoryIdempotencyStore<string>();
558
670
  emit({ kind: "worker_start", queueAdapter: SPEC_QUEUE_ADAPTER, concurrency: SPEC_CONCURRENCY });
559
671
 
@@ -572,8 +684,11 @@ ${mcpBoot} const queue = buildQueue();
572
684
  seedMessages: [{ role: "user", content: input }],
573
685
  tools: defaultCatalog.list(),
574
686
  installSigintHandler: false,
575
- maxTokens: ${ir.agent.maxTokens ?? 1024},${budgetField(ir, " ")}${limitsFields(ir, " ")}${hooksField}${permField}
687
+ maxTokens: ${ir.agent.maxTokens ?? 1024},${budgetField(ir, " ")}${limitsFields(ir, " ")}${hooksField}${permField}${renderApprovalFields(ir, " ")}
576
688
  });
689
+ // control.v1 counters.turns — bumped where the model actually ran, so a
690
+ // cache-served re-delivery (\`job_end.fromCache\`) is not double-counted.
691
+ __control.counters.turns++;
577
692
  return reply.trim();
578
693
  },
579
694
  concurrency: SPEC_CONCURRENCY,
@@ -585,7 +700,38 @@ ${mcpBoot} const queue = buildQueue();
585
700
  observer: {
586
701
  onJobEnd: (job, outcome) => {
587
702
  if (outcome.kind === "ok") {
588
- emit({ kind: "job_end", jobId: job.id, attempt: job.attempt, status: "ok", fromCache: outcome.fromCache });
703
+ // The handler's return value IS the work product — a batch run
704
+ // whose stdout carried only status JSON had no observable result
705
+ // at all (replies were recoverable only from the session
706
+ // transcript). Emit it verbatim, plus its size so the line stays
707
+ // scannable. CREWHAUS_BATCH_EMIT_RESULT=0 suppresses the payload
708
+ // (large or sensitive results shipped to logs) while keeping
709
+ // resultBytes.
710
+ const includeResult = process.env["CREWHAUS_BATCH_EMIT_RESULT"] !== "0";
711
+ emit({
712
+ kind: "job_end",
713
+ jobId: job.id,
714
+ attempt: job.attempt,
715
+ status: "ok",
716
+ fromCache: outcome.fromCache,
717
+ resultBytes: Buffer.byteLength(outcome.value ?? "", "utf8"),
718
+ ...(includeResult ? { result: outcome.value } : {}),
719
+ });
720
+ } else if (outcome.kind === "deferred") {
721
+ // NOT a failure: the turn parked on a tool permission that needs a
722
+ // human. The job is neither ack'd nor dead-lettered — it returns to
723
+ // the queue after the defer window and the attempt does not count
724
+ // against maxRetries. Reported under its own status so an operator
725
+ // watching this stream can tell "waiting on someone" apart from
726
+ // "broken", and knows to run \`crewhaus approvals list\`.
727
+ emit({
728
+ kind: "job_end",
729
+ jobId: job.id,
730
+ attempt: job.attempt,
731
+ status: "awaiting_approval",
732
+ defers: outcome.defers,
733
+ error: (outcome.error as Error).message ?? String(outcome.error),
734
+ });
589
735
  } else {
590
736
  emit({
591
737
  kind: "job_end",
@@ -615,7 +761,7 @@ ${scheduleBoot}
615
761
  };
616
762
  process.on("SIGINT", () => void shutdown("SIGINT"));
617
763
  process.on("SIGTERM", () => void shutdown("SIGTERM"));
618
-
764
+ ${controlDrain}${controlStart}
619
765
  ${idleLoop}
620
766
  }
621
767
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/target-batch-worker",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
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,10 @@
15
15
  "test": "bun test src"
16
16
  },
17
17
  "dependencies": {
18
- "@crewhaus/errors": "0.4.0",
19
- "@crewhaus/infra-utils": "0.4.0",
20
- "@crewhaus/ir": "0.4.0"
18
+ "@crewhaus/errors": "0.5.0",
19
+ "@crewhaus/gateway-protocol": "0.5.0",
20
+ "@crewhaus/infra-utils": "0.5.0",
21
+ "@crewhaus/ir": "0.5.0"
21
22
  },
22
23
  "license": "Apache-2.0",
23
24
  "author": {