pulseed 0.6.5 → 0.7.0

package/dist/tools/kaggle/KaggleExperimentTools.js

@@ -1,1189 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { z } from "zod";
-import { KAGGLE_VALIDATION_CHECKLIST, KaggleMetricDirectionSchema, KaggleLongRunValidationContractSchema, normalizedMetricScore, parseKaggleMetricsCompatible, summarizeKaggleValidation, } from "./metrics.js";
-import { getKaggleExperimentDir, resolveKaggleWorkspaceInput, resolveWorkspaceRelativePath, stateRelativePath, validateKaggleExperimentId, workspaceRelativePath, } from "./paths.js";
-import { ensureDirectoryWithinWorkspaceRoot } from "../../base/utils/workspace-root.js";
-import { defaultProcessSessionManager, } from "../system/ProcessSessionTool/ProcessSessionTool.js";
-const DEFAULT_MAX_LOG_CHARS = 12_000;
-export const KaggleExperimentStartInputSchema = z.object({
-    workspace: z.string().min(1),
-    competition: z.string().min(1),
-    experiment_id: z.string().min(1).optional(),
-    command: z.string().min(1),
-    args: z.array(z.string()).default([]),
-    env: z.record(z.string()).optional(),
-    strategy_id: z.string().optional(),
-    task_id: z.string().optional(),
-    expected_metrics_path: z.string().min(1).optional(),
-    artifact_refs: z.array(z.string().min(1)).default([]),
-    validation_contract: KaggleLongRunValidationContractSchema,
-}).strict();
-export const KaggleExperimentReadInputSchema = z.object({
-    workspace: z.string().min(1),
-    competition: z.string().min(1),
-    experiment_id: z.string().min(1).optional(),
-    session_id: z.string().min(1).optional(),
-    maxChars: z.number().int().min(1).max(100_000).default(DEFAULT_MAX_LOG_CHARS),
-    waitMs: z.number().int().min(0).max(30_000).default(0),
-}).strict().refine((input) => input.experiment_id || input.session_id, {
-    message: "experiment_id or session_id is required",
-});
-export const KaggleExperimentListInputSchema = z.object({
-    workspace: z.string().min(1),
-    competition: z.string().min(1),
-    include_exited: z.boolean().default(true),
-}).strict();
-export const KaggleExperimentStopInputSchema = z.object({
-    workspace: z.string().min(1),
-    competition: z.string().min(1),
-    experiment_id: z.string().min(1).optional(),
-    session_id: z.string().min(1).optional(),
-    signal: z.enum(["SIGTERM", "SIGINT", "SIGHUP", "SIGKILL"]).default("SIGTERM"),
-    waitMs: z.number().int().min(0).max(30_000).default(1_000),
-}).strict().refine((input) => input.experiment_id || input.session_id, {
-    message: "experiment_id or session_id is required",
-});
-export const KaggleMetricReportInputSchema = z.object({
-    workspace: z.string().min(1),
-    competition: z.string().min(1),
-    experiment_id: z.string().min(1).optional(),
-    metrics_path: z.string().min(1).optional(),
-    baseline_score: z.number().finite().optional(),
-}).strict().refine((input) => input.experiment_id || input.metrics_path, {
-    message: "experiment_id or metrics_path is required",
-});
-export const KaggleCompareExperimentsInputSchema = z.object({
-    workspace: z.string().min(1),
-    competition: z.string().min(1),
-    experiment_ids: z.array(z.string().min(1)).optional(),
-    metric_direction: KaggleMetricDirectionSchema.optional(),
-}).strict();
-class KaggleToolBase {
-    manager;
-    constructor(manager = defaultProcessSessionManager) {
-        this.manager = manager;
-    }
-}
-export class KaggleExperimentStartTool extends KaggleToolBase {
-    metadata = {
-        name: "kaggle_experiment_start",
-        aliases: ["kaggle_start_experiment"],
-        permissionLevel: "execute",
-        isReadOnly: false,
-        isDestructive: false,
-        shouldDefer: false,
-        alwaysLoad: false,
-        maxConcurrency: 2,
-        maxOutputChars: DEFAULT_MAX_LOG_CHARS,
-        tags: ["kaggle", "experiment", "process", "ml"],
-    };
-    inputSchema = KaggleExperimentStartInputSchema;
-    description() {
-        return "Start a named Kaggle training experiment under the PulSeed workspace root, teeing process output into a durable train.log artifact.";
-    }
-    async call(input, context) {
-        const startTime = Date.now();
-        try {
-            const commandArgs = input.args ?? [];
-            const artifactRefs = input.artifact_refs ?? [];
-            const validationContract = KaggleLongRunValidationContractSchema.parse(input.validation_contract);
-            const experimentId = input.experiment_id
-                ? validateKaggleExperimentId(input.experiment_id)
-                : generateExperimentId();
-            const resolved = resolveExperiment(input.workspace, input.competition, experimentId);
-            await ensureDirectoryWithinWorkspaceRoot(resolved.experimentDir);
-            await fs.writeFile(resolved.logPath, "", { flag: "a" });
-            const metricsPath = input.expected_metrics_path
-                ? resolveWorkspaceRelativePath(resolved.workspaceRoot, input.expected_metrics_path, "expected_metrics_path")
-                : resolved.metricsPath;
-            const extraRefs = artifactRefs.map((ref) => resolveWorkspaceRelativePath(resolved.workspaceRoot, ref, "artifact_refs"));
-            const commandMetadata = {
-                schema_version: "kaggle-command-v1",
-                experiment_id: experimentId,
-                competition: input.competition,
-                command: input.command,
-                args: commandArgs,
-                env_keys: Object.keys(input.env ?? {}).sort(),
-                cwd: resolved.workspaceRoot,
-                created_at: new Date().toISOString(),
-                log_path: resolved.logPath,
-                metrics_path: metricsPath,
-                report_path: resolved.reportPath,
-                next_action_path: resolved.nextActionPath,
-                validation_contract: validationContract,
-                validation_checklist: KAGGLE_VALIDATION_CHECKLIST,
-            };
-            await fs.writeFile(resolved.commandPath, `${JSON.stringify(commandMetadata, null, 2)}\n`, "utf-8");
-            const session = this.manager.start({
-                command: process.execPath,
-                args: teeWrapperArgs(input.command, commandArgs, resolved.logPath, metricsPath, resolved.reportPath, resolved.nextActionPath, experimentId, input.competition),
-                cwd: resolved.workspaceRoot,
-                env: input.env,
-                label: `kaggle:${input.competition}:${experimentId}`,
-                task_id: input.task_id,
-                strategy_id: input.strategy_id,
-                artifact_refs: [
-                    resolved.logPath,
-                    metricsPath,
-                    resolved.metadataPath,
-                    resolved.commandPath,
-                    resolved.processPath,
-                    resolved.childProcessPath,
-                    resolved.reportPath,
-                    resolved.nextActionPath,
-                    ...extraRefs,
-                ],
-            }, resolved.workspaceRoot, context);
-            const metadata = experimentMetadata({ ...input, args: commandArgs, artifact_refs: artifactRefs, validation_contract: validationContract }, resolved, experimentId, metricsPath, extraRefs, session);
-            await fs.writeFile(resolved.metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
-            await fs.writeFile(resolved.processPath, `${JSON.stringify(session, null, 2)}\n`, "utf-8");
-            const output = {
-                experiment_id: experimentId,
-                competition: input.competition,
-                process: session,
-                validation_contract: validationContract,
-                validation_checklist: KAGGLE_VALIDATION_CHECKLIST,
-                metadata: artifactRef(resolved.workspaceRoot, resolved.metadataPath),
-                artifacts: {
-                    log: artifactRef(resolved.workspaceRoot, resolved.logPath),
-                    metrics: artifactRef(resolved.workspaceRoot, metricsPath),
-                    command: artifactRef(resolved.workspaceRoot, resolved.commandPath),
-                    process: artifactRef(resolved.workspaceRoot, resolved.processPath),
-                    child_process: artifactRef(resolved.workspaceRoot, resolved.childProcessPath),
-                    report: artifactRef(resolved.workspaceRoot, resolved.reportPath),
-                    next_action: artifactRef(resolved.workspaceRoot, resolved.nextActionPath),
-                    extra: extraRefs.map((ref) => artifactRef(resolved.workspaceRoot, ref)),
-                },
-                wait_condition_hints: {
-                    process_session_exited: {
-                        type: "process_session_exited",
-                        session_id: session.session_id,
-                    },
-                    metrics_file_exists: {
-                        type: "file_exists",
-                        path: stateRelativePath(metricsPath),
-                        absolute_path: metricsPath,
-                    },
-                    report_file_exists: {
-                        type: "file_exists",
-                        path: stateRelativePath(resolved.reportPath),
-                        absolute_path: resolved.reportPath,
-                    },
-                    next_action_file_exists: {
-                        type: "file_exists",
-                        path: stateRelativePath(resolved.nextActionPath),
-                        absolute_path: resolved.nextActionPath,
-                    },
-                },
-                metric_threshold_guidance: {
-                    wait_condition_type: "metric_threshold",
-                    metric: "cv_score",
-                    operator: "read_metrics_direction_first",
-                    value_required: true,
-                    metric_source: "wait_metadata.metrics",
-                    metrics_artifact_state_relative_path: stateRelativePath(metricsPath),
-                },
-            };
-            return {
-                success: true,
-                data: output,
-                summary: `Started Kaggle experiment ${experimentId} as process session ${session.session_id}`,
-                durationMs: Date.now() - startTime,
-                artifacts: [
-                    resolved.metadataPath,
-                    resolved.commandPath,
-                    resolved.processPath,
-                    resolved.logPath,
-                    metricsPath,
-                    resolved.reportPath,
-                    resolved.nextActionPath,
-                    ...(session.metadataPath ? [session.metadataPath] : []),
-                    ...extraRefs,
-                ],
-            };
-        }
-        catch (err) {
-            return failureResult(`Failed to start Kaggle experiment: ${err.message}`, startTime);
-        }
-    }
-    async checkPermissions(input) {
-        return {
-            status: "needs_approval",
-            reason: `Start Kaggle training command for ${input.competition}: ${input.command} ${(input.args ?? []).join(" ")}`.trim(),
-        };
-    }
-    isConcurrencySafe(_input) {
-        return false;
-    }
-}
-export class KaggleExperimentReadTool extends KaggleToolBase {
-    metadata = {
-        name: "kaggle_experiment_read",
-        aliases: ["kaggle_read_experiment"],
-        permissionLevel: "read_metrics",
-        isReadOnly: true,
-        isDestructive: false,
-        shouldDefer: false,
-        alwaysLoad: false,
-        maxConcurrency: 5,
-        maxOutputChars: DEFAULT_MAX_LOG_CHARS,
-        tags: ["kaggle", "experiment", "process", "ml"],
-    };
-    inputSchema = KaggleExperimentReadInputSchema;
-    description() {
-        return "Read a Kaggle experiment from durable metadata, train.log, metrics.json, and the live process buffer when available.";
-    }
-    async call(input, _context) {
-        const startTime = Date.now();
-        try {
-            const located = await locateExperiment(input.workspace, input.competition, input.experiment_id, input.session_id);
-            if (!located) {
-                return failureResult("Kaggle experiment not found", startTime);
-            }
-            const liveRead = located.sessionId
-                ? await this.manager.read({
-                    session_id: located.sessionId,
-                    maxChars: input.maxChars,
-                    waitMs: input.waitMs,
-                    consume: false,
-                })
-                : null;
-            const processSnapshot = liveRead ?? await readProcessSnapshotFromMetadata(located.processPath);
-            const log = await readTail(located.logPath, input.maxChars);
-            const metrics = await readMetrics(located.metricsPath, metricsFallback(located.workspaceRoot, input.competition, located.experimentId, located.metricsPath));
-            const missingArtifacts = await missingPaths([located.logPath, located.metricsPath, located.reportPath, located.nextActionPath]);
-            const output = {
-                experiment_id: located.experimentId,
-                session_id: located.sessionId,
-                status: statusFromProcessAndMetrics(processSnapshot, metrics.ok ? metrics.metrics : null),
-                process: processSnapshot,
-                live_output: liveRead?.output ?? null,
-                log,
-                metrics: metrics.ok ? metrics.metrics : null,
-                metrics_status: metrics.ok ? "ok" : metrics.reason,
-                metrics_error: metrics.ok ? null : metrics.message,
-                metrics_source_schema: metrics.ok ? metrics.source_schema : null,
-                metrics_warnings: metrics.ok ? metrics.warnings : [],
-                missing_artifacts: missingArtifacts.map((artifactPath) => artifactRef(located.workspaceRoot, artifactPath)),
-                artifacts: {
-                    log: artifactRef(located.workspaceRoot, located.logPath),
-                    metrics: artifactRef(located.workspaceRoot, located.metricsPath),
-                    metadata: artifactRef(located.workspaceRoot, located.metadataPath),
-                    process: artifactRef(located.workspaceRoot, located.processPath),
-                    report: artifactRef(located.workspaceRoot, located.reportPath),
-                    next_action: artifactRef(located.workspaceRoot, located.nextActionPath),
-                },
-            };
-            return {
-                success: true,
-                data: output,
-                summary: `Read Kaggle experiment ${located.experimentId}: ${output.status}`,
-                durationMs: Date.now() - startTime,
-                artifacts: [located.metadataPath, located.processPath, located.logPath, located.metricsPath, located.reportPath, located.nextActionPath],
-            };
-        }
-        catch (err) {
-            return failureResult(`Failed to read Kaggle experiment: ${err.message}`, startTime);
-        }
-    }
-    async checkPermissions(_input) {
-        return { status: "allowed" };
-    }
-    isConcurrencySafe(_input) {
-        return true;
-    }
-}
-export class KaggleExperimentListTool extends KaggleToolBase {
-    metadata = {
-        name: "kaggle_experiment_list",
-        aliases: ["kaggle_list_experiments"],
-        permissionLevel: "read_metrics",
-        isReadOnly: true,
-        isDestructive: false,
-        shouldDefer: false,
-        alwaysLoad: false,
-        maxConcurrency: 5,
-        maxOutputChars: DEFAULT_MAX_LOG_CHARS,
-        tags: ["kaggle", "experiment", "process", "ml"],
-    };
-    inputSchema = KaggleExperimentListInputSchema;
-    description() {
-        return "List Kaggle experiments by merging durable experiment directories with currently live process sessions.";
-    }
-    async call(input, _context) {
-        const startTime = Date.now();
-        try {
-            const workspaceRoot = resolveKaggleWorkspaceInput(input.workspace, input.competition);
-            const experiments = new Map();
-            for (const experimentId of await listExperimentIds(workspaceRoot)) {
-                const located = resolveLocatedExperiment(workspaceRoot, input.competition, experimentId);
-                const metadata = await readJsonObject(located.metadataPath);
-                const processSnapshot = await readProcessSnapshotFromMetadata(located.processPath);
-                const metrics = await readMetrics(located.metricsPath, metricsFallback(workspaceRoot, input.competition, experimentId, located.metricsPath));
-                experiments.set(experimentId, {
-                    experiment_id: experimentId,
-                    session_id: typeof metadata?.process === "object" && metadata.process !== null
-                        ? metadata.process.session_id
-                        : undefined,
-                    status: statusFromProcessAndMetrics(processSnapshot, metrics.ok ? metrics.metrics : null),
-                    source: "filesystem",
-                    metrics: metrics.ok ? metrics.metrics : null,
-                    metrics_status: metrics.ok ? "ok" : metrics.reason,
-                    metrics_source_schema: metrics.ok ? metrics.source_schema : null,
-                    metrics_warnings: metrics.ok ? metrics.warnings : [],
-                    artifacts: {
-                        log: artifactRef(workspaceRoot, located.logPath),
-                        metrics: artifactRef(workspaceRoot, located.metricsPath),
-                        metadata: artifactRef(workspaceRoot, located.metadataPath),
-                        report: artifactRef(workspaceRoot, located.reportPath),
-                        next_action: artifactRef(workspaceRoot, located.nextActionPath),
-                    },
-                });
-            }
-            for (const session of this.manager.list(input.include_exited)) {
-                const experimentId = experimentIdFromSession(session, workspaceRoot);
-                if (!experimentId)
-                    continue;
-                const located = resolveLocatedExperiment(workspaceRoot, input.competition, experimentId);
-                const existing = experiments.get(experimentId) ?? {};
-                const metrics = await readMetrics(located.metricsPath, metricsFallback(workspaceRoot, input.competition, experimentId, located.metricsPath));
-                experiments.set(experimentId, {
-                    ...existing,
-                    experiment_id: experimentId,
-                    session_id: session.session_id,
-                    status: statusFromProcessAndMetrics(session, metrics.ok ? metrics.metrics : null),
-                    source: existing.source ? "filesystem+live" : "live",
-                    process: session,
-                    metrics: metrics.ok ? metrics.metrics : null,
-                    metrics_status: metrics.ok ? "ok" : metrics.reason,
-                    metrics_source_schema: metrics.ok ? metrics.source_schema : null,
-                    metrics_warnings: metrics.ok ? metrics.warnings : [],
-                    artifacts: {
-                        log: artifactRef(workspaceRoot, located.logPath),
-                        metrics: artifactRef(workspaceRoot, located.metricsPath),
-                        metadata: artifactRef(workspaceRoot, located.metadataPath),
-                        report: artifactRef(workspaceRoot, located.reportPath),
-                        next_action: artifactRef(workspaceRoot, located.nextActionPath),
-                    },
-                });
-            }
-            const data = [...experiments.values()].sort((a, b) => String(a.experiment_id).localeCompare(String(b.experiment_id)));
-            return {
-                success: true,
-                data,
-                summary: `Found ${data.length} Kaggle experiment(s) for ${input.competition}`,
-                durationMs: Date.now() - startTime,
-                artifacts: data.flatMap((item) => {
-                    const artifacts = item.artifacts;
-                    return artifacts ? Object.values(artifacts).map((ref) => ref.path) : [];
-                }),
-            };
-        }
-        catch (err) {
-            return failureResult(`Failed to list Kaggle experiments: ${err.message}`, startTime);
-        }
-    }
-    async checkPermissions(_input) {
-        return { status: "allowed" };
-    }
-    isConcurrencySafe(_input) {
-        return true;
-    }
-}
-export class KaggleExperimentStopTool extends KaggleToolBase {
-    metadata = {
-        name: "kaggle_experiment_stop",
-        aliases: ["kaggle_stop_experiment"],
-        permissionLevel: "execute",
-        isReadOnly: false,
-        isDestructive: false,
-        shouldDefer: false,
-        alwaysLoad: false,
-        maxConcurrency: 1,
-        maxOutputChars: DEFAULT_MAX_LOG_CHARS,
-        tags: ["kaggle", "experiment", "process", "ml"],
-    };
-    inputSchema = KaggleExperimentStopInputSchema;
-    description() {
-        return "Stop a running Kaggle experiment process session.";
-    }
-    async call(input, _context) {
-        const startTime = Date.now();
-        try {
-            const located = await locateExperiment(input.workspace, input.competition, input.experiment_id, input.session_id);
-            const sessionId = input.session_id ?? located?.sessionId;
-            if (!sessionId) {
-                return failureResult("Kaggle experiment session not found", startTime);
-            }
-            if (located) {
-                await signalKaggleChildProcess(located.childProcessPath, input.signal);
-            }
-            const stopped = await this.manager.stop({ session_id: sessionId, signal: input.signal, waitMs: input.waitMs });
-            if (!stopped) {
-                return failureResult(`Process session not found: ${sessionId}`, startTime);
-            }
-            if (located) {
-                await fs.writeFile(located.processPath, `${JSON.stringify(stopped, null, 2)}\n`, "utf-8");
-            }
-            return {
-                success: true,
-                data: {
-                    experiment_id: located?.experimentId ?? null,
-                    session_id: sessionId,
-                    process: stopped,
-                    artifacts: located ? {
-                        process: artifactRef(located.workspaceRoot, located.processPath),
-                        log: artifactRef(located.workspaceRoot, located.logPath),
-                    } : null,
-                },
-                summary: `Stopped Kaggle experiment process session ${sessionId}`,
-                durationMs: Date.now() - startTime,
-                artifacts: located ? [located.processPath, located.logPath] : stopped.artifactRefs,
-            };
-        }
-        catch (err) {
-            return failureResult(`Failed to stop Kaggle experiment: ${err.message}`, startTime);
-        }
-    }
-    async checkPermissions(input) {
-        return {
-            status: "needs_approval",
-            reason: `Stop Kaggle experiment ${input.experiment_id ?? input.session_id}`,
-        };
-    }
-    isConcurrencySafe(_input) {
-        return false;
-    }
-}
-export class KaggleMetricReportTool extends KaggleToolBase {
-    metadata = {
-        name: "kaggle_metric_report",
-        aliases: ["kaggle_report_metric"],
-        permissionLevel: "read_only",
-        isReadOnly: true,
-        isDestructive: false,
-        shouldDefer: false,
-        alwaysLoad: false,
-        maxConcurrency: 5,
-        maxOutputChars: DEFAULT_MAX_LOG_CHARS,
-        tags: ["kaggle", "metrics", "ml"],
-    };
-    inputSchema = KaggleMetricReportInputSchema;
-    description() {
-        return "Validate a Kaggle metrics.json artifact and return direction-aware score information for wait metadata.";
-    }
-    async call(input, _context) {
-        const startTime = Date.now();
-        try {
-            const workspaceRoot = resolveKaggleWorkspaceInput(input.workspace, input.competition);
-            const metricsPath = input.metrics_path
-                ? resolveWorkspaceRelativePath(workspaceRoot, input.metrics_path, "metrics_path")
-                : path.join(getKaggleExperimentDir(workspaceRoot, input.experiment_id), "metrics.json");
-            const fallbackExperimentId = input.experiment_id ?? experimentIdFromMetricsPath(workspaceRoot, metricsPath);
-            const metrics = await readMetrics(metricsPath, metricsFallback(workspaceRoot, input.competition, fallbackExperimentId, metricsPath));
-            if (!metrics.ok) {
-                return {
-                    success: false,
-                    data: {
-                        status: "failure",
-                        reason: metrics.reason,
-                        message: metrics.message,
-                        issues: metrics.issues ?? [],
-                        artifact: artifactRef(workspaceRoot, metricsPath),
-                    },
-                    summary: `Failed to read Kaggle metrics: ${metrics.message} (${stateRelativePath(metricsPath)})`,
-                    error: metrics.message,
-                    durationMs: Date.now() - startTime,
-                    artifacts: [metricsPath],
-                };
-            }
-            const normalizedScore = normalizedMetricScore(metrics.metrics);
-            const baselineDelta = input.baseline_score === undefined
-                ? null
-                : metrics.metrics.direction === "maximize"
-                    ? metrics.metrics.cv_score - input.baseline_score
-                    : input.baseline_score - metrics.metrics.cv_score;
-            const warnings = [
-                ...metrics.warnings,
-                ...(metrics.metrics.cv_std === null ? ["cv_std is null"] : []),
-                ...(metrics.metrics.holdout_score === null ? ["holdout_score is null"] : []),
-                ...(!metrics.metrics.artifacts.submission ? ["submission artifact is missing"] : []),
-                ...(!metrics.metrics.artifacts.model ? ["model artifact is missing"] : []),
-            ];
-            const data = {
-                status: "ok",
-                experiment_id: metrics.metrics.experiment_id,
-                metric_name: metrics.metrics.metric_name,
-                direction: metrics.metrics.direction,
-                score: metrics.metrics.cv_score,
-                normalized_score: normalizedScore,
-                baseline_delta: baselineDelta,
-                confidence: confidenceForMetrics(metrics.metrics),
-                metrics: metrics.metrics,
-                metrics_source_schema: metrics.source_schema,
-                warnings,
-                validation_checklist: KAGGLE_VALIDATION_CHECKLIST,
-                artifact: artifactRef(workspaceRoot, metricsPath),
-                wait_metadata: {
-                    metrics: {
-                        cv_score: metrics.metrics.cv_score,
-                        normalized_score: normalizedScore,
-                        baseline_delta: baselineDelta,
-                    },
-                },
-                metric_threshold_guidance: {
-                    wait_condition_type: "metric_threshold",
-                    metric: "cv_score",
-                    operator: metrics.metrics.direction === "maximize" ? "gte" : "lte",
-                    value_required: true,
-                    metric_source: "wait_metadata.metrics",
-                    metrics_artifact_state_relative_path: stateRelativePath(metricsPath),
-                },
-            };
-            return {
-                success: true,
-                data,
-                summary: `Kaggle metric ${metrics.metrics.metric_name}=${metrics.metrics.cv_score} (${metrics.metrics.direction}) for ${metrics.metrics.experiment_id}`,
-                durationMs: Date.now() - startTime,
-                artifacts: [metricsPath],
-            };
-        }
-        catch (err) {
-            return failureResult(`Failed to report Kaggle metrics: ${err.message}`, startTime);
-        }
-    }
-    async checkPermissions(_input) {
-        return { status: "allowed" };
-    }
-    isConcurrencySafe(_input) {
-        return true;
-    }
-}
-export class KaggleCompareExperimentsTool extends KaggleToolBase {
-    metadata = {
-        name: "kaggle_compare_experiments",
-        aliases: ["kaggle_compare_metrics"],
-        permissionLevel: "read_only",
-        isReadOnly: true,
-        isDestructive: false,
-        shouldDefer: false,
-        alwaysLoad: false,
-        maxConcurrency: 5,
-        maxOutputChars: DEFAULT_MAX_LOG_CHARS,
-        tags: ["kaggle", "metrics", "ml"],
-    };
-    inputSchema = KaggleCompareExperimentsInputSchema;
-    description() {
-        return "Compare Kaggle experiment metrics and select the best run using maximize or minimize semantics.";
-    }
-    async call(input, _context) {
-        const startTime = Date.now();
-        try {
-            const workspaceRoot = resolveKaggleWorkspaceInput(input.workspace, input.competition);
-            const experimentIds = input.experiment_ids?.map(validateKaggleExperimentId) ?? await listExperimentIds(workspaceRoot);
-            const rows = [];
-            for (const experimentId of experimentIds) {
-                const metricsPath = path.join(getKaggleExperimentDir(workspaceRoot, experimentId), "metrics.json");
-                const metrics = await readMetrics(metricsPath, metricsFallback(workspaceRoot, input.competition, experimentId, metricsPath));
-                if (!metrics.ok) {
-                    rows.push({
-                        experiment_id: experimentId,
-                        status: metrics.reason,
-                        summary: metrics.message,
-                        issues: metrics.issues ?? [],
-                        artifact: artifactRef(workspaceRoot, metricsPath),
-                    });
-                    continue;
-                }
-                const direction = input.metric_direction ?? metrics.metrics.direction;
-                const normalizedScore = direction === "maximize" ? metrics.metrics.cv_score : -metrics.metrics.cv_score;
-                const validation = summarizeKaggleValidation(metrics.metrics);
-                rows.push({
-                    experiment_id: experimentId,
-                    status: "ok",
-                    metric_name: metrics.metrics.metric_name,
-                    direction,
-                    score: metrics.metrics.cv_score,
-                    normalized_score: normalizedScore,
-                    robust_score: normalizedScore - validation.robust_penalty,
-                    validation,
-                    metrics: metrics.metrics,
-                    metrics_source_schema: metrics.source_schema,
-                    metrics_warnings: metrics.warnings,
-                    artifact: artifactRef(workspaceRoot, metricsPath),
-                });
-            }
-            const validRows = rows
-                .filter((row) => row.status === "ok")
-                .sort((a, b) => b.normalized_score - a.normalized_score);
-            if (validRows.length === 0) {
-                return {
-                    success: true,
-                    data: {
-                        status: "inconclusive",
-                        best_experiment_id: null,
-                        delta: null,
-                        rows,
-                        recommendation: "No valid metrics.json files were available to compare.",
-                    },
-                    summary: "Kaggle experiment comparison inconclusive: no valid metrics.json files",
-                    durationMs: Date.now() - startTime,
-                    artifacts: rows.map((row) => row.artifact.path),
-                };
-            }
-            const metricNames = new Set(validRows.map((row) => row.metric_name));
-            const metricDirections = new Set(validRows.map((row) => row.metrics.direction));
-            if (metricNames.size > 1 || (!input.metric_direction && metricDirections.size > 1)) {
-                return {
-                    success: true,
-                    data: {
-                        status: "inconclusive",
-                        best_experiment_id: null,
-                        delta: null,
-                        rows,
-                        recommendation: "Experiments must share metric_name and direction before comparison.",
-                    },
-                    summary: "Kaggle experiment comparison inconclusive: metrics are not comparable",
-                    durationMs: Date.now() - startTime,
-                    artifacts: rows.map((row) => row.artifact.path),
-                };
-            }
-            const rawRows = [...validRows].sort((a, b) => b.normalized_score - a.normalized_score);
-            const robustRows = [...validRows].sort((a, b) => b.robust_score - a.robust_score || b.normalized_score - a.normalized_score);
-            const best = robustRows[0];
-            const rawBest = rawRows[0];
-            const runnerUp = robustRows[1];
-            const delta = runnerUp ? best.robust_score - runnerUp.robust_score : null;
-            const rankTable = rows.map((row) => row.status === "ok"
-                ? {
-                    ...row,
-                    rank: rawRows.findIndex((valid) => valid.experiment_id === row.experiment_id) + 1,
-                    raw_rank: rawRows.findIndex((valid) => valid.experiment_id === row.experiment_id) + 1,
-                    robust_rank: robustRows.findIndex((valid) => valid.experiment_id === row.experiment_id) + 1,
-                }
-                : { ...row, rank: null });
-            return {
-                success: true,
-                data: {
-                    status: rows.length === validRows.length ? "ok" : "inconclusive",
-                    best_experiment_id: best.experiment_id,
-                    raw_best_experiment_id: rawBest.experiment_id,
-                    recommendation_mode: "validation_adjusted",
-                    raw_cv_delta: rawRows[1] ? rawBest.normalized_score - rawRows[1].normalized_score : null,
-                    direction: best.direction,
-                    metric_name: best.metric_name,
-                    delta,
-                    rows: rankTable,
-                    final_report_sections: [
-                        "local_cv_oof",
-                        "public_leaderboard_gap",
-                        "private_leaderboard_uncertainty",
-                        "portfolio_slot_rationale",
-                    ],
-                    validation_checklist: KAGGLE_VALIDATION_CHECKLIST,
-                    recommendation: delta === null
-                        ? `Use ${best.experiment_id}; it is the only valid experiment.`
-                        : best.experiment_id === rawBest.experiment_id
-                            ? `Use ${best.experiment_id}; it leads after CV stability, OOF safety, leakage, drift, and public-gap checks.`
-                            : `Use ${best.experiment_id}; raw CV top-1 ${rawBest.experiment_id} is not the safe recommendation after validation risk adjustment.`,
-                },
-                summary: `Best Kaggle experiment is ${best.experiment_id} (${best.metric_name}=${best.score}, ${best.direction})`,
-                durationMs: Date.now() - startTime,
-                artifacts: rows.map((row) => row.artifact.path),
-            };
-        }
-        catch (err) {
-            return failureResult(`Failed to compare Kaggle experiments: ${err.message}`, startTime);
-        }
-    }
-    async checkPermissions(_input) {
-        return { status: "allowed" };
-    }
-    isConcurrencySafe(_input) {
-        return true;
-    }
-}
-function resolveExperiment(workspace, competition, experimentId) {
-    const workspaceRoot = resolveKaggleWorkspaceInput(workspace, competition);
-    const experimentDir = getKaggleExperimentDir(workspaceRoot, experimentId);
-    return {
-        workspaceRoot,
-        experimentId,
-        experimentDir,
-        metadataPath: path.join(experimentDir, "config.json"),
-        commandPath: path.join(experimentDir, "command.json"),
-        processPath: path.join(experimentDir, "process.json"),
-        childProcessPath: path.join(experimentDir, "child-process.json"),
-        logPath: path.join(experimentDir, "train.log"),
-        metricsPath: path.join(experimentDir, "metrics.json"),
-        reportPath: path.join(experimentDir, "summary.md"),
-        nextActionPath: path.join(experimentDir, "next-action.json"),
-    };
-}
-function resolveLocatedExperiment(workspaceRoot, competition, experimentId) {
-    return resolveExperiment(workspaceRoot, competition, experimentId);
-}
-async function locateExperiment(workspace, competition, experimentId, sessionId) {
-    const workspaceRoot = resolveKaggleWorkspaceInput(workspace, competition);
-    if (experimentId) {
-        const resolved = resolveLocatedExperiment(workspaceRoot, competition, validateKaggleExperimentId(experimentId));
-        const metadata = await readJsonObject(resolved.metadataPath);
-        const metadataSessionId = typeof metadata?.process === "object" && metadata.process !== null
-            ? metadata.process.session_id
-            : undefined;
-        return { ...resolved, sessionId: sessionId ?? metadataSessionId };
-    }
-    for (const candidateId of await listExperimentIds(workspaceRoot)) {
-        const resolved = resolveLocatedExperiment(workspaceRoot, competition, candidateId);
-        const metadata = await readJsonObject(resolved.metadataPath);
-        const metadataSessionId = typeof metadata?.process === "object" && metadata.process !== null
-            ? metadata.process.session_id
-            : undefined;
-        if (metadataSessionId === sessionId) {
-            return { ...resolved, sessionId };
-        }
-    }
-    return null;
-}
-function experimentMetadata(input, resolved, experimentId, metricsPath, extraRefs, session) {
-    const now = new Date().toISOString();
-    return {
-        schema_version: "kaggle-experiment-v1",
-        experiment_id: experimentId,
-        competition: input.competition,
-        workspace_root: resolved.workspaceRoot,
-        workspace_state_relative_path: stateRelativePath(resolved.workspaceRoot),
-        experiment_dir: resolved.experimentDir,
-        experiment_state_relative_path: stateRelativePath(resolved.experimentDir),
-        created_at: now,
-        updated_at: now,
-        command: {
-            command: input.command,
-            args: input.args,
-            env_keys: Object.keys(input.env ?? {}).sort(),
-        },
-        validation_contract: input.validation_contract,
-        validation_checklist: KAGGLE_VALIDATION_CHECKLIST,
-        process: {
-            session_id: session.session_id,
-            metadata_path: session.metadataPath,
-            metadata_state_relative_path: session.metadataPath ? stateRelativePath(session.metadataPath) : undefined,
-        },
-        strategy_id: input.strategy_id ?? null,
-        task_id: input.task_id ?? null,
-        artifacts: {
-            log: artifactRef(resolved.workspaceRoot, resolved.logPath),
-            metrics: artifactRef(resolved.workspaceRoot, metricsPath),
-            command: artifactRef(resolved.workspaceRoot, resolved.commandPath),
-            process: artifactRef(resolved.workspaceRoot, resolved.processPath),
-            child_process: artifactRef(resolved.workspaceRoot, resolved.childProcessPath),
-            report: artifactRef(resolved.workspaceRoot, resolved.reportPath),
-            next_action: artifactRef(resolved.workspaceRoot, resolved.nextActionPath),
-            extra: extraRefs.map((ref) => artifactRef(resolved.workspaceRoot, ref)),
-        },
-    };
-}
-function artifactRef(workspaceRoot, artifactPath) {
-    return {
-        path: artifactPath,
-        workspace_relative_path: workspaceRelativePath(workspaceRoot, artifactPath),
-        state_relative_path: stateRelativePath(artifactPath),
-    };
-}
-function metricsFallback(workspaceRoot, competition, experimentId, metricsPath) {
-    const metricsDir = path.dirname(metricsPath);
-    return {
-        experiment_id: experimentId,
-        competition,
-        log_path: workspaceRelativePath(workspaceRoot, path.join(metricsDir, "train.log")),
-    };
-}
-function experimentIdFromMetricsPath(workspaceRoot, metricsPath) {
-    const parts = workspaceRelativePath(workspaceRoot, metricsPath).split("/");
-    const experimentsIndex = parts.indexOf("experiments");
-    if (experimentsIndex >= 0) {
-        const candidate = parts[experimentsIndex + 1];
-        if (candidate && candidate !== "metrics.json")
-            return candidate;
-    }
-    const parent = path.basename(path.dirname(metricsPath));
-    return parent === "experiments" ? undefined : parent;
-}
-async function readMetrics(metricsPath, fallback = {}) {
-    let raw;
-    try {
-        raw = await fs.readFile(metricsPath, "utf-8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            return { ok: false, reason: "missing", message: "metrics.json is missing" };
-        }
-        throw err;
-    }
-    try {
-        return parseKaggleMetricsCompatible(JSON.parse(raw), fallback);
-    }
-    catch (err) {
-        return {
-            ok: false,
-            reason: "malformed",
-            message: `metrics.json is not valid JSON: ${err.message}`,
-        };
-    }
-}
-async function readTail(filePath, maxChars) {
-    try {
-        const raw = await fs.readFile(filePath, "utf-8");
-        return {
-            text: raw.length > maxChars ? raw.slice(raw.length - maxChars) : raw,
-            truncated: raw.length > maxChars,
-            path: filePath,
-        };
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            return { text: "", truncated: false, path: filePath };
-        }
-        throw err;
-    }
-}
-async function readJsonObject(filePath) {
-    try {
-        const raw = await fs.readFile(filePath, "utf-8");
-        const parsed = JSON.parse(raw);
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-async function readProcessSnapshotFromMetadata(processPath) {
-    const localProcess = await readJsonObject(processPath);
-    const processMetadataPath = typeof localProcess?.metadataPath === "string" ? localProcess.metadataPath : null;
-    if (processMetadataPath) {
-        const durable = await readJsonObject(processMetadataPath);
-        if (durable)
-            return durable;
-    }
-    return localProcess;
-}
-async function missingPaths(pathsToCheck) {
-    const missing = [];
-    for (const candidate of pathsToCheck) {
-        try {
-            await fs.access(candidate);
-        }
-        catch (err) {
-            if (err.code === "ENOENT") {
-                missing.push(candidate);
-                continue;
-            }
-            throw err;
-        }
-    }
-    return missing;
-}
-async function listExperimentIds(workspaceRoot) {
-    const experimentsDir = path.join(workspaceRoot, "experiments");
-    try {
-        const entries = await fs.readdir(experimentsDir, { withFileTypes: true });
-        return entries
-            .filter((entry) => entry.isDirectory())
-            .map((entry) => entry.name)
-            .filter((name) => {
-            try {
-                validateKaggleExperimentId(name);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        });
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return [];
-        throw err;
-    }
-}
-function experimentIdFromSession(session, workspaceRoot) {
-    for (const ref of session.artifactRefs ?? []) {
-        const relative = path.relative(path.join(workspaceRoot, "experiments"), path.resolve(ref));
-        if (relative.startsWith("..") || path.isAbsolute(relative))
-            continue;
-        const [experimentId] = relative.split(path.sep);
-        if (!experimentId)
-            continue;
-        try {
-            return validateKaggleExperimentId(experimentId);
-        }
-        catch {
-            continue;
-        }
-    }
-    return null;
-}
-function statusFromProcessAndMetrics(processSnapshot, metrics) {
-    if (processSnapshot?.running)
-        return "running";
-    if (metrics?.status === "completed")
-        return "completed";
-    if (metrics?.status === "failed")
-        return "failed";
-    if (processSnapshot && processSnapshot.exitCode !== null) {
-        return processSnapshot.exitCode === 0 ? "completed" : "failed";
-    }
-    return "unknown";
-}
-function confidenceForMetrics(metrics) {
-    return metrics.status === "completed" && metrics.cv_std !== null && metrics.valid_rows > 0 ? "high" : "medium";
-}
-function generateExperimentId() {
-    const timestamp = new Date().toISOString()
-        .replace(/[-:]/g, "")
-        .replace(/\.\d{3}Z$/, "Z");
-    return `exp-${timestamp}`;
-}
-function teeWrapperArgs(command, args, logPath, metricsPath, reportPath, nextActionPath, experimentId, competition) {
-    const script = `
-const { spawn } = require("node:child_process");
-const fs = require("node:fs");
-const path = require("node:path");
-const command = process.argv[1];
-const args = JSON.parse(process.argv[2]);
-const logPath = process.argv[3];
-const childProcessPath = process.argv[4];
-const metricsPath = process.argv[5];
-const reportPath = process.argv[6];
-const nextActionPath = process.argv[7];
-const experimentId = process.argv[8];
-const competition = process.argv[9];
-const workspaceRoot = path.dirname(path.dirname(path.dirname(logPath)));
-fs.mkdirSync(path.dirname(logPath), { recursive: true });
-const log = fs.createWriteStream(logPath, { flags: "a" });
-const child = spawn(command, args, { cwd: process.cwd(), env: process.env, stdio: ["ignore", "pipe", "pipe"] });
-fs.writeFileSync(childProcessPath, JSON.stringify({ pid: child.pid, command, args, startedAt: new Date().toISOString() }, null, 2));
-let exiting = false;
-const write = (stream, chunk) => {
-  stream.write(chunk);
-  log.write(chunk);
-};
-const forwardSignal = (signal) => {
-  if (exiting) return;
-  exiting = true;
-  if (child.exitCode === null && !child.killed) {
-    child.kill(signal);
-  }
-};
-for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-  process.on(signal, () => forwardSignal(signal));
-}
-child.stdout.on("data", (chunk) => write(process.stdout, chunk));
-child.stderr.on("data", (chunk) => write(process.stderr, chunk));
-child.on("error", (err) => {
-  const msg = "[kaggle experiment process error] " + err.message + "\\n";
-  process.stderr.write(msg);
-  log.write(msg);
-});
-child.on("exit", (code, signal) => {
-  writeCompletionArtifacts(code, signal);
-  const msg = "[kaggle experiment exited code=" + (code ?? "null") + " signal=" + (signal ?? "null") + "]\\n";
-  log.write(msg, () => process.exit(code ?? 1));
-});
-
-function writeCompletionArtifacts(code, signal) {
-  const observedAt = new Date().toISOString();
-  const metrics = readMetricsArtifact();
-  const metric = extractMetric(metrics.value);
-  const exitOk = code === 0 && !signal;
-  const status = metrics.value && typeof metrics.value.status === "string"
-    ? metrics.value.status
-    : exitOk ? "completed" : "failed";
-  const report = renderReport({
-    observedAt,
-    code,
-    signal,
-    status,
-    metrics,
-    metric,
-  });
-  const nextAction = buildNextAction({
-    observedAt,
-    code,
-    signal,
-    status,
-    metrics,
-    metric,
-  });
-  try {
-    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
-    fs.writeFileSync(reportPath, report, "utf-8");
-    fs.writeFileSync(nextActionPath, JSON.stringify(nextAction, null, 2) + "\\n", "utf-8");
-  } catch (err) {
-    const msg = "[kaggle experiment artifact error] " + err.message + "\\n";
-    process.stderr.write(msg);
-    log.write(msg);
-  }
-}
-
-function readMetricsArtifact() {
-  try {
-    const raw = fs.readFileSync(metricsPath, "utf-8");
-    return { available: true, value: JSON.parse(raw), error: null };
-  } catch (err) {
-    return { available: false, value: null, error: err.message };
-  }
-}
-
-function extractMetric(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const metricName = firstString(value.metric_name)
-    || firstNumericMetricName(value.all_metrics)
-    || (isFiniteNumber(value.balanced_accuracy) ? "balanced_accuracy" : null)
-    || (isFiniteNumber(value.accuracy) ? "accuracy" : null);
-  if (!metricName) return null;
-  const score = firstNumber(value.cv_score, value.metric_value, value.score, value[metricName], value.all_metrics && value.all_metrics[metricName]);
-  if (score === null) return null;
-  const direction = normalizeDirection(firstString(value.direction) || firstString(value.metric_direction), metricName);
-  return { metric_name: metricName, score, direction };
-}
-
-function renderReport(info) {
-  const lines = [
-    "# Kaggle Experiment " + experimentId,
-    "",
-    "- Competition: " + competition,
-    "- Status: " + info.status,
-    "- Exit: code=" + (info.code ?? "null") + " signal=" + (info.signal ?? "null"),
-    "- Observed at: " + info.observedAt,
-    "- Log: " + relativePath(logPath),
-    "- Metrics: " + relativePath(metricsPath),
-  ];
-  if (info.metric) {
-    lines.push("- Metric: " + info.metric.metric_name + "=" + info.metric.score + " (" + info.metric.direction + ")");
-  } else if (info.metrics.error) {
-    lines.push("- Metric: unavailable (" + info.metrics.error + ")");
-  } else {
-    lines.push("- Metric: unavailable");
-  }
-  lines.push("");
-  lines.push("## Next Action");
-  lines.push(nextActionSummary(info));
-  lines.push("");
-  lines.push("## Artifacts");
-  lines.push("- train.log");
-  lines.push("- metrics.json" + (info.metrics.available ? "" : " (missing or invalid)"));
-  lines.push("- next-action.json");
-  return lines.join("\\n") + "\\n";
-}
-
-function buildNextAction(info) {
-  const actionType = info.metric && info.status === "completed" ? "compare_experiment" : "investigate_run";
-  return {
-    schema_version: "long-running-next-action-v1",
-    created_at: info.observedAt,
-    source: {
-      kind: "kaggle_experiment",
-      experiment_id: experimentId,
-      competition,
-    },
-    observation: {
-      status: info.status,
-      exit_code: info.code,
-      signal: info.signal,
-      metric: info.metric,
-      artifacts: {
-        log: relativePath(logPath),
-        metrics: relativePath(metricsPath),
-        report: relativePath(reportPath),
-      },
-      metrics_error: info.metrics.error,
-    },
-    action: {
-      type: actionType,
-      summary: nextActionSummary(info),
-      candidate_tools: actionType === "compare_experiment"
-        ? ["kaggle_metric_report", "kaggle_compare_experiments"]
-        : ["kaggle_experiment_read"],
-    },
-  };
-}
-
-function nextActionSummary(info) {
-  if (info.metric && info.status === "completed") {
-    return "Compare " + experimentId + " using " + info.metric.metric_name + " before deciding on another run or submission preparation.";
-  }
-  if (info.metrics.error) {
-    return "Inspect train.log and restore a readable metrics.json before comparing experiments.";
-  }
-  return "Inspect train.log and metrics.json before planning the next run.";
-}
-
-function relativePath(target) {
-  return path.relative(workspaceRoot, target).split(path.sep).join("/");
-}
-
-function firstString(value) {
-  return typeof value === "string" && value.trim() ? value : null;
-}
-
-function firstNumber(...values) {
-  for (const value of values) {
-    if (isFiniteNumber(value)) return value;
-  }
-  return null;
-}
-
-function firstNumericMetricName(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  for (const key of ["balanced_accuracy", "accuracy", "macro_f1", "weighted_f1", "log_loss", "rmse"]) {
-    if (isFiniteNumber(value[key])) return key;
-  }
-  for (const [key, field] of Object.entries(value)) {
-    if (isFiniteNumber(field)) return key;
-  }
-  return null;
-}
-
-function isFiniteNumber(value) {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
-function inferDirection(metricName) {
-  return metricName === "rmse" || metricName === "log_loss" ? "minimize" : "maximize";
-}
-
-function normalizeDirection(value, metricName) {
-  if (value === "maximize" || value === "higher" || value === "higher_is_better" || value === "greater_is_better") return "maximize";
-  if (value === "minimize" || value === "lower" || value === "lower_is_better" || value === "less_is_better") return "minimize";
-  return inferDirection(metricName);
-}
-`;
-    const childProcessPath = path.join(path.dirname(logPath), "child-process.json");
-    return ["-e", script, command, JSON.stringify(args), logPath, childProcessPath, metricsPath, reportPath, nextActionPath, experimentId, competition];
-}
-function failureResult(message, startTime) {
-    return {
-        success: false,
-        data: null,
-        summary: message,
-        error: message,
-        durationMs: Date.now() - startTime,
-    };
-}
-async function signalKaggleChildProcess(childProcessPath, signal) {
-    const childProcess = await readJsonObject(childProcessPath);
-    const pid = typeof childProcess?.pid === "number" ? childProcess.pid : null;
-    if (!pid)
-        return;
-    try {
-        process.kill(pid, signal);
-    }
-    catch (err) {
-        if (err.code !== "ESRCH") {
-            throw err;
-        }
-    }
-}
-//# sourceMappingURL=KaggleExperimentTools.js.map