@wardby/cli 0.2.1 → 0.3.0

package/dist/coding/profile.js

@@ -1,19 +1,23 @@
-import { isIP } from "node:net";
 import { z } from "zod";
 import { isImmutableDockerImage } from "../providers/jobs/docker-isolation.js";
 import { MAX_CODING_TASK_BYTES, normalizeGitHubRepository, normalizeGitRef } from "./protocol.js";
+import { MAX_COLLECT_EXCLUDE_PATHS, validateCollectExcludePath } from "./collect-exclude.js";
 import { CODING_PROVIDERS } from "./provider.js";
+import { WARDBY_PROTECTED_PATHS, isWellFormedProtectedPath, protectsSomePath } from "./protected-paths.js";
+import { parseAllowlist, resolvePolicy } from "./registry/allowlist.js";
+import { REGISTRY_ADAPTERS } from "./registry/adapters.js";
+import { AllowedServiceNamesSchema } from "./services/catalog.js";
 export const MIN_CODING_TIMEOUT_SEC = 60;
 export const MAX_CODING_TIMEOUT_SEC = 7200;
-export const MAX_ALLOWED_EGRESS_HOSTS = 64;
 export const MAX_PROTECTED_PATHS = 128;
 export const DEFAULT_PROTECTED_PATHS = [
     ".github/workflows/**",
     ".github/CODEOWNERS",
     "CODEOWNERS",
     "docs/CODEOWNERS",
+    // Enforced for every run anyway (providers/vcs/git.ts protectedPathMatcher); listed so new agents show it.
+    ...WARDBY_PROTECTED_PATHS,
 ];
-const MAX_HOST_BYTES = 253;
 const MAX_PROTECTED_PATH_BYTES = 512;
 const INVALID_MULTILINE_CONTROL = /[\u0000\u000B\u000C\u000E-\u001F\u007F]/;
 const INVALID_SINGLE_LINE_CONTROL = /[\u0000-\u001F\u007F]/;
@@ -50,27 +54,21 @@ const defaultTaskSchema = z
     .refine((value) => !INVALID_MULTILINE_CONTROL.test(value), "must not contain control characters")
     .refine((value) => value.trim().length > 0, "must not be blank")
     .nullable();
-const egressHostSchema = z
-    .string()
-    .transform((value) => value.trim().toLowerCase())
-    .refine((value) => value.length > 0 && byteLength(value) <= MAX_HOST_BYTES, "must be a bounded hostname")
-    .refine((value) => !INVALID_SINGLE_LINE_CONTROL.test(value), "must not contain control characters")
-    .refine((value) => isIP(value) === 0, "IP addresses and CIDRs are not allowed")
-    .refine((value) => !/^\d+(?:\.\d+){3}$/.test(value), "IP-like hostnames are not allowed")
-    .refine((value) => !value.includes("://") &&
-    !value.includes("/") &&
-    !value.includes("@") &&
-    !value.includes(":") &&
-    !value.includes("*"), "must be an exact hostname")
-    .refine((value) => value !== "localhost" && value.includes("."), "must be a fully qualified hostname")
-    .refine((value) => value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)), "must be a valid ASCII hostname");
 const protectedPathSchema = z
     .string()
     .transform((value) => value.trim())
     .refine((value) => value.length > 0 && byteLength(value) <= MAX_PROTECTED_PATH_BYTES, "must be a bounded path")
     .refine((value) => !INVALID_SINGLE_LINE_CONTROL.test(value), "must not contain control characters")
-    .refine((value) => !value.startsWith("/") && !value.startsWith("./") && !value.includes("\\"), "must be a repository-relative POSIX path")
-    .refine((value) => !value.split("/").some((part) => part === "" || part === "." || part === ".."), "must not contain empty or traversal components");
+    .refine(isWellFormedProtectedPath, "must be a repository-relative POSIX path without empty or traversal components, or ! and a literal file path (no wildcards) for an exception");
+const collectExcludePathSchema = z.string().transform((value, ctx) => {
+    try {
+        return validateCollectExcludePath(value);
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "must be a repository-relative path without wildcards" });
+        return z.NEVER;
+    }
+});
 const KNOWN_TOOLCHAINS = ["node", "node-python"];
 const toolchainSchema = z.enum(KNOWN_TOOLCHAINS);
 const toolchainVersionSchema = z.string().trim().min(1).max(32).nullable();
@@ -82,6 +80,30 @@ const workerImageRefSchema = z
     .refine(isImmutableDockerImage, "must be an immutable repository digest")
     .nullable();
 const workspaceDiskMbSchema = z.number().int().min(64).max(32_768).nullable();
+const packageAllowlistSchema = z
+    .record(z.string(), z.array(z.string().min(1).max(256)).max(256))
+    .superRefine((value, ctx) => {
+    try {
+        parseAllowlist(value, REGISTRY_ADAPTERS);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: error instanceof Error ? error.message : "invalid allowlist",
+        });
+    }
+});
+const packagePolicySchema = z
+    .object({ minReleaseAgeDays: z.number().int().min(0).max(30).optional() })
+    .strict()
+    .superRefine((value, ctx) => {
+    try {
+        resolvePolicy(value);
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "invalid package policy" });
+    }
+});
 const codingProfileFields = {
     provider: z.enum(CODING_PROVIDERS),
     repository: repositorySchema,
@@ -93,15 +115,20 @@ const codingProfileFields = {
     toolchainVersion: toolchainVersionSchema,
     workerImageRef: workerImageRefSchema,
     workspaceDiskMb: workspaceDiskMbSchema,
-    allowedEgress: z
-        .array(egressHostSchema)
-        .max(MAX_ALLOWED_EGRESS_HOSTS)
-        .transform((hosts) => [...new Set(hosts)]),
     protectedPaths: z
         .array(protectedPathSchema)
         .min(1)
         .max(MAX_PROTECTED_PATHS)
+        .refine(protectsSomePath, "must protect at least one path; entries starting with ! are only exceptions")
+        .transform((paths) => [...new Set(paths)]),
+    collectExclude: z
+        .array(collectExcludePathSchema)
+        .max(MAX_COLLECT_EXCLUDE_PATHS)
         .transform((paths) => [...new Set(paths)]),
+    packageAllowlist: packageAllowlistSchema,
+    packagePolicy: packagePolicySchema,
+    /** Coding-run services this agent's runs may start: catalog names, any version (docs/coding-services.md). */
+    services: AllowedServiceNamesSchema,
 };
 export const CodingProfileSchema = z
     .object({
@@ -111,12 +138,15 @@ export const CodingProfileSchema = z
     defaultTask: codingProfileFields.defaultTask.default(null),
     allowWebhookTaskOverride: codingProfileFields.allowWebhookTaskOverride.default(false),
     timeoutSec: codingProfileFields.timeoutSec.default(1800),
-    allowedEgress: codingProfileFields.allowedEgress.default([]),
     protectedPaths: codingProfileFields.protectedPaths.default([...DEFAULT_PROTECTED_PATHS]),
+    collectExclude: codingProfileFields.collectExclude.default([]),
     toolchain: codingProfileFields.toolchain.default("node"),
     toolchainVersion: codingProfileFields.toolchainVersion.default(null),
     workerImageRef: codingProfileFields.workerImageRef.default(null),
     workspaceDiskMb: codingProfileFields.workspaceDiskMb.default(null),
+    packageAllowlist: codingProfileFields.packageAllowlist.default({}),
+    packagePolicy: codingProfileFields.packagePolicy.default({}),
+    services: codingProfileFields.services.default([]),
 })
     .strict();
 export const CodingProfilePatchSchema = z
@@ -127,11 +157,14 @@ export const CodingProfilePatchSchema = z
     defaultTask: codingProfileFields.defaultTask.optional(),
     allowWebhookTaskOverride: codingProfileFields.allowWebhookTaskOverride.optional(),
     timeoutSec: codingProfileFields.timeoutSec.optional(),
-    allowedEgress: codingProfileFields.allowedEgress.optional(),
     protectedPaths: codingProfileFields.protectedPaths.optional(),
+    collectExclude: codingProfileFields.collectExclude.optional(),
     toolchain: codingProfileFields.toolchain.optional(),
     toolchainVersion: codingProfileFields.toolchainVersion.optional(),
     workerImageRef: codingProfileFields.workerImageRef.optional(),
     workspaceDiskMb: codingProfileFields.workspaceDiskMb.optional(),
+    packageAllowlist: codingProfileFields.packageAllowlist.optional(),
+    packagePolicy: codingProfileFields.packagePolicy.optional(),
+    services: codingProfileFields.services.optional(),
 })
     .strict();

package/dist/coding/protected-path-wording.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a host (a builder continuation comment, a mention status comment) is
+ * told when a coding run's changes touched a path this agent may not edit
+ * (protectedPathMatcher in src/providers/vcs/git.ts). Public repositories
+ * read these, so the path -- taken from the run's own diff -- is treated as
+ * untrusted text: it never carries a backtick, a control character, or more
+ * than MAX_PATH_CHARS.
+ */
+/** CodingRun.failureCategory for a run whose collected changes touched a protected path. */
+export declare const PROTECTED_PATH_CATEGORY = "protected_path";
+/** The path a `vcs_protected_path:<path>` error names, or null for any other error. */
+export declare function protectedPathFromError(error: unknown): string | null;
+/**
+ * The host sentence for a run stopped because its changes touched a
+ * protected path. Named the file when `path` sanitises to something usable;
+ * otherwise falls back to a sentence that doesn't try to name it.
+ */
+export declare function protectedPathSentence(path: string | null | undefined): string;
+/**
+ * The fixed line for a mention status comment naming a failed protected_path
+ * sub-run (host-status.ts). That comment reads children from the database,
+ * which has no path -- only the category -- so this line never names a file.
+ */
+export declare const PROTECTED_PATH_HOST_LINE = "A sub-run could not open its changes: it changed a file its agent may not edit, so none of its changes were kept.";

package/dist/coding/protected-path-wording.js

@@ -0,0 +1,55 @@
+/**
+ * What a host (a builder continuation comment, a mention status comment) is
+ * told when a coding run's changes touched a path this agent may not edit
+ * (protectedPathMatcher in src/providers/vcs/git.ts). Public repositories
+ * read these, so the path -- taken from the run's own diff -- is treated as
+ * untrusted text: it never carries a backtick, a control character, or more
+ * than MAX_PATH_CHARS.
+ */
+/** CodingRun.failureCategory for a run whose collected changes touched a protected path. */
+export const PROTECTED_PATH_CATEGORY = "protected_path";
+/** git.ts's finalizeChanges throws this when the collected diff touches a protected path. */
+const PROTECTED_PATH_ERROR_PREFIX = "vcs_protected_path:";
+/** The path a `vcs_protected_path:<path>` error names, or null for any other error. */
+export function protectedPathFromError(error) {
+    const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    if (!message.startsWith(PROTECTED_PATH_ERROR_PREFIX))
+        return null;
+    const path = message.slice(PROTECTED_PATH_ERROR_PREFIX.length);
+    return path.length > 0 ? path : null;
+}
+const MAX_PATH_CHARS = 200;
+/**
+ * A single-line, backtick-free rendering of a repository path safe to drop
+ * into one Markdown code span: control characters and backticks (which would
+ * otherwise close the span early) are neutralised, runs of whitespace
+ * collapse to one line, and the result is capped with an ellipsis. Null when
+ * nothing usable is left.
+ */
+function sanitizePath(path) {
+    // eslint-disable-next-line no-control-regex -- deliberately stripping C0/DEL control characters.
+    const withoutControls = path.replace(/[\u0000-\u001f\u007f]+/g, " ");
+    const oneLine = withoutControls.replace(/\s+/g, " ").trim();
+    const withoutBackticks = oneLine.replace(/`/g, "'");
+    if (withoutBackticks.length === 0)
+        return null;
+    return withoutBackticks.length > MAX_PATH_CHARS ? `${withoutBackticks.slice(0, MAX_PATH_CHARS)}…` : withoutBackticks;
+}
+/**
+ * The host sentence for a run stopped because its changes touched a
+ * protected path. Named the file when `path` sanitises to something usable;
+ * otherwise falls back to a sentence that doesn't try to name it.
+ */
+export function protectedPathSentence(path) {
+    const safe = path ? sanitizePath(path) : null;
+    const named = safe
+        ? `its changes include \`${safe}\`, which this agent may not edit`
+        : "its changes include a file this agent may not edit";
+    return `${named}, so none of its changes were kept. Ask again without changing that file, or have the repository owner make that change.`;
+}
+/**
+ * The fixed line for a mention status comment naming a failed protected_path
+ * sub-run (host-status.ts). That comment reads children from the database,
+ * which has no path -- only the category -- so this line never names a file.
+ */
+export const PROTECTED_PATH_HOST_LINE = "A sub-run could not open its changes: it changed a file its agent may not edit, so none of its changes were kept.";

package/dist/coding/protected-paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Protected for every coding run, whatever an agent's own protectedPaths say
+ * (docs/coding-services.md): wardby's own configuration under .wardby/, except
+ * the service declaration, which any builder may propose in its pull request
+ * (it takes effect only after a person merges it, since dispatch reads it from
+ * the base branch). Part of DEFAULT_PROTECTED_PATHS so new agents show it, and
+ * always added by protectedPathMatcher (providers/vcs/git.ts) so agents created
+ * before it existed get it too. The matcher applies it ahead of the agent's own
+ * list: the declaration is never protected, and nothing else under .wardby/ can
+ * be unprotected by an agent's exceptions.
+ */
+export declare const WARDBY_PROTECTED_PATHS: readonly [".wardby/**", "!.wardby/services.yaml"];
+/**
+ * A leading "!" makes a protectedPaths entry an exception (providers/vcs/git.ts
+ * protectedPathMatcher): one literal file path carved out of the agent's own
+ * patterns. Exceptions take no wildcards, so "!**" or "!.github/**" cannot
+ * switch a whole protected tree off.
+ */
+export declare const PROTECTED_PATH_EXCEPTION = "!";
+export declare function isProtectedPathException(path: string): boolean;
+/** The glob of a protectedPaths entry: the entry itself, or what follows an exception's leading "!". */
+export declare function protectedPathBody(path: string): string;
+/**
+ * Whether a trimmed protectedPaths entry has a valid shape: a repository-relative
+ * POSIX glob with no empty or traversal components, or, behind one leading "!",
+ * such a path with no glob metacharacters. Length and control-character bounds
+ * are the caller's.
+ */
+export declare function isWellFormedProtectedPath(path: string): boolean;
+/** Exceptions only carve paths out; a list of nothing but exceptions protects nothing. */
+export declare function protectsSomePath(paths: readonly string[]): boolean;

package/dist/coding/protected-paths.js

@@ -0,0 +1,48 @@
+/**
+ * Protected for every coding run, whatever an agent's own protectedPaths say
+ * (docs/coding-services.md): wardby's own configuration under .wardby/, except
+ * the service declaration, which any builder may propose in its pull request
+ * (it takes effect only after a person merges it, since dispatch reads it from
+ * the base branch). Part of DEFAULT_PROTECTED_PATHS so new agents show it, and
+ * always added by protectedPathMatcher (providers/vcs/git.ts) so agents created
+ * before it existed get it too. The matcher applies it ahead of the agent's own
+ * list: the declaration is never protected, and nothing else under .wardby/ can
+ * be unprotected by an agent's exceptions.
+ */
+export const WARDBY_PROTECTED_PATHS = [".wardby/**", "!.wardby/services.yaml"];
+/**
+ * A leading "!" makes a protectedPaths entry an exception (providers/vcs/git.ts
+ * protectedPathMatcher): one literal file path carved out of the agent's own
+ * patterns. Exceptions take no wildcards, so "!**" or "!.github/**" cannot
+ * switch a whole protected tree off.
+ */
+export const PROTECTED_PATH_EXCEPTION = "!";
+export function isProtectedPathException(path) {
+    return path.startsWith(PROTECTED_PATH_EXCEPTION);
+}
+/** The glob of a protectedPaths entry: the entry itself, or what follows an exception's leading "!". */
+export function protectedPathBody(path) {
+    return isProtectedPathException(path) ? path.slice(PROTECTED_PATH_EXCEPTION.length) : path;
+}
+/** Glob metacharacters an exception may not contain: it names one literal file. */
+const EXCEPTION_GLOB_CHARACTERS = /[*?[\]{}]/;
+/**
+ * Whether a trimmed protectedPaths entry has a valid shape: a repository-relative
+ * POSIX glob with no empty or traversal components, or, behind one leading "!",
+ * such a path with no glob metacharacters. Length and control-character bounds
+ * are the caller's.
+ */
+export function isWellFormedProtectedPath(path) {
+    const body = protectedPathBody(path);
+    return (body.length > 0 &&
+        !isProtectedPathException(body) &&
+        !(isProtectedPathException(path) && EXCEPTION_GLOB_CHARACTERS.test(body)) &&
+        !body.startsWith("/") &&
+        !body.startsWith("./") &&
+        !body.includes("\\") &&
+        !body.split("/").some((part) => part === "" || part === "." || part === ".."));
+}
+/** Exceptions only carve paths out; a list of nothing but exceptions protects nothing. */
+export function protectsSomePath(paths) {
+    return paths.some((path) => !isProtectedPathException(path));
+}

package/dist/coding/protocol.d.ts

@@ -6,6 +6,18 @@ export declare const MAX_CODING_SUMMARY_BYTES: number;
 export declare const MAX_CODING_TESTS = 64;
 export declare const MAX_CODING_TEST_COMMAND_BYTES: number;
 export declare const MAX_TAG_BYTES = 32;
+/**
+ * Coding-run services (docs/coding-services.md): the catalog name and version
+ * grammar, shared by the repository's .wardby/services.yaml, the catalog, and
+ * the worker input.
+ */
+export declare const CODING_SERVICE_NAME: RegExp;
+export declare const CODING_SERVICE_VERSION: RegExp;
+export declare const MAX_CODING_SERVICES = 5;
+/** A variable a service hands the agent's shells (DATABASE_URL, PGHOST, REDIS_URL, ...). */
+export declare const CODING_SERVICE_ENV_NAME: RegExp;
+export declare const MAX_CODING_SERVICE_ENV = 16;
+export declare const MAX_CODING_SERVICE_ENV_VALUE_BYTES = 1024;
 /**
  * A worker's output-schema failure, reduced to where and how it failed, never
  * what the model wrote: `<path>:<zod issue code>`, where the path is dot-joined
@@ -14,6 +26,11 @@ export declare const MAX_TAG_BYTES = 32;
  */
 export declare const MAX_CODING_OUTPUT_ISSUES = 8;
 export declare const SAFE_CODING_OUTPUT_ISSUE: RegExp;
+export declare const INVALID_SINGLE_LINE_CONTROL: RegExp;
+export declare function byteLength(value: string): number;
+export declare function isReservedServiceEnvName(name: string): boolean;
+/** The variables one service hands the agent's shells: upper-case names wardby does not reserve. */
+export declare const CodingServiceTestEnvSchema: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>;
 export declare function normalizeGitHubRepository(value: string): string;
 export declare function normalizeGitRef(value: string): string;
 export declare const CodingBaseRefSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
@@ -21,11 +38,12 @@ export declare const CodingTaskOverrideSchema: z.ZodEffects<z.ZodEffects<z.ZodEf
 /**
  * A coding worker receives only its task text, so a coding agent's own
  * instructions (its systemPrompt) travel inside that text, ahead of the
- * request. Blank instructions leave the task unchanged. The combination must
- * still fit MAX_CODING_TASK_BYTES; exceeding it is an error naming both parts
- * rather than a silent truncation of either.
+ * request, followed by any note wardby generates for the run (the services it
+ * started: src/coding/services/note.ts). Blank instructions and no note leave
+ * the task unchanged. The combination must still fit MAX_CODING_TASK_BYTES;
+ * exceeding it is an error naming both parts rather than a silent truncation.
  */
-export declare function composeCodingTask(instructions: string | null | undefined, task: string): string;
+export declare function composeCodingTask(instructions: string | null | undefined, task: string, note?: string): string;
 /**
  * The tag only labels a pull request title, so a model's malformed tag must not
  * sink an otherwise finished run. A tag that already passes is kept as-is; any
@@ -35,6 +53,8 @@ export declare function composeCodingTask(instructions: string | null | undefine
  * re-validates whatever survives.
  */
 export declare function normalizeCodingTag(value: unknown): string | null | undefined;
+/** Longest line a debug-traced worker writes to its log (src/coding-worker/debug-trace.ts). */
+export declare const MAX_DEBUG_TRACE_LINE_BYTES: number;
 export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     runId: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
@@ -60,6 +80,33 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     }, {
         runId: string;
     }>>;
+    /**
+     * Admin-requested debug trace (CodingAgentProfile.debugTraceUntil): the
+     * worker writes its full stream trace to its own log. Absent means off;
+     * the control plane writes the key only when true, so an input for an
+     * untraced run is unchanged for workers that predate it.
+     */
+    debugTrace: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Coding-run services started next to this run (docs/coding-services.md):
+     * each one's catalog name and version, and the variables the agent's shells
+     * receive. Absent means none; the control plane writes the key only when a
+     * run has services, so every other input is unchanged for workers that
+     * predate it.
+     */
+    services: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        testEnv: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>, Record<string, string>, Record<string, string>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }, {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }>, "many">>;
 }, "strict", z.ZodTypeAny, {
     repository: string;
     schemaVersion: 1;
@@ -73,6 +120,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }, {
     repository: string;
     schemaVersion: 1;
@@ -86,6 +139,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }>, {
     repository: string;
     schemaVersion: 1;
@@ -99,6 +158,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }, {
     repository: string;
     schemaVersion: 1;
@@ -112,6 +177,12 @@ export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     continuationOf?: {
         runId: string;
     } | undefined;
+    debugTrace?: boolean | undefined;
+    services?: {
+        name: string;
+        version: string;
+        testEnv: Record<string, string>;
+    }[] | undefined;
 }>;
 export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;

package/dist/coding/protocol.js

@@ -6,6 +6,18 @@ export const MAX_CODING_SUMMARY_BYTES = 8 * 1024;
 export const MAX_CODING_TESTS = 64;
 export const MAX_CODING_TEST_COMMAND_BYTES = 2 * 1024;
 export const MAX_TAG_BYTES = 32;
+/**
+ * Coding-run services (docs/coding-services.md): the catalog name and version
+ * grammar, shared by the repository's .wardby/services.yaml, the catalog, and
+ * the worker input.
+ */
+export const CODING_SERVICE_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+export const CODING_SERVICE_VERSION = /^[0-9A-Za-z][0-9A-Za-z._-]{0,19}$/;
+export const MAX_CODING_SERVICES = 5;
+/** A variable a service hands the agent's shells (DATABASE_URL, PGHOST, REDIS_URL, ...). */
+export const CODING_SERVICE_ENV_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+export const MAX_CODING_SERVICE_ENV = 16;
+export const MAX_CODING_SERVICE_ENV_VALUE_BYTES = 1024;
 /**
  * A worker's output-schema failure, reduced to where and how it failed, never
  * what the model wrote: `<path>:<zod issue code>`, where the path is dot-joined
@@ -21,8 +33,8 @@ const MAX_RUN_ID_BYTES = 128;
 const MAX_COST_USD = 1_000_000;
 const MAX_JSON_NESTING_DEPTH = 64;
 const INVALID_MULTILINE_CONTROL = /[\u0000\u000B\u000C\u000E-\u001F\u007F]/;
-const INVALID_SINGLE_LINE_CONTROL = /[\u0000-\u001F\u007F]/;
-function byteLength(value) {
+export const INVALID_SINGLE_LINE_CONTROL = /[\u0000-\u001F\u007F]/;
+export function byteLength(value) {
     return Buffer.byteLength(value, "utf8");
 }
 function boundedText(maxBytes, singleLine = false) {
@@ -33,6 +45,72 @@ function boundedText(maxBytes, singleLine = false) {
         .refine((value) => !invalidControl.test(value), "must not contain control characters")
         .refine((value) => value.trim().length > 0, "must not be blank");
 }
+/**
+ * Names the worker owns: its shell basics, anything that would redirect a
+ * process's loader or network proxy, and the registry proxy's and Wardby's own
+ * settings. No service may set one, whatever its catalog entry says.
+ */
+const RESERVED_SERVICE_ENV_NAMES = new Set([
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "PATH",
+    "SHELL",
+    "TMPDIR",
+    "USER",
+    "LD_PRELOAD",
+    "LD_LIBRARY_PATH",
+    "NODE_OPTIONS",
+    "NODE_PATH",
+    "PYTHONPATH",
+    "PYTHONHOME",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "ALL_PROXY",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+]);
+const RESERVED_SERVICE_ENV_PREFIXES = [
+    "WARDBY_",
+    "CODEX_",
+    "OPENAI_",
+    "ANTHROPIC_",
+    "PIP_",
+    "NPM_CONFIG_",
+    "UV_",
+    "GIT_",
+];
+export function isReservedServiceEnvName(name) {
+    return (RESERVED_SERVICE_ENV_NAMES.has(name) || RESERVED_SERVICE_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)));
+}
+const serviceEnvValueSchema = z
+    .string()
+    .refine((value) => byteLength(value) <= MAX_CODING_SERVICE_ENV_VALUE_BYTES, `must be at most ${MAX_CODING_SERVICE_ENV_VALUE_BYTES} UTF-8 bytes`)
+    .refine((value) => !INVALID_SINGLE_LINE_CONTROL.test(value), "must not contain control characters");
+/** The variables one service hands the agent's shells: upper-case names wardby does not reserve. */
+export const CodingServiceTestEnvSchema = z.record(z.string(), serviceEnvValueSchema).superRefine((env, ctx) => {
+    const names = Object.keys(env);
+    if (names.length > MAX_CODING_SERVICE_ENV) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `must have at most ${MAX_CODING_SERVICE_ENV} variables` });
+    }
+    for (const name of names) {
+        if (!CODING_SERVICE_ENV_NAME.test(name) || isReservedServiceEnvName(name)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [name],
+                message: "must be an upper-case variable name wardby does not reserve",
+            });
+        }
+    }
+});
+const workerServiceSchema = z
+    .object({
+    name: z.string().regex(CODING_SERVICE_NAME),
+    version: z.string().regex(CODING_SERVICE_VERSION),
+    testEnv: CodingServiceTestEnvSchema,
+})
+    .strict();
 function repositoryParts(value) {
     if (byteLength(value) > MAX_REPOSITORY_INPUT_BYTES || INVALID_SINGLE_LINE_CONTROL.test(value)) {
         throw new Error("invalid GitHub repository");
@@ -119,12 +197,13 @@ export const CodingTaskOverrideSchema = boundedText(MAX_CODING_TASK_BYTES);
 /**
  * A coding worker receives only its task text, so a coding agent's own
  * instructions (its systemPrompt) travel inside that text, ahead of the
- * request. Blank instructions leave the task unchanged. The combination must
- * still fit MAX_CODING_TASK_BYTES; exceeding it is an error naming both parts
- * rather than a silent truncation of either.
+ * request, followed by any note wardby generates for the run (the services it
+ * started: src/coding/services/note.ts). Blank instructions and no note leave
+ * the task unchanged. The combination must still fit MAX_CODING_TASK_BYTES;
+ * exceeding it is an error naming both parts rather than a silent truncation.
  */
-export function composeCodingTask(instructions, task) {
-    const standing = instructions?.trim();
+export function composeCodingTask(instructions, task, note) {
+    const standing = [instructions?.trim(), note?.trim()].filter((part) => Boolean(part)).join("\n\n");
     if (!standing)
         return task;
     const composed = `Standing instructions for this coding agent:\n${standing}\n\nRequest:\n${task}`;
@@ -186,6 +265,8 @@ const testResultSchema = z
     outcome: z.enum(["passed", "failed", "skipped"]),
 })
     .strict();
+/** Longest line a debug-traced worker writes to its log (src/coding-worker/debug-trace.ts). */
+export const MAX_DEBUG_TRACE_LINE_BYTES = 16 * 1024;
 export const CodingTaskInputSchema = z
     .object({
     schemaVersion: z.literal(CODING_PROTOCOL_VERSION),
@@ -206,6 +287,21 @@ export const CodingTaskInputSchema = z
      * only enforces that headRef is internally consistent with it.
      */
     continuationOf: z.object({ runId: runIdSchema }).strict().optional(),
+    /**
+     * Admin-requested debug trace (CodingAgentProfile.debugTraceUntil): the
+     * worker writes its full stream trace to its own log. Absent means off;
+     * the control plane writes the key only when true, so an input for an
+     * untraced run is unchanged for workers that predate it.
+     */
+    debugTrace: z.boolean().optional(),
+    /**
+     * Coding-run services started next to this run (docs/coding-services.md):
+     * each one's catalog name and version, and the variables the agent's shells
+     * receive. Absent means none; the control plane writes the key only when a
+     * run has services, so every other input is unchanged for workers that
+     * predate it.
+     */
+    services: z.array(workerServiceSchema).min(1).max(MAX_CODING_SERVICES).optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -217,6 +313,10 @@ export const CodingTaskInputSchema = z
             message: "must match wardby/run-<runId> (or wardby/run-<continuationOf.runId>)",
         });
     }
+    const names = (value.services ?? []).map((service) => service.name);
+    if (new Set(names).size !== names.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["services"], message: "must name each service once" });
+    }
 });
 export const CodingAgentOutputSchema = z
     .object({

package/dist/coding/registry/adapters.d.ts

@@ -0,0 +1,2 @@
+import type { EcosystemId, RegistryAdapter } from "./types.js";
+export declare const REGISTRY_ADAPTERS: ReadonlyMap<EcosystemId, RegistryAdapter>;

package/dist/coding/registry/adapters.js

@@ -0,0 +1,9 @@
+/**
+ * The registry adapter map: every ecosystem the coding package registry
+ * proxies, keyed by its EcosystemId. Adding a new ecosystem means adding it
+ * here (and to the allowlist/profile validation that reads this map) --
+ * nothing else in the registry core hardcodes "npm" or "pypi".
+ */
+import { npmAdapter } from "./npm.js";
+import { pypiAdapter } from "./pypi.js";
+export const REGISTRY_ADAPTERS = new Map([npmAdapter, pypiAdapter].map((adapter) => [adapter.id, adapter]));

package/dist/coding/registry/allowlist.d.ts

@@ -0,0 +1,9 @@
+import type { AllowlistEntry, RegistryAdapter } from "./types.js";
+export type PackageAllowlist = Readonly<Record<string, readonly string[]>>;
+export interface PackagePolicy {
+    minReleaseAgeDays: number;
+}
+export declare const DEFAULT_MIN_RELEASE_AGE_DAYS = 3;
+export declare function resolvePolicy(value: unknown): PackagePolicy;
+export declare function parseAllowlist(allowlist: PackageAllowlist, adapters: ReadonlyMap<string, RegistryAdapter>): Map<string, AllowlistEntry[]>;
+export declare function matchRoot(entries: readonly AllowlistEntry[], normalizedName: string): AllowlistEntry | undefined;