@wardby/cli 0.6.0 → 0.8.0

package/dist/core/dispatch.js

@@ -1,5 +1,7 @@
-import { CODING_PROTOCOL_VERSION, CodingTaskInputSchema, normalizeGitHubRepository, normalizeGitRef, publicCodingRunResult, composeCodingTask, } from "../coding/protocol.js";
+import { normalizeHostedRepository } from "../coding/code-host.js";
+import { CODING_PROTOCOL_VERSION, CodingTaskInputSchema, normalizeGitRef, publicCodingRunResult, composeCodingTask, } from "../coding/protocol.js";
 import { assertCodingProvider, assertCodingProviderModel } from "../coding/provider.js";
+import { isPackageAuditActive } from "../coding/registry/audit-mode.js";
 import { ModelUnavailableError, entryOf } from "../providers/llm/catalog-types.js";
 import { parseAllowedServiceNames, workerServices } from "../coding/services/catalog.js";
 import { MAX_SERVICE_DECLARATION_BYTES, ServiceDeclarationError, parseServiceDeclaration, } from "../coding/services/declaration.js";
@@ -7,11 +9,12 @@ import { servicesInstructionNote } from "../coding/services/note.js";
 import { resolveRunServices } from "../coding/services/resolve.js";
 import { DECLARATION_UNAVAILABLE_SENTENCE, LAUNCHER_UNSUPPORTED_SENTENCE, invalidDeclarationSentence, serviceRefusal, } from "../coding/services/wording.js";
 import { attributeRun } from "./attribution.js";
-import { effectiveBudgetForRun, MIN_RESERVATION_USD } from "./budget-groups.js";
-import { DEFAULT_KNOWLEDGE_BUNDLE_PATH } from "../knowledge/concept.js";
+import { effectiveBudgetForRun, MIN_RESERVATION_USD, } from "./budget-groups.js";
+import { KNOWLEDGE_CONFIG_MAX_BYTES, KNOWLEDGE_CONFIG_PATH, resolveKnowledgeLocation } from "../knowledge/location.js";
 import { KNOWLEDGE_INDEX_READ_MAX_BYTES, knowledgeSection } from "../knowledge/note.js";
 import { logger } from "./logger.js";
 import { CodingModelProviderMismatchError, resolveCodingEntry } from "./run-pricing.js";
+import { resolveCodingRepository, } from "./coding-repository.js";
 import { CONTENDED_TX_MAX_WAIT_MS } from "./timing.js";
 import { fileSelfDefectForRun } from "./self-defects.js";
 const dispatchLog = logger.child({ module: "dispatch" });
@@ -107,21 +110,45 @@ export function budgetExhaustedError(constraint) {
  * agents to groups is not blocked. It serializes grouped coding dispatches
  * across all groups; each holds it only for one short transaction.
  */
-const GROUP_DISPATCH_LOCK_SQL = 'LOCK TABLE "BudgetGroup" IN SHARE ROW EXCLUSIVE MODE';
+export const GROUP_DISPATCH_LOCK_SQL = 'LOCK TABLE "BudgetGroup" IN SHARE ROW EXCLUSIVE MODE';
+/** Rounded down to CodingRun's 6 decimal places. */
+function floorToMicroUsd(usd) {
+    return Math.floor(usd / MIN_RESERVATION_USD) * MIN_RESERVATION_USD;
+}
 /**
- * A coding run's budget reservation: the requested ceiling (override or the
+ * A coding run's budget reservation: the requested base (override or the
  * agent's budgetUsd) tightened by its budget group and run tree, where every
- * live in-flight run's unspent hold already counts as spent. Rounded down to
- * CodingRun.budgetReservedUsd's 6 decimal places; less than that is refused.
+ * live in-flight run's unspent hold already counts as spent. Only the base is
+ * reserved (CodingRun.budgetReservedUsd, and budgetBaseUsd beside it). The
+ * agent's allowedOverrunPercent raises the requested base to the run's limit
+ * (CodingRun.budgetLimitUsd), which is never reserved: the run may spend past
+ * its base only through top-ups its group and run tree have room for when it
+ * needs them (budget-topup.ts). Rounded down to 6 decimal places; a base less
+ * than that is refused.
  */
 async function reserveCodingBudget(tx, agent, now, options) {
+    const overrunPercent = agent.allowedOverrunPercent;
     const effective = await effectiveBudgetForRun(tx, agent, now, options.parentRunId);
     const requested = options.budgetUsdOverride ?? Number(agent.budgetUsd);
-    const budgetUsd = Math.floor(Math.min(requested, effective.effectiveBudgetUsd) / MIN_RESERVATION_USD) * MIN_RESERVATION_USD;
-    if (budgetUsd < MIN_RESERVATION_USD && effective.exhaustedBy) {
-        return { budgetUsd: 0, refusal: budgetExhaustedError(effective.exhaustedBy) };
+    const baseBudgetUsd = floorToMicroUsd(Math.min(requested, effective.effectiveBudgetUsd));
+    if (baseBudgetUsd < MIN_RESERVATION_USD && effective.exhaustedBy) {
+        return {
+            budgetUsd: 0,
+            baseBudgetUsd: 0,
+            limitUsd: null,
+            refusal: budgetExhaustedError(effective.exhaustedBy),
+            ...(effective.exhaustedDetail
+                ? { refusalDetail: { limit: effective.exhaustedBy, detail: effective.exhaustedDetail } }
+                : {}),
+        };
     }
-    return { budgetUsd };
+    const limitUsd = overrunPercent > 0 ? floorToMicroUsd((requested * (100 + overrunPercent)) / 100) : null;
+    return {
+        budgetUsd: baseBudgetUsd,
+        baseBudgetUsd,
+        limitUsd: limitUsd !== null && limitUsd > baseBudgetUsd ? limitUsd : null,
+        ...(effective.limitedBy ? { limitedBy: effective.limitedBy } : {}),
+    };
 }
 /**
  * Attempts for the persist transaction, and the jittered backoff between
@@ -180,7 +207,7 @@ export async function checkContinuation(reader, runId, repository, dispatchingOw
         : candidate;
     if (!root)
         return { ok: false, reason: "unknown_run" };
-    if (normalizeGitHubRepository(root.repository) !== normalizeGitHubRepository(repository)) {
+    if (normalizeHostedRepository(root.repository) !== normalizeHostedRepository(repository)) {
         return { ok: false, reason: "other_repository" };
     }
     const rootResult = publicCodingRunResult(root.result);
@@ -206,6 +233,15 @@ export async function checkContinuation(reader, runId, repository, dispatchingOw
         },
     };
 }
+function codingTarget(reader, options, profile) {
+    return resolveCodingRepository(reader, {
+        agentId: options.agentId,
+        profile,
+        requested: options.codingRepository,
+        continuesCodingRunId: options.continuesCodingRunId,
+        requireExplicit: options.requireExplicitRepository,
+    });
+}
 /**
  * Resolves a coding run's branch: an override, else a continuation root's
  * (see checkContinuation), else the profile's base.
@@ -269,30 +305,49 @@ const UNREADABLE_DECLARATION = {
 };
 /**
  * The knowledge note's input (docs/knowledge.md): the repository's bundle
- * index at the run's base, read before the transaction like the services
+ * index at the run's base (in the folder .wardby/knowledge.yaml names, else
+ * docs/knowledge/), read before the transaction like the services
  * declaration. Any failure means no note, never a failed dispatch.
  */
 async function readKnowledgeIndex(options, profile, resolvedBranch, ownerId) {
-    const executor = options.executor;
-    if (!executor.readCodingRepositoryFile)
+    if (!options.executor.readCodingRepositoryFile)
         return undefined;
+    let baseRef;
     try {
         // Resolved here, inside the try: a branch problem is the transaction's to report, not the note's.
-        const branch = resolvedBranch ?? (await resolveCodingBranch(options.db, options, profile, ownerId));
-        const indexText = await executor.readCodingRepositoryFile({
-            repository: profile.repository,
-            baseRef: normalizeGitRef(branch.baseRef),
-            path: `${DEFAULT_KNOWLEDGE_BUNDLE_PATH}/index.md`,
+        baseRef = (resolvedBranch ?? (await resolveCodingBranch(options.db, options, profile, ownerId))).baseRef;
+    }
+    catch (err) {
+        dispatchLog.warn({ err, repository: profile.repository }, "knowledge index read failed; dispatching without it");
+        return undefined;
+    }
+    return readKnowledgeIndexAt(options.executor, profile.repository, baseRef);
+}
+/** The bundle index at a known base ref; also how a deferred coding run reads it when it starts. */
+export async function readKnowledgeIndexAt(executor, repository, baseRef) {
+    const readFile = executor.readCodingRepositoryFile?.bind(executor);
+    if (!readFile)
+        return undefined;
+    const ref = normalizeGitRef(baseRef);
+    // The repository may name its bundle folder in .wardby/knowledge.yaml; anything wrong with that file falls back to the default.
+    const { bundlePath, warning } = await resolveKnowledgeLocation(() => readFile({ repository, baseRef: ref, path: KNOWLEDGE_CONFIG_PATH, maxBytes: KNOWLEDGE_CONFIG_MAX_BYTES }));
+    if (warning)
+        dispatchLog.warn({ repository, baseRef: ref }, warning);
+    try {
+        const indexText = await readFile({
+            repository,
+            baseRef: ref,
+            path: `${bundlePath}/index.md`,
             maxBytes: KNOWLEDGE_INDEX_READ_MAX_BYTES,
         });
-        return indexText ? { bundlePath: DEFAULT_KNOWLEDGE_BUNDLE_PATH, indexText } : undefined;
+        return indexText ? { bundlePath, indexText } : undefined;
     }
     catch (err) {
         if (err instanceof Error && err.message in UNREADABLE_DECLARATION) {
-            dispatchLog.info({ repository: profile.repository, reason: err.message }, "knowledge index unreadable; dispatching without it");
+            dispatchLog.info({ repository, reason: err.message }, "knowledge index unreadable; dispatching without it");
             return undefined;
         }
-        dispatchLog.warn({ err, repository: profile.repository }, "knowledge index read failed; dispatching without it");
+        dispatchLog.warn({ err, repository }, "knowledge index read failed; dispatching without it");
         return undefined;
     }
 }
@@ -304,56 +359,54 @@ async function readKnowledgeIndex(options, profile, resolvedBranch, ownerId) {
  */
 async function readServiceDeclaration(options, profile, ownerId) {
     const branch = await resolveCodingBranch(options.db, options, profile, ownerId);
-    const read = { repository: profile.repository, profileBaseRef: profile.baseRef, branch };
-    const executor = options.executor;
+    return {
+        repository: profile.repository,
+        profileBaseRef: profile.baseRef,
+        branch,
+        outcome: await readServiceDeclarationAt(options.executor, profile.repository, branch.baseRef),
+    };
+}
+/** The declaration at a known base ref, parsed; also how a deferred coding run reads it when it starts. */
+export async function readServiceDeclarationAt(executor, repository, baseRef) {
     if (!executor.readCodingServiceDeclaration)
-        return { ...read, outcome: { kind: "none" } };
+        return { kind: "none" };
     let text;
     try {
-        text = await executor.readCodingServiceDeclaration({
-            repository: profile.repository,
-            baseRef: normalizeGitRef(branch.baseRef),
-        });
+        text = await executor.readCodingServiceDeclaration({ repository, baseRef: normalizeGitRef(baseRef) });
     }
     catch (err) {
         const reason = UNREADABLE_DECLARATION[err instanceof Error ? err.message : ""];
         if (reason) {
             return {
-                ...read,
-                outcome: {
-                    kind: "refused",
-                    refusal: serviceRefusal("service_declaration_invalid", invalidDeclarationSentence(reason)),
-                },
+                kind: "refused",
+                refusal: serviceRefusal("service_declaration_invalid", invalidDeclarationSentence(reason)),
             };
         }
-        dispatchLog.warn({ err, agentId: options.agentId }, "could not read the repository's service declaration");
+        dispatchLog.warn({ err, repository }, "could not read the repository's service declaration");
         return {
-            ...read,
-            outcome: {
-                kind: "refused",
-                refusal: serviceRefusal("service_declaration_unavailable", DECLARATION_UNAVAILABLE_SENTENCE),
-            },
+            kind: "refused",
+            refusal: serviceRefusal("service_declaration_unavailable", DECLARATION_UNAVAILABLE_SENTENCE),
         };
     }
     if (text === null)
-        return { ...read, outcome: { kind: "none" } };
+        return { kind: "none" };
     try {
-        return { ...read, outcome: { kind: "declared", services: parseServiceDeclaration(text) } };
+        return { kind: "declared", services: parseServiceDeclaration(text) };
     }
     catch (err) {
         if (!(err instanceof ServiceDeclarationError))
             throw err;
         return {
-            ...read,
-            outcome: {
-                kind: "refused",
-                refusal: serviceRefusal("service_declaration_invalid", invalidDeclarationSentence(err.reason)),
-            },
+            kind: "refused",
+            refusal: serviceRefusal("service_declaration_invalid", invalidDeclarationSentence(err.reason)),
         };
     }
 }
-/** Inside the transaction: the run's services, or the refusal that stops it. */
-async function resolveDispatchServices(tx, outcome, allowed, executor, provider, request, instructions) {
+/**
+ * Inside the transaction: the run's services, or the refusal that stops it. Takes only the
+ * catalog, so a deferred coding run's start resolves them the same way with a plain client.
+ */
+export async function resolveDispatchServices(tx, outcome, allowed, executor, provider, request, instructions) {
     if (outcome.kind === "refused")
         return { refusal: outcome.refusal };
     if (outcome.kind === "none" || outcome.services.length === 0)
@@ -385,16 +438,30 @@ export async function dispatchRun(options) {
         },
     });
     const lockGroups = preview?.kind === "coding" && preview.budgetGroupId != null;
+    // The native gateway's executor has no coding configuration: the run is recorded
+    // unresolved and the process that starts it reads and resolves (resolveDeferredCodingRun).
+    const deferCoding = options.executor.defersCodingResolution === true;
+    // The repository this run works in, resolved from the agent's list before any network read. A
+    // refusal propagates: nothing has been written, and it is not a retryable conflict.
+    const previewTarget = !deferCoding && preview?.kind === "coding" && preview.codingProfile
+        ? await codingTarget(options.db, options, preview.codingProfile)
+        : undefined;
     // Only an agent allowed some service reads the repository's declaration; any
     // other coding agent never calls the host for it and gets no services.
-    const declarationRead = preview?.kind === "coding" &&
+    const declarationRead = !deferCoding &&
+        preview?.kind === "coding" &&
         preview.codingProfile &&
+        previewTarget &&
         parseAllowedServiceNames(preview.codingProfile.services).length > 0
-        ? await readServiceDeclaration(options, preview.codingProfile, preview.ownerId ?? null)
+        ? await readServiceDeclaration(options, previewTarget, preview.ownerId ?? null)
         : undefined;
     // The knowledge note's input: the repository's bundle index at the run's base (a network call).
-    const knowledgeIndex = preview?.kind === "coding" && preview.codingProfile && options.executor.readCodingRepositoryFile
-        ? await readKnowledgeIndex(options, preview.codingProfile, declarationRead?.branch, preview.ownerId ?? null)
+    const knowledgeIndex = !deferCoding &&
+        preview?.kind === "coding" &&
+        preview.codingProfile &&
+        previewTarget &&
+        options.executor.readCodingRepositoryFile
+        ? await readKnowledgeIndex(options, previewTarget, declarationRead?.branch, preview.ownerId ?? null)
         : undefined;
     const persistOnce = () => options.db.$transaction(async (tx) => {
         if (lockGroups)
@@ -426,11 +493,14 @@ export async function dispatchRun(options) {
         let modelFailure;
         let services = [];
         let servicesRefusal;
+        let target;
         if (agent.kind === "coding") {
             if (!agent.codingProfile)
                 throw new Error(`Coding agent "${agent.id}" has no coding profile.`);
             // An unknown coding provider is a broken profile, not a catalog state: still thrown.
             assertCodingProvider(agent.codingProfile.provider);
+            // Resolved again inside the transaction: an unlink since the preview refuses the run here.
+            target = await codingTarget(tx, options, agent.codingProfile);
             // Recorded on the run row below: the run is billed at this entry for its whole life.
             // A model the catalog cannot run (missing, disabled, or another provider's) fails
             // the run here instead of throwing: the run row commits with the reason, so the
@@ -446,8 +516,7 @@ export async function dispatchRun(options) {
                 modelFailure = err.message;
             }
             if (!modelFailure && declarationRead) {
-                if (declarationRead.repository !== agent.codingProfile.repository ||
-                    declarationRead.profileBaseRef !== agent.codingProfile.baseRef) {
+                if (declarationRead.repository !== target.repository || declarationRead.profileBaseRef !== target.baseRef) {
                     // The declaration was read for a profile that changed before this transaction.
                     throw new Error("The coding agent's repository or base branch changed during dispatch; try again.");
                 }
@@ -471,6 +540,7 @@ export async function dispatchRun(options) {
                 // Fixed for the run's life: the executor routes on this, never on the agent's current setting.
                 nativeExecutionMode: agent.kind === "native" ? agent.nativeExecutionMode : null,
                 parentRunId: options.parentRunId,
+                parentCallId: options.parentCallId,
                 grantedParentMemoryKeys: options.grantedParentMemoryKeys ?? [],
                 taskOverride: options.taskOverride,
                 triggeredById: options.triggeredById ?? null,
@@ -490,6 +560,13 @@ export async function dispatchRun(options) {
                     : {}),
             },
         });
+        if (refusal && codingBudget?.refusalDetail && refusal === codingBudget.refusal) {
+            const { limit, detail } = codingBudget.refusalDetail;
+            // Group and lead names are filled at read time.
+            await tx.runBudgetEvent.create({
+                data: { runId: run.id, kind: "refused", limit, details: { source: "dispatch", ...detail } },
+            });
+        }
         if (options.afterPersist)
             await options.afterPersist(tx, run);
         const attributed = await attributeRun(tx, run.id, {
@@ -497,25 +574,30 @@ export async function dispatchRun(options) {
             continuesCodingRunId: options.continuesCodingRunId,
             intent: options.attribution,
         }, now);
-        if (agent.kind === "coding" && agent.codingProfile && codingBudget && !refusal) {
+        if (agent.kind === "coding" && agent.codingProfile && target && codingBudget && !refusal) {
             // Checked above too; repeated so the provider type narrows here.
             assertCodingProviderModel(agent.codingProfile.provider, agent.model);
             const request = options.codingTask ?? agent.codingProfile.defaultTask;
             if (!request)
                 throw new Error(`Coding agent "${agent.id}" requires a task.`);
             // The worker sees only the task text, so the agent's own instructions, and the
-            // services note, ride in it.
-            const task = composeCodingTask(agent.systemPrompt, request, servicesInstructionNote(services), knowledgeIndex ? knowledgeSection(knowledgeIndex) : undefined);
+            // services note, ride in it. Deferred, the task is stored raw and composed when the
+            // run starts; composing here only checks its size, so it throws exactly as today.
+            if (deferCoding)
+                composeCodingTask(agent.systemPrompt, request);
+            const task = deferCoding
+                ? request
+                : composeCodingTask(agent.systemPrompt, request, servicesInstructionNote(services), knowledgeIndex ? knowledgeSection(knowledgeIndex) : undefined);
             const budgetUsd = codingBudget.budgetUsd;
             // Resolved once: before the transaction when the declaration was read from it.
-            const branch = declarationRead?.branch ?? (await resolveCodingBranch(tx, options, agent.codingProfile, agent.ownerId));
+            const branch = declarationRead?.branch ?? (await resolveCodingBranch(tx, options, target, agent.ownerId));
             const { baseRef, continuationOf, rootCodingRunId, mergeOrder: inheritedMergeOrder } = branch;
             const headRef = branch.headRef ?? `wardby/run-${run.id}`;
             const mergeOrder = resolveMergeOrder(options, inheritedMergeOrder);
             const input = CodingTaskInputSchema.parse({
                 schemaVersion: CODING_PROTOCOL_VERSION,
                 runId: run.id,
-                repository: agent.codingProfile.repository,
+                repository: target.repository,
                 baseRef,
                 headRef,
                 task,
@@ -531,18 +613,25 @@ export async function dispatchRun(options) {
                 toolchainVersion: agent.codingProfile.toolchainVersion,
                 workerImageRef: agent.codingProfile.workerImageRef,
             };
-            const workerImage = options.executor.resolveCodingWorkerImage?.(imageSelector);
+            // Deferred, both stay null until the starting process resolves them.
+            const workerImage = deferCoding ? null : options.executor.resolveCodingWorkerImage?.(imageSelector);
             // Claude Code's commands run in its tool runner, so the toolchain picks that image too; fixed
             // here with the worker image so the run keeps both however the deployment changes later.
-            const toolImage = options.executor.resolveCodingToolImage?.(imageSelector) ?? null;
+            const toolImage = deferCoding ? null : (options.executor.resolveCodingToolImage?.(imageSelector) ?? null);
+            const traced = agent.codingProfile.debugTraceUntil != null &&
+                now.getTime() < agent.codingProfile.debugTraceUntil.getTime();
+            const { packageAuditMode, packageAuditUntil } = agent.codingProfile;
             await tx.codingRun.create({
                 data: {
                     runId: run.id,
+                    budgetLimitedBy: codingBudget.limitedBy ?? null,
                     issueProvider: attributed?.provider ?? null,
                     issueKey: attributed?.key ?? null,
                     task: input.task,
+                    request,
                     repository: input.repository,
                     baseRef: input.baseRef,
+                    viaRepositoryLink: target.viaRepositoryLink,
                     headRef: input.headRef,
                     provider: agent.codingProfile.provider,
                     model: input.model,
@@ -554,15 +643,25 @@ export async function dispatchRun(options) {
                     workerImage,
                     toolImage,
                     budgetReservedUsd: budgetUsd,
+                    budgetBaseUsd: codingBudget.baseBudgetUsd,
+                    budgetLimitUsd: codingBudget.limitUsd,
                     rootCodingRunId,
                     mergeOrder,
                     workspaceDiskMb: agent.codingProfile.workspaceDiskMb,
                     maxTurns: agent.codingProfile.maxTurns,
+                    maxOutputTokens: agent.codingProfile.maxOutputTokens,
                     repoSkills: agent.codingProfile.repoSkills,
                     claudeBareMode: agent.codingProfile.claudeBareMode,
+                    dependencyCache: agent.codingProfile.dependencyCache,
+                    sessionResume: agent.codingProfile.sessionResume,
                     // Fixed here so a run's tracing never changes mid-run.
-                    debugTrace: agent.codingProfile.debugTraceUntil != null &&
-                        now.getTime() < agent.codingProfile.debugTraceUntil.getTime(),
+                    debugTrace: traced,
+                    debugTraceMaxMb: traced ? agent.codingProfile.debugTraceMaxMb : null,
+                    // Fixed here too: a run keeps the mode its dispatch saw for its
+                    // whole life, however the window moves afterwards.
+                    packageAuditMode: isPackageAuditActive(packageAuditMode, packageAuditUntil, now)
+                        ? packageAuditMode
+                        : null,
                     services,
                 },
             });
@@ -570,7 +669,8 @@ export async function dispatchRun(options) {
         else if (agent.kind !== "coding" &&
             (options.codingTask !== undefined ||
                 options.codingBaseRef !== undefined ||
-                options.continuesCodingRunId !== undefined)) {
+                options.continuesCodingRunId !== undefined ||
+                options.codingRepository !== undefined)) {
             throw new Error("Coding overrides cannot be supplied for a native agent.");
         }
         const task = options.task

package/dist/core/engine-native.js

@@ -178,7 +178,7 @@ export class NativeEngine {
      * once all have settled, the first rejection by call order is rethrown.
      */
     async runToolCalls(ctx, step, turn, toolCalls) {
-        const runCall = (index) => step(`turn:${turn}:tool:${index}`, () => ctx.runSandboxTool(toolCalls[index].name, toolCalls[index].argsJson));
+        const runCall = (index) => step(`turn:${turn}:tool:${index}`, () => ctx.runSandboxTool(toolCalls[index].name, toolCalls[index].argsJson, toolCalls[index].id));
         const concurrent = ctx.runsConcurrently;
         const results = new Array(toolCalls.length);
         let index = 0;

package/dist/core/error-code.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The code a wardby error message leads with (`some_code` or `some_code: detail`), or undefined.
+ * Worker-safe: the native sandbox worker image ships this module.
+ */
+export declare function errorCodeOf(message: string | null | undefined): string | undefined;
+/** The code an unexpected error's message leads with, if it is code-shaped (has an underscore) and short enough. */
+export declare function causeCodeOf(err: unknown): string | undefined;
+/**
+ * The only codes that may be shown from an arbitrary error's text (to a worker, or to the model in a
+ * tool result): wardby's own codes that an unexpected error on those paths can lead with. Anything
+ * else, however code-shaped, could be a value from an error's text, so it never crosses.
+ * - coding_execution_not_configured, coding_profile_missing: a coding delegation reaching a process
+ *   that cannot start coding runs (core/deferred-coding.ts, providers/executor/routing.ts).
+ * - message_too_large, message_not_json, message_invalid, unsupported_protocol_version: the native
+ *   worker protocol's own ProtocolError codes (native-worker/protocol.ts).
+ * - invalid_merge_order: dispatchRun's refusal of a bad mergeOrder (core/dispatch.ts).
+ * - coding_worker_image_invalid: a coding worker image that is not pinned by digest
+ *   (providers/executor/container.ts).
+ * - native_sandbox_unavailable: createRun/the router refusing a sandbox-mode agent with no sandbox executor
+ *   (core/runner.ts).
+ * - run_tree_exhausted: dispatchRun refusing a run whose tree budget is spent (core/dispatch.ts).
+ * - secret_in_value, secret_check_unavailable: the datastore and memory write guard refusing a value
+ *   that holds an attached secret's value (core/secret-guard.ts); the code carries only the name of
+ *   the secret, never its value, across the gateway.
+ */
+export declare const GATEWAY_CAUSE_CODES: ReadonlySet<string>;
+/**
+ * The codes wardby itself writes as a failed coding or native child run's Run.error (read from the
+ * literals in core/dispatch.ts, core/coding-queue.ts, providers/executor/*, core/run-pricing.ts,
+ * providers/llm/catalog-types.ts and the native sandbox). A parent may be told which of these a
+ * child failed with; any other leading word is not shown. Includes GATEWAY_CAUSE_CODES, and the
+ * container executor's terminal codes: `coding_failure_<category>` for every category
+ * failureCategory files a failure under (providers/executor/container.ts), and
+ * `coding_provider_<class>` for every provider failure class (core/provider-wording.ts).
+ */
+export declare const CHILD_RUN_FAILURE_CODES: ReadonlySet<string>;
+/** The leading code of an arbitrary error or message, only when it is declared in `allowed`. */
+export declare function declaredCodeOf(err: unknown, allowed?: ReadonlySet<string>): string | undefined;

package/dist/core/error-code.js

@@ -0,0 +1,169 @@
+/**
+ * The code a wardby error message leads with (`some_code` or `some_code: detail`), or undefined.
+ * Worker-safe: the native sandbox worker image ships this module.
+ */
+export function errorCodeOf(message) {
+    return message ? /^([a-z][a-z0-9_]*)(:|$)/.exec(message)?.[1] : undefined;
+}
+/** The longest cause code carried; a longer leading word is not a code. */
+const MAX_CAUSE_CODE_LENGTH = 64;
+/** The code an unexpected error's message leads with, if it is code-shaped (has an underscore) and short enough. */
+export function causeCodeOf(err) {
+    const code = errorCodeOf(err instanceof Error ? err.message : typeof err === "string" ? err : undefined);
+    // Only the code form leaves a boundary: snake_case with an underscore, so a bare word
+    // (which could be a token) never crosses.
+    return code && code.includes("_") && code.length <= MAX_CAUSE_CODE_LENGTH ? code : undefined;
+}
+/**
+ * The only codes that may be shown from an arbitrary error's text (to a worker, or to the model in a
+ * tool result): wardby's own codes that an unexpected error on those paths can lead with. Anything
+ * else, however code-shaped, could be a value from an error's text, so it never crosses.
+ * - coding_execution_not_configured, coding_profile_missing: a coding delegation reaching a process
+ *   that cannot start coding runs (core/deferred-coding.ts, providers/executor/routing.ts).
+ * - message_too_large, message_not_json, message_invalid, unsupported_protocol_version: the native
+ *   worker protocol's own ProtocolError codes (native-worker/protocol.ts).
+ * - invalid_merge_order: dispatchRun's refusal of a bad mergeOrder (core/dispatch.ts).
+ * - coding_worker_image_invalid: a coding worker image that is not pinned by digest
+ *   (providers/executor/container.ts).
+ * - native_sandbox_unavailable: createRun/the router refusing a sandbox-mode agent with no sandbox executor
+ *   (core/runner.ts).
+ * - run_tree_exhausted: dispatchRun refusing a run whose tree budget is spent (core/dispatch.ts).
+ * - secret_in_value, secret_check_unavailable: the datastore and memory write guard refusing a value
+ *   that holds an attached secret's value (core/secret-guard.ts); the code carries only the name of
+ *   the secret, never its value, across the gateway.
+ */
+export const GATEWAY_CAUSE_CODES = new Set([
+    "coding_execution_not_configured",
+    "coding_profile_missing",
+    "message_too_large",
+    "message_not_json",
+    "message_invalid",
+    "unsupported_protocol_version",
+    "invalid_merge_order",
+    "coding_worker_image_invalid",
+    "native_sandbox_unavailable",
+    "run_tree_exhausted",
+    "secret_in_value",
+    "secret_check_unavailable",
+]);
+/**
+ * The codes wardby itself writes as a failed coding or native child run's Run.error (read from the
+ * literals in core/dispatch.ts, core/coding-queue.ts, providers/executor/*, core/run-pricing.ts,
+ * providers/llm/catalog-types.ts and the native sandbox). A parent may be told which of these a
+ * child failed with; any other leading word is not shown. Includes GATEWAY_CAUSE_CODES, and the
+ * container executor's terminal codes: `coding_failure_<category>` for every category
+ * failureCategory files a failure under (providers/executor/container.ts), and
+ * `coding_provider_<class>` for every provider failure class (core/provider-wording.ts).
+ */
+export const CHILD_RUN_FAILURE_CODES = new Set([
+    ...GATEWAY_CAUSE_CODES,
+    "coding_failure_turn_limit",
+    "coding_failure_service_unready",
+    "coding_failure_preflight",
+    "coding_failure_job",
+    "coding_failure_repo_access_unavailable",
+    "coding_failure_repo_access",
+    "coding_failure_github",
+    "coding_failure_protected_path",
+    "coding_failure_continuation_closed",
+    "coding_failure_merge_conflict",
+    "coding_failure_target_merge",
+    "coding_failure_workspace",
+    "coding_failure_budget",
+    "coding_failure_artifact",
+    "coding_failure_cancelled",
+    "coding_failure_executor",
+    "coding_failure_mcp_pins_unavailable",
+    "coding_provider_quota",
+    "coding_provider_rate_limited",
+    "coding_provider_unavailable",
+    "coding_provider_rejected",
+    "coding_ambiguous_provisioning",
+    "coding_artifact_duplicate_key",
+    "coding_artifact_invalid_json",
+    "coding_artifact_nesting_limit",
+    "coding_artifact_path_invalid",
+    "coding_artifact_root_invalid",
+    "coding_artifact_size_limit",
+    "coding_budget_exhausted",
+    "coding_capability_exists",
+    "coding_capability_unavailable",
+    "coding_credential_ref_invalid",
+    "coding_credential_reference_invalid",
+    "coding_credential_unavailable",
+    "coding_dispatch_unavailable",
+    "coding_head_ref_invalid",
+    "coding_input_invalid_file",
+    "coding_job_handle_conflict",
+    "coding_job_handle_mismatch",
+    "coding_job_status_unavailable",
+    "coding_output_invalid",
+    "coding_output_missing",
+    "coding_output_run_mismatch",
+    "coding_output_size_limit",
+    "coding_provider_not_configured",
+    "coding_provider_unsupported",
+    "coding_queue_timeout",
+    "coding_recovery_incomplete",
+    "coding_recovery_unavailable",
+    "coding_resource_limits_invalid",
+    "coding_result_missing",
+    "coding_result_run_mismatch",
+    "coding_run_budget_invalid",
+    "coding_run_no_longer_active",
+    "coding_run_not_active",
+    "coding_run_not_found",
+    "coding_run_ownership_invalid",
+    "coding_run_pricing_mismatch",
+    "coding_run_status_invalid",
+    "coding_run_terminal_conflict",
+    "coding_service_catalog_invalid",
+    "coding_service_unready",
+    "coding_services_unsupported",
+    "coding_services_unsupported_launcher",
+    "coding_stream_agent_exited",
+    "coding_stream_failed",
+    "coding_stream_proxy_denied",
+    "coding_stream_proxy_unreachable",
+    "coding_stream_quota_exceeded",
+    "coding_stream_rate_limited",
+    "coding_stream_timeout",
+    "coding_stream_upstream_error",
+    "coding_toolchain_unsupported",
+    "coding_turn_failed",
+    "coding_turn_limit",
+    "coding_workspace_disk_exceeds_limit",
+    "coding_workspace_lost",
+    "model_unavailable",
+    "model_not_allowed",
+    "executor_run_not_found",
+    "run_not_drivable",
+    "ownership_lost",
+    "step_replay_mismatch",
+    "worker_error",
+    "worker_tool_runner_unreachable",
+    "sandbox_dispatch_unavailable",
+    "native_sandbox_capacity",
+    "native_sandbox_deadline_exceeded",
+    "native_sandbox_docker_failed",
+    "native_sandbox_gateway_error",
+    "native_sandbox_gateway_unavailable",
+    "native_sandbox_image_not_pinned",
+    "native_sandbox_invalid_run_id",
+    "native_sandbox_invalid_warm_token",
+    "native_sandbox_isolation_mismatch",
+    "native_sandbox_launch_abandoned",
+    "native_sandbox_network_unenforced",
+    "native_sandbox_platform_unsupported",
+    "native_sandbox_recovery_unavailable",
+    "native_sandbox_requires_catalog",
+    "native_sandbox_warm_delivery_failed",
+    "native_sandbox_worker_exited",
+    "native_sandbox_worker_lost",
+    "native_sandbox_worker_unready",
+]);
+/** The leading code of an arbitrary error or message, only when it is declared in `allowed`. */
+export function declaredCodeOf(err, allowed = GATEWAY_CAUSE_CODES) {
+    const code = causeCodeOf(err);
+    return code && allowed.has(code) ? code : undefined;
+}