voratiq 0.1.0-beta.0

package/dist/utils/yaml-reader.d.ts

@@ -0,0 +1,14 @@
+export interface YamlParseErrorDetail {
+    reason?: string;
+    message?: string;
+    line?: number;
+    column?: number;
+    error: unknown;
+    isYamlError: boolean;
+}
+export interface ParseYamlDocumentOptions<TError extends Error> {
+    emptyValue?: unknown;
+    onEmpty?: () => void;
+    formatError: (detail: YamlParseErrorDetail) => TError;
+}
+export declare function parseYamlDocument<TError extends Error>(content: string, options: ParseYamlDocumentOptions<TError>): unknown;

package/dist/utils/yaml-reader.js

@@ -0,0 +1,41 @@
+import { load } from "js-yaml";
+import { toErrorMessage } from "./errors.js";
+import { isYamlException } from "./yaml.js";
+const DEFAULT_EMPTY_VALUE = {};
+export function parseYamlDocument(content, options) {
+    const { emptyValue = DEFAULT_EMPTY_VALUE, onEmpty, formatError } = options;
+    const source = content.trim();
+    if (source.length === 0) {
+        onEmpty?.();
+        return emptyValue;
+    }
+    try {
+        const document = load(source, { json: false });
+        return document ?? emptyValue;
+    }
+    catch (error) {
+        throw formatError(buildYamlParseErrorDetail(error));
+    }
+}
+function buildYamlParseErrorDetail(error) {
+    if (isYamlException(error)) {
+        const { reason, message, mark } = error;
+        return {
+            reason: reason ?? undefined,
+            message: message ?? undefined,
+            line: typeof mark?.line === "number" && Number.isFinite(mark.line)
+                ? mark.line + 1
+                : undefined,
+            column: typeof mark?.column === "number" && Number.isFinite(mark.column)
+                ? mark.column + 1
+                : undefined,
+            error,
+            isYamlError: true,
+        };
+    }
+    return {
+        message: toErrorMessage(error),
+        error,
+        isYamlError: false,
+    };
+}

package/dist/utils/yaml.d.ts

@@ -0,0 +1,33 @@
+import type { YAMLException } from "js-yaml";
+export interface ConfigSnapshot {
+    content: string;
+    normalized: string;
+    exists: boolean;
+}
+/**
+ * Reads a YAML (or general text) config file and returns its snapshot.
+ */
+export declare function readConfigSnapshot(filePath: string): Promise<ConfigSnapshot>;
+/**
+ * Normalizes YAML text for comparisons by trimming whitespace and normalizing line endings.
+ */
+export declare function normalizeConfigText(value: string): string;
+/**
+ * Writes config content to disk if the normalized version differs from the previous snapshot.
+ */
+export declare function writeConfigIfChanged(filePath: string, nextContent: string, previousNormalized: string): Promise<boolean>;
+export interface YamlConfigLoadResult<T> {
+    snapshot: ConfigSnapshot;
+    config: T;
+}
+export declare function loadYamlConfig<T>(filePath: string, parse: (content: string) => T): Promise<YamlConfigLoadResult<T>>;
+export declare function isDefaultYamlTemplate(snapshot: ConfigSnapshot, defaultTemplate: string): boolean;
+export interface PersistYamlConfigOptions {
+    filePath: string;
+    serialized: string;
+    original: ConfigSnapshot;
+    defaultTemplate: string;
+    isDefaultTemplate?: boolean;
+}
+export declare function persistYamlConfig(options: PersistYamlConfigOptions): Promise<boolean>;
+export declare function isYamlException(error: unknown): error is YAMLException;

package/dist/utils/yaml.js

@@ -0,0 +1,75 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { isFileSystemError } from "./fs.js";
+/**
+ * Reads a YAML (or general text) config file and returns its snapshot.
+ */
+export async function readConfigSnapshot(filePath) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        return {
+            content,
+            normalized: normalizeConfigText(content),
+            exists: true,
+        };
+    }
+    catch (error) {
+        if (isFileSystemError(error) && error.code === "ENOENT") {
+            return { content: "", normalized: "", exists: false };
+        }
+        throw error;
+    }
+}
+/**
+ * Normalizes YAML text for comparisons by trimming whitespace and normalizing line endings.
+ */
+export function normalizeConfigText(value) {
+    if (value.length === 0) {
+        return "";
+    }
+    return value.replace(/\r\n/g, "\n").trim();
+}
+/**
+ * Writes config content to disk if the normalized version differs from the previous snapshot.
+ */
+export async function writeConfigIfChanged(filePath, nextContent, previousNormalized) {
+    const nextNormalized = normalizeConfigText(nextContent);
+    if (nextNormalized === previousNormalized) {
+        return false;
+    }
+    await writeFile(filePath, ensureTrailingNewline(nextContent), "utf8");
+    return true;
+}
+export async function loadYamlConfig(filePath, parse) {
+    const snapshot = await readConfigSnapshot(filePath);
+    return {
+        snapshot,
+        config: parse(snapshot.content),
+    };
+}
+export function isDefaultYamlTemplate(snapshot, defaultTemplate) {
+    if (!snapshot.exists) {
+        return true;
+    }
+    const defaults = normalizeConfigText(defaultTemplate);
+    return snapshot.normalized === defaults;
+}
+export async function persistYamlConfig(options) {
+    const { filePath, serialized, original, defaultTemplate, isDefaultTemplate } = options;
+    if (!original.exists) {
+        return writeConfigIfChanged(filePath, serialized, "__missing__");
+    }
+    const wasDefaultTemplate = isDefaultTemplate ?? isDefaultYamlTemplate(original, defaultTemplate);
+    const previousNormalized = wasDefaultTemplate
+        ? normalizeConfigText(defaultTemplate)
+        : original.normalized;
+    return writeConfigIfChanged(filePath, serialized, previousNormalized);
+}
+function ensureTrailingNewline(content) {
+    return content.endsWith("\n") ? content : `${content}\n`;
+}
+export function isYamlException(error) {
+    return (Boolean(error) &&
+        typeof error === "object" &&
+        "name" in error &&
+        error.name === "YAMLException");
+}

package/dist/workspace/agents.d.ts

@@ -0,0 +1,33 @@
+import { WorkspaceSetupRunError } from "../commands/run/errors.js";
+import type { AgentId } from "../configs/agents/types.js";
+import type { EnvironmentConfig } from "../configs/environment/types.js";
+import { type AgentWorkspacePaths } from "./layout.js";
+export interface ArtifactCollectionResult {
+    summaryCaptured: boolean;
+    diffStatistics?: string;
+    commitSha?: string;
+    diffAttempted: boolean;
+    diffCaptured: boolean;
+}
+export interface SandboxPersona {
+    authorName: string;
+    authorEmail: string;
+}
+export declare function prepareAgentWorkspace(options: {
+    paths: AgentWorkspacePaths;
+    baseRevisionSha: string;
+    root: string;
+    agentId: AgentId;
+    runId: string;
+    environment: EnvironmentConfig;
+}): Promise<void>;
+export declare function collectAgentArtifacts(options: {
+    baseRevisionSha: string;
+    workspacePath: string;
+    summaryPath: string;
+    diffPath: string;
+    root: string;
+    environment: EnvironmentConfig;
+    persona: SandboxPersona;
+}): Promise<ArtifactCollectionResult>;
+export declare function ensureWorkspaceError(error: unknown): WorkspaceSetupRunError;

package/dist/workspace/agents.js

@@ -0,0 +1,189 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { AgentProcessError, GitOperationError, WorkspaceSetupRunError, } from "../commands/run/errors.js";
+import { toErrorMessage } from "../utils/errors.js";
+import { createWorktree, gitAddAll, gitCommitAll, gitDiff, gitDiffShortStat, gitHasStagedChanges, runGitCommand, } from "../utils/git.js";
+import { resolvePath } from "../utils/path.js";
+import { enforceCredentialExclusion } from "./credential-guard.js";
+import { cleanupWorkspaceDependencies, ensureWorkspaceDependencies, WorkspaceDependencyCleanupError, } from "./dependencies.js";
+import { WorkspaceSetupError } from "./errors.js";
+import { scaffoldAgentWorkspace, WORKSPACE_SUMMARY_FILENAME, } from "./layout.js";
+import { ensureWorkspaceShim } from "./shim.js";
+export async function prepareAgentWorkspace(options) {
+    const { paths, baseRevisionSha, root, agentId, runId, environment } = options;
+    try {
+        await scaffoldAgentWorkspace(paths);
+        await rm(resolvePath(paths.agentRoot, "tmp"), {
+            recursive: true,
+            force: true,
+        }).catch(() => { });
+    }
+    catch (error) {
+        throw ensureWorkspaceError(error);
+    }
+    try {
+        await createWorktree({
+            root,
+            worktreePath: paths.workspacePath,
+            branch: `voratiq/run/${runId}/${agentId}`,
+            baseRevision: baseRevisionSha,
+        });
+        await ensureWorkspaceDependencies({
+            root,
+            workspacePath: paths.workspacePath,
+            environment,
+        });
+        await ensureWorkspaceShim({
+            workspacePath: paths.workspacePath,
+        });
+    }
+    catch (error) {
+        throw ensureWorkspaceError(error);
+    }
+}
+export async function collectAgentArtifacts(options) {
+    const { baseRevisionSha, workspacePath, summaryPath, diffPath, root, environment, persona, } = options;
+    let dependenciesCleanup = {
+        nodeRemoved: false,
+        pythonRemoved: false,
+    };
+    let cleanupFailed = false;
+    try {
+        dependenciesCleanup = await cleanupWorkspaceDependencies({
+            root,
+            workspacePath,
+            environment,
+        });
+    }
+    catch (error) {
+        cleanupFailed = true;
+        if (error instanceof WorkspaceDependencyCleanupError) {
+            dependenciesCleanup = error.cleanup;
+        }
+    }
+    let runFailed = true;
+    let artifactResult;
+    let dependencyRestoreError;
+    try {
+        await runGitStep("Git add failed", async () => gitAddAll(workspacePath));
+        const hasChangesBeforeSummary = await gitHasStagedChanges(workspacePath);
+        if (!hasChangesBeforeSummary) {
+            throw new AgentProcessError({
+                detail: "Agent process failed. No workspace changes detected.",
+            });
+        }
+        const { summary } = await harvestSummary({
+            workspacePath,
+            summaryPath,
+        });
+        await runGitStep("Git add failed", async () => gitAddAll(workspacePath));
+        const hasChanges = await gitHasStagedChanges(workspacePath);
+        if (!hasChanges) {
+            throw new AgentProcessError({
+                detail: "Agent process failed. No workspace changes detected.",
+            });
+        }
+        let diffStatistics;
+        let commitSha;
+        await runGitStep("Git commit failed", async () => gitCommitAll({
+            cwd: workspacePath,
+            message: summary,
+            authorName: persona.authorName,
+            authorEmail: persona.authorEmail,
+        }));
+        commitSha = await runGitStep("Git rev-parse failed", async () => runGitCommand(["rev-parse", "HEAD"], { cwd: workspacePath }));
+        const diffContent = await runGitStep("Git diff failed", async () => gitDiff({
+            cwd: workspacePath,
+            baseRevision: baseRevisionSha,
+            targetRevision: "HEAD",
+        }));
+        await enforceCredentialExclusion({
+            workspacePath,
+            diffContent,
+        });
+        await writeFile(diffPath, diffContent, { encoding: "utf8" });
+        diffStatistics = await runGitStep("Git diff --shortstat failed", async () => gitDiffShortStat({
+            cwd: workspacePath,
+            baseRevision: baseRevisionSha,
+            targetRevision: "HEAD",
+        }));
+        runFailed = false;
+        artifactResult = {
+            summaryCaptured: true,
+            diffStatistics,
+            commitSha,
+            diffAttempted: true,
+            diffCaptured: true,
+        };
+    }
+    finally {
+        const cleanupTouched = dependenciesCleanup.nodeRemoved || dependenciesCleanup.pythonRemoved;
+        const shouldRestoreDependencies = cleanupTouched || cleanupFailed;
+        if (shouldRestoreDependencies) {
+            try {
+                await ensureWorkspaceDependencies({
+                    root,
+                    workspacePath,
+                    environment,
+                });
+            }
+            catch (error) {
+                if (!runFailed) {
+                    dependencyRestoreError = new AgentProcessError({
+                        detail: `[voratiq] Failed to restore workspace dependencies after export: ${toErrorMessage(error)}`,
+                    });
+                }
+            }
+        }
+    }
+    if (dependencyRestoreError) {
+        throw dependencyRestoreError;
+    }
+    if (!artifactResult) {
+        throw new AgentProcessError({
+            detail: "Agent process failed before artifacts were collected.",
+        });
+    }
+    return artifactResult;
+}
+export function ensureWorkspaceError(error) {
+    if (error instanceof WorkspaceSetupError) {
+        return new WorkspaceSetupRunError(error.detail, {
+            detailLines: error.detailLines,
+            hintLines: error.hintLines,
+        });
+    }
+    return new WorkspaceSetupRunError(toErrorMessage(error));
+}
+async function harvestSummary(options) {
+    const { workspacePath, summaryPath } = options;
+    const workspaceSummaryPath = resolvePath(workspacePath, WORKSPACE_SUMMARY_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(workspaceSummaryPath, "utf8");
+    }
+    catch (error) {
+        throw new AgentProcessError({ detail: toErrorMessage(error) });
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new AgentProcessError({
+            detail: "Agent process failed. Summary is empty.",
+        });
+    }
+    await writeFile(summaryPath, `${trimmed}\n`, { encoding: "utf8" });
+    await rm(workspaceSummaryPath, { force: true });
+    return {
+        summary: trimmed,
+    };
+}
+async function runGitStep(operationMessage, step) {
+    try {
+        return await step();
+    }
+    catch (error) {
+        throw new GitOperationError({
+            operation: operationMessage,
+            detail: toErrorMessage(error),
+        });
+    }
+}

package/dist/workspace/chat/artifacts.d.ts

@@ -0,0 +1,14 @@
+import type { ChatArtifactFormat } from "./types.js";
+export type ChatArtifactStatus = "captured" | "already-exists" | "not-found" | "error";
+export interface ChatArtifactCaptureResult {
+    status: ChatArtifactStatus;
+    artifactPath?: string;
+    format?: ChatArtifactFormat;
+    sourceCount?: number;
+    error?: unknown;
+}
+export interface PreserveChatArtifactsOptions {
+    providerId: string;
+    agentRoot: string;
+}
+export declare function preserveProviderChatTranscripts(options: PreserveChatArtifactsOptions): Promise<ChatArtifactCaptureResult>;

package/dist/workspace/chat/artifacts.js

@@ -0,0 +1,157 @@
+import { once } from "node:events";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { finished } from "node:stream/promises";
+import { pathExists } from "../../utils/fs.js";
+import { ARTIFACTS_DIRNAME, CHAT_JSON_FILENAME, CHAT_JSONL_FILENAME, } from "../structure.js";
+import { findProviderTranscripts } from "./sources.js";
+export async function preserveProviderChatTranscripts(options) {
+    const { providerId, agentRoot } = options;
+    if (!providerId) {
+        return { status: "not-found" };
+    }
+    const existing = await locateExistingChatArtifact(agentRoot);
+    if (existing !== undefined) {
+        const { path, format } = existing;
+        return {
+            status: "already-exists",
+            artifactPath: path,
+            format,
+        };
+    }
+    let transcriptPaths;
+    try {
+        transcriptPaths = await findProviderTranscripts(providerId, agentRoot);
+    }
+    catch (error) {
+        return {
+            status: "error",
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+    const selection = selectTranscriptFiles(transcriptPaths);
+    if (!selection) {
+        return { status: "not-found" };
+    }
+    const { format: selectionFormat, files } = selection;
+    const artifactPath = resolve(agentRoot, ARTIFACTS_DIRNAME, selectionFormat === "json" ? CHAT_JSON_FILENAME : CHAT_JSONL_FILENAME);
+    try {
+        await mkdir(dirname(artifactPath), { recursive: true });
+        if (selectionFormat === "json") {
+            await bundleJsonTranscripts({
+                files,
+                artifactPath,
+                agentRoot,
+                providerId,
+            });
+        }
+        else {
+            await concatenateJsonlTranscripts(files, artifactPath);
+        }
+        return {
+            status: "captured",
+            artifactPath,
+            format: selectionFormat,
+            sourceCount: files.length,
+        };
+    }
+    catch (error) {
+        await rm(artifactPath, { force: true }).catch(() => { });
+        return {
+            status: "error",
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+async function locateExistingChatArtifact(agentRoot) {
+    const candidates = [
+        {
+            path: resolve(agentRoot, ARTIFACTS_DIRNAME, CHAT_JSONL_FILENAME),
+            format: "jsonl",
+        },
+        {
+            path: resolve(agentRoot, ARTIFACTS_DIRNAME, CHAT_JSON_FILENAME),
+            format: "json",
+        },
+    ];
+    for (const candidate of candidates) {
+        if (await pathExists(candidate.path)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function selectTranscriptFiles(transcriptPaths) {
+    const jsonlFiles = transcriptPaths.filter((path) => path.toLowerCase().endsWith(".jsonl"));
+    if (jsonlFiles.length > 0) {
+        return { format: "jsonl", files: [...jsonlFiles].sort() };
+    }
+    const jsonFiles = transcriptPaths
+        .filter((path) => path.toLowerCase().endsWith(".json"))
+        .sort();
+    if (jsonFiles.length > 0) {
+        return { format: "json", files: jsonFiles };
+    }
+    return undefined;
+}
+async function bundleJsonTranscripts(options) {
+    const { files, artifactPath, agentRoot, providerId } = options;
+    if (files.length === 0) {
+        throw new Error("No JSON transcripts available to bundle");
+    }
+    const transcripts = [];
+    for (const file of files) {
+        const raw = await readFile(file, "utf8");
+        transcripts.push({
+            source: relative(agentRoot, file),
+            payload: parseJsonOrString(raw),
+        });
+    }
+    const payload = {
+        provider: providerId,
+        collectedAt: new Date().toISOString(),
+        transcripts,
+    };
+    await writeFile(artifactPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+async function concatenateJsonlTranscripts(files, artifactPath) {
+    const writer = createWriteStream(artifactPath, {
+        flags: "w",
+        encoding: "utf8",
+    });
+    try {
+        for (const file of files) {
+            await appendFileContents(file, writer);
+        }
+        writer.end();
+        await finished(writer);
+    }
+    catch (error) {
+        writer.destroy();
+        throw error;
+    }
+}
+async function appendFileContents(sourcePath, writer) {
+    const reader = createReadStream(sourcePath, { encoding: "utf8" });
+    let endsWithNewline = false;
+    for await (const chunk of reader) {
+        endsWithNewline = chunk.endsWith("\n");
+        if (!writer.write(chunk)) {
+            await once(writer, "drain");
+        }
+    }
+    if (!endsWithNewline) {
+        if (!writer.write("\n")) {
+            await once(writer, "drain");
+        }
+    }
+}
+function parseJsonOrString(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return content;
+    }
+}

package/dist/workspace/chat/sources.d.ts

@@ -0,0 +1,5 @@
+export type TranscriptLocator = (agentRoot: string) => Promise<readonly string[]>;
+export declare function findProviderTranscripts(providerId: string, agentRoot: string): Promise<readonly string[]>;
+export declare function findClaudeTranscripts(agentRoot: string): Promise<readonly string[]>;
+export declare function findCodexTranscripts(agentRoot: string): Promise<readonly string[]>;
+export declare function findGeminiTranscripts(agentRoot: string): Promise<readonly string[]>;

package/dist/workspace/chat/sources.js

@@ -0,0 +1,80 @@
+import { readdir } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
+import { isMissing } from "../../utils/fs.js";
+import { SANDBOX_DIRNAME } from "../structure.js";
+const locatorMap = {
+    claude: findClaudeTranscripts,
+    codex: findCodexTranscripts,
+    gemini: findGeminiTranscripts,
+};
+export async function findProviderTranscripts(providerId, agentRoot) {
+    const locator = locatorMap[providerId];
+    if (!locator) {
+        return [];
+    }
+    return locator(agentRoot);
+}
+export async function findClaudeTranscripts(agentRoot) {
+    const projectsRoot = resolveSandboxPath(agentRoot, ".claude", "projects");
+    return collectFiles(projectsRoot, {
+        extensions: [".jsonl"],
+        maxDepth: 2,
+    });
+}
+export async function findCodexTranscripts(agentRoot) {
+    const sessionsRoot = resolveSandboxPath(agentRoot, ".codex", "sessions");
+    return collectFiles(sessionsRoot, { extensions: [".jsonl"], maxDepth: 6 });
+}
+export async function findGeminiTranscripts(agentRoot) {
+    const tmpRoot = resolveSandboxPath(agentRoot, ".gemini", "tmp");
+    const entries = await safeReadDir(tmpRoot);
+    const transcripts = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const chatsDir = resolvePath(tmpRoot, entry.name, "chats");
+        const chatFiles = await collectFiles(chatsDir, {
+            extensions: [".json", ".jsonl"],
+            maxDepth: 1,
+        });
+        transcripts.push(...chatFiles);
+    }
+    return transcripts.sort();
+}
+function resolveSandboxPath(agentRoot, ...segments) {
+    return resolvePath(agentRoot, SANDBOX_DIRNAME, ...segments);
+}
+async function collectFiles(root, { extensions, maxDepth = Number.POSITIVE_INFINITY }) {
+    const results = [];
+    await traverse(root, 0);
+    results.sort();
+    return results;
+    async function traverse(current, depth) {
+        if (depth > maxDepth) {
+            return;
+        }
+        const entries = await safeReadDir(current);
+        for (const entry of entries) {
+            const entryPath = resolvePath(current, entry.name);
+            if (entry.isDirectory()) {
+                await traverse(entryPath, depth + 1);
+                continue;
+            }
+            if (extensions.some((extension) => entry.name.endsWith(extension))) {
+                results.push(entryPath);
+            }
+        }
+    }
+}
+async function safeReadDir(directory) {
+    try {
+        return await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return [];
+        }
+        throw error;
+    }
+}

package/dist/workspace/chat/types.d.ts

@@ -0,0 +1 @@
+export type ChatArtifactFormat = "json" | "jsonl";

package/dist/workspace/chat/types.js

@@ -0,0 +1 @@
+export {};

package/dist/workspace/cleanup.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Remove a run workspace directory, ignoring cleanup errors to preserve the original failure context.
+ */
+export declare function cleanupRunWorkspace(runRoot: string): Promise<void>;

package/dist/workspace/cleanup.js

@@ -0,0 +1,12 @@
+import { rm } from "node:fs/promises";
+/**
+ * Remove a run workspace directory, ignoring cleanup errors to preserve the original failure context.
+ */
+export async function cleanupRunWorkspace(runRoot) {
+    try {
+        await rm(runRoot, { recursive: true, force: true });
+    }
+    catch {
+        // Intentionally ignore cleanup failures.
+    }
+}

package/dist/workspace/credential-guard.d.ts

@@ -0,0 +1,4 @@
+export declare function enforceCredentialExclusion(options: {
+    workspacePath: string;
+    diffContent: string;
+}): Promise<void>;