@wardby/cli 0.2.1 → 0.4.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 /**
  * Minimal CLI.
  *
- *   wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule "<cron>"] [--timezone <tz>] [--memory-enabled]
+ *   wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule "<cron>"] [--timezone <tz>] [--memory-enabled] [--effort <level>]
  *   wardby agent list
  *   wardby agent schedule <name> --cron "<expr>" [--timezone <tz>] [--disable]
  *   wardby run <name>
@@ -20,31 +20,43 @@ import { readFileSync } from "node:fs";
 import { execFile as execFileCallback } from "node:child_process";
 import { parseArgs } from "node:util";
 import { promisify } from "node:util";
-import { loadCodingConcurrencyConfig, loadContainerExecutorConfig, loadKubernetesJobConfig, loadProviderConfig, } from "./config/providers.js";
+import { loadCodingConcurrencyConfig, loadContainerExecutorConfig, loadKubernetesJobConfig, loadMcpConfig, loadProviderConfig, } from "./config/providers.js";
 import { drainCodingQueue } from "./core/coding-queue.js";
 import { isImmutableDockerImage } from "./providers/jobs/docker-isolation.js";
 import { ClientNodeKubernetesApi } from "./providers/jobs/kubernetes-client.js";
 import { describePreflightFailure, kubernetesPreflight } from "./providers/jobs/kubernetes-preflight.js";
-import { RoutingLlmProvider, resolveLlmRegistrations } from "./providers/llm/index.js";
+import { RoutingLlmProvider, isLlmEffort, modelSupportedEfforts, resolveLlmRegistrations, } from "./providers/llm/index.js";
+import { startModelCatalog } from "./providers/llm/catalog-store.js";
 import { buildConfiguredExecutor, buildExecutor } from "./providers/executor/index.js";
 import { PostgresDatastore } from "./providers/datastore/index.js";
 import { PostgresAgentMemory } from "./providers/memory/index.js";
 import { buildSecretCipher } from "./providers/secrets/index.js";
 import { prisma } from "./core/db.js";
 import { runAgent } from "./core/runner.js";
+import { cancelRunOnSignal } from "./core/run-heartbeat.js";
+import { buildIssueTrackers } from "./providers/issue-tracker/index.js";
+import { buildReviewHosts } from "./providers/review-host/index.js";
+import { createRepoAccessGate } from "./core/repo-access.js";
 import { validateCronExpression } from "./core/cron.js";
+import { assertAgentModelAvailable } from "./core/run-pricing.js";
 import { startScheduler } from "./core/scheduler.js";
 import { startReconciler } from "./core/reconciler.js";
 import { NativeEngine } from "./core/engine-native.js";
 import { logger } from "./core/logger.js";
 import { deriveJsonSchema } from "./sandbox/zod-params.js";
+import { findSameNamedAttachedTool, reservedToolNameReason, resolveToolRef } from "./core/tool-names.js";
+import { ToolAttachedError, deleteToolGuarded, formatAttachedAgents, formatToolLine, hasToolChanges, prepareToolUpdate, updateToolGuarded, } from "./core/tool-admin.js";
 import { ToolCapabilitiesPatchSchema } from "./sandbox/tool-capabilities.js";
 import { startMcp } from "./mcp/index.js";
 import { startServe } from "./serve.js";
 import { authCommand } from "./mcp/auth/self-hosted/cli.js";
+import { hostAccountCommand } from "./mcp/auth/host-account-cli.js";
+import { grantsCommand, resolveCliAgentOwner } from "./mcp/auth/grants-cli.js";
+import { everyoneGrantData } from "./core/grants.js";
 import { parseImportArgs } from "./import/cli-args.js";
 import { runImport } from "./import/index.js";
 import { CLI_USAGE } from "./cli-help.js";
+import { helpCommand } from "./help/cli.js";
 const cliLog = logger.child({ module: "cli" });
 const RUN_STATUSES = [
     "pending",
@@ -106,6 +118,9 @@ async function agentCreate(args) {
             timezone: { type: "string" },
             "max-turns": { type: "string" },
             "memory-enabled": { type: "boolean" },
+            effort: { type: "string" },
+            owner: { type: "string" },
+            public: { type: "boolean" },
         },
     });
     if (!values.name || !values.model || !values.prompt || !values.budget) {
@@ -128,17 +143,58 @@ async function agentCreate(args) {
             fail(`invalid --schedule/--timezone: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    const agent = await prisma.agent.create({
-        data: {
-            name: values.name,
-            model: values.model,
-            systemPrompt: values.prompt,
-            budgetUsd,
-            schedule: values.schedule ?? null,
-            timezone,
-            maxTurns,
-            memoryEnabled: values["memory-enabled"] ?? false,
-        },
+    // Started before validating the model so an admin override recorded in
+    // ModelCatalogEntry (a disabled model, a narrowed effort list) is
+    // respected here too, not just at run time.
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    try {
+        assertAgentModelAvailable(values.model);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    if (values.effort !== undefined) {
+        const accepted = modelSupportedEfforts(values.model);
+        if (!isLlmEffort(values.effort) || !accepted.includes(values.effort)) {
+            fail(`model "${values.model}" does not accept --effort "${values.effort}"` +
+                (accepted.length > 0 ? ` (accepted: ${accepted.join(", ")}).` : " (it accepts no effort setting)."));
+        }
+    }
+    modelCatalog.close();
+    // Owned by --owner or the local operator; never owner-less (resource-
+    // sharing grants spec §3.8). --public shares it with everyone at execute.
+    let ownerId;
+    try {
+        ownerId = await resolveCliAgentOwner(prisma, values.owner, loadMcpConfig().localPrincipal);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    const agent = await prisma.$transaction(async (tx) => {
+        const created = await tx.agent.create({
+            data: {
+                name: values.name,
+                model: values.model,
+                systemPrompt: values.prompt,
+                budgetUsd,
+                schedule: values.schedule ?? null,
+                timezone,
+                maxTurns,
+                memoryEnabled: values["memory-enabled"] ?? false,
+                effort: values.effort ?? null,
+                ownerId: ownerId,
+            },
+        });
+        if (values.public) {
+            await tx.resourceGrant.create({ data: everyoneGrantData("agent", created.id, "execute", "operator") });
+        }
+        return created;
     });
     console.log(agent.id);
 }
@@ -155,6 +211,9 @@ async function toolCreate(args) {
     if (!values.name || !values.description || !values.params || !values.code) {
         fail("tool create requires --name, --description, --params <file>, and --code <file>.");
     }
+    const reserved = reservedToolNameReason(values.name);
+    if (reserved)
+        fail(reserved);
     let paramsZod;
     let code;
     try {
@@ -170,12 +229,19 @@ async function toolCreate(args) {
         fail(`could not read --code file "${values.code}": ${err instanceof Error ? err.message : String(err)}`);
     }
     // Fails at registration, not at call time: a malformed schema never gets
-    // persisted. The derived schema is cached on the row (no "update tool"
-    // path exists, so it can never go stale) rather than re-derived per run.
+    // persisted. The derived schema is cached on the row rather than
+    // re-derived per run; MCP update_tool re-derives it whenever paramsZod
+    // changes, so it never goes stale.
     const schemaResult = await deriveJsonSchema(paramsZod);
     if (!schemaResult.ok) {
         fail(`invalid --params schema: ${schemaResult.errorMessage}`);
     }
+    // CLI tools are public (no owner), and the (ownerId, name) unique index
+    // treats NULL owners as distinct, so it can't stop a second public tool
+    // with this name -- check here instead.
+    if (await prisma.tool.findFirst({ where: { ownerId: null, name: values.name } })) {
+        fail(`a public tool named "${values.name}" already exists.`);
+    }
     const tool = await prisma.tool.create({
         data: {
             name: values.name,
@@ -203,11 +269,14 @@ async function toolAttach(args, detach) {
     });
     const [toolName, agentName] = positionals;
     if (!toolName || !agentName) {
-        fail(`tool ${detach ? "detach" : "attach"} requires <tool-name> <agent-name>.`);
-    }
-    const tool = await prisma.tool.findUnique({ where: { name: toolName } });
-    if (!tool)
-        fail(`unknown tool "${toolName}".`);
+        fail(`tool ${detach ? "detach" : "attach"} requires <tool-name|tool-id> <agent-name>.`);
+    }
+    // Tool names are unique per owner, not globally: an ambiguous name fails
+    // with the candidate ids, and an id is accepted in its place.
+    const resolved = await resolveToolRef(prisma, toolName);
+    if (!resolved.ok)
+        fail(resolved.error);
+    const tool = resolved.tool;
     const agent = await prisma.agent.findUnique({ where: { name: agentName } });
     if (!agent)
         fail(`unknown agent "${agentName}".`);
@@ -229,6 +298,14 @@ async function toolAttach(args, detach) {
             (allowedSharedDatastorePrefixes[boundName] ??= []).push(prefix);
         }
     }
+    // Same guard as MCP attach_tool: one agent never holds two tools with the
+    // same name, since the runtime dispatches by name. Operator-only, so unlike
+    // attach_tool this check-then-upsert is not one Serializable transaction
+    // (the runner's load-time duplicate check still catches a race).
+    const clash = await findSameNamedAttachedTool(prisma, agent.id, tool);
+    if (clash) {
+        fail(`agent "${agentName}" already has a different tool named "${tool.name}" attached (${clash.id}); detach it first.`);
+    }
     const patch = ToolCapabilitiesPatchSchema.safeParse({
         allowedSecrets: values["allow-secret"],
         allowedDatastorePrefixes: values["allow-datastore-prefix"],
@@ -238,6 +315,10 @@ async function toolAttach(args, detach) {
     if (!patch.success) {
         fail(`invalid tool capabilities: ${patch.error.issues.map((i) => i.message).join("; ")}`);
     }
+    // The operator is trusted with the database, so it grants these
+    // capabilities in the agent owner's name: the runner honours them only
+    // with the owner's consent stamp (resource-sharing grants spec §3.4.2).
+    // An owner-less agent has no owner to stamp: its capabilities stay inert.
     await prisma.agentTool.upsert({
         where: { agentId_toolId: { agentId: agent.id, toolId: tool.id } },
         create: {
@@ -247,8 +328,10 @@ async function toolAttach(args, detach) {
             allowedDatastorePrefixes: patch.data.allowedDatastorePrefixes ?? [],
             allowedHosts: patch.data.allowedHosts ?? [],
             allowedSharedDatastorePrefixes: patch.data.allowedSharedDatastorePrefixes ?? {},
+            capabilitiesGrantedById: agent.ownerId,
         },
         update: {
+            capabilitiesGrantedById: agent.ownerId,
             ...(patch.data.allowedSecrets !== undefined ? { allowedSecrets: patch.data.allowedSecrets } : {}),
             ...(patch.data.allowedDatastorePrefixes !== undefined
                 ? { allowedDatastorePrefixes: patch.data.allowedDatastorePrefixes }
@@ -273,16 +356,116 @@ async function toolList(args) {
             return;
         }
         for (const a of attached)
-            console.log(`${a.tool.name}  ${a.tool.description}`);
+            console.log(formatToolLine(a.tool));
         return;
     }
-    const tools = await prisma.tool.findMany({ orderBy: { name: "asc" } });
+    const tools = await prisma.tool.findMany({ orderBy: [{ name: "asc" }, { id: "asc" }] });
     if (tools.length === 0) {
         console.log("no tools registered.");
         return;
     }
     for (const t of tools)
-        console.log(`${t.name}  ${t.description}`);
+        console.log(formatToolLine(t));
+}
+/**
+ * The operator may change any tool, public ones included; only a row that
+ * vanished since it was resolved is refused. Thrown rather than fail()ed:
+ * it runs inside the transaction, which must roll back, not exit mid-way.
+ */
+function operatorAuthorize(ref) {
+    return (tool) => {
+        if (!tool)
+            throw new Error(`unknown tool "${ref}".`);
+    };
+}
+/**
+ * `wardby tool update <tool-name|tool-id>` -- the operator's counterpart of
+ * MCP update_tool, and the only way to change a public tool. Same
+ * validation (jsonSchema re-derived from --params) and the same attachment
+ * rule, judged against the tool's owner (core/tool-admin.ts).
+ */
+async function toolUpdate(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            description: { type: "string" },
+            params: { type: "string" },
+            code: { type: "string" },
+        },
+    });
+    const [ref] = positionals;
+    if (!ref)
+        fail("tool update requires <tool-name|tool-id>.");
+    const readFile = (flag, path) => {
+        if (path === undefined)
+            return undefined;
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch (err) {
+            fail(`could not read ${flag} file "${path}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const changes = {
+        description: values.description,
+        paramsZod: readFile("--params", values.params),
+        code: readFile("--code", values.code),
+    };
+    if (!hasToolChanges(changes)) {
+        fail("tool update requires at least one of --description, --params <file>, --code <file>.");
+    }
+    const resolved = await resolveToolRef(prisma, ref);
+    if (!resolved.ok)
+        fail(resolved.error);
+    const prepared = await prepareToolUpdate(changes);
+    if (!prepared.ok)
+        fail(`invalid --params schema: ${prepared.errorMessage}`);
+    try {
+        await updateToolGuarded(prisma, resolved.tool.id, prepared.data, operatorAuthorize(ref));
+    }
+    catch (err) {
+        if (err instanceof ToolAttachedError) {
+            fail(`tool "${ref}" is attached to agents with a different owner: ${formatAttachedAgents(err.agents)}. Detach it from those agents first, or create a new tool.`);
+        }
+        throw err;
+    }
+    console.log(`updated tool ${resolved.tool.id}.`);
+}
+/** `wardby tool delete <tool-name|tool-id> [--detach]` -- MCP delete_tool's rules, public tools included. */
+async function toolDelete(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { detach: { type: "boolean" } },
+    });
+    const [ref] = positionals;
+    if (!ref)
+        fail("tool delete requires <tool-name|tool-id>.");
+    const resolved = await resolveToolRef(prisma, ref);
+    if (!resolved.ok)
+        fail(resolved.error);
+    let detachedFrom;
+    try {
+        detachedFrom = await deleteToolGuarded(prisma, resolved.tool.id, {
+            detach: values.detach ?? false,
+            authorize: operatorAuthorize(ref),
+        });
+    }
+    catch (err) {
+        if (!(err instanceof ToolAttachedError))
+            throw err;
+        if (err.reason === "other_owners") {
+            fail(`tool "${ref}" is attached to agents with a different owner: ${formatAttachedAgents(err.agents)}. Detach it from those agents first (wardby tool detach).`);
+        }
+        if (err.reason === "needs_detach") {
+            fail(`tool "${ref}" is still attached to ${formatAttachedAgents(err.agents)}. Pass --detach to detach it and delete it.`);
+        }
+        fail(`tool "${ref}" is still attached to an agent; nothing was deleted.`);
+    }
+    console.log(detachedFrom.length > 0
+        ? `deleted tool ${resolved.tool.id} (detached from ${detachedFrom.join(", ")}).`
+        : `deleted tool ${resolved.tool.id}.`);
 }
 async function agentSchedule(args) {
     const [name, ...rest] = args;
@@ -347,20 +530,36 @@ async function run(name) {
     if (agent.kind === "coding") {
         fail("Coding agents are MCP-first: use trigger_agent so task input and ownership are recorded safely.");
     }
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
     const llm = buildLlmProvider();
     const engine = buildEngine();
     const secrets = buildSecrets();
     const datastore = buildDatastore(secrets);
     const memory = buildMemory();
     let run;
+    // Ctrl-C (or a SIGTERM) records the run as cancelled rather than leaving a
+    // `running` row behind.
+    let removeSignalHandlers;
     try {
-        run = await runAgent(name, { llm, engine, datastore, secrets, memory }, prisma, (delta) => {
+        run = await runAgent(name, { llm, engine, datastore, secrets, memory, reviewHosts: buildReviewHosts(), issueTrackers: buildIssueTrackers() }, prisma, (delta) => {
             process.stdout.write(delta);
+        }, (created) => {
+            removeSignalHandlers = cancelRunOnSignal(prisma, created.id);
         });
     }
     catch (err) {
         fail(err instanceof Error ? err.message : String(err));
     }
+    finally {
+        removeSignalHandlers?.();
+        modelCatalog.close();
+    }
     process.stdout.write("\n");
     const completedAgent = await prisma.agent.findUnique({ where: { id: run.agentId } });
     const budgetUsd = completedAgent ? Number(completedAgent.budgetUsd) : NaN;
@@ -486,22 +685,35 @@ async function scheduler(args) {
     // Parsed before anything starts, so a malformed CODING_MAX_CONCURRENT or
     // CODING_QUEUE_TIMEOUT_SEC fails fast.
     const concurrency = loadCodingConcurrencyConfig();
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
     const config = loadProviderConfig();
     const llm = buildLlmProvider();
     const engine = buildEngine();
     const secrets = buildSecrets();
     const datastore = buildDatastore(secrets);
     const memory = buildMemory();
-    const nativeExecutor = buildExecutor(config, { llm, engine, datastore, secrets, memory }, prisma);
-    const executor = buildConfiguredExecutor({ native: nativeExecutor, db: prisma, providerConfig: config });
+    const reviewHosts = buildReviewHosts();
+    const issueTrackers = buildIssueTrackers();
+    // One repository-access gate (and cache) for native repo_* calls and coding runs.
+    const repoAccess = createRepoAccessGate({ db: prisma, hosts: reviewHosts });
+    const nativeExecutor = buildExecutor(config, { llm, engine, datastore, secrets, memory, reviewHosts, issueTrackers, repoAccess }, prisma);
+    const executor = buildConfiguredExecutor({ native: nativeExecutor, db: prisma, providerConfig: config, repoAccess });
     await executor.launch?.();
-    const reconciler = startReconciler({ db: prisma, executor });
+    const reconciler = startReconciler({ db: prisma, executor, reviewHosts, issueTrackers });
+    const selfDefects = { db: prisma, issueTrackers };
     const sched = startScheduler({
         executor,
         db: prisma,
         scope,
+        selfDefects,
         onLeaderTick: async () => {
-            await drainCodingQueue({ db: prisma, executor, ...concurrency });
+            await drainCodingQueue({ db: prisma, executor, ...concurrency, selfDefects });
         },
     });
     console.log(`wardby scheduler started (scope "${scope}"). Press Ctrl+C to stop.`);
@@ -512,7 +724,10 @@ async function scheduler(args) {
             reconciler.stop();
             void Promise.resolve(executor.close?.())
                 .catch((err) => cliLog.warn({ err }, "executor close failed during scheduler shutdown"))
-                .finally(resolve);
+                .finally(() => {
+                modelCatalog.close();
+                resolve();
+            });
         };
         process.once("SIGINT", shutdown);
         process.once("SIGTERM", shutdown);
@@ -560,19 +775,46 @@ async function serve(args) {
 }
 async function importCommand(rest) {
     const opts = parseImportArgs(rest);
-    const { report, result } = await runImport({ ...opts, db: prisma, env: process.env });
-    console.log(report);
-    if (result) {
-        for (const w of result.webhookSecrets)
-            console.log(`webhook secret (${w.agentName}): ${w.secret}`);
+    // runImport builds an LLM provider and classifies each agent's model as
+    // routable/unroutable from currentModelCatalog() — without a store
+    // started here first, that falls back to the shipped catalog, so an
+    // admin-disabled model would be (wrongly) imported as routable and a
+    // DB-only custom model would be (wrongly) imported as disabled.
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    try {
+        const { report, result } = await runImport({ ...opts, db: prisma, env: process.env });
+        console.log(report);
+        if (result) {
+            for (const w of result.webhookSecrets)
+                console.log(`webhook secret (${w.agentName}): ${w.secret}`);
+        }
+    }
+    finally {
+        modelCatalog.close();
     }
 }
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     try {
-        if (command === "auth") {
+        if (command === "auth" && rest[0] === "host-account") {
+            // Both auth modes: keyed on Principal, not the self-hosted AuthUser.
+            await hostAccountCommand(rest.slice(1), prisma);
+        }
+        else if (command === "grants") {
+            await grantsCommand(rest, prisma);
+        }
+        else if (command === "auth") {
             await authCommand(rest, prisma, process.env.AUTH_CREDENTIAL_HASH_KEY ?? "");
         }
+        else if (command === "help") {
+            await helpCommand(rest);
+        }
         else if (command === "agent" && rest[0] === "create") {
             await agentCreate(rest.slice(1));
         }
@@ -591,6 +833,12 @@ async function main() {
         else if (command === "tool" && rest[0] === "detach") {
             await toolAttach(rest.slice(1), true);
         }
+        else if (command === "tool" && rest[0] === "update") {
+            await toolUpdate(rest.slice(1));
+        }
+        else if (command === "tool" && rest[0] === "delete") {
+            await toolDelete(rest.slice(1));
+        }
         else if (command === "tool" && rest[0] === "list") {
             await toolList(rest.slice(1));
         }

package/dist/coding/base-commit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The coding workspace has no git metadata, so the worker cannot learn which
+ * commit it is looking at. The executor appends it to the task when it writes
+ * the worker input (after cloning). Never grows a task past the limit.
+ */
+export declare function withBaseCommit(task: string, baseCommit: string): string;

package/dist/coding/base-commit.js

@@ -0,0 +1,12 @@
+import { byteLength, MAX_CODING_TASK_BYTES } from "./protocol.js";
+/**
+ * The coding workspace has no git metadata, so the worker cannot learn which
+ * commit it is looking at. The executor appends it to the task when it writes
+ * the worker input (after cloning). Never grows a task past the limit.
+ */
+export function withBaseCommit(task, baseCommit) {
+    if (!/^[0-9a-f]{40}$/.test(baseCommit))
+        return task;
+    const withLine = `${task}\n\nBase commit: ${baseCommit} (the commit this workspace was checked out at; the workspace has no git metadata).`;
+    return byteLength(withLine) <= MAX_CODING_TASK_BYTES ? withLine : task;
+}

package/dist/coding/collect-exclude.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Paths a coding run's workspace never sends back: dependency and cache folders
+ * (matched by name at any depth) plus per-agent repository-relative paths. The
+ * same set is rendered three ways so the Kubernetes keeper's tar, the Docker
+ * staging prune, and Git staging all agree on what "excluded" means.
+ */
+export declare const BUILTIN_COLLECT_EXCLUDE_NAMES: readonly ["node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache", ".tox", ".vite", ".cache"];
+export declare const MAX_COLLECT_EXCLUDE_PATHS = 64;
+export interface CollectExclusions {
+    names: readonly string[];
+    paths: readonly string[];
+}
+export declare function validateCollectExcludePath(value: string): string;
+export declare function collectExclusions(paths: readonly string[]): CollectExclusions;
+/** For values read back from the database or a job record, which are untrusted shapes. */
+export declare function normalizeCollectExclusions(value: unknown): CollectExclusions;
+export declare function isCollectExcluded(relativePath: string, exclusions: CollectExclusions): boolean;
+/**
+ * GNU tar options for `tar -C <workspace> -cf - .`, whose member names start with
+ * "./". Names are unanchored (they match any path component); paths are anchored
+ * to the archive root. An excluded directory's contents are skipped with it.
+ */
+export declare function tarExcludeArgs(exclusions: CollectExclusions): string[];
+/** Git exclude pathspecs, appended after ":/" when staging. */
+export declare function gitExcludePathspecs(exclusions: CollectExclusions): string[];

package/dist/coding/collect-exclude.js

@@ -0,0 +1,76 @@
+/**
+ * Paths a coding run's workspace never sends back: dependency and cache folders
+ * (matched by name at any depth) plus per-agent repository-relative paths. The
+ * same set is rendered three ways so the Kubernetes keeper's tar, the Docker
+ * staging prune, and Git staging all agree on what "excluded" means.
+ */
+export const BUILTIN_COLLECT_EXCLUDE_NAMES = [
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    ".tox",
+    ".vite",
+    ".cache",
+];
+export const MAX_COLLECT_EXCLUDE_PATHS = 64;
+const MAX_PATH_BYTES = 512;
+const CONTROL = /[\u0000-\u001F\u007F]/;
+const GLOB = /[*?[\]]/;
+export function validateCollectExcludePath(value) {
+    const path = value.trim();
+    const valid = path.length > 0 &&
+        Buffer.byteLength(path, "utf8") <= MAX_PATH_BYTES &&
+        !CONTROL.test(path) &&
+        !GLOB.test(path) &&
+        !path.includes("\\") &&
+        !path.startsWith("/") &&
+        !path.startsWith("./") &&
+        !path.split("/").some((part) => part === "" || part === "." || part === "..");
+    if (!valid)
+        throw new Error("collect_exclude_path_invalid");
+    return path;
+}
+export function collectExclusions(paths) {
+    if (paths.length > MAX_COLLECT_EXCLUDE_PATHS)
+        throw new Error("collect_exclude_path_invalid");
+    return { names: [...BUILTIN_COLLECT_EXCLUDE_NAMES], paths: [...new Set(paths.map(validateCollectExcludePath))] };
+}
+/** For values read back from the database or a job record, which are untrusted shapes. */
+export function normalizeCollectExclusions(value) {
+    if (value === undefined || value === null)
+        return collectExclusions([]);
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+        throw new Error("collect_exclude_invalid");
+    }
+    return collectExclusions(value);
+}
+export function isCollectExcluded(relativePath, exclusions) {
+    const segments = relativePath.split("/");
+    if (segments.some((segment) => exclusions.names.includes(segment)))
+        return true;
+    return exclusions.paths.some((path) => relativePath === path || relativePath.startsWith(`${path}/`));
+}
+/**
+ * GNU tar options for `tar -C <workspace> -cf - .`, whose member names start with
+ * "./". Names are unanchored (they match any path component); paths are anchored
+ * to the archive root. An excluded directory's contents are skipped with it.
+ */
+export function tarExcludeArgs(exclusions) {
+    return [
+        "--no-anchored",
+        ...exclusions.names.map((name) => `--exclude=${name}`),
+        "--anchored",
+        ...exclusions.paths.map((path) => `--exclude=./${path}`),
+    ];
+}
+/** Git exclude pathspecs, appended after ":/" when staging. */
+export function gitExcludePathspecs(exclusions) {
+    return [
+        ...exclusions.names.flatMap((name) => [`:(exclude,glob)**/${name}`, `:(exclude,glob)**/${name}/**`]),
+        ...exclusions.paths.map((path) => `:(exclude,literal)${path}`),
+    ];
+}