@cat-factory/executor-harness 1.66.0 → 1.70.0

package/dist/job.js

@@ -1,5 +1,6 @@
 import { parseValidationChecksSpec, } from './validation-checks.js';
 import { parseReproductionSpec, } from './reproduction-proof.js';
+import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
 function str(value, path) {
     if (typeof value !== 'string' || value.length === 0) {
         throw new Error(`Invalid job: '${path}' must be a non-empty string`);
@@ -95,6 +96,8 @@ function parseHarnessAuth(o) {
         harness,
         proxyBaseUrl: str(o.proxyBaseUrl, 'proxyBaseUrl'),
         sessionToken: str(o.sessionToken, 'sessionToken'),
+        // Opt-IN, so a backend that doesn't serve the phase route (or predates it) is the default.
+        ...(o.proxyPhasePath === true ? { proxyPhasePath: true } : {}),
     };
 }
 /**
@@ -411,78 +414,6 @@ function parseContextFiles(value) {
     }
     return files;
 }
-/**
- * Sanitize a skill resource's relative path: keep the subdirectory structure (so
- * `templates/report.md` materialises nested) but reject anything that could escape the skill
- * directory — absolute paths, `..` traversal, backslashes, empty/dot segments. Returns undefined
- * for an unsafe path (the resource is then dropped).
- */
-function sanitizeSkillRelPath(value) {
-    if (typeof value !== 'string')
-        return undefined;
-    const segments = value.replace(/\\/g, '/').split('/');
-    const clean = [];
-    for (const seg of segments) {
-        if (seg === '' || seg === '.')
-            continue;
-        if (seg === '..')
-            return undefined;
-        // Same character class as a context-file name, per segment.
-        const c = seg.replace(/[^A-Za-z0-9._-]/g, '');
-        if (!c || c === '.' || c === '..' || c.startsWith('.'))
-            return undefined;
-        clean.push(c);
-    }
-    return clean.length ? clean.join('/') : undefined;
-}
-/**
- * Fallback native-skill directory name when the authored name has no id-safe characters (e.g. a
- * purely non-ASCII skill name). The name is only a path segment / manifest label, so a safe
- * default keeps the skill installable rather than dropping it — which, on the claude-code path,
- * would leave the prompt pointing at a skill that was never installed (a blind run).
- */
-const FALLBACK_SKILL_NAME = 'skill';
-/** A skill's own directory name, sanitized to a safe single path segment (undefined if empty). */
-function sanitizeSkillName(value) {
-    if (typeof value !== 'string')
-        return undefined;
-    const base = value.replace(/\\/g, '/').split('/').pop() ?? '';
-    const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '');
-    if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.'))
-        return undefined;
-    return cleaned;
-}
-/** Validate the optional `skill` field, or undefined when absent/malformed. */
-function parseSkillSpec(value) {
-    if (typeof value !== 'object' || value === null)
-        return undefined;
-    const o = value;
-    const instructions = typeof o.instructions === 'string' ? o.instructions : undefined;
-    // No instructions ⇒ there is nothing to run — drop the skill (the prompt still carries the
-    // folded-in directive on the Pi/codex path). An unsafe/empty NAME only affects the install
-    // directory, so fall back to a safe default rather than dropping the whole skill.
-    if (!instructions)
-        return undefined;
-    const name = sanitizeSkillName(o.name) ?? FALLBACK_SKILL_NAME;
-    const description = typeof o.description === 'string' ? o.description : '';
-    const resources = [];
-    if (Array.isArray(o.resources)) {
-        const used = new Set();
-        for (const entry of o.resources) {
-            if (typeof entry !== 'object' || entry === null)
-                continue;
-            const e = entry;
-            const relPath = sanitizeSkillRelPath(e.relPath);
-            if (!relPath || used.has(relPath))
-                continue;
-            if (typeof e.content !== 'string')
-                continue;
-            used.add(relPath);
-            resources.push({ relPath, content: e.content });
-        }
-    }
-    return { name, description, instructions, resources };
-}
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -669,7 +600,8 @@ export function parseAgentJob(input) {
         bootstrap: parseAgentBootstrapSpec(o.bootstrap),
         contextFiles: parseContextFiles(o.contextFiles),
         packageRegistries: parsePackageRegistries(o.packageRegistries),
-        skill: parseSkillSpec(o.skill),
+        skills: parseSkillSpecs(o.skills),
+        mcpServers: parseMcpServerSpecs(o.mcpServers),
         testSecrets: parseTestSecrets(o.testSecrets),
         guardLimits: parseGuardLimits(o.guardLimits),
         validation: parseValidationSpec(o.validation),
@@ -731,7 +663,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, validationChecks, reproduction, reviewPrNumber, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -748,7 +680,8 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
-        ...(skill ? { skill } : {}),
+        ...(skills ? { skills } : {}),
+        ...(mcpServers ? { mcpServers } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(pr ? { pr } : {}),

package/dist/pi-workspace.js

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { readEffortReport } from './effort.js';
 import { log } from './logger.js';
-import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, phasedProxyBaseUrl, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
 import { mergeGuardLimits, progressGuardLimitsFromEnv, } from './progress-guard.js';
 import { runSubscriptionHarness } from './agent-runner.js';
 // The thin base every container agent shares: an ephemeral working directory, and
@@ -142,14 +142,14 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // harness paths; kept out of the agent's commits via a local git exclude entry.
     const contextFiles = spec.contextFiles ?? [];
     await materializeContextFiles(spec.dir, contextFiles);
-    // Repo-sourced skill (slice 2): claude-code installs it natively into its ISOLATED config dir,
-    // so it reads from there. Everything else reads the checkout, so materialise the skill's
-    // resources under `.cat-context/skill/` (its instructions are folded into the prompt by the
-    // backend) — Pi, codex, and AMBIENT claude-code, which has no isolated config dir to install
-    // into (the runner refuses to write a repo's skill into the developer's own `~/.claude`; see
-    // `runClaudeCode`). A resource-free skill is a no-op here.
-    if (spec.skill && !installsSkillNatively(spec)) {
-        await materializeSkillResources(spec.dir, spec.skill);
+    // Skills: claude-code installs them natively into its ISOLATED config dir, so it reads from
+    // there. Everything else reads the checkout, so materialise each skill's resources under
+    // `.cat-context/skill/<name>/` (their instructions are folded into the prompt by the backend) —
+    // Pi, codex, and AMBIENT claude-code, which has no isolated config dir to install into (the
+    // runner refuses to write a skill into the developer's own `~/.claude`; see `runClaudeCode`).
+    // Resource-free skills are a no-op here.
+    if (spec.skills?.length && !installsSkillNatively(spec)) {
+        await materializeSkillResources(spec.dir, spec.skills);
     }
     // Subscription harnesses (Claude Code / Codex) authenticate with the leased
     // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
@@ -169,7 +169,8 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
             ...(spec.ambientAuth ? { ambientAuth: true } : {}),
-            ...(spec.skill ? { skill: spec.skill } : {}),
+            ...(spec.skills?.length ? { skills: spec.skills } : {}),
+            ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
             ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
             signal: opts.signal,
             // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
@@ -220,7 +221,15 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         hasBlueprints,
         ...(spec.multiRepo ? { multiRepo: true } : {}),
     });
-    await writePiModelsConfig({ model: spec.model, proxyBaseUrl });
+    // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so
+    // the phase this pass runs under is carried on the URL it is pointed at. Resolved per pass
+    // (this whole function re-runs for every repair round), which is what makes a repair round's
+    // spend distinguishable from the first pass's. Only when the BACKEND said it serves that
+    // route, since a runner pool or `LOCAL_HARNESS_IMAGE` can pair this image with an older one.
+    await writePiModelsConfig({
+        model: spec.model,
+        proxyBaseUrl: phasedProxyBaseUrl(proxyBaseUrl, opts.currentPhase?.(), spec.proxyPhasePath),
+    });
     const { signal, onActivity, onProgress, onSpan } = opts;
     const piOutcome = await runPi({
         cwd: spec.dir,
@@ -240,12 +249,12 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     return withEffortReport(spec.dir, piOutcome);
 }
 /**
- * Whether the claude-code runner will install this run's repo-sourced skill natively (into the
- * CLI's config dir) rather than the caller materialising it into the checkout. True ONLY for a
+ * Whether the claude-code runner will install this run's skills natively (into the CLI's config
+ * dir) rather than the caller materialising them into the checkout. True ONLY for a
  * leased-credential claude-code run, which gets a throwaway per-run config home. An AMBIENT run
- * uses the developer's own `~/.claude`, which the runner will not write a repo's skill into —
- * it would outlive the run in their personal setup, and two concurrent jobs carrying same-named
- * skills from different repos would overwrite each other's.
+ * uses the developer's own `~/.claude`, which the runner will not write a skill into — it would
+ * outlive the run in their personal setup, and two concurrent jobs carrying same-named skills
+ * would overwrite each other's.
  */
 export function installsSkillNatively(spec) {
     return spec.harness === 'claude-code' && !spec.ambientAuth;

package/dist/pi.js

@@ -24,6 +24,63 @@ import { ProgressGuard, progressGuardLimitsFromEnv, toolCallSignal, } from './pr
  * {@link runDiagnostics} flagging the rare case where even 32k is not enough.
  */
 export const PI_MAX_OUTPUT_TOKENS = 32_768;
+/**
+ * Longest phase label the backend keeps. Mirrors kernel's `MAX_PHASE_CHARS`; see
+ * {@link normalizeProxyPhase} for why this is a copy rather than an import.
+ */
+const MAX_PHASE_CHARS = 32;
+/**
+ * Normalise a phase label to what the backend will actually store: trimmed, lowercased,
+ * `[a-z0-9-]` only, bounded. `''` when the label is not a phase at all.
+ *
+ * A deliberate COPY of kernel's `normalizeCallPhase` — the container image is built from `src/`
+ * plus typescript alone, so the harness can carry no runtime dependency on a workspace package
+ * (the same constraint that forced `src/host-markdown.ts`). A copy that can drift is worse than
+ * no copy: if the harness rejected a label the backend would have accepted, the call would take
+ * the plain path and land unattributed, and if it accepted one the backend rejects it would
+ * spend a request on a segment destined for `''`. `test/llm-phase.conformity.test.ts` pins the
+ * two to identical verdicts over a corpus, so the alphabet can only be changed in both.
+ */
+export function normalizeProxyPhase(phase) {
+    if (typeof phase !== 'string')
+        return '';
+    const trimmed = phase.trim().toLowerCase();
+    if (!trimmed || trimmed.length > MAX_PHASE_CHARS)
+        return '';
+    return /^[a-z0-9-]+$/.test(trimmed) ? trimmed : '';
+}
+/**
+ * Point Pi's provider at the phase-tagged completions path for the pass about to run, so the
+ * backend can stamp WHICH slice of the run spent each call (the agent's own loop vs a pre-PR
+ * validation repair round vs a reproduction-proof repair round) — see
+ * `docs/initiatives/token-burn-instrumentation.md`. The harness drives those loops, so it is
+ * the only component that knows; reconstructing the boundary downstream from wall-clock
+ * timestamps is exactly the brittle inference this avoids.
+ *
+ * A URL segment because the harness does not make these requests: Pi does, from a config whose
+ * only per-run knobs are the base URL and the token — there is no per-request header to set.
+ *
+ * `supported` is the BACKEND's declaration that it serves the phase-tagged route, carried on the
+ * job body exactly as `webSearch` carries "point the search tool at my `/web-search`". Without it
+ * this function would encode a routing shape the receiving backend may not have: a runner pool
+ * pins its OWN harness image (`RunnerPoolManifest`), and `LOCAL_HARNESS_IMAGE` overrides the
+ * recommended pin outright, so "the image and the backend are a matched set" holds for the
+ * Cloudflare deployment and nowhere else. An image ahead of its backend would 404 EVERY model
+ * call — a dead run, not degraded telemetry. Absent/false ⇒ the plain path, and the calls land
+ * in the backend's unattributed slice.
+ *
+ * Pure so the join is unit-testable without spawning anything.
+ */
+export function phasedProxyBaseUrl(proxyBaseUrl, phase, supported) {
+    if (!supported)
+        return proxyBaseUrl;
+    // A label the backend would discard would be sent only to be thrown away, so send the plain
+    // path instead — the call is then honestly unattributed rather than attributed to nothing.
+    const normalized = normalizeProxyPhase(phase);
+    if (!normalized)
+        return proxyBaseUrl;
+    return `${proxyBaseUrl.replace(/\/+$/, '')}/phase/${normalized}`;
+}
 /** Write the Pi provider config that routes all model calls through the proxy. */
 export async function writePiModelsConfig(opts) {
     const dir = join(homedir(), '.pi', 'agent');
@@ -203,26 +260,34 @@ export async function materializeContextFiles(cwd, files) {
         // No writable .git/info; the files simply stay untracked (still not auto-added on most flows).
     }
 }
-/** Subdirectory of {@link CONTEXT_DIR} where a repo-sourced skill's resources are materialised. */
+/** Subdirectory of {@link CONTEXT_DIR} where a skill's resources are materialised, per skill. */
 export const SKILL_CONTEXT_SUBDIR = 'skill';
 /**
- * Materialise a repo-sourced skill's RESOURCE files under `.cat-context/skill/` in the checkout
- * (repo-sourced Claude Skills, slice 2) — the path for every run that does NOT get a native
- * install: Pi, codex, and ambient claude-code (no isolated `CLAUDE_CONFIG_DIR` to install into).
- * Their agents read the checkout, and the skill's instructions are folded into their prompt by the
- * backend (`renderSkillForHarness`, which keys off ambient auth as well as the harness). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
- * dirs are created as needed. Kept out of the agent's commits via the same `.cat-context/` git
- * exclude entry. A skill with no resource bodies is a no-op.
+ * Materialise the run's skills' RESOURCE files under `.cat-context/skill/<name>/` in the checkout
+ * — the path for every run that does NOT get a native install: Pi, codex, and ambient claude-code
+ * (no isolated `CLAUDE_CONFIG_DIR` to install into). Their agents read the checkout, and the
+ * skills' instructions are folded into their prompt by the backend (`renderSkillsForHarness`,
+ * which keys off ambient auth as well as the harness).
+ *
+ * Each skill gets its OWN subdirectory: several skills can apply to one run (a step's pick plus
+ * the kind's declared playbooks), and a flat directory would let two skills' `templates/report.md`
+ * overwrite each other — silently handing the agent the wrong template. The names were sanitized
+ * to a single safe path segment at the job boundary, as were the resource sub-paths (no
+ * traversal), so nested dirs are created as needed. Kept out of the agent's commits via the same
+ * `.cat-context/` git exclude entry. Skills with no resource bodies are a no-op.
  */
-export async function materializeSkillResources(cwd, skill) {
-    if (!skill.resources.length)
+export async function materializeSkillResources(cwd, skills) {
+    const withResources = skills.filter((s) => s.resources.length);
+    if (!withResources.length)
         return;
-    const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR);
-    await mkdir(dir, { recursive: true });
-    for (const r of skill.resources) {
-        const dest = join(dir, r.relPath);
-        await mkdir(dirname(dest), { recursive: true });
-        await writeFile(dest, r.content, 'utf8');
+    for (const skill of withResources) {
+        const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR, skill.name);
+        await mkdir(dir, { recursive: true });
+        for (const r of skill.resources) {
+            const dest = join(dir, r.relPath);
+            await mkdir(dirname(dest), { recursive: true });
+            await writeFile(dest, r.content, 'utf8');
+        }
     }
     const gitRoot = await findGitRoot(cwd);
     if (!gitRoot)

package/dist/runner.js

@@ -224,9 +224,17 @@ export class JobRegistry {
                     // instance for its terminal result, so both channels carry the same `seq` and the
                     // backend mints one stable row id per call.
                     call.seq = entry.callMetricSeq++;
+                    // …and the phase the job is in RIGHT NOW, which is what spent the call: the handlers
+                    // mark `validation-repair` / `reproduction-repair` around each repair pass, so a
+                    // looped run's telemetry says which loop the tokens went to instead of filing every
+                    // turn under one undifferentiated "agent"
+                    // (`docs/initiatives/token-burn-instrumentation.md`). Stamped at EMIT time, not at
+                    // drain time: a poll can land long after the phase moved on.
+                    call.phase = phase;
                     entry.callMetricBuffer.push(call);
                 },
                 onPhase: (next) => markPhase(next),
+                currentPhase: () => phase,
                 log: jobLog,
             });
             markPhase('done');

package/dist/structured-output.js

@@ -1,6 +1,6 @@
 import { redact, redactSecrets, secretsToRedact } from './redact.js';
 import { log } from './logger.js';
-import { PI_MAX_OUTPUT_TOKENS } from './pi.js';
+import { PI_MAX_OUTPUT_TOKENS, phasedProxyBaseUrl } from './pi.js';
 // A reusable abstraction for the "agent returns a structured JSON document as its
 // final assistant message" pattern (requirements, blueprint, merger — and any future
 // kind). An agent of this kind emits its result as text, not a tool call, and the
@@ -31,6 +31,12 @@ const REPAIR_SYSTEM = 'You repair malformed JSON. You are given text that was me
     'JSON object but does not parse. Return ONLY the corrected JSON object: no prose, ' +
     'no markdown code fences, no commentary, and never repeat or duplicate any tokens. ' +
     'Preserve the original content faithfully; only fix the JSON structure.';
+/**
+ * The run phase a structured-output repair call is billed to. A constant, not a `currentPhase`
+ * read: this call is made by the harness itself (the agent has already finished and left text
+ * that won't parse), so it belongs to no pass the registry marks.
+ */
+const STRUCTURED_REPAIR_PHASE = 'structured-repair';
 /**
  * Largest immediately-repeated run length we look for. The corruption duplicates
  * whole model tokens, which carry whitespace/punctuation context and run to ~10-15
@@ -195,7 +201,12 @@ async function callRepair(badText, spec, access) {
     if (!access.proxyBaseUrl || !access.sessionToken) {
         throw new Error('structured-output repair requires the LLM proxy (Pi harness)');
     }
-    const url = `${access.proxyBaseUrl.replace(/\/+$/, '')}/chat/completions`;
+    // A repair round is its own slice of the run's burn, not part of the agent's loop that
+    // produced the unparseable text — and unlike the phases the registry marks, this call is made
+    // by the HARNESS itself, so its phase is a constant rather than a read of `currentPhase`
+    // (docs/initiatives/token-burn-instrumentation.md).
+    const repairBaseUrl = phasedProxyBaseUrl(access.proxyBaseUrl, STRUCTURED_REPAIR_PHASE, access.proxyPhasePath);
+    const url = `${repairBaseUrl.replace(/\/+$/, '')}/chat/completions`;
     const messages = [
         { role: 'system', content: REPAIR_SYSTEM },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.66.0",
+  "version": "1.70.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",
@@ -26,9 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.175.0",
-    "@cat-factory/server": "0.165.0",
-    "@cat-factory/spend": "0.12.104"
+    "@cat-factory/kernel": "0.179.0",
+    "@cat-factory/server": "0.167.0",
+    "@cat-factory/spend": "0.12.108"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",