@cat-factory/executor-harness 1.92.2 → 1.94.0

package/dist/agent-capabilities.d.ts

@@ -55,12 +55,30 @@ export declare function mcpServerSecretValues(servers: readonly McpServerSpec[])
  * last — so the first wins and the collision is dropped rather than silently mixing two playbooks.
  */
 export declare function parseSkillSpecs(value: unknown): SkillSpec[] | undefined;
+/**
+ * The optional job-body CAPABILITY fields this image parses, reported on `/health` and on the
+ * `POST /jobs` acceptance so a backend can tell whether the body it just sent will be honoured.
+ *
+ * The gap it closes: an image older than a capability does not fail on it, it ignores the field.
+ * The backend composes the PROMPT, so a dropped `mcpServers` leaves the agent reading that it has
+ * tools it has no client for: a blind run rather than a failed one, and previously invisible to
+ * the backend, which has no way to know what image a self-hosted runner pool pins.
+ *
+ * Kept byte-identical to kernel's `HARNESS_BODY_CAPABILITIES` (the image is built from `src/` plus
+ * typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts`, the same copy-plus-pin arrangement
+ * {@link MCP_SERVER_ID_PATTERN} uses.
+ *
+ * A member is added here in the SAME change that teaches the parser the field, never ahead of it:
+ * the whole value of the list is that it is the image's own honest answer.
+ */
+export declare const HARNESS_BODY_CAPABILITIES: readonly string[];
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
  *
  * Kept byte-identical to kernel's `MCP_SERVER_ID_PATTERN` (the harness image is built from `src/`
  * plus typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
- * against it by `test/agent-capabilities.conformity.test.ts` — the same copy-plus-pin arrangement
+ * against it by `test/agent-capabilities.conformity.test.ts`, the same copy-plus-pin arrangement
  * `src/host-markdown.ts` uses.
  */
 export declare const MCP_SERVER_ID_PATTERN: RegExp;

package/dist/agent-capabilities.js

@@ -111,12 +111,30 @@ export function parseSkillSpecs(value) {
     }
     return skills.length ? skills : undefined;
 }
+/**
+ * The optional job-body CAPABILITY fields this image parses, reported on `/health` and on the
+ * `POST /jobs` acceptance so a backend can tell whether the body it just sent will be honoured.
+ *
+ * The gap it closes: an image older than a capability does not fail on it, it ignores the field.
+ * The backend composes the PROMPT, so a dropped `mcpServers` leaves the agent reading that it has
+ * tools it has no client for: a blind run rather than a failed one, and previously invisible to
+ * the backend, which has no way to know what image a self-hosted runner pool pins.
+ *
+ * Kept byte-identical to kernel's `HARNESS_BODY_CAPABILITIES` (the image is built from `src/` plus
+ * typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts`, the same copy-plus-pin arrangement
+ * {@link MCP_SERVER_ID_PATTERN} uses.
+ *
+ * A member is added here in the SAME change that teaches the parser the field, never ahead of it:
+ * the whole value of the list is that it is the image's own honest answer.
+ */
+export const HARNESS_BODY_CAPABILITIES = ['mcpServers', 'skills'];
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
  *
  * Kept byte-identical to kernel's `MCP_SERVER_ID_PATTERN` (the harness image is built from `src/`
  * plus typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
- * against it by `test/agent-capabilities.conformity.test.ts` — the same copy-plus-pin arrangement
+ * against it by `test/agent-capabilities.conformity.test.ts`, the same copy-plus-pin arrangement
  * `src/host-markdown.ts` uses.
  */
 export const MCP_SERVER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;

package/dist/runner.d.ts

@@ -256,6 +256,24 @@ export declare class JobRegistry<TJob = unknown, TResult extends JobResultBase =
      * number of jobs aborted.
      */
     abortAll(reason: string): number;
+    /**
+     * Abort ONE job and answer with the state it actually reached.
+     *
+     * The caller is a backend that has decided this job must not run: it refused the dispatch as
+     * blind, and the harness starts work on acceptance, so without this the agent runs to completion
+     * and can push a branch and open a pull request for a step the engine already failed. Aborting
+     * every job ({@link abortAll}) is not an option: a pooled container serves other runs.
+     *
+     * Waits for the job to SETTLE rather than returning the moment the signal is fired, because a
+     * fired signal is not a stopped agent and the caller's whole problem is telling those apart: it
+     * reports "stopped" to a human only on the strength of this answer. The window matches the
+     * graceful-shutdown one for the same reason (the CLI usually honours SIGTERM in milliseconds; the
+     * cap covers one that had to be force-killed through the 5s escalation in `killChildProcess`),
+     * and a job still `running` when it expires is reported as such rather than assumed dead.
+     *
+     * Returns undefined when no job of that id exists here, which the caller must NOT read as a stop.
+     */
+    abort(id: string, reason: string): Promise<JobState | undefined>;
     /**
      * How many jobs are still RUNNING. Graceful shutdown polls this so it can exit the moment the
      * aborted jobs have actually settled (the common case: the CLI honours SIGTERM in ms) instead

package/dist/runner.js

@@ -33,6 +33,13 @@ function toView(entry) {
     const { promise: _promise, spanBuffer: _spanBuffer, followUpBuffer: _followUpBuffer, callMetricBuffer: _callMetricBuffer, callMetricSeq: _callMetricSeq, abort: _abort, ...view } = entry;
     return { ...view };
 }
+/**
+ * How long {@link JobRegistry.abort} waits for an aborted job to actually settle before answering
+ * with whatever state it is in. Sized like the graceful-shutdown window (and for the same reason):
+ * the agent CLI normally honours SIGTERM in milliseconds, and this covers one that had to be
+ * force-killed through the 5s SIGTERM→SIGKILL escalation, with a margin.
+ */
+const ABORT_SETTLE_MS = 6_000;
 /**
  * Tracks background jobs by id. Keyed by the backend-supplied job id (the per-step
  * job id) so a re-dispatched start re-attaches to the running job rather than starting
@@ -124,6 +131,46 @@ export class JobRegistry {
         }
         return aborted;
     }
+    /**
+     * Abort ONE job and answer with the state it actually reached.
+     *
+     * The caller is a backend that has decided this job must not run: it refused the dispatch as
+     * blind, and the harness starts work on acceptance, so without this the agent runs to completion
+     * and can push a branch and open a pull request for a step the engine already failed. Aborting
+     * every job ({@link abortAll}) is not an option: a pooled container serves other runs.
+     *
+     * Waits for the job to SETTLE rather than returning the moment the signal is fired, because a
+     * fired signal is not a stopped agent and the caller's whole problem is telling those apart: it
+     * reports "stopped" to a human only on the strength of this answer. The window matches the
+     * graceful-shutdown one for the same reason (the CLI usually honours SIGTERM in milliseconds; the
+     * cap covers one that had to be force-killed through the 5s escalation in `killChildProcess`),
+     * and a job still `running` when it expires is reported as such rather than assumed dead.
+     *
+     * Returns undefined when no job of that id exists here, which the caller must NOT read as a stop.
+     */
+    async abort(id, reason) {
+        const entry = this.jobs.get(id);
+        if (!entry)
+            return undefined;
+        // Already terminal: nothing to stop, and re-firing a cleared abort would be a no-op anyway.
+        // This is what makes the call idempotent for a caller that retries.
+        if (entry.state !== 'running')
+            return entry.state;
+        entry.abort?.(reason);
+        let timer;
+        try {
+            await Promise.race([
+                entry.promise,
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, ABORT_SETTLE_MS);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return entry.state;
+    }
     /**
      * How many jobs are still RUNNING. Graceful shutdown polls this so it can exit the moment the
      * aborted jobs have actually settled (the common case: the CLI honours SIGTERM in ms) instead

package/dist/server.js

@@ -1,5 +1,6 @@
 import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
+import { HARNESS_BODY_CAPABILITIES } from './agent-capabilities.js';
 import { parseAgentJob, parseInlineJob } from './job.js';
 import { handleAgent } from './agent.js';
 import { handleInline } from './inline.js';
@@ -103,6 +104,7 @@ const server = createServer((req, res) => {
             return send(res, 200, {
                 status: 'ok',
                 ...(HARNESS_VERSION ? { version: HARNESS_VERSION } : {}),
+                capabilities: HARNESS_BODY_CAPABILITIES,
             });
         }
         // All non-health endpoints are gated by the optional shared secret.
@@ -120,6 +122,28 @@ const server = createServer((req, res) => {
             }
             return send(res, 404, { error: 'job not found' });
         }
+        // Stop one job: DELETE /jobs/{id}. The counterpart of the capability handshake below. A
+        // backend that reads the acceptance and decides the body cannot be honoured has, by then,
+        // already started an agent, and the only thing that keeps it from running to completion (and
+        // opening a pull request for a step the engine has failed) is being told to stop.
+        //
+        // Scoped to ONE job on purpose: a pooled container serves other runs, so the shutdown-time
+        // `abortAll` is not an alternative. The response reports the state the job actually REACHED
+        // (the registry waits for it to settle), never merely that the signal was sent, because the
+        // caller turns this into a statement to a human about whether anything is still running.
+        if (req.method === 'DELETE' && req.url?.startsWith('/jobs/')) {
+            const id = decodeURIComponent(req.url.slice('/jobs/'.length));
+            // `abort` (not `get`) is the existence probe: `get` DRAINS the job's span / follow-up /
+            // call-metric buffers, so probing with it would swallow telemetry the backend never polled.
+            for (const { registry } of Object.values(KINDS)) {
+                const state = await registry.abort(id, 'stopped by the backend');
+                if (state)
+                    return send(res, 200, { jobId: id, state });
+            }
+            // No such job here. A 404 is NOT "already stopped": it is also what a caller addressing the
+            // wrong runner sees, so it must stay distinguishable from the 200 above.
+            return send(res, 404, { error: 'job not found' });
+        }
         // Start (or re-attach to) a job: POST /jobs with the kind in the body. The body's
         // `kind` selects the validator + registry; the rest is that kind's job spec.
         // Returns immediately with the job id; the caller polls GET /jobs/{id} for live
@@ -137,7 +161,16 @@ const server = createServer((req, res) => {
                 }
                 const job = entry.parse(raw);
                 const view = entry.registry.start(job.jobId, job);
-                return send(res, 202, { jobId: view.id, state: view.state });
+                // The capability handshake rides the ACCEPTANCE, not the poll view. The dispatch site
+                // is the only place the body it just sent is still in scope, and it is the last moment
+                // a blind run can be refused before the agent starts working from a prompt the body
+                // cannot back up. It is also a static fact about the IMAGE, so repeating it on every
+                // poll of a job that may run for an hour would be noise.
+                return send(res, 202, {
+                    jobId: view.id,
+                    state: view.state,
+                    capabilities: HARNESS_BODY_CAPABILITIES,
+                });
             }
             catch (error) {
                 // Parse failures (incl. host-allowlist rejection) are client errors → 400.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.92.2",
+  "version": "1.94.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.13.0",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.242.0",
-    "@cat-factory/server": "0.222.0",
-    "@cat-factory/spend": "0.15.6"
+    "@cat-factory/kernel": "0.249.0",
+    "@cat-factory/server": "0.229.0",
+    "@cat-factory/spend": "0.15.14"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-capabilities.ts

@@ -163,12 +163,31 @@ export function parseSkillSpecs(value: unknown): SkillSpec[] | undefined {
   return skills.length ? skills : undefined
 }
 
+/**
+ * The optional job-body CAPABILITY fields this image parses, reported on `/health` and on the
+ * `POST /jobs` acceptance so a backend can tell whether the body it just sent will be honoured.
+ *
+ * The gap it closes: an image older than a capability does not fail on it, it ignores the field.
+ * The backend composes the PROMPT, so a dropped `mcpServers` leaves the agent reading that it has
+ * tools it has no client for: a blind run rather than a failed one, and previously invisible to
+ * the backend, which has no way to know what image a self-hosted runner pool pins.
+ *
+ * Kept byte-identical to kernel's `HARNESS_BODY_CAPABILITIES` (the image is built from `src/` plus
+ * typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts`, the same copy-plus-pin arrangement
+ * {@link MCP_SERVER_ID_PATTERN} uses.
+ *
+ * A member is added here in the SAME change that teaches the parser the field, never ahead of it:
+ * the whole value of the list is that it is the image's own honest answer.
+ */
+export const HARNESS_BODY_CAPABILITIES: readonly string[] = ['mcpServers', 'skills']
+
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
  *
  * Kept byte-identical to kernel's `MCP_SERVER_ID_PATTERN` (the harness image is built from `src/`
  * plus typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
- * against it by `test/agent-capabilities.conformity.test.ts` — the same copy-plus-pin arrangement
+ * against it by `test/agent-capabilities.conformity.test.ts`, the same copy-plus-pin arrangement
  * `src/host-markdown.ts` uses.
  */
 export const MCP_SERVER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/

package/src/runner.ts

@@ -304,6 +304,14 @@ function toView<TResult extends JobResultBase>(entry: JobEntry<TResult>): JobVie
   return { ...view }
 }
 
+/**
+ * How long {@link JobRegistry.abort} waits for an aborted job to actually settle before answering
+ * with whatever state it is in. Sized like the graceful-shutdown window (and for the same reason):
+ * the agent CLI normally honours SIGTERM in milliseconds, and this covers one that had to be
+ * force-killed through the 5s SIGTERM→SIGKILL escalation, with a margin.
+ */
+const ABORT_SETTLE_MS = 6_000
+
 /**
  * Tracks background jobs by id. Keyed by the backend-supplied job id (the per-step
  * job id) so a re-dispatched start re-attaches to the running job rather than starting
@@ -394,6 +402,44 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
     return aborted
   }
 
+  /**
+   * Abort ONE job and answer with the state it actually reached.
+   *
+   * The caller is a backend that has decided this job must not run: it refused the dispatch as
+   * blind, and the harness starts work on acceptance, so without this the agent runs to completion
+   * and can push a branch and open a pull request for a step the engine already failed. Aborting
+   * every job ({@link abortAll}) is not an option: a pooled container serves other runs.
+   *
+   * Waits for the job to SETTLE rather than returning the moment the signal is fired, because a
+   * fired signal is not a stopped agent and the caller's whole problem is telling those apart: it
+   * reports "stopped" to a human only on the strength of this answer. The window matches the
+   * graceful-shutdown one for the same reason (the CLI usually honours SIGTERM in milliseconds; the
+   * cap covers one that had to be force-killed through the 5s escalation in `killChildProcess`),
+   * and a job still `running` when it expires is reported as such rather than assumed dead.
+   *
+   * Returns undefined when no job of that id exists here, which the caller must NOT read as a stop.
+   */
+  async abort(id: string, reason: string): Promise<JobState | undefined> {
+    const entry = this.jobs.get(id)
+    if (!entry) return undefined
+    // Already terminal: nothing to stop, and re-firing a cleared abort would be a no-op anyway.
+    // This is what makes the call idempotent for a caller that retries.
+    if (entry.state !== 'running') return entry.state
+    entry.abort?.(reason)
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      await Promise.race([
+        entry.promise,
+        new Promise<void>((resolve) => {
+          timer = setTimeout(resolve, ABORT_SETTLE_MS)
+        }),
+      ])
+    } finally {
+      clearTimeout(timer)
+    }
+    return entry.state
+  }
+
   /**
    * How many jobs are still RUNNING. Graceful shutdown polls this so it can exit the moment the
    * aborted jobs have actually settled (the common case: the CLI honours SIGTERM in ms) instead

package/src/server.ts

@@ -1,5 +1,6 @@
 import { timingSafeEqual } from 'node:crypto'
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { HARNESS_BODY_CAPABILITIES } from './agent-capabilities.js'
 import { parseAgentJob, parseInlineJob } from './job.js'
 import { handleAgent } from './agent.js'
 import { handleInline } from './inline.js'
@@ -122,6 +123,7 @@ const server = createServer((req, res) => {
       return send(res, 200, {
         status: 'ok',
         ...(HARNESS_VERSION ? { version: HARNESS_VERSION } : {}),
+        capabilities: HARNESS_BODY_CAPABILITIES,
       })
     }
     // All non-health endpoints are gated by the optional shared secret.
@@ -138,6 +140,27 @@ const server = createServer((req, res) => {
       }
       return send(res, 404, { error: 'job not found' })
     }
+    // Stop one job: DELETE /jobs/{id}. The counterpart of the capability handshake below. A
+    // backend that reads the acceptance and decides the body cannot be honoured has, by then,
+    // already started an agent, and the only thing that keeps it from running to completion (and
+    // opening a pull request for a step the engine has failed) is being told to stop.
+    //
+    // Scoped to ONE job on purpose: a pooled container serves other runs, so the shutdown-time
+    // `abortAll` is not an alternative. The response reports the state the job actually REACHED
+    // (the registry waits for it to settle), never merely that the signal was sent, because the
+    // caller turns this into a statement to a human about whether anything is still running.
+    if (req.method === 'DELETE' && req.url?.startsWith('/jobs/')) {
+      const id = decodeURIComponent(req.url.slice('/jobs/'.length))
+      // `abort` (not `get`) is the existence probe: `get` DRAINS the job's span / follow-up /
+      // call-metric buffers, so probing with it would swallow telemetry the backend never polled.
+      for (const { registry } of Object.values(KINDS)) {
+        const state = await registry.abort(id, 'stopped by the backend')
+        if (state) return send(res, 200, { jobId: id, state })
+      }
+      // No such job here. A 404 is NOT "already stopped": it is also what a caller addressing the
+      // wrong runner sees, so it must stay distinguishable from the 200 above.
+      return send(res, 404, { error: 'job not found' })
+    }
     // Start (or re-attach to) a job: POST /jobs with the kind in the body. The body's
     // `kind` selects the validator + registry; the rest is that kind's job spec.
     // Returns immediately with the job id; the caller polls GET /jobs/{id} for live
@@ -155,7 +178,16 @@ const server = createServer((req, res) => {
         }
         const job = entry.parse(raw)
         const view = entry.registry.start(job.jobId, job as never)
-        return send(res, 202, { jobId: view.id, state: view.state })
+        // The capability handshake rides the ACCEPTANCE, not the poll view. The dispatch site
+        // is the only place the body it just sent is still in scope, and it is the last moment
+        // a blind run can be refused before the agent starts working from a prompt the body
+        // cannot back up. It is also a static fact about the IMAGE, so repeating it on every
+        // poll of a job that may run for an hour would be noise.
+        return send(res, 202, {
+          jobId: view.id,
+          state: view.state,
+          capabilities: HARNESS_BODY_CAPABILITIES,
+        })
       } catch (error) {
         // Parse failures (incl. host-allowlist rejection) are client errors → 400.
         const message = redactSecrets(error instanceof Error ? error.message : String(error))