auditor-lambda 0.3.40 → 0.5.0

package/dist/cli/prompts.js

@@ -0,0 +1,225 @@
+import { renderCommand } from "./args.js";
+export function nextStepCommand(root, artifactsDir) {
+    return renderCommand([
+        "audit-code",
+        "next-step",
+        "--root",
+        root,
+        "--artifacts-dir",
+        artifactsDir,
+    ]);
+}
+export function mergeAndIngestCommand(artifactsDir, runId) {
+    return renderCommand([
+        "audit-code",
+        "merge-and-ingest",
+        "--artifacts-dir",
+        artifactsDir,
+        "--run-id",
+        runId,
+    ]);
+}
+export function renderDispatchReviewPrompt(params) {
+    const mergeCommand = mergeAndIngestCommand(params.artifactsDir, params.activeReviewRun.run_id);
+    const continueCommand = nextStepCommand(params.root, params.artifactsDir);
+    const modelLine = params.hostCanSelectSubagentModel
+        ? "When launching each subagent, map `entry.model_hint.tier` (`small`, `standard`, `deep`) to an available host model without asking the user for model names."
+        : "Ignore `entry.model_hint`; this host did not report per-subagent model selection.";
+    const toolsLine = params.hostCanRestrictSubagentTools
+        ? "Restrict review subagents to read/search plus the packet submit command named in their prompt. Do not give them source edit/write tools."
+        : "Do not ask the user about per-subagent tool restrictions; this host did not report a callable restriction facility.";
+    const dispatchDataLines = params.dispatchQuotaPath
+        ? [
+            "Read these generated files:",
+            "",
+            `  Dispatch plan:  ${params.dispatchPlanPath}`,
+            `  Dispatch quota: ${params.dispatchQuotaPath}`,
+            "",
+            "Use the `wave_size` from the quota data. If `cooldown_until` is non-null, wait until that timestamp before starting the first wave.",
+            "",
+            "`host_concurrency_limit` records any detected hard host cap that contributed to `wave_size`.",
+            "",
+            "For each wave: use the `task` tool (or equivalent subagent dispatch) to launch up to `wave_size` subagents in parallel (one per entry), wait for all to finish, then start the next wave.",
+        ]
+        : [
+            "Read this generated dispatch plan:",
+            "",
+            `  ${params.dispatchPlanPath}`,
+            "",
+            "Launch one subagent for each entry in the plan.",
+        ];
+    return [
+        "# audit-code dispatch review",
+        "",
+        ...dispatchDataLines,
+        "",
+        "Pass each `entry.prompt_path` literally to its subagent; do not load packet prompt files into this orchestrator context.",
+        "",
+        "Subagent prompt shape:",
+        "",
+        '  Read and follow the audit instructions in: <entry.prompt_path>',
+        "",
+        modelLine,
+        toolsLine,
+        "",
+        "Each subagent must submit its packet through the submit command printed in its packet prompt and stop after successful submission.",
+        "",
+        "**File access pre-approval:** Each dispatch plan entry includes an `access` object with `read_paths` and `write_paths`. If your host supports per-subagent file access restrictions, pre-approve those paths before launching each subagent. Workers should not access files outside their declared paths.",
+        "",
+        "**After all waves complete:**",
+        "",
+        "Run exactly:",
+        "",
+        `  ${mergeCommand}`,
+        "",
+        "If merge-and-ingest fails, stop and report the exact command and error output. Do not manually merge results or edit audit state.",
+        "",
+        "If merge-and-ingest succeeds, run:",
+        "",
+        `  ${continueCommand}`,
+        "",
+        "Read and follow only the new step prompt path returned by that command.",
+        "",
+    ].join("\n");
+}
+export function renderSingleTaskFallbackStepPrompt(params) {
+    return [
+        "# audit-code single-task fallback step",
+        "",
+        "Use this step only because the host reported no callable subagent facility.",
+        "",
+        "Read and follow exactly this generated single-task prompt:",
+        "",
+        `  ${params.singleTaskPromptPath}`,
+        "",
+        "Complete exactly one AuditResult for the task named there, write the JSON array to the prompt's audit_results_path, run the exact worker_command from that prompt, then stop.",
+        "",
+        "Do not run dispatch commands, do not prepare packets, do not run next-step again in this turn, and do not read a report after the worker command.",
+        "",
+        "The only backend command allowed after writing the result is:",
+        "",
+        `  ${renderCommand(params.activeReviewRun.worker_command)}`,
+        "",
+    ].join("\n");
+}
+export function renderEdgeReasoningStepPrompt(params) {
+    return [
+        params.basePrompt,
+        "",
+        "## Results path",
+        "",
+        'Write the JSON object ({"rewrites":[{"from":"...","to":"...","kind":"...","reason":"..."}]}) to:',
+        "",
+        `  ${params.resultsPath}`,
+        "",
+        `Cache key (edge-set content hash): ${params.contentHash}.`,
+        "If you already produced rewrites for this exact key, you may reuse them instead of regenerating.",
+        "",
+        `Then run: ${params.continueCommand}`,
+        "",
+        "Read and follow only the new step prompt returned by that command.",
+        "",
+    ].join("\n");
+}
+export function renderEdgeReasoningDispatchPrompt(params) {
+    return [
+        "# audit-code edge reasoning (subagent dispatch)",
+        "",
+        `The dependency graph has ${params.candidateCount} low-confidence edge(s) whose`,
+        "machine-generated `reason` text can be clarified. This is a single, bounded,",
+        "optional pass: it only rewrites the `reason` string of those edges — it never",
+        "adds, removes, re-targets, or re-weights an edge.",
+        "",
+        "Dispatch exactly ONE subagent (via the `task` tool or equivalent). Hand it this",
+        "prompt file path; do not load the file into this orchestrator context:",
+        "",
+        `  ${params.promptPath}`,
+        "",
+        "Subagent prompt shape:",
+        "",
+        "  Read and follow the edge-reasoning instructions in: <prompt path above>",
+        "",
+        'The subagent must write its JSON result ({"rewrites":[...]}) to:',
+        "",
+        `  ${params.resultsPath}`,
+        "",
+        `Cache key (edge-set content hash): ${params.contentHash}.`,
+        "If you hold a cached result for this exact key from a previous run, you may write",
+        "it to the results path directly instead of dispatching a subagent.",
+        "",
+        "**File access pre-approval:** if your host supports per-subagent file access",
+        `restrictions, allow the subagent to read ${params.promptPath} and write ${params.resultsPath}.`,
+        "",
+        "After the subagent writes the result, run exactly:",
+        "",
+        `  ${params.continueCommand}`,
+        "",
+        "Read and follow only the new step prompt returned by that command.",
+        "",
+    ].join("\n");
+}
+export function renderPresentReportPrompt(finalReportPath) {
+    return [
+        "# audit-code present report",
+        "",
+        "The deterministic audit is complete.",
+        "",
+        `Read the final audit report from: ${finalReportPath}`,
+        "",
+        "Present the completed audit with work blocks first.",
+        "",
+        "Do not run the orchestrator again for this completed audit.",
+        "",
+    ].join("\n");
+}
+export function renderAnalyzerInstallPrompt(params) {
+    const analyzerLines = params.unresolved.flatMap((entry) => [
+        `- **${entry.id}** — needs \`${entry.dependency ?? entry.id}\`; ${entry.supportedCount} in-scope file(s) would be analyzed.`,
+    ]);
+    const exampleObject = `{ ${params.unresolved
+        .map((entry) => `"${entry.id}": "ephemeral"`)
+        .join(", ")} }`;
+    return [
+        "# audit-code analyzer install",
+        "",
+        "The deterministic regex graph is built. These optional language analyzers can",
+        "produce a richer graph (real module resolution, inheritance, and a call graph),",
+        "but their compiler dependency is not installed in the audited repo:",
+        "",
+        ...analyzerLines,
+        "",
+        "Choose how to resolve each one and write a JSON object of `{ \"<analyzer-id>\": <setting> }`",
+        "to the decisions path below. Valid settings:",
+        "",
+        "- `ephemeral` — install into a shared, version-keyed cache (never touches this project); compile once, reuse across audits.",
+        "- `permanent` — same as `ephemeral` but a durable opt-in recorded in session config.",
+        "- `skip` — do not run this analyzer; keep the regex floor.",
+        "",
+        "Default if you are unsure or cannot install: choose `skip`. The audit proceeds either way.",
+        "",
+        "## Decisions path",
+        "",
+        "Write your choices to:",
+        "",
+        `  ${params.decisionsPath}`,
+        "",
+        `Example: ${exampleObject}`,
+        "",
+        `Then run: ${params.continueCommand}`,
+        "",
+        "Read and follow only the new step prompt returned by that command.",
+        "",
+    ].join("\n");
+}
+export function renderBlockedStepPrompt(reason) {
+    return [
+        "# audit-code blocked",
+        "",
+        "The audit cannot continue automatically from this step.",
+        "",
+        "Report this blocker verbatim and stop:",
+        "",
+        reason,
+        "",
+    ].join("\n");
+}

package/dist/cli/steps.d.ts

@@ -0,0 +1,29 @@
+import type { StepStatus } from "@audit-tools/shared";
+import type { AccessDeclaration } from "../types/workerSession.js";
+export declare const STEP_CONTRACT_VERSION = "audit-code-step/v1alpha1";
+export type StepKind = "dispatch_review" | "single_task_fallback" | "design_review" | "analyzer_install" | "edge_reasoning" | "edge_reasoning_dispatch" | "synthesis_narrative" | "present_report" | "blocked";
+export interface StepArtifact {
+    contract_version: typeof STEP_CONTRACT_VERSION;
+    step_kind: StepKind;
+    prompt_path: string;
+    status: StepStatus;
+    run_id: string | null;
+    allowed_commands: string[];
+    stop_condition: string;
+    repo_root: string;
+    artifacts_dir: string;
+    artifact_paths: Record<string, string | null>;
+    access?: AccessDeclaration;
+}
+export declare function writeCurrentStep(params: {
+    artifactsDir: string;
+    stepKind: StepKind;
+    status: StepStatus;
+    runId: string | null;
+    allowedCommands: string[];
+    stopCondition: string;
+    repoRoot: string;
+    artifactPaths: Record<string, string | null>;
+    prompt: string;
+    access?: AccessDeclaration;
+}): Promise<StepArtifact>;

package/dist/cli/steps.js

@@ -0,0 +1,30 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeJsonFile } from "@audit-tools/shared";
+export const STEP_CONTRACT_VERSION = "audit-code-step/v1alpha1";
+export async function writeCurrentStep(params) {
+    const stepsDir = join(params.artifactsDir, "steps");
+    await mkdir(stepsDir, { recursive: true });
+    const promptPath = join(stepsDir, "current-prompt.md");
+    const stepPath = join(stepsDir, "current-step.json");
+    await writeFile(promptPath, params.prompt, "utf8");
+    const step = {
+        contract_version: STEP_CONTRACT_VERSION,
+        step_kind: params.stepKind,
+        prompt_path: promptPath,
+        status: params.status,
+        run_id: params.runId,
+        allowed_commands: params.allowedCommands,
+        stop_condition: params.stopCondition,
+        repo_root: params.repoRoot,
+        artifacts_dir: params.artifactsDir,
+        artifact_paths: {
+            current_step: stepPath,
+            current_prompt: promptPath,
+            ...params.artifactPaths,
+        },
+        ...(params.access ? { access: params.access } : {}),
+    };
+    await writeJsonFile(stepPath, step);
+    return step;
+}

package/dist/cli/waveManifest.d.ts

@@ -0,0 +1,40 @@
+import type { AuditTask } from "../types.js";
+declare const WAVE_MANIFEST_CONTRACT = "audit-code-wave/v1alpha1";
+export interface WaveSlotEntry {
+    run_id: string;
+    task_path: string;
+    prompt_path: string;
+    result_path: string;
+    stdout_path: string;
+    stderr_path: string;
+    status_path: string;
+    audit_results_path: string;
+    pending_tasks_path: string;
+    task_ids: string[];
+}
+export interface WaveManifest {
+    contract_version: typeof WAVE_MANIFEST_CONTRACT;
+    obligation_id: string;
+    started_at: string;
+    pid: number;
+    slots: WaveSlotEntry[];
+}
+export declare function waveManifestPath(artifactsDir: string): string;
+export declare function writeWaveManifest(artifactsDir: string, manifest: Omit<WaveManifest, "contract_version">): Promise<void>;
+export declare function readWaveManifest(artifactsDir: string): Promise<WaveManifest | null>;
+export declare function removeWaveManifest(artifactsDir: string): Promise<void>;
+export declare function buildWaveSlotEntry(slot: {
+    runId: string;
+    paths: {
+        taskPath: string;
+        promptPath: string;
+        resultPath: string;
+        stdoutPath: string;
+        stderrPath: string;
+        statusPath: string;
+    };
+    auditResultsPath: string;
+    pendingTasksPath: string;
+    group: AuditTask[];
+}): WaveSlotEntry;
+export {};

package/dist/cli/waveManifest.js

@@ -0,0 +1,41 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { isFileMissingError, readJsonFile, writeJsonFile } from "@audit-tools/shared";
+const WAVE_MANIFEST_FILENAME = "wave-manifest.json";
+const WAVE_MANIFEST_CONTRACT = "audit-code-wave/v1alpha1";
+export function waveManifestPath(artifactsDir) {
+    return join(artifactsDir, "dispatch", WAVE_MANIFEST_FILENAME);
+}
+export async function writeWaveManifest(artifactsDir, manifest) {
+    await writeJsonFile(waveManifestPath(artifactsDir), {
+        contract_version: WAVE_MANIFEST_CONTRACT,
+        ...manifest,
+    });
+}
+export async function readWaveManifest(artifactsDir) {
+    try {
+        return await readJsonFile(waveManifestPath(artifactsDir));
+    }
+    catch (error) {
+        if (isFileMissingError(error))
+            return null;
+        throw error;
+    }
+}
+export async function removeWaveManifest(artifactsDir) {
+    await rm(waveManifestPath(artifactsDir), { force: true });
+}
+export function buildWaveSlotEntry(slot) {
+    return {
+        run_id: slot.runId,
+        task_path: slot.paths.taskPath,
+        prompt_path: slot.paths.promptPath,
+        result_path: slot.paths.resultPath,
+        stdout_path: slot.paths.stdoutPath,
+        stderr_path: slot.paths.stderrPath,
+        status_path: slot.paths.statusPath,
+        audit_results_path: slot.auditResultsPath,
+        pending_tasks_path: slot.pendingTasksPath,
+        task_ids: slot.group.map((t) => t.task_id),
+    };
+}

package/dist/cli/workerResult.d.ts

@@ -0,0 +1,18 @@
+import type { WorkerResult } from "../types/workerResult.js";
+import type { RunPaths } from "../io/runArtifacts.js";
+export declare const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
+export declare function buildWorkerResult(params: {
+    runId: string;
+    obligationId: string | null;
+    status: WorkerResult["status"];
+    progressMade: boolean;
+    selectedExecutor: string | null;
+    artifactsWritten: string[];
+    summary: string;
+    nextLikelyStep: string | null;
+    errors: string[];
+}): WorkerResult;
+export declare function persistWorkerRunArtifacts(paths: RunPaths, workerResult: WorkerResult, executionMode: string): Promise<void>;
+export declare function isWorkerResult(value: unknown): value is WorkerResult;
+export declare function buildWorkerFailureBlocker(workerResult: WorkerResult): string;
+export declare function formatAuditResultValidationError(issues: ReturnType<typeof import("../validation/auditResults.js").validateAuditResults>): string;

package/dist/cli/workerResult.js

@@ -0,0 +1,42 @@
+import { writeJsonFile } from "@audit-tools/shared";
+import { formatAuditResultIssues } from "../validation/auditResults.js";
+export const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
+export function buildWorkerResult(params) {
+    return {
+        contract_version: WORKER_RESULT_CONTRACT_VERSION,
+        run_id: params.runId,
+        obligation_id: params.obligationId,
+        status: params.status,
+        progress_made: params.progressMade,
+        selected_executor: params.selectedExecutor,
+        artifacts_written: params.artifactsWritten,
+        summary: params.summary,
+        next_likely_step: params.nextLikelyStep,
+        errors: params.errors,
+    };
+}
+export async function persistWorkerRunArtifacts(paths, workerResult, executionMode) {
+    await writeJsonFile(paths.resultPath, workerResult);
+    await writeJsonFile(paths.statusPath, {
+        run_id: workerResult.run_id,
+        status: workerResult.status,
+        execution_mode: executionMode,
+        result_path: paths.resultPath,
+    });
+}
+export function isWorkerResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.contract_version ===
+            WORKER_RESULT_CONTRACT_VERSION);
+}
+export function buildWorkerFailureBlocker(workerResult) {
+    const details = workerResult.errors.filter((error) => error.trim().length > 0);
+    return details.length > 0
+        ? `${workerResult.summary} ${details.join(" ")}`
+        : workerResult.summary;
+}
+export function formatAuditResultValidationError(issues) {
+    return (`audit-results validation failed with ${issues.length} error(s):\n` +
+        formatAuditResultIssues(issues));
+}

package/dist/cli.d.ts

@@ -1,24 +1,5 @@
-import type { SessionConfig } from "./types/sessionConfig.js";
-type UiMode = "visible" | "headless";
-declare function getFlag(argv: string[], name: string, fallback?: string): string | undefined;
-declare function hasFlag(argv: string[], name: string): boolean;
-export declare function resolveHostDispatchCapability(options: {
-    explicit?: boolean;
-    sessionConfig: SessionConfig;
-    env?: NodeJS.ProcessEnv;
-}): boolean;
-declare function getArtifactsDir(argv: string[]): string;
-declare function getRootDir(argv: string[]): string;
-declare function warnIfNotGitRepo(root: string): void;
-declare function getBatchResultsDir(argv: string[]): string | undefined;
-declare function getMaxRuns(argv: string[]): number;
-declare function getAgentBatchSize(argv: string[], sessionConfig: SessionConfig): number;
-declare function getParallelWorkers(argv: string[], sessionConfig: SessionConfig): number;
-declare function getTimeoutMs(argv: string[], sessionConfig: SessionConfig): number;
-declare function chunkArray<T>(arr: T[], size: number): T[][];
-declare function getUiMode(argv: string[], fallback?: UiMode): UiMode;
-declare function countLines(path: string): Promise<number>;
-declare function looksLikeCliFlag(value: string | undefined): boolean;
+export { resolveHostDispatchCapability, DIRECT_CLI_DEFAULTS, getFlag, hasFlag, getOptionalBooleanFlag, getArtifactsDir, getRootDir, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines, warnIfNotGitRepo, } from "./cli/args.js";
+import { type UiMode, getFlag, hasFlag, getArtifactsDir, getRootDir, warnIfNotGitRepo, getBatchResultsDir, getMaxRuns, getAgentBatchSize, getParallelWorkers, getTimeoutMs, chunkArray, getUiMode, looksLikeCliFlag, countLines } from "./cli/args.js";
 export declare const cliTestUtils: {
     defaults: {
         rootDir: string;
@@ -46,4 +27,3 @@ export declare const cliTestUtils: {
 };
 export declare function runSample(argv?: string[]): Promise<void>;
 export declare function runCli(argv: string[]): Promise<void>;
-export {};