@wardby/cli 0.6.0 → 0.7.0

package/dist/coding/protocol.js

@@ -3,7 +3,8 @@ import { isAbsolute, resolve } from "node:path";
 export const CODING_PROTOCOL_VERSION = 1;
 /** The code host every coding run's repository and pull request live on (see pullRequestUrlSchema); the one place to change when another is added. */
 export const CODING_CODE_PROVIDER = "github";
-export const MAX_CODING_ARTIFACT_BYTES = 64 * 1024;
+/** result.json and the agent output file: room for a full summary and test list, JSON-escaped. */
+export const MAX_CODING_ARTIFACT_BYTES = 256 * 1024;
 /** The worker input artifact (input.json): larger than results because it can carry Claude Code repo context. */
 export const MAX_CODING_INPUT_BYTES = 512 * 1024;
 /** Bounds on CodingTaskInput.claudeContext, enforced by the builder (src/coding/claude-context.ts) and this schema. */
@@ -11,10 +12,19 @@ export const CLAUDE_CONTEXT_LIMITS = { maxFiles: 200, maxFileBytes: 64 * 1024, m
 export const MAX_CODING_TASK_BYTES = 16 * 1024;
 /** Room reserved at the end of a composed task for lines the executor appends (e.g. the base commit). */
 export const CODING_TASK_TRAILER_RESERVE_BYTES = 256;
-export const MAX_CODING_SUMMARY_BYTES = 8 * 1024;
+/**
+ * A coding run's summary (the agent's final message, posted as the PR body):
+ * longer text is cut at a line boundary with SUMMARY_TRUNCATED_MARKER rather
+ * than failing the run.
+ */
+export const MAX_CODING_SUMMARY_BYTES = 64 * 1024;
+export const SUMMARY_TRUNCATED_MARKER = "\n\n[summary truncated]";
 export const MAX_CODING_TESTS = 64;
 export const MAX_CODING_TEST_COMMAND_BYTES = 2 * 1024;
 export const MAX_TAG_BYTES = 32;
+/** The workspace volume bounds every launcher enforces (docker-isolation.ts, kubernetes-isolation.ts). */
+export const MIN_CODING_DISK_MB = 64;
+export const MAX_CODING_DISK_MB = 32_768;
 /**
  * Coding-run services (docs/coding-services.md): the catalog name and version
  * grammar, shared by the repository's .wardby/services.yaml, the catalog, and
@@ -46,6 +56,42 @@ export const INVALID_SINGLE_LINE_CONTROL = /[\u0000-\u001F\u007F]/;
 export function byteLength(value) {
     return Buffer.byteLength(value, "utf8");
 }
+/**
+ * `text` unchanged when `measure(text) <= max`; otherwise its longest prefix
+ * that fits with `marker` appended, cut back to the last line break when one
+ * is in the second half, and never inside a surrogate pair.
+ */
+export function truncateText(text, max, measure = byteLength, marker = SUMMARY_TRUNCATED_MARKER) {
+    if (measure(text) <= max)
+        return text;
+    const room = max - measure(marker);
+    if (room <= 0)
+        return marker.trim();
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (measure(text.slice(0, mid)) <= room)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    let cut = text.slice(0, low);
+    if (/[\uD800-\uDBFF]$/.test(cut))
+        cut = cut.slice(0, -1);
+    const lineBreak = cut.lastIndexOf("\n");
+    if (lineBreak > cut.length / 2)
+        cut = cut.slice(0, lineBreak);
+    return `${cut.trimEnd()}${marker}`;
+}
+/**
+ * A summary field: over-long text is redacted, then truncated (truncateText),
+ * then checked like any bounded text. Redacting first keeps a credential that
+ * straddles the cut from leaving its front half in the output.
+ */
+function summaryText() {
+    return z.preprocess((value) => typeof value === "string" ? truncateText(redactTokenShapedValues(value), MAX_CODING_SUMMARY_BYTES) : value, boundedText(MAX_CODING_SUMMARY_BYTES));
+}
 function boundedText(maxBytes, singleLine = false) {
     const invalidControl = singleLine ? INVALID_SINGLE_LINE_CONTROL : INVALID_MULTILINE_CONTROL;
     return z
@@ -87,6 +133,9 @@ const RESERVED_SERVICE_ENV_PREFIXES = [
     "ANTHROPIC_",
     "PIP_",
     "NPM_CONFIG_",
+    "YARN_",
+    "PNPM_",
+    "COREPACK_",
     "UV_",
     "GIT_",
 ];
@@ -325,8 +374,22 @@ const testResultSchema = z
 export const MAX_CODING_TURNS = 1000;
 /** The Claude Code worker's turn limit when the agent sets none; the run's budget and timeout are the real limits. */
 export const DEFAULT_CLAUDE_MAX_TURNS = 200;
+/**
+ * The most output tokens per model reply on a Claude Code run when the agent sets
+ * none (CodingAgentProfile.maxOutputTokens); thinking counts toward it. The coding
+ * proxy reserves maxOutputTokens x the model's output price per request against
+ * the run budget, so higher values need a larger budget.
+ */
+export const DEFAULT_CLAUDE_MAX_OUTPUT_TOKENS = 32_000;
+/** Bounds on CodingAgentProfile.maxOutputTokens (Claude Code runs). */
+export const MIN_CLAUDE_MAX_OUTPUT_TOKENS = 1024;
+export const MAX_CLAUDE_MAX_OUTPUT_TOKENS = 128_000;
 /** 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;
+/** A traced run's total trace output when the agent sets no cap (CodingAgentProfile.debugTraceMaxMb), in MiB. */
+export const DEFAULT_DEBUG_TRACE_MAX_MB = 2;
+/** Upper bound on CodingAgentProfile.debugTraceMaxMb. */
+export const MAX_DEBUG_TRACE_MAX_MB = 64;
 /** C0 and C1 control characters, which have no place in a context file path. */
 const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
 /**
@@ -400,12 +463,44 @@ export const CodingTaskInputSchema = z
      * untraced run is unchanged for workers that predate it.
      */
     debugTrace: z.boolean().optional(),
+    /**
+     * Dependency cache (CodingAgentProfile.dependencyCache, fixed on the run at
+     * dispatch). The control plane writes the key only when true, so an input
+     * for any other run is unchanged for workers that predate it (their strict
+     * schema would refuse the key).
+     */
+    dependencyCache: z.literal(true).optional(),
+    /**
+     * Session resume (CodingAgentProfile.sessionResume, fixed on the run at dispatch): the worker keeps
+     * Claude Code's session and writes a sanitised transcript next to its result. Written only when
+     * true, so other runs' input is unchanged for workers that predate it.
+     */
+    sessionResume: z.literal(true).optional(),
+    /**
+     * The run's workspace volume size in MiB (the job's limits.diskMb), so the dependency cache can
+     * stay inside it: on Kubernetes the emptyDir sizeLimit is invisible to statfs. Written only with
+     * dependencyCache, so every other input is unchanged for workers that predate it.
+     */
+    diskMb: z.number().int().min(MIN_CODING_DISK_MB).max(MAX_CODING_DISK_MB).optional(),
+    /**
+     * Cap on a traced run's total trace output, in MiB (CodingRun.debugTraceMaxMb).
+     * Written only on a traced run whose agent sets one; absent means the
+     * worker default (DEFAULT_DEBUG_TRACE_MAX_MB).
+     */
+    debugTraceMaxMb: z.number().int().min(1).max(MAX_DEBUG_TRACE_MAX_MB).optional(),
     /**
      * Claude Code turn limit (CodingAgentProfile.maxTurns, fixed on the run at
      * dispatch). Absent means the worker default; written only when the agent
      * sets one, so other runs' input is unchanged for workers that predate it.
      */
     maxTurns: z.number().int().min(1).max(MAX_CODING_TURNS).optional(),
+    /**
+     * Claude Code output tokens per model reply (CodingAgentProfile.maxOutputTokens,
+     * fixed on the run at dispatch). Absent means the worker default
+     * (DEFAULT_CLAUDE_MAX_OUTPUT_TOKENS); written only when the agent sets one, so
+     * other runs' input is unchanged for workers that predate it.
+     */
+    maxOutputTokens: z.number().int().min(MIN_CLAUDE_MAX_OUTPUT_TOKENS).max(MAX_CLAUDE_MAX_OUTPUT_TOKENS).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
@@ -446,6 +541,9 @@ export const CodingTaskInputSchema = z
             message: "must match wardby/run-<runId> (or wardby/run-<continuationOf.runId>)",
         });
     }
+    if (value.diskMb !== undefined && value.dependencyCache !== true) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["diskMb"], message: "only with dependencyCache" });
+    }
     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" });
@@ -464,22 +562,140 @@ export const CodingTaskInputSchema = z
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["claudeContext", "files"], message: "context too large" });
     }
 });
-export const CodingAgentOutputSchema = z
-    .object({
+const agentOutputFields = {
     schemaVersion: z.literal(CODING_PROTOCOL_VERSION),
     runId: runIdSchema,
     outcome: z.enum(["changes_ready", "no_changes", "budget_exhausted"]),
-    summary: boundedText(MAX_CODING_SUMMARY_BYTES),
+    summary: summaryText(),
     tests: z.array(testResultSchema).max(MAX_CODING_TESTS),
     // Model-written, so normalized rather than rejected; see normalizeCodingTag.
     tag: z.preprocess(normalizeCodingTag, tagSchema),
+};
+function redactAgentOutput(value) {
+    return {
+        ...value,
+        summary: redactTokenShapedValues(value.summary),
+        tests: value.tests.map((test) => ({ ...test, command: redactTokenShapedValues(test.command) })),
+        ...(value.tag !== undefined ? { tag: redactTokenShapedValues(value.tag) } : {}),
+    };
+}
+/** What the model returns. Strict: it can never carry a worker-written field such as dependencyCache. */
+export const CodingAgentOutputSchema = z.object(agentOutputFields).strict().transform(redactAgentOutput);
+// ------------------------------------------------------------ dependency cache report
+/**
+ * The run's dependency cache (src/coding-worker/dependency-cache.mjs), as the worker reports it in
+ * result.json and the control plane stores it (CodingRun.dependencyCacheResult, get_run). Worker-
+ * written, never model-written: the model's output schema above refuses the key. Only stable codes,
+ * repository folder names and bounded numbers; never npm output.
+ */
+export const MAX_DEPENDENCY_CACHE_PROJECTS = 4;
+export const DEPENDENCY_CACHE_OUTCOMES = ["hit", "nearest", "cold", "skipped", "refused"];
+export const DEPENDENCY_CACHE_REBUILD_OUTCOMES = ["ok", "failed", "timeout", "skipped", "unsealed"];
+const DEPENDENCY_CACHE_CODE = /^[a-z][a-z0-9_]{0,63}$/;
+/** "." or up to three folder segments: the proxy's project-path rule (dependency-cache/key.ts). */
+export const DEPENDENCY_CACHE_PATH = /^(?:\.|[A-Za-z0-9_@+-][A-Za-z0-9._@+-]{0,99}(?:\/[A-Za-z0-9_@+-][A-Za-z0-9._@+-]{0,99}){0,2})$/;
+const MAX_DEPENDENCY_CACHE_NUMBER = Number.MAX_SAFE_INTEGER;
+const dependencyCacheCount = z.number().int().min(0).max(MAX_DEPENDENCY_CACHE_NUMBER);
+const dependencyCacheProjectSchema = z
+    .object({
+    path: z
+        .string()
+        .regex(DEPENDENCY_CACHE_PATH)
+        .refine((path) => !path.split("/").includes("node_modules")),
+    result: z.enum(DEPENDENCY_CACHE_OUTCOMES),
+    key: z
+        .string()
+        .regex(/^[a-z0-9]{1,64}$/)
+        .optional(),
+    sizeBytes: dependencyCacheCount.optional(),
+    restoreMs: dependencyCacheCount.optional(),
+    installMs: dependencyCacheCount.optional(),
+    reason: z.string().regex(DEPENDENCY_CACHE_CODE).optional(),
+    rebuild: z.enum(DEPENDENCY_CACHE_REBUILD_OUTCOMES).optional(),
+})
+    .strict();
+export const DependencyCacheReportSchema = z
+    .object({
+    projects: z.array(dependencyCacheProjectSchema).max(MAX_DEPENDENCY_CACHE_PROJECTS),
+    /** Projects left out of `projects` (over the cap, or not reportable). */
+    omitted: z.number().int().min(1).max(MAX_DEPENDENCY_CACHE_NUMBER).optional(),
+    /** Set when no project could be reported at all: a stable code (timeout, internal_error, worker_error, ...). */
+    reason: z.string().regex(DEPENDENCY_CACHE_CODE).optional(),
+})
+    .strict();
+const INSTALLED_OUTCOMES = new Set(["hit", "nearest", "cold"]);
+const RESTORED_OUTCOMES = new Set(["hit", "nearest"]);
+const MAX_RAW_DEPENDENCY_CACHE_PROJECTS = 1024;
+/**
+ * Bounds whatever the module (or a tool runner over its socket) returned into a report: projects
+ * that don't fit the schema are dropped and counted in `omitted`; past the cap, installed and
+ * refused projects are kept ahead of skipped ones, in their original order. A value that isn't a
+ * report at all becomes `{ projects: [], reason: "report_invalid" }`. Never throws.
+ */
+export function sanitizeDependencyCacheReport(value) {
+    const invalid = () => ({ projects: [], reason: "report_invalid" });
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return invalid();
+    const raw = value;
+    if (!Array.isArray(raw.projects) || raw.projects.length > MAX_RAW_DEPENDENCY_CACHE_PROJECTS)
+        return invalid();
+    if (Object.keys(raw).some((key) => key !== "projects" && key !== "reason" && key !== "omitted"))
+        return invalid();
+    const valid = [];
+    for (const project of raw.projects) {
+        const parsed = dependencyCacheProjectSchema.safeParse(project);
+        if (parsed.success)
+            valid.push(parsed.data);
+    }
+    const kept = valid
+        .map((project, index) => ({ project, index, rank: project.result === "skipped" ? 1 : 0 }))
+        .sort((a, b) => a.rank - b.rank || a.index - b.index)
+        .slice(0, MAX_DEPENDENCY_CACHE_PROJECTS)
+        .sort((a, b) => a.index - b.index)
+        .map((entry) => entry.project);
+    const earlier = typeof raw.omitted === "number" && Number.isSafeInteger(raw.omitted) && raw.omitted > 0;
+    const omitted = Math.min(MAX_DEPENDENCY_CACHE_NUMBER, raw.projects.length - kept.length + (earlier ? raw.omitted : 0));
+    const reason = typeof raw.reason === "string" && DEPENDENCY_CACHE_CODE.test(raw.reason) ? raw.reason : undefined;
+    return {
+        projects: kept,
+        ...(omitted > 0 ? { omitted } : {}),
+        ...(reason ? { reason } : {}),
+    };
+}
+/** Folders the dependency cache installed (hit, nearest or cold), "." for the repository root. */
+export function installedDependencyFolders(report) {
+    return (report?.projects ?? []).filter((project) => INSTALLED_OUTCOMES.has(project.result)).map((p) => p.path);
+}
+/** Folders whose node_modules came from a cached snapshot (hit or nearest): the PR body's line. */
+export function restoredDependencyFolders(report) {
+    return (report?.projects ?? []).filter((project) => RESTORED_OUTCOMES.has(project.result)).map((p) => p.path);
+}
+/** The one line both workers add to the agent's prompt when dependencies were installed; else undefined. */
+export function dependencyCacheTaskNote(report) {
+    const folders = installedDependencyFolders(report);
+    if (folders.length === 0)
+        return undefined;
+    const named = folders.map((path) => (path === "." ? "the repo root" : path)).join(", ");
+    return `Dependencies are pre-installed from the committed lockfile in: ${named}. Don't run \`npm ci\` there; add packages with a single install command.`;
+}
+/**
+ * What a worker writes to result.json and the control plane reads back: the model's output plus
+ * worker-written fields. `dependencyCache` is written only on a run whose input asked for it, so an
+ * older control plane never sees the key; a malformed one is bounded (sanitizeDependencyCacheReport)
+ * rather than failing the run.
+ */
+export const CodingWorkerOutputSchema = z
+    .object({
+    ...agentOutputFields,
+    dependencyCache: z
+        .unknown()
+        .optional()
+        .transform((value) => (value === undefined ? undefined : sanitizeDependencyCacheReport(value))),
 })
     .strict()
-    .transform((value) => ({
-    ...value,
-    summary: redactTokenShapedValues(value.summary),
-    tests: value.tests.map((test) => ({ ...test, command: redactTokenShapedValues(test.command) })),
-    ...(value.tag !== undefined ? { tag: redactTokenShapedValues(value.tag) } : {}),
+    .transform(({ dependencyCache, ...value }) => ({
+    ...redactAgentOutput(value),
+    ...(dependencyCache !== undefined ? { dependencyCache } : {}),
 }));
 const pullRequestUrlSchema = z
     .string()
@@ -513,7 +729,7 @@ export const CodingRunResultSchema = z
         .optional(),
     pullRequestUrl: pullRequestUrlSchema.optional(),
     pullRequestNumber: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
-    summary: boundedText(MAX_CODING_SUMMARY_BYTES),
+    summary: summaryText(),
     tests: z.array(testResultSchema).max(MAX_CODING_TESTS),
     usage: usageSchema,
     tag: tagSchema,
@@ -570,7 +786,10 @@ export function publicCodingRunResult(value) {
  */
 const PEM_PRIVATE_KEY = /-----BEGIN (?:[A-Z ]{1,32} )?PRIVATE KEY-----[\s\S]{0,6144}?-----END (?:[A-Z ]{1,32} )?PRIVATE KEY-----/g;
 const TOKEN_PATTERNS = [
-    /sk-(?:ant-)?[A-Za-z0-9_-]{16,}/gi,
+    // Not after a letter or digit: "task-…", "risk-…" and "disk-…" words are
+    // not keys, and redacting them garbled run output and failed knowledge
+    // checks on file names such as "mcp-task-cancellation-stamp.md".
+    /(?<![A-Za-z0-9])sk-(?:ant-)?[A-Za-z0-9_-]{16,}/gi,
     /github_pat_[A-Za-z0-9_]{20,}/g,
     /gh[pousr]_[A-Za-z0-9]{20,}/g,
     /AKIA[0-9A-Z]{16}/g,
@@ -748,6 +967,10 @@ export function parseCodingTaskInputJson(text) {
 export function parseCodingAgentOutputJson(text) {
     return CodingAgentOutputSchema.parse(parseJsonWithoutDuplicateKeys(text));
 }
+/** The control plane's read of a worker's result.json (see CodingWorkerOutputSchema). */
+export function parseCodingWorkerOutputJson(text) {
+    return CodingWorkerOutputSchema.parse(parseJsonWithoutDuplicateKeys(text));
+}
 export function parseCodingRunResultJson(text) {
     return CodingRunResultSchema.parse(parseJsonWithoutDuplicateKeys(text));
 }

package/dist/coding/redact.d.ts

@@ -0,0 +1,3 @@
+export declare const REDACTED = "[REDACTED]";
+/** Redacts the given exact secrets, then every token-shaped value. */
+export declare function redactSecrets(text: string, secrets?: readonly string[]): string;

package/dist/coding/redact.js

@@ -0,0 +1,12 @@
+import { redactExactSecretValues } from "../core/secret-spans.js";
+import { redactTokenShapedValues } from "./protocol.js";
+export const REDACTED = "[REDACTED]";
+/** Shapes protocol.ts's list does not cover, or covers only at longer lengths. */
+const EXTRA_TOKEN_PATTERNS = [/rrp_[A-Za-z0-9_-]{8,}/g, /rrg_[A-Za-z0-9_-]{8,}/g, /\bBearer\s+[^\s"',;]+/gi];
+/** Redacts the given exact secrets, then every token-shaped value. */
+export function redactSecrets(text, secrets = []) {
+    // The shared span-union redactor; any non-empty value counts here, as it always has.
+    let redacted = redactExactSecretValues(text, secrets, { marker: REDACTED, minLength: 1 });
+    redacted = redactTokenShapedValues(redacted);
+    return EXTRA_TOKEN_PATTERNS.reduce((value, pattern) => value.replace(pattern, REDACTED), redacted);
+}

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

@@ -1,9 +1,21 @@
+/**
+ * The per-agent package allowlist and policy model: parsing raw allowlist
+ * strings (via each ecosystem's adapter) into `AllowlistEntry` values, and
+ * matching a normalized package name against them.
+ */
+import { z } from "zod";
 import type { AllowlistEntry, RegistryAdapter } from "./types.js";
 export type PackageAllowlist = Readonly<Record<string, readonly string[]>>;
 export interface PackagePolicy {
     minReleaseAgeDays: number;
+    /** Advisory ids (GHSA-…, CVE-…) whose installs this agent may proceed with; malware (MAL-…) is never acceptable. */
+    acceptedAdvisories: readonly string[];
 }
 export declare const DEFAULT_MIN_RELEASE_AGE_DAYS = 3;
+export declare const ACCEPTED_ADVISORY_ID: RegExp;
+export declare const MAX_ACCEPTED_ADVISORIES = 32;
+/** The one definition of the acceptedAdvisories field, shared by the policy and the coding profile. */
+export declare const acceptedAdvisoriesSchema: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodString>>;
 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;

package/dist/coding/registry/allowlist.js

@@ -5,8 +5,21 @@
  */
 import { z } from "zod";
 export const DEFAULT_MIN_RELEASE_AGE_DAYS = 3;
+export const ACCEPTED_ADVISORY_ID = /^[A-Z][A-Z0-9]*-[A-Za-z0-9-]{3,64}$/;
+export const MAX_ACCEPTED_ADVISORIES = 32;
+/** The one definition of the acceptedAdvisories field, shared by the policy and the coding profile. */
+export const acceptedAdvisoriesSchema = z
+    .array(z
+    .string()
+    .refine((id) => !id.startsWith("MAL-"), "acceptedAdvisories: malware advisories (MAL-…) can never be accepted.")
+    .pipe(z.string().regex(ACCEPTED_ADVISORY_ID, "must look like GHSA-xxxx-xxxx-xxxx or CVE-2026-12345")))
+    .max(MAX_ACCEPTED_ADVISORIES)
+    .refine((ids) => new Set(ids).size === ids.length, "must not contain duplicates");
 const PolicySchema = z
-    .object({ minReleaseAgeDays: z.number().int().min(0).max(30).default(DEFAULT_MIN_RELEASE_AGE_DAYS) })
+    .object({
+    minReleaseAgeDays: z.number().int().min(0).max(30).default(DEFAULT_MIN_RELEASE_AGE_DAYS),
+    acceptedAdvisories: acceptedAdvisoriesSchema.default([]),
+})
     .strict();
 export function resolvePolicy(value) {
     return PolicySchema.parse(value ?? {});

package/dist/coding/registry/audit-mode.d.ts

@@ -0,0 +1,153 @@
+export declare const PACKAGE_AUDIT_MODES: readonly ["audit", "full"];
+export type PackageAuditMode = (typeof PACKAGE_AUDIT_MODES)[number];
+/** The window `packageAuditMode` opens when `packageAuditMinutes` is omitted: 24 hours. */
+export declare const DEFAULT_PACKAGE_AUDIT_MINUTES: number;
+/** The longest window one update may open: 7 days. */
+export declare const MAX_PACKAGE_AUDIT_MINUTES: number;
+/**
+ * How an audited package reached the run: named by the project or a lockfile
+ * project (`top-level`), declared by an audited package (`transitive`),
+ * fetched with no metadata or plan to prove a parent (`unknown`), or on the
+ * allowlist graph and recorded only for advisories served past (`allowed`).
+ */
+export type AuditRelation = "top-level" | "transitive" | "unknown" | "allowed";
+export interface AuditAdvisory {
+    id: string;
+    severity: string;
+    summary: string;
+}
+/** Why one request or plan approval was audited; `advisories` only for full-mode waivers. */
+export interface PackageAuditVerdict {
+    relation: AuditRelation;
+    /** The top-level audited package that pulled it in (transitive only). */
+    via?: string;
+    advisories?: AuditAdvisory[];
+}
+/** A RegistryAuditRecord row as read back (advisories is untrusted JSON). */
+export interface PackageAuditRow {
+    ecosystem: string;
+    name: string;
+    version: string;
+    relation: string;
+    via: string | null;
+    sizeBytes: number | null;
+    advisories: unknown;
+}
+/** One audited package version as get_run, the PR body and the status comment show it. */
+export interface PackageAuditEntry {
+    ecosystem: string;
+    name: string;
+    version: string;
+    size: number | null;
+    relation: AuditRelation;
+    via?: string;
+    advisories?: AuditAdvisory[];
+}
+export declare class PackageAuditPatchError extends Error {
+}
+export declare function isPackageAuditMode(value: unknown): value is PackageAuditMode;
+/** Whether a stored mode is in force: set, and its window has not ended. */
+export declare function isPackageAuditActive(mode: string | null | undefined, until: Date | null | undefined, now: Date): mode is PackageAuditMode;
+/** The get_agent / update_agent warning while a mode is in force. */
+export declare function packageAuditActiveWarning(mode: PackageAuditMode, until: Date): string;
+/**
+ * update_agent's packageAuditMode / packageAuditMinutes semantics: a mode
+ * opens a window of the given minutes (24 hours by default), minutes alone
+ * re-arm the stored mode, and null clears both. Returns undefined when the
+ * patch names neither field; throws PackageAuditPatchError for a 400.
+ */
+export declare function resolvePackageAuditPatch(stored: {
+    mode: PackageAuditMode | null;
+}, patch: {
+    packageAuditMode?: PackageAuditMode | null;
+    packageAuditMinutes?: number;
+}, now: Date): {
+    mode: PackageAuditMode | null;
+    until: Date | null;
+} | undefined;
+export declare const MAX_AUDIT_SUMMARY_CHARS = 200;
+/** An advisory summary (OSV free text) as plain, single-line, bounded text. */
+export declare function sanitizeAuditSummary(value: unknown): string;
+/** Untrusted advisory JSON reduced to well-formed, non-malware entries (at most 16, distinct ids). */
+export declare function sanitizeAuditAdvisories(value: unknown): AuditAdvisory[];
+/** A stored verdict (RegistryApprovedVersion.audit, untrusted JSON) read back; null when absent or malformed. */
+export declare function parsePackageAuditVerdict(value: unknown): PackageAuditVerdict | null;
+export interface PackageAuditSummary {
+    entries: PackageAuditEntry[];
+    /** Names to add to the allowlist: top-level, per ecosystem, first-seen order. */
+    toApprove: {
+        ecosystem: string;
+        name: string;
+        dependencies: number;
+    }[];
+    /** Names recorded only with relation `unknown` (a direct download, or after a plan fallback): they
+     *  may be dependencies of allowlisted packages, so they are listed apart and approved only by name. */
+    unknown: {
+        ecosystem: string;
+        name: string;
+        dependencies: number;
+    }[];
+    advisoryRows: {
+        ecosystem: string;
+        name: string;
+        version: string;
+        advisory: AuditAdvisory;
+    }[];
+}
+/**
+ * A run's (or a PR's runs') audit rows deduplicated on ecosystem + name +
+ * version (advisories unioned) and ordered top-level, unknown, transitive,
+ * allowed. An unrecognised relation reads as `unknown`, so it is listed to
+ * approve rather than hidden.
+ */
+export declare function summarizePackageAudit(rows: readonly PackageAuditRow[]): PackageAuditSummary;
+/** How a name recorded with relation `unknown` is labelled wherever it is listed. */
+export declare const UNKNOWN_RELATION_LABEL = "Relation unknown \u2014 may be a dependency; approve only if needed directly";
+/**
+ * The package audit block for a PR body (`format: "pr"`, a `[!CAUTION]`
+ * banner plus the names to approve and, in full mode, the advisories served
+ * past), a status comment (`format: "status"`, short), or Slack mrkdwn
+ * (`slack`, already escaped). Control-plane text only: names, versions and
+ * ids pass through codeSpan.
+ */
+export declare function packageAuditWording(mode: PackageAuditMode, summary: PackageAuditSummary, opts?: {
+    slack?: boolean;
+    format?: "pr" | "status";
+}): string;
+/** What a short audit notice needs (a status comment, a Slack message): a bounded, count-only digest.
+ *  A type alias, not an interface, so it stays assignable to a stored JSON payload. */
+export type PackageAuditDigest = {
+    /** Names to approve, at most 10. */
+    toApprove: {
+        ecosystem: string;
+        name: string;
+    }[];
+    /** Names to approve beyond those listed. */
+    moreToApprove: number;
+    /** Names with relation `unknown`, at most 10, listed apart (see PackageAuditSummary.unknown). */
+    unknown: {
+        ecosystem: string;
+        name: string;
+    }[];
+    moreUnknown: number;
+    /** Dependencies of audited packages, recorded transitive. */
+    transitive: number;
+    /** Advisories full mode served past (0 in audit mode). */
+    advisories: number;
+};
+export declare function packageAuditDigest(mode: PackageAuditMode, summary: PackageAuditSummary): PackageAuditDigest;
+/** The short audit notice as GitHub/Jira Markdown or, with `slack`, Slack mrkdwn (already escaped). */
+export declare function packageAuditStatusText(mode: PackageAuditMode, digest: PackageAuditDigest, slack: boolean): string;
+/** A run's (or a pull request's runs') package audit: the mode and what it recorded. */
+export interface PackageAuditReport {
+    mode: PackageAuditMode;
+    entries: readonly PackageAuditEntry[];
+}
+/** Entries back as rows, so several runs' entries summarize (dedup, order) like one run's. */
+export declare function packageAuditRows(entries: readonly PackageAuditEntry[]): PackageAuditRow[];
+/**
+ * Several runs' audit reports as one (a pull request's runs): entries merged
+ * on ecosystem + name + version with advisories unioned, and the strongest
+ * mode seen (`full` over `audit`). Undefined when no run had the mode.
+ */
+export declare function mergePackageAuditReports(reports: readonly (PackageAuditReport | undefined)[]): PackageAuditReport | undefined;