pulseed 0.5.4 → 0.6.0

package/dist/tools/kaggle/KaggleExperimentTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KaggleExperimentTools.d.ts","sourceRoot":"","sources":["../../../src/tools/kaggle/KaggleExperimentTools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,KAAK,EACL,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,UAAU,EACX,MAAM,aAAa,CAAC;AAgBrB,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,oDAAoD,CAAC;AAI5D,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWlC,CAAC;AACZ,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;EAIjC,CAAC;AACZ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;EAKrC,CAAC;AACZ,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAqEhG,uBAAe,cAAc,CAAC,MAAM,CAAE,YAAW,KAAK,CAAC,MAAM,CAAC;IAIhD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qBAAqB;IAH7D,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBAEzC,OAAO,GAAE,qBAAoD;IAE5F,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM;IAC9D,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAClG,QAAQ,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CACnD;AAED,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,0BAA0B,CAAC;IACvF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAoC;IAExD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,0BAA0B,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA2GtF,gBAAgB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOzF,iBAAiB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO;CAG/D;AAED,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACrF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAmC;IAEvD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAmDtF,gBAAgB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzF,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO;CAG9D;AAED,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACrF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;OAAmC;IAEvD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAkEtF,gBAAgB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzF,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO;CAG9D;AAED,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACrF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAmC;IAEvD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAsCtF,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOxF,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO;CAG9D;AAED,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,uBAAuB,CAAC;IACjF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAiC;IAErD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,uBAAuB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA6EpF,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIvF,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO;CAG5D;AAED,qBAAa,4BAA6B,SAAQ,cAAc,CAAC,6BAA6B,CAAC;IAC7F,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;OAAuC;IAE3D,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,6BAA6B,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAiG1F,gBAAgB,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI7F,iBAAiB,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO;CAGlE"}
+{"version":3,"file":"KaggleExperimentTools.d.ts","sourceRoot":"","sources":["../../../src/tools/kaggle/KaggleExperimentTools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,KAAK,EACL,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,UAAU,EACX,MAAM,aAAa,CAAC;AAqBrB,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,oDAAoD,CAAC;AAI5D,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYlC,CAAC;AACZ,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;EAIjC,CAAC;AACZ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;EAKrC,CAAC;AACZ,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAiFhG,uBAAe,cAAc,CAAC,MAAM,CAAE,YAAW,KAAK,CAAC,MAAM,CAAC;IAIhD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qBAAqB;IAH7D,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBAEzC,OAAO,GAAE,qBAAoD;IAE5F,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM;IAC9D,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAClG,QAAQ,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CACnD;AAED,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,0BAA0B,CAAC;IACvF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAoC;IAExD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,0BAA0B,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA2ItF,gBAAgB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOzF,iBAAiB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO;CAG/D;AAED,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACrF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAmC;IAEvD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAuDtF,gBAAgB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzF,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO;CAG9D;AAED,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACrF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;OAAmC;IAEvD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA0EtF,gBAAgB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzF,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO;CAG9D;AAED,qBAAa,wBAAyB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACrF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAmC;IAEvD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAsCtF,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOxF,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO;CAG9D;AAED,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,uBAAuB,CAAC;IACjF,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAiC;IAErD,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,uBAAuB,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAiFpF,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIvF,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO;CAG5D;AAED,qBAAa,4BAA6B,SAAQ,cAAc,CAAC,6BAA6B,CAAC;IAC7F,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAW7B;IACF,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;OAAuC;IAE3D,WAAW,IAAI,MAAM;IAIf,IAAI,CAAC,KAAK,EAAE,6BAA6B,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA4H1F,gBAAgB,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI7F,iBAAiB,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO;CAGlE"}

package/dist/tools/kaggle/KaggleExperimentTools.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { KaggleMetricDirectionSchema, normalizedMetricScore, parseKaggleMetrics, } from "./metrics.js";
+import { KAGGLE_VALIDATION_CHECKLIST, KaggleMetricDirectionSchema, KaggleLongRunValidationContractSchema, normalizedMetricScore, parseKaggleMetricsCompatible, summarizeKaggleValidation, } from "./metrics.js";
 import { ensureDirectoryWithinStateRoot, getKaggleExperimentDir, resolveKaggleWorkspaceInput, resolveWorkspaceRelativePath, stateRelativePath, validateKaggleExperimentId, workspaceRelativePath, } from "./paths.js";
 import { defaultProcessSessionManager, } from "../system/ProcessSessionTool/ProcessSessionTool.js";
 const DEFAULT_MAX_LOG_CHARS = 12_000;
@@ -16,6 +16,7 @@ export const KaggleExperimentStartInputSchema = z.object({
     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),
@@ -85,6 +86,7 @@ export class KaggleExperimentStartTool extends KaggleToolBase {
         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();
@@ -106,11 +108,15 @@ export class KaggleExperimentStartTool extends KaggleToolBase {
                 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),
+                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}`,
@@ -123,16 +129,20 @@ export class KaggleExperimentStartTool extends KaggleToolBase {
                     resolved.commandPath,
                     resolved.processPath,
                     resolved.childProcessPath,
+                    resolved.reportPath,
+                    resolved.nextActionPath,
                     ...extraRefs,
                 ],
             }, resolved.workspaceRoot, context);
-            const metadata = experimentMetadata({ ...input, args: commandArgs, artifact_refs: artifactRefs }, resolved, experimentId, metricsPath, extraRefs, session);
+            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),
@@ -140,6 +150,8 @@ export class KaggleExperimentStartTool extends KaggleToolBase {
                     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: {
@@ -152,6 +164,16 @@ export class KaggleExperimentStartTool extends KaggleToolBase {
                         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",
@@ -173,6 +195,8 @@ export class KaggleExperimentStartTool extends KaggleToolBase {
                     resolved.processPath,
                     resolved.logPath,
                     metricsPath,
+                    resolved.reportPath,
+                    resolved.nextActionPath,
                     ...(session.metadataPath ? [session.metadataPath] : []),
                     ...extraRefs,
                 ],
@@ -226,8 +250,8 @@ export class KaggleExperimentReadTool extends KaggleToolBase {
                 : null;
             const processSnapshot = liveRead ?? await readProcessSnapshotFromMetadata(located.processPath);
             const log = await readTail(located.logPath, input.maxChars);
-            const metrics = await readMetrics(located.metricsPath);
-            const missingArtifacts = await missingPaths([located.logPath, located.metricsPath]);
+            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,
@@ -238,12 +262,16 @@ export class KaggleExperimentReadTool extends KaggleToolBase {
                 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 {
@@ -251,7 +279,7 @@ export class KaggleExperimentReadTool extends KaggleToolBase {
                 data: output,
                 summary: `Read Kaggle experiment ${located.experimentId}: ${output.status}`,
                 durationMs: Date.now() - startTime,
-                artifacts: [located.metadataPath, located.processPath, located.logPath, located.metricsPath],
+                artifacts: [located.metadataPath, located.processPath, located.logPath, located.metricsPath, located.reportPath, located.nextActionPath],
             };
         }
         catch (err) {
@@ -291,7 +319,7 @@ export class KaggleExperimentListTool extends KaggleToolBase {
                 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);
+                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
@@ -301,10 +329,14 @@ export class KaggleExperimentListTool extends KaggleToolBase {
                     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),
                     },
                 });
             }
@@ -314,7 +346,7 @@ export class KaggleExperimentListTool extends KaggleToolBase {
                     continue;
                 const located = resolveLocatedExperiment(workspaceRoot, input.competition, experimentId);
                 const existing = experiments.get(experimentId) ?? {};
-                const metrics = await readMetrics(located.metricsPath);
+                const metrics = await readMetrics(located.metricsPath, metricsFallback(workspaceRoot, input.competition, experimentId, located.metricsPath));
                 experiments.set(experimentId, {
                     ...existing,
                     experiment_id: experimentId,
@@ -324,10 +356,14 @@ export class KaggleExperimentListTool extends KaggleToolBase {
                     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),
                     },
                 });
             }
@@ -443,7 +479,8 @@ export class KaggleMetricReportTool extends KaggleToolBase {
             const metricsPath = input.metrics_path
                 ? resolveWorkspaceRelativePath(workspaceRoot, input.metrics_path, "metrics_path")
                 : path.join(getKaggleExperimentDir(workspaceRoot, input.experiment_id), "metrics.json");
-            const metrics = await readMetrics(metricsPath);
+            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,
@@ -467,6 +504,7 @@ export class KaggleMetricReportTool extends KaggleToolBase {
                     ? 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"] : []),
@@ -482,7 +520,9 @@ export class KaggleMetricReportTool extends KaggleToolBase {
                 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: {
@@ -544,7 +584,7 @@ export class KaggleCompareExperimentsTool extends KaggleToolBase {
             const rows = [];
             for (const experimentId of experimentIds) {
                 const metricsPath = path.join(getKaggleExperimentDir(workspaceRoot, experimentId), "metrics.json");
-                const metrics = await readMetrics(metricsPath);
+                const metrics = await readMetrics(metricsPath, metricsFallback(workspaceRoot, input.competition, experimentId, metricsPath));
                 if (!metrics.ok) {
                     rows.push({
                         experiment_id: experimentId,
@@ -557,6 +597,7 @@ export class KaggleCompareExperimentsTool extends KaggleToolBase {
                 }
                 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",
@@ -564,7 +605,11 @@ export class KaggleCompareExperimentsTool extends KaggleToolBase {
                     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),
                 });
             }
@@ -603,24 +648,44 @@ export class KaggleCompareExperimentsTool extends KaggleToolBase {
                     artifacts: rows.map((row) => row.artifact.path),
                 };
             }
-            const best = validRows[0];
-            const runnerUp = validRows[1];
-            const delta = runnerUp ? best.normalized_score - runnerUp.normalized_score : null;
+            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: validRows.findIndex((valid) => valid.experiment_id === row.experiment_id) + 1 }
+                ? {
+                    ...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.`
-                        : `Use ${best.experiment_id}; it leads by ${delta}.`,
+                        : 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,
@@ -651,6 +716,8 @@ function resolveExperiment(workspace, competition, experimentId) {
         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) {
@@ -695,6 +762,8 @@ function experimentMetadata(input, resolved, experimentId, metricsPath, extraRef
             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,
@@ -708,6 +777,8 @@ function experimentMetadata(input, resolved, experimentId, metricsPath, extraRef
             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)),
         },
     };
@@ -719,7 +790,26 @@ function artifactRef(workspaceRoot, artifactPath) {
         state_relative_path: stateRelativePath(artifactPath),
     };
 }
-async function readMetrics(metricsPath) {
+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");
@@ -731,7 +821,7 @@ async function readMetrics(metricsPath) {
         throw err;
     }
     try {
-        return parseKaggleMetrics(JSON.parse(raw));
+        return parseKaggleMetricsCompatible(JSON.parse(raw), fallback);
     }
     catch (err) {
         return {
@@ -854,7 +944,7 @@ function generateExperimentId() {
         .replace(/\.\d{3}Z$/, "Z");
     return `exp-${timestamp}`;
 }
-function teeWrapperArgs(command, args, logPath) {
+function teeWrapperArgs(command, args, logPath, metricsPath, reportPath, nextActionPath, experimentId, competition) {
     const script = `
 const { spawn } = require("node:child_process");
 const fs = require("node:fs");
@@ -863,6 +953,12 @@ 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"] });
@@ -890,12 +986,181 @@ child.on("error", (err) => {
   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];
+    return ["-e", script, command, JSON.stringify(args), logPath, childProcessPath, metricsPath, reportPath, nextActionPath, experimentId, competition];
 }
 function failureResult(message, startTime) {
     return {