@cat-factory/server 0.290.1 → 0.292.0

package/dist/agents/containerJobAddressing.js

@@ -0,0 +1,88 @@
+// How a container job is IDENTIFIED and ADDRESSED: the id the harness keys it by, the ref the
+// transport routes it by, and the image variant that decides which container both mean.
+//
+// Extracted from `ContainerAgentExecutor` because the three answer one question ("which job, in
+// which container") and the executor is at its size budget. They are pure functions of the run
+// context or the job handle, which is what lets the dispatch site and the poll site derive the
+// same answer with nothing carried between them: the poll runs in another process after a
+// durable replay and rebuilds the handle from the persisted step alone.
+/**
+ * The harness job id for one dispatch: the run (execution) id, the agent kind, and — past the
+ * first job of that kind in the run — the `dispatchEpoch`. A run executes a sequence of steps that
+ * all share the one per-run container, so each job needs an id that is UNIQUE WITHIN THE RUN: the
+ * harness keys its per-kind job registries by it, and two jobs sharing an id alias there (the bug
+ * where an `architect` /explore poll read back the `spec-writer`'s /spec result). The run itself is
+ * addressed separately by the execution id (the {@link RunnerJobRef.runId}).
+ *
+ * The epoch is what makes that uniqueness total, because the engine dispatches one kind more than
+ * once per run in two ways: a step RE-dispatched (a Tester re-test after a fixer round, a gate's
+ * helper retry, a companion's rework round, an eviction recovery) and the same helper kind
+ * escalated off DIFFERENT steps (`fixer` serves four gates). The harness re-attaches to an EXISTING
+ * job id rather than re-running (replay idempotency), and a container-reusing transport — a warm
+ * local pool, a self-hosted runner pool — keeps that registry alive across rounds, since reclaiming
+ * a pooled member does NOT destroy it. So a reused id replays a completed job: the Tester that
+ * appeared to "pass regardless" and never re-tested, an eviction recovery landing back on the job
+ * whose runner just died. `dispatchEpochFor` counts the run's prior dispatches of the kind, so the
+ * id names the n-th job of that kind and the run's first keeps the unsuffixed shape.
+ */
+export function stepJobId(executionId, agentKind, dispatchEpoch = 0) {
+    const base = `${executionId}-${agentKind}`;
+    return dispatchEpoch > 0 ? `${base}-${dispatchEpoch}` : base;
+}
+/** The provider slug from a handle's `provider:model` string (fallback when the handle omits `provider`). */
+export function providerOf(model) {
+    if (!model)
+        return 'unknown';
+    const colon = model.indexOf(':');
+    return colon > 0 ? model.slice(0, colon) : model;
+}
+/**
+ * The executor image a kind's steps run on, as the kind DECLARED it on its registration
+ * (`ui` selects the heavier Playwright + browser image; absent means the default one, so the
+ * browser never bloats every other kind's cold start).
+ *
+ * Read at the dispatch site AND at the poll/stop site rather than persisted on the handle,
+ * because a per-run container backend puts a differently-imaged step in its OWN container and
+ * every later call has to address that one. Both sites already hold the agent kind, so the
+ * variant is a pure function of state the step carries, and a handle minted before this existed
+ * resolves to exactly what it ran on.
+ */
+export function imageVariantFor(agentKind, registry) {
+    return agentKind ? registry.agentStep(agentKind)?.image : undefined;
+}
+/**
+ * Every container a RUN holds, as image variants: `undefined` (the ordinary one, always — it is
+ * where the run's default-image steps ran) plus one per NON-DEFAULT image any of the dispatched
+ * kinds declared.
+ *
+ * This is what makes a run-level reclaim total. A per-run container backend hosts a whole run in
+ * ONE container UNLESS a step declared a different image, and then there are two; addressing
+ * only the ordinary one leaves a browser container running until its maximum lifetime elapses.
+ * Deriving the set from the kinds the run DISPATCHED (rather than reclaiming every variant this
+ * build knows) keeps the reclaim to containers that exist: `idFromName` answers a stub for a
+ * container that never ran, so a blanket sweep would instantiate one per unused variant and
+ * report the kill as a success.
+ */
+export function runImageVariants(agentKinds, registry) {
+    const variants = new Set([undefined]);
+    for (const kind of agentKinds) {
+        const image = imageVariantFor(kind, registry);
+        if (image && image !== 'default')
+            variants.add(image);
+    }
+    return [...variants];
+}
+/**
+ * The {@link RunnerJobRef} a job handle addresses: the run (for the per-run container)
+ * plus the per-step job id. Falls back to the job id as the run id for a handle minted
+ * before run ids were carried (or a single-job flow where the two coincide).
+ */
+export function refForHandle(handle, registry) {
+    const image = imageVariantFor(handle.agentKind, registry);
+    return {
+        runId: handle.runId ?? handle.jobId,
+        jobId: handle.jobId,
+        ...(image ? { image } : {}),
+    };
+}
+//# sourceMappingURL=containerJobAddressing.js.map

package/dist/agents/containerJobAddressing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerJobAddressing.js","sourceRoot":"","sources":["../../src/agents/containerJobAddressing.ts"],"names":[],"mappings":"AAGA,8FAA8F;AAC9F,wFAAwF;AACxF,EAAE;AACF,gGAAgG;AAChG,+FAA+F;AAC/F,+FAA+F;AAC/F,0FAA0F;AAC1F,wEAAwE;AAExE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CAAC,WAAmB,EAAE,SAAiB,EAAE,aAAa,GAAG,CAAC;IACjF,MAAM,IAAI,GAAG,GAAG,WAAW,IAAI,SAAS,EAAE,CAAA;IAC1C,OAAO,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9D,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAChC,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA6B,EAC7B,QAA2B;IAE3B,OAAO,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACrE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAA6B,EAC7B,QAA2B;IAE3B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAiC,CAAC,SAAS,CAAC,CAAC,CAAA;IACrE,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QAC7C,IAAI,KAAK,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IACvD,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAA;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAsB,EAAE,QAA2B;IAC9E,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IACzD,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;QACnC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/server",
-  "version": "0.290.1",
+  "version": "0.292.0",
   "description": "Runtime-neutral HTTP layer for the Agent Architecture Board: the Hono controllers, middleware (auth/authz/CORS/error), request helpers and the gateway seams shared by every deployment facade (Cloudflare Worker, Node service).",
   "repository": {
     "type": "git",
@@ -31,13 +31,13 @@
     "jose": "^6.2.8",
     "pino": "^10.3.1",
     "valibot": "^1.4.2",
-    "@cat-factory/agents": "0.133.1",
+    "@cat-factory/agents": "0.133.3",
     "@cat-factory/contracts": "0.317.0",
-    "@cat-factory/kernel": "0.305.0",
-    "@cat-factory/integrations": "0.164.1",
+    "@cat-factory/integrations": "0.165.1",
     "@cat-factory/mcp-server": "0.41.0",
-    "@cat-factory/orchestration": "0.276.0",
-    "@cat-factory/spend": "0.15.99"
+    "@cat-factory/orchestration": "0.277.0",
+    "@cat-factory/spend": "0.15.101",
+    "@cat-factory/kernel": "0.307.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",