@cat-factory/executor-harness 1.64.4 → 1.68.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`);
@@ -411,78 +412,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 +598,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 +661,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 +678,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

@@ -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
@@ -240,12 +241,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

@@ -203,26 +203,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/subagents.js

@@ -137,7 +137,13 @@ export function startSubagentWatcher(root, opts) {
             return;
         const message = event.message;
         const u = claudeCallUsage(message.usage);
-        if (u.inputTokens === 0 && u.outputTokens === 0)
+        // Every input class counts towards "did this turn report usage at all": a turn riding a
+        // warm cache legitimately reports 0 fresh input, and skipping it would drop precisely the
+        // cache-heavy calls this telemetry exists to weigh.
+        if (u.inputTokens === 0 &&
+            u.cacheReadTokens === 0 &&
+            u.cacheWriteTokens === 0 &&
+            u.outputTokens === 0)
             return;
         const content = Array.isArray(message.content) ? message.content : [];
         const { text, reasoning } = claudeAssistantContent(content);
@@ -154,11 +160,16 @@ export function startSubagentWatcher(root, opts) {
             responseText: redactBody(text, secrets),
             reasoningText: redactBody(reasoning, secrets),
             inputTokens: u.inputTokens,
-            cachedInputTokens: u.cachedInputTokens,
+            cacheReadTokens: u.cacheReadTokens,
+            cacheWriteTokens: u.cacheWriteTokens,
             outputTokens: u.outputTokens,
             finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
         }, opts.onCallMetric);
-        usage.inputTokens += u.inputTokens;
+        // The run-level `usage` is the COARSE rotation-window weight, which counts every billed
+        // input bucket — unlike the per-call metric above, whose `inputTokens` is fresh-only. Sum
+        // all three classes back together here or a cache-heavy subagent looks nearly free to the
+        // rotation.
+        usage.inputTokens += u.inputTokens + u.cacheReadTokens + u.cacheWriteTokens;
         usage.outputTokens += u.outputTokens;
     };
     const NEWLINE = 0x0a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.64.4",
+  "version": "1.68.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.171.0",
-    "@cat-factory/server": "0.162.1",
-    "@cat-factory/spend": "0.12.100"
+    "@cat-factory/kernel": "0.176.0",
+    "@cat-factory/server": "0.166.0",
+    "@cat-factory/spend": "0.12.105"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",