voratiq 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/commands/shared/session-id.d.ts

@@ -0,0 +1 @@
+export { generateSessionId } from "../../utils/session-id.js";

package/dist/commands/shared/session-id.js

@@ -0,0 +1 @@
+export { generateSessionId } from "../../utils/session-id.js";

package/dist/commands/spec/command.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedExtraContextFile } from "../../competition/shared/extra-context.js";
+import { type SpecAgentEntry, type SpecRecord } from "../../domain/spec/model/types.js";
+import type { SpecProgressRenderer } from "../../render/transcripts/spec.js";
+export interface ExecuteSpecCommandInput {
+    root: string;
+    specsFilePath: string;
+    description: string;
+    agentIds?: readonly string[];
+    profileName?: string;
+    maxParallel?: number;
+    title?: string;
+    extraContextFiles?: readonly ResolvedExtraContextFile[];
+    onStatus?: (message: string) => void;
+    renderer?: SpecProgressRenderer;
+}
+export interface ExecuteSpecCommandResult {
+    sessionId: string;
+    status: string;
+    record: SpecRecord;
+    agents: readonly SpecAgentEntry[];
+}
+export declare function executeSpecCommand(input: ExecuteSpecCommandInput): Promise<ExecuteSpecCommandResult>;

package/dist/commands/spec/command.js

@@ -0,0 +1,330 @@
+import { executeCompetitionWithAdapter } from "../../competition/command-adapter.js";
+import { AgentNotFoundError } from "../../configs/agents/errors.js";
+import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
+import { buildLifecycleStartFields, buildOperationLifecycleCompleteFields, } from "../../domain/shared/lifecycle.js";
+import { createSpecCompetitionAdapter, } from "../../domain/spec/competition/adapter.js";
+import { deriveSpecStatusFromAgents, } from "../../domain/spec/model/types.js";
+import { appendSpecRecord, finalizeSpecRecord, flushSpecRecordBuffer, rewriteSpecRecord, } from "../../domain/spec/persistence/adapter.js";
+import { buildPersistedExtraContextFields } from "../../extra-context/contract.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { getHeadRevision } from "../../utils/git.js";
+import { resolveEffectiveMaxParallel } from "../shared/max-parallel.js";
+import { resolveStageCompetitors } from "../shared/resolve-stage-competitors.js";
+import { generateSessionId } from "../shared/session-id.js";
+import { SpecAgentNotFoundError, SpecGenerationFailedError } from "./errors.js";
+export async function executeSpecCommand(input) {
+    const { root, specsFilePath, description, agentIds: cliAgentIds, profileName, maxParallel: requestedMaxParallel, title: providedTitle, extraContextFiles = [], onStatus, renderer, } = input;
+    let competitors;
+    try {
+        const normalizedCliIds = cliAgentIds && cliAgentIds.length > 0 ? [...cliAgentIds] : undefined;
+        const resolution = resolveStageCompetitors({
+            root,
+            stageId: "spec",
+            cliAgentIds: normalizedCliIds,
+            profileName,
+        });
+        competitors = resolution.competitors;
+        if (competitors.length === 0) {
+            throw new SpecGenerationFailedError(["Spec agent resolution failed."]);
+        }
+    }
+    catch (error) {
+        if (error instanceof AgentNotFoundError) {
+            throw new SpecAgentNotFoundError(error.agentId);
+        }
+        throw error;
+    }
+    const environment = loadEnvironmentConfig({ root });
+    const effectiveMaxParallel = resolveEffectiveMaxParallel({
+        competitorCount: competitors.length,
+        requestedMaxParallel,
+    });
+    const specTitle = providedTitle && providedTitle.trim().length > 0
+        ? providedTitle.trim()
+        : undefined;
+    const baseRevisionSha = await getHeadRevision(root);
+    const sessionId = generateSessionId();
+    const startedAt = new Date().toISOString();
+    const createdAt = startedAt;
+    const initialAgents = competitors.map((agent) => ({
+        agentId: agent.id,
+        status: "queued",
+    }));
+    const record = {
+        sessionId,
+        createdAt,
+        startedAt,
+        status: "running",
+        baseRevisionSha,
+        description,
+        agents: initialAgents,
+        ...buildPersistedExtraContextFields(extraContextFiles),
+    };
+    await appendSpecRecord({
+        root,
+        specsFilePath,
+        record,
+    });
+    let currentAgents = [...initialAgents];
+    onStatus?.("Generating specification…");
+    renderer?.begin({
+        sessionId,
+        createdAt,
+        startedAt,
+        workspacePath: `.voratiq/spec/sessions/${sessionId}`,
+        status: "running",
+    });
+    let executionResults;
+    try {
+        const baseAdapter = createSpecCompetitionAdapter({
+            root,
+            sessionId,
+            description,
+            specTitle,
+            environment,
+            extraContextFiles,
+        });
+        executionResults = await executeCompetitionWithAdapter({
+            candidates: [...competitors],
+            maxParallel: effectiveMaxParallel,
+            adapter: {
+                ...baseAdapter,
+                onPreparationFailure: async (result) => {
+                    currentAgents = await persistSpecAgentFailure({
+                        root,
+                        specsFilePath,
+                        sessionId,
+                        agentId: result.agentId,
+                        tokenUsage: result.tokenUsage,
+                        error: result.error ?? null,
+                    });
+                    const failedAgent = currentAgents.find((agent) => agent.agentId === result.agentId);
+                    renderer?.update({
+                        agentId: result.agentId,
+                        status: "failed",
+                        startedAt: failedAgent?.startedAt,
+                        completedAt: failedAgent?.completedAt,
+                        tokenUsage: result.tokenUsage,
+                        tokenUsageResult: result.tokenUsageResult,
+                    });
+                },
+                onCandidateRunning: async (prepared, index) => {
+                    await baseAdapter.onCandidateRunning?.(prepared, index);
+                    currentAgents = await persistSpecAgentRunning({
+                        root,
+                        specsFilePath,
+                        sessionId,
+                        agentId: prepared.candidate.id,
+                    });
+                    const runningAgent = currentAgents.find((agent) => agent.agentId === prepared.candidate.id);
+                    renderer?.update({
+                        agentId: prepared.candidate.id,
+                        status: "running",
+                        startedAt: runningAgent?.startedAt,
+                    });
+                },
+                onCandidateCompleted: async (_prepared, result) => {
+                    currentAgents = await persistSpecAgentCompletion({
+                        root,
+                        specsFilePath,
+                        sessionId,
+                        result,
+                    });
+                    const completedAgent = currentAgents.find((agent) => agent.agentId === result.agentId);
+                    renderer?.update({
+                        agentId: result.agentId,
+                        status: completedAgent?.status ?? result.status,
+                        startedAt: completedAgent?.startedAt,
+                        completedAt: completedAgent?.completedAt,
+                        tokenUsage: result.tokenUsage,
+                        tokenUsageResult: result.tokenUsageResult,
+                    });
+                },
+            },
+        });
+    }
+    catch (error) {
+        const detail = toErrorMessage(error);
+        await finalizeSpecRecord({
+            root,
+            specsFilePath,
+            sessionId,
+            status: "failed",
+            error: detail,
+        });
+        renderer?.complete("failed");
+        await flushSpecRecordBuffer({ specsFilePath, sessionId });
+        throw new SpecGenerationFailedError([detail]);
+    }
+    const agentEntries = currentAgents.some((agent) => agent.status === "succeeded" || agent.status === "failed")
+        ? currentAgents
+        : mapExecutionResultsToSpecAgents(executionResults, startedAt);
+    // Derive session status from agent outcomes.
+    const sessionStatus = deriveSpecStatusFromAgents(agentEntries.map((a) => a.status));
+    const latestRecord = await finalizeSpecRecord({
+        root,
+        specsFilePath,
+        sessionId,
+        status: sessionStatus,
+        agents: agentEntries,
+        error: sessionStatus === "failed" ? collectAgentErrors(agentEntries) : undefined,
+    });
+    await flushSpecRecordBuffer({ specsFilePath, sessionId });
+    renderer?.complete(latestRecord.status, {
+        startedAt: latestRecord.startedAt,
+        completedAt: latestRecord.completedAt,
+    });
+    if (sessionStatus === "failed") {
+        const errorDetails = agentEntries
+            .filter((a) => a.error)
+            .map((a) => `${a.agentId}: ${a.error}`);
+        throw new SpecGenerationFailedError(errorDetails.length > 0
+            ? errorDetails
+            : ["All agents failed to generate a specification."]);
+    }
+    return {
+        sessionId,
+        status: latestRecord.status,
+        record: latestRecord,
+        agents: latestRecord.agents,
+    };
+}
+function collectAgentErrors(agents) {
+    const errors = agents
+        .filter((a) => a.error)
+        .map((a) => `${a.agentId}: ${a.error}`);
+    return errors.length > 0 ? errors.join("; ") : null;
+}
+async function persistSpecAgentRunning(options) {
+    const { root, specsFilePath, sessionId, agentId } = options;
+    const timestamp = new Date().toISOString();
+    const updated = await rewriteSpecRecord({
+        root,
+        specsFilePath,
+        sessionId,
+        mutate: (record) => ({
+            ...record,
+            agents: record.agents.map((agent) => agent.agentId === agentId
+                ? {
+                    ...agent,
+                    status: "running",
+                    ...buildLifecycleStartFields({
+                        existingStartedAt: agent.startedAt,
+                        timestamp,
+                    }),
+                    completedAt: undefined,
+                    error: null,
+                }
+                : agent),
+        }),
+    });
+    return [...updated.agents];
+}
+async function persistSpecAgentCompletion(options) {
+    const { root, specsFilePath, sessionId, result } = options;
+    const completedAt = new Date().toISOString();
+    const updated = await rewriteSpecRecord({
+        root,
+        specsFilePath,
+        sessionId,
+        mutate: (record) => ({
+            ...record,
+            agents: record.agents.map((agent) => {
+                if (agent.agentId !== result.agentId) {
+                    return agent;
+                }
+                const startedAt = buildLifecycleStartFields({
+                    existingStartedAt: agent.startedAt,
+                    timestamp: completedAt,
+                }).startedAt;
+                const completeFields = buildOperationLifecycleCompleteFields({
+                    existing: {
+                        startedAt,
+                        completedAt: agent.completedAt,
+                    },
+                    completedAt,
+                });
+                if (result.status === "succeeded") {
+                    return {
+                        ...agent,
+                        status: "succeeded",
+                        ...completeFields,
+                        outputPath: result.outputPath,
+                        dataPath: result.dataPath,
+                        tokenUsage: result.tokenUsage,
+                        error: null,
+                    };
+                }
+                return {
+                    ...agent,
+                    status: "failed",
+                    ...completeFields,
+                    tokenUsage: result.tokenUsage,
+                    error: result.error ?? null,
+                };
+            }),
+        }),
+    });
+    return [...updated.agents];
+}
+async function persistSpecAgentFailure(options) {
+    const { root, specsFilePath, sessionId, agentId, tokenUsage, error } = options;
+    const completedAt = new Date().toISOString();
+    const updated = await rewriteSpecRecord({
+        root,
+        specsFilePath,
+        sessionId,
+        mutate: (record) => ({
+            ...record,
+            agents: record.agents.map((agent) => {
+                if (agent.agentId !== agentId) {
+                    return agent;
+                }
+                const startedAt = buildLifecycleStartFields({
+                    existingStartedAt: agent.startedAt,
+                    timestamp: completedAt,
+                }).startedAt;
+                const completeFields = buildOperationLifecycleCompleteFields({
+                    existing: {
+                        startedAt,
+                        completedAt: agent.completedAt,
+                    },
+                    completedAt,
+                });
+                return {
+                    ...agent,
+                    status: "failed",
+                    ...completeFields,
+                    ...(tokenUsage ? { tokenUsage } : {}),
+                    error: error ?? null,
+                };
+            }),
+        }),
+    });
+    return [...updated.agents];
+}
+function mapExecutionResultsToSpecAgents(executionResults, startedAt) {
+    return executionResults.map((result) => {
+        const completedAt = new Date().toISOString();
+        const base = {
+            agentId: result.agentId,
+            startedAt,
+            completedAt,
+        };
+        if (result.status === "succeeded") {
+            return {
+                ...base,
+                status: "succeeded",
+                outputPath: result.outputPath,
+                dataPath: result.dataPath,
+                tokenUsage: result.tokenUsage,
+            };
+        }
+        return {
+            ...base,
+            status: "failed",
+            tokenUsage: result.tokenUsage,
+            error: result.error ?? null,
+        };
+    });
+}

package/dist/commands/spec/errors.d.ts

@@ -0,0 +1,11 @@
+import { CliError } from "../../cli/errors.js";
+export declare class SpecError extends CliError {
+    constructor(headline: string, detailLines?: readonly string[], hintLines?: readonly string[]);
+}
+export declare class SpecAgentNotFoundError extends SpecError {
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+export declare class SpecGenerationFailedError extends SpecError {
+    constructor(detailLines?: readonly string[]);
+}

package/dist/commands/spec/errors.js

@@ -0,0 +1,23 @@
+import { CliError } from "../../cli/errors.js";
+export class SpecError extends CliError {
+    constructor(headline, detailLines = [], hintLines = []) {
+        super(headline, detailLines, hintLines);
+        this.name = "SpecError";
+    }
+}
+export class SpecAgentNotFoundError extends SpecError {
+    agentId;
+    constructor(agentId) {
+        super(`Agent \`${agentId}\` not found in \`agents.yaml\`.`, [], ["Add this agent to `agents.yaml`."]);
+        this.agentId = agentId;
+        this.name = "SpecAgentNotFoundError";
+    }
+}
+export class SpecGenerationFailedError extends SpecError {
+    constructor(detailLines = []) {
+        super("Specification generation failed.", detailLines, [
+            "Inspect `stderr.log` to diagnose the failure.",
+        ]);
+        this.name = "SpecGenerationFailedError";
+    }
+}

package/dist/commands/verify/agents.d.ts

@@ -0,0 +1,8 @@
+import type { AgentDefinition } from "../../configs/agents/types.js";
+export declare function resolveVerificationAgents(options: {
+    agentIds?: readonly string[];
+    root: string;
+    agentOverrideFlag?: string;
+    profileName?: string;
+}): AgentDefinition[];
+export declare function assertVerifierPreflight(agents: readonly AgentDefinition[]): Promise<void>;

package/dist/commands/verify/agents.js

@@ -0,0 +1,29 @@
+import { verifyAgentProviders } from "../../agents/runtime/auth.js";
+import { AgentNotFoundError } from "../../configs/agents/errors.js";
+import { resolveStageCompetitors } from "../shared/resolve-stage-competitors.js";
+export function resolveVerificationAgents(options) {
+    const { agentIds, root, agentOverrideFlag, profileName } = options;
+    try {
+        const resolution = resolveStageCompetitors({
+            root,
+            stageId: "verify",
+            cliAgentIds: agentIds,
+            cliOverrideFlag: agentOverrideFlag,
+            profileName,
+        });
+        return [...resolution.competitors];
+    }
+    catch (error) {
+        if (error instanceof AgentNotFoundError) {
+            throw new Error(`Verifier agent not found: ${error.agentId}`);
+        }
+        throw error;
+    }
+}
+export async function assertVerifierPreflight(agents) {
+    const providerIssues = await verifyAgentProviders(agents.map((agent) => ({ id: agent.id, provider: agent.provider })));
+    if (providerIssues.length > 0) {
+        const detail = providerIssues.map((issue) => issue.message).join("; ");
+        throw new Error(`Verifier preflight failed: ${detail}`);
+    }
+}

package/dist/commands/verify/command.d.ts

@@ -0,0 +1,23 @@
+import type { VerificationRecord } from "../../domain/verify/model/types.js";
+import type { VerifyProgressRenderer } from "../../render/transcripts/verify.js";
+import { type VerifyTargetSelection } from "./targets.js";
+export interface VerifyCommandInput {
+    root: string;
+    specsFilePath: string;
+    runsFilePath: string;
+    reductionsFilePath: string;
+    messagesFilePath: string;
+    verificationsFilePath: string;
+    target: VerifyTargetSelection;
+    agentIds?: readonly string[];
+    agentOverrideFlag?: string;
+    profileName?: string;
+    maxParallel?: number;
+    extraContextFiles?: readonly import("../../competition/shared/extra-context.js").ResolvedExtraContextFile[];
+    renderer?: VerifyProgressRenderer;
+}
+export interface VerifyCommandResult {
+    verificationId: string;
+    record: VerificationRecord;
+}
+export declare function executeVerifyCommand(input: VerifyCommandInput): Promise<VerifyCommandResult>;

package/dist/commands/verify/command.js

@@ -0,0 +1,168 @@
+import { teardownSessionAuth } from "../../agents/runtime/registry.js";
+import { createTeardownController } from "../../competition/shared/teardown.js";
+import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
+import { loadVerificationConfig } from "../../configs/verification/loader.js";
+import { buildBlindedAliasMap } from "../../domain/verify/competition/blinding.js";
+import { deriveVerificationStatusFromMethods, maybePersistSelectedSpecPath, } from "../../domain/verify/competition/finalize.js";
+import { executeAndPersistProgrammaticMethod } from "../../domain/verify/competition/programmatic.js";
+import { executeAndPersistRubricMethods } from "../../domain/verify/competition/rubric.js";
+import { createVerificationRecordMutators } from "../../domain/verify/model/mutators.js";
+import { appendVerificationRecord, flushVerificationRecordBuffer, } from "../../domain/verify/persistence/adapter.js";
+import { buildPersistedExtraContextFields } from "../../extra-context/contract.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { normalizePathForDisplay, relativeToRoot } from "../../utils/path.js";
+import { resolveWorkspacePath, VORATIQ_VERIFICATION_SESSIONS_DIR, } from "../../workspace/structure.js";
+import { generateSessionId } from "../shared/session-id.js";
+import { assertVerifierPreflight, resolveVerificationAgents, } from "./agents.js";
+import { finalizeActiveVerification, registerActiveVerification, } from "./lifecycle.js";
+import { resolveVerifyRubricMaxParallel } from "./max-parallel.js";
+import { resolveVerifyTarget } from "./targets.js";
+export async function executeVerifyCommand(input) {
+    const { root, specsFilePath, runsFilePath, reductionsFilePath, messagesFilePath, verificationsFilePath, target, agentIds, agentOverrideFlag, profileName, maxParallel, extraContextFiles = [], renderer, } = input;
+    const resolvedTarget = await resolveVerifyTarget({
+        root,
+        specsFilePath,
+        runsFilePath,
+        reductionsFilePath,
+        messagesFilePath,
+        verificationsFilePath,
+        target,
+    });
+    const verificationConfig = loadVerificationConfig({ root });
+    const verificationAgents = resolveVerificationAgents({
+        agentIds,
+        root,
+        agentOverrideFlag,
+        profileName,
+    });
+    await assertVerifierPreflight(verificationAgents);
+    const environment = loadEnvironmentConfig({ root });
+    const verificationId = generateSessionId();
+    const createdAt = new Date().toISOString();
+    const aliasMap = buildBlindedAliasMap(resolvedTarget);
+    const rubricMaxParallel = resolveVerifyRubricMaxParallel({
+        targetKind: resolvedTarget.target.kind,
+        verificationConfig,
+        verifierAgentCount: verificationAgents.length,
+        requestedMaxParallel: maxParallel,
+    });
+    await appendVerificationRecord({
+        root,
+        verificationsFilePath,
+        record: {
+            sessionId: verificationId,
+            createdAt,
+            status: "queued",
+            target: resolvedTarget.target,
+            ...buildPersistedExtraContextFields(extraContextFiles),
+            ...(aliasMap ? { blinded: { enabled: true, aliasMap } } : {}),
+            methods: [],
+        },
+    });
+    renderer?.begin({
+        verificationId,
+        createdAt,
+        startedAt: createdAt,
+        workspacePath: normalizePathForDisplay(relativeToRoot(root, resolveWorkspacePath(root, VORATIQ_VERIFICATION_SESSIONS_DIR, verificationId))),
+        status: "running",
+    });
+    const teardown = createTeardownController(`verify \`${verificationId}\``);
+    teardown.addAction({
+        key: `verify-auth:${verificationId}`,
+        label: "session auth",
+        cleanup: async () => {
+            await teardownSessionAuth(verificationId);
+        },
+    });
+    registerActiveVerification({
+        root,
+        verificationsFilePath,
+        verificationId,
+        teardown,
+    });
+    const mutators = createVerificationRecordMutators({
+        root,
+        verificationsFilePath,
+        verificationId,
+    });
+    await mutators.recordVerificationRunning(createdAt);
+    try {
+        const [programmaticResult, rubricResult] = await Promise.allSettled([
+            executeAndPersistProgrammaticMethod({
+                root,
+                verificationId,
+                resolvedTarget,
+                verificationConfig,
+                environment,
+                mutators,
+                renderer,
+            }),
+            executeAndPersistRubricMethods({
+                root,
+                verificationId,
+                resolvedTarget,
+                verificationConfig,
+                verifierAgents: verificationAgents,
+                aliasMap,
+                environment,
+                extraContextFiles,
+                maxParallel: rubricMaxParallel,
+                teardown,
+                mutators,
+                renderer,
+            }),
+        ]);
+        if (programmaticResult.status === "rejected") {
+            throw programmaticResult.reason;
+        }
+        if (rubricResult.status === "rejected") {
+            throw rubricResult.reason;
+        }
+        const persistedRecord = await mutators.readRecord();
+        if (!persistedRecord) {
+            throw new Error(`Verification record \`${verificationId}\` not found after method execution.`);
+        }
+        await maybePersistSelectedSpecPath({
+            root,
+            verificationsFilePath,
+            verificationId,
+            resolvedTarget,
+            aliasMap,
+            methods: persistedRecord.methods,
+        });
+        const record = await completeVerificationRecord({
+            mutators,
+            status: deriveVerificationStatusFromMethods(persistedRecord.methods),
+        });
+        renderer?.complete(record.status, {
+            startedAt: record.startedAt,
+            completedAt: record.completedAt,
+        });
+        return { verificationId, record };
+    }
+    catch (error) {
+        const failedRecord = await completeVerificationRecord({
+            mutators,
+            status: "failed",
+            error: toErrorMessage(error),
+        }).catch(() => undefined);
+        if (failedRecord) {
+            renderer?.complete(failedRecord.status, {
+                startedAt: failedRecord.startedAt,
+                completedAt: failedRecord.completedAt,
+            });
+            await flushVerificationRecordBuffer({
+                verificationsFilePath,
+                sessionId: verificationId,
+            }).catch(() => { });
+        }
+        throw error;
+    }
+    finally {
+        await finalizeActiveVerification(verificationId);
+    }
+}
+async function completeVerificationRecord(options) {
+    const { mutators, status, error } = options;
+    return await mutators.completeVerification({ status, error });
+}

package/dist/commands/verify/lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { TeardownController } from "../../competition/shared/teardown.js";
+import type { VerificationStatus } from "../../status/index.js";
+export declare const VERIFY_ABORT_DETAIL = "Verification aborted before completion.";
+interface ActiveVerificationContext {
+    root: string;
+    verificationsFilePath: string;
+    verificationId: string;
+    teardown?: TeardownController;
+}
+export declare function registerActiveVerification(context: ActiveVerificationContext): void;
+export declare function clearActiveVerification(verificationId: string): void;
+export declare function terminateActiveVerification(status: Extract<VerificationStatus, "failed" | "aborted">): Promise<void>;
+export declare function finalizeActiveVerification(verificationId: string): Promise<void>;
+export {};