@tradejs/node 3.1.29-beta.282 → 3.1.29-beta.283

package/dist/diagnostics.d.mts

@@ -179,4 +179,57 @@ declare const verifyRuntimeFeedbackReplaySource: ({ bundleDir, runtimeEvidenceBu
     runtimeEvidence: VerifiedRuntimeEvidenceBundle;
 }>;
 
-export { RUNTIME_EVIDENCE_COMPLETE_FILE, RUNTIME_EVIDENCE_MANIFEST_FILE, RUNTIME_EVIDENCE_PAYLOAD_FILE, RUNTIME_FEEDBACK_COMPLETE_FILE, RUNTIME_FEEDBACK_LOG_FILE, RUNTIME_FEEDBACK_MANIFEST_FILE, RUNTIME_FEEDBACK_REPLAY_FILE, type RuntimeEvidenceArtifactManifest, type RuntimeEvidenceDeploymentSnapshot, type RuntimeEvidenceProducer, type RuntimeEvidenceStrategySnapshot, type RuntimeFeedbackReplayManifest, type VerifiedRuntimeEvidenceBundle, type VerifiedRuntimeFeedbackReplayBundle, activeRuntimeEvidenceStrategies, assertCurrentRuntimeEvidenceArtifact, discoverRuntimeEvidenceBundles, discoverRuntimeFeedbackReplayBundles, parseRuntimeEvidenceDeploymentSnapshot, parseRuntimeEvidenceProducer, publishRuntimeEvidenceBundle, resolveRuntimeEvidenceDeploymentSnapshot, resolveRuntimeEvidenceProducer, resolveRuntimeEvidenceTickerUniverse, runtimeDeploymentFromEvidence, runtimeLineageMatchesStrategySnapshot, sealRuntimeFeedbackReplayBundle, verifyRuntimeEvidenceBundle, verifyRuntimeFeedbackReplayBundle, verifyRuntimeFeedbackReplaySource };
+/** Version of the complete feedback read contract, independent of package versions. */
+declare const MCP_FEEDBACK_CONTRACT: {
+    readonly version: 1;
+    readonly hostProtocolVersion: 2;
+    readonly replayQueue: {
+        readonly waitingStates: readonly ["waiting_resources", "waiting_executor"];
+        readonly automaticFailedRetries: false;
+    };
+    readonly artifactEncoding: "base64";
+    readonly maximumChunkBytes: 48000;
+    readonly artifactFiles: readonly ["payload", "manifest.json", ".complete", "replay.log"];
+    readonly requiredTools: readonly ["tradejs_info", "diagnostics_list_reports", "diagnostics_get_report", "artifact_get", "job_get", "job_get_logs"];
+};
+type McpToolDescription = {
+    name: string;
+    inputSchema: {
+        properties?: Record<string, unknown>;
+    };
+};
+/** Check the actual client's tools/list, not only what the server advertises. */
+declare const assertMcpFeedbackContract: (version: unknown, tools: McpToolDescription[]) => void;
+
+type McpArtifactFile = 'payload' | 'manifest.json' | '.complete' | 'replay.log';
+type McpBundleDescriptor = {
+    id: string;
+    kind: 'runtime-evidence' | 'runtime-feedback-replay';
+    files: {
+        file: McpArtifactFile;
+        bytes: number;
+        sha256: string;
+        available: boolean;
+    }[];
+};
+declare class McpReadTransportError extends Error {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+type ChunkRequest = {
+    artifactId: string;
+    file: McpArtifactFile;
+    offset: number;
+    length: number;
+};
+/** The caller owns the authenticated MCP connection. This function only reads artifacts. */
+declare const downloadMcpBundle: ({ descriptor, root, contractVersion, tools, readChunk, wait, }: {
+    descriptor: McpBundleDescriptor;
+    root: string;
+    contractVersion: unknown;
+    tools: McpToolDescription[];
+    readChunk: (request: ChunkRequest) => Promise<unknown>;
+    wait?: (ms: number) => Promise<unknown>;
+}) => Promise<VerifiedRuntimeEvidenceBundle | VerifiedRuntimeFeedbackReplayBundle>;
+
+export { MCP_FEEDBACK_CONTRACT, type McpArtifactFile, type McpBundleDescriptor, McpReadTransportError, type McpToolDescription, RUNTIME_EVIDENCE_COMPLETE_FILE, RUNTIME_EVIDENCE_MANIFEST_FILE, RUNTIME_EVIDENCE_PAYLOAD_FILE, RUNTIME_FEEDBACK_COMPLETE_FILE, RUNTIME_FEEDBACK_LOG_FILE, RUNTIME_FEEDBACK_MANIFEST_FILE, RUNTIME_FEEDBACK_REPLAY_FILE, type RuntimeEvidenceArtifactManifest, type RuntimeEvidenceDeploymentSnapshot, type RuntimeEvidenceProducer, type RuntimeEvidenceStrategySnapshot, type RuntimeFeedbackReplayManifest, type VerifiedRuntimeEvidenceBundle, type VerifiedRuntimeFeedbackReplayBundle, activeRuntimeEvidenceStrategies, assertCurrentRuntimeEvidenceArtifact, assertMcpFeedbackContract, discoverRuntimeEvidenceBundles, discoverRuntimeFeedbackReplayBundles, downloadMcpBundle, parseRuntimeEvidenceDeploymentSnapshot, parseRuntimeEvidenceProducer, publishRuntimeEvidenceBundle, resolveRuntimeEvidenceDeploymentSnapshot, resolveRuntimeEvidenceProducer, resolveRuntimeEvidenceTickerUniverse, runtimeDeploymentFromEvidence, runtimeLineageMatchesStrategySnapshot, sealRuntimeFeedbackReplayBundle, verifyRuntimeEvidenceBundle, verifyRuntimeFeedbackReplayBundle, verifyRuntimeFeedbackReplaySource };

package/dist/diagnostics.d.ts

@@ -179,4 +179,57 @@ declare const verifyRuntimeFeedbackReplaySource: ({ bundleDir, runtimeEvidenceBu
     runtimeEvidence: VerifiedRuntimeEvidenceBundle;
 }>;
 
-export { RUNTIME_EVIDENCE_COMPLETE_FILE, RUNTIME_EVIDENCE_MANIFEST_FILE, RUNTIME_EVIDENCE_PAYLOAD_FILE, RUNTIME_FEEDBACK_COMPLETE_FILE, RUNTIME_FEEDBACK_LOG_FILE, RUNTIME_FEEDBACK_MANIFEST_FILE, RUNTIME_FEEDBACK_REPLAY_FILE, type RuntimeEvidenceArtifactManifest, type RuntimeEvidenceDeploymentSnapshot, type RuntimeEvidenceProducer, type RuntimeEvidenceStrategySnapshot, type RuntimeFeedbackReplayManifest, type VerifiedRuntimeEvidenceBundle, type VerifiedRuntimeFeedbackReplayBundle, activeRuntimeEvidenceStrategies, assertCurrentRuntimeEvidenceArtifact, discoverRuntimeEvidenceBundles, discoverRuntimeFeedbackReplayBundles, parseRuntimeEvidenceDeploymentSnapshot, parseRuntimeEvidenceProducer, publishRuntimeEvidenceBundle, resolveRuntimeEvidenceDeploymentSnapshot, resolveRuntimeEvidenceProducer, resolveRuntimeEvidenceTickerUniverse, runtimeDeploymentFromEvidence, runtimeLineageMatchesStrategySnapshot, sealRuntimeFeedbackReplayBundle, verifyRuntimeEvidenceBundle, verifyRuntimeFeedbackReplayBundle, verifyRuntimeFeedbackReplaySource };
+/** Version of the complete feedback read contract, independent of package versions. */
+declare const MCP_FEEDBACK_CONTRACT: {
+    readonly version: 1;
+    readonly hostProtocolVersion: 2;
+    readonly replayQueue: {
+        readonly waitingStates: readonly ["waiting_resources", "waiting_executor"];
+        readonly automaticFailedRetries: false;
+    };
+    readonly artifactEncoding: "base64";
+    readonly maximumChunkBytes: 48000;
+    readonly artifactFiles: readonly ["payload", "manifest.json", ".complete", "replay.log"];
+    readonly requiredTools: readonly ["tradejs_info", "diagnostics_list_reports", "diagnostics_get_report", "artifact_get", "job_get", "job_get_logs"];
+};
+type McpToolDescription = {
+    name: string;
+    inputSchema: {
+        properties?: Record<string, unknown>;
+    };
+};
+/** Check the actual client's tools/list, not only what the server advertises. */
+declare const assertMcpFeedbackContract: (version: unknown, tools: McpToolDescription[]) => void;
+
+type McpArtifactFile = 'payload' | 'manifest.json' | '.complete' | 'replay.log';
+type McpBundleDescriptor = {
+    id: string;
+    kind: 'runtime-evidence' | 'runtime-feedback-replay';
+    files: {
+        file: McpArtifactFile;
+        bytes: number;
+        sha256: string;
+        available: boolean;
+    }[];
+};
+declare class McpReadTransportError extends Error {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+type ChunkRequest = {
+    artifactId: string;
+    file: McpArtifactFile;
+    offset: number;
+    length: number;
+};
+/** The caller owns the authenticated MCP connection. This function only reads artifacts. */
+declare const downloadMcpBundle: ({ descriptor, root, contractVersion, tools, readChunk, wait, }: {
+    descriptor: McpBundleDescriptor;
+    root: string;
+    contractVersion: unknown;
+    tools: McpToolDescription[];
+    readChunk: (request: ChunkRequest) => Promise<unknown>;
+    wait?: (ms: number) => Promise<unknown>;
+}) => Promise<VerifiedRuntimeEvidenceBundle | VerifiedRuntimeFeedbackReplayBundle>;
+
+export { MCP_FEEDBACK_CONTRACT, type McpArtifactFile, type McpBundleDescriptor, McpReadTransportError, type McpToolDescription, RUNTIME_EVIDENCE_COMPLETE_FILE, RUNTIME_EVIDENCE_MANIFEST_FILE, RUNTIME_EVIDENCE_PAYLOAD_FILE, RUNTIME_FEEDBACK_COMPLETE_FILE, RUNTIME_FEEDBACK_LOG_FILE, RUNTIME_FEEDBACK_MANIFEST_FILE, RUNTIME_FEEDBACK_REPLAY_FILE, type RuntimeEvidenceArtifactManifest, type RuntimeEvidenceDeploymentSnapshot, type RuntimeEvidenceProducer, type RuntimeEvidenceStrategySnapshot, type RuntimeFeedbackReplayManifest, type VerifiedRuntimeEvidenceBundle, type VerifiedRuntimeFeedbackReplayBundle, activeRuntimeEvidenceStrategies, assertCurrentRuntimeEvidenceArtifact, assertMcpFeedbackContract, discoverRuntimeEvidenceBundles, discoverRuntimeFeedbackReplayBundles, downloadMcpBundle, parseRuntimeEvidenceDeploymentSnapshot, parseRuntimeEvidenceProducer, publishRuntimeEvidenceBundle, resolveRuntimeEvidenceDeploymentSnapshot, resolveRuntimeEvidenceProducer, resolveRuntimeEvidenceTickerUniverse, runtimeDeploymentFromEvidence, runtimeLineageMatchesStrategySnapshot, sealRuntimeFeedbackReplayBundle, verifyRuntimeEvidenceBundle, verifyRuntimeFeedbackReplayBundle, verifyRuntimeFeedbackReplaySource };

package/dist/diagnostics.js

@@ -43,7 +43,7 @@ var init_jevInput = __esm({
     import_data = require("@tradejs/core/data");
     import_jev = require("@tradejs/core/jev");
     object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
-    at = (value, ...path7) => path7.reduce((current, key) => object(current)[key], value);
+    at = (value, ...path8) => path8.reduce((current, key) => object(current)[key], value);
     finite = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
     fact = (value) => {
       if (value == null || typeof value === "boolean") return value ?? null;
@@ -453,25 +453,25 @@ var init_jevTraining = __esm({
           "Jev training is bounded to 20000 rows; select a frozen sample first"
         );
       for (const row of rows) {
-        const record = row?.record;
-        if (row?.schema !== "tradejs-jev-study/v4" || !row.signalId || record?.schema !== "tradejs-jev-record/v4" || record.input?.schema !== "tradejs-jev-input/v4" || record.input.questionSet !== import_jev2.JEV_QUESTION_SET || !Number.isFinite(record.input.timestamp) || record.inputHash !== (0, import_jev3.jevHash)(record.input) || record.questionsHash !== (0, import_jev3.jevHash)(questionsForJevInput(record.input)) || record.id !== (0, import_jev3.jevHash)({
-          inputHash: record.inputHash,
-          questionsHash: record.questionsHash,
-          provider: record.provider
+        const record2 = row?.record;
+        if (row?.schema !== "tradejs-jev-study/v4" || !row.signalId || record2?.schema !== "tradejs-jev-record/v4" || record2.input?.schema !== "tradejs-jev-input/v4" || record2.input.questionSet !== import_jev2.JEV_QUESTION_SET || !Number.isFinite(record2.input.timestamp) || record2.inputHash !== (0, import_jev3.jevHash)(record2.input) || record2.questionsHash !== (0, import_jev3.jevHash)(questionsForJevInput(record2.input)) || record2.id !== (0, import_jev3.jevHash)({
+          inputHash: record2.inputHash,
+          questionsHash: record2.questionsHash,
+          provider: record2.provider
         }))
           throw new Error("Invalid Jev study provenance");
-        (0, import_jev3.validateJevResponse)(record.response, record.input.questions);
+        (0, import_jev3.validateJevResponse)(record2.response, record2.input.questions);
         for (const dimension of import_jev2.JEV_DIMENSIONS) {
-          const expected = record.input.questions.includes(dimension) ? record.response.answers[dimension].score / (0, import_jev3.jevScoreMaximum)(dimension) : null;
-          if (record.scores[dimension] !== expected)
+          const expected = record2.input.questions.includes(dimension) ? record2.response.answers[dimension].score / (0, import_jev3.jevScoreMaximum)(dimension) : null;
+          if (record2.scores[dimension] !== expected)
             throw new Error("Jev study scores do not match the teacher response");
         }
         if (row.profit != null && !Number.isFinite(row.profit))
           throw new Error("Invalid study outcome");
-        const prior = unique.get(record.inputHash);
-        if (prior && (prior.record.id !== record.id || prior.profit !== row.profit || (0, import_jev3.jevHash)(prior.record.response) !== (0, import_jev3.jevHash)(record.response)))
+        const prior = unique.get(record2.inputHash);
+        if (prior && (prior.record.id !== record2.id || prior.profit !== row.profit || (0, import_jev3.jevHash)(prior.record.response) !== (0, import_jev3.jevHash)(record2.response)))
           throw new Error("Conflicting duplicated Jev sample");
-        unique.set(record.inputHash, row);
+        unique.set(record2.inputHash, row);
       }
       const ordered = [...unique.values()].sort(
         (a, b) => a.record.input.timestamp - b.record.input.timestamp || a.record.id.localeCompare(b.record.id)
@@ -777,6 +777,8 @@ var init_jevTraining = __esm({
 // src/diagnostics.ts
 var diagnostics_exports = {};
 __export(diagnostics_exports, {
+  MCP_FEEDBACK_CONTRACT: () => MCP_FEEDBACK_CONTRACT,
+  McpReadTransportError: () => McpReadTransportError,
   RUNTIME_EVIDENCE_COMPLETE_FILE: () => RUNTIME_EVIDENCE_COMPLETE_FILE,
   RUNTIME_EVIDENCE_MANIFEST_FILE: () => RUNTIME_EVIDENCE_MANIFEST_FILE,
   RUNTIME_EVIDENCE_PAYLOAD_FILE: () => RUNTIME_EVIDENCE_PAYLOAD_FILE,
@@ -786,8 +788,10 @@ __export(diagnostics_exports, {
   RUNTIME_FEEDBACK_REPLAY_FILE: () => RUNTIME_FEEDBACK_REPLAY_FILE,
   activeRuntimeEvidenceStrategies: () => activeRuntimeEvidenceStrategies,
   assertCurrentRuntimeEvidenceArtifact: () => assertCurrentRuntimeEvidenceArtifact,
+  assertMcpFeedbackContract: () => assertMcpFeedbackContract,
   discoverRuntimeEvidenceBundles: () => discoverRuntimeEvidenceBundles,
   discoverRuntimeFeedbackReplayBundles: () => discoverRuntimeFeedbackReplayBundles,
+  downloadMcpBundle: () => downloadMcpBundle,
   parseRuntimeEvidenceDeploymentSnapshot: () => parseRuntimeEvidenceDeploymentSnapshot,
   parseRuntimeEvidenceProducer: () => parseRuntimeEvidenceProducer,
   publishRuntimeEvidenceBundle: () => publishRuntimeEvidenceBundle,
@@ -982,24 +986,24 @@ var evaluateJevInput = async ({
     promise = getRecord();
     pending.set(pendingKey, promise);
   }
-  let record;
+  let record2;
   try {
-    record = await promise;
+    record2 = await promise;
   } finally {
     pending.delete(pendingKey);
   }
   return {
-    record,
+    record: record2,
     assessment: {
       ...base,
       status: "available",
       recordId: id,
-      model: record.response.model,
-      scores: record.scores,
+      model: record2.response.model,
+      scores: record2.scores,
       confidence: Object.fromEntries(
         import_jev4.JEV_DIMENSIONS.map((key) => [
           key,
-          record.response.answers[key]?.confidence ?? null
+          record2.response.answers[key]?.confidence ?? null
         ])
       )
     }
@@ -2922,7 +2926,7 @@ var recordRuntimeTradeOpen = async (params) => {
   if (!userName) {
     return null;
   }
-  const record = {
+  const record2 = {
     ...params,
     entryCount: 1,
     lastEntryPrice: params.entryPrice,
@@ -2936,33 +2940,33 @@ var recordRuntimeTradeOpen = async (params) => {
     exitTimestamp: null,
     lastSyncedAt: now()
   };
-  const dayKey = (0, import_time.getRuntimeStorageDayKey)(record.entryTimestamp);
-  const runtimeScopeId = record.deploymentId ?? record.accountId;
+  const dayKey = (0, import_time.getRuntimeStorageDayKey)(record2.entryTimestamp);
+  const runtimeScopeId = record2.deploymentId ?? record2.accountId;
   try {
     await Promise.all([
-      (0, import_redis2.setData)(import_redis2.redisKeys.runtimeTrade(userName, record.orderId), record, {
+      (0, import_redis2.setData)(import_redis2.redisKeys.runtimeTrade(userName, record2.orderId), record2, {
         expire: 0
       }),
       (0, import_redis2.setHashJsonField)(
         import_redis2.redisKeys.runtimeTradeBucket(userName, dayKey),
-        record.orderId,
-        record,
+        record2.orderId,
+        record2,
         { expire: 0 }
       ),
       (0, import_redis2.setData)(
-        import_redis2.redisKeys.runtimeActiveTrade(userName, record.symbol, runtimeScopeId),
-        { orderId: record.orderId },
+        import_redis2.redisKeys.runtimeActiveTrade(userName, record2.symbol, runtimeScopeId),
+        { orderId: record2.orderId },
         { expire: 0 }
       )
     ]);
   } catch (error) {
     import_logger2.logger.error(
       "runtime trade open journal failed: %s %s",
-      record.symbol,
+      record2.symbol,
       error?.message || String(error)
     );
   }
-  return record;
+  return record2;
 };
 var recordRuntimeTradeIncrease = async (params) => {
   const {
@@ -8287,10 +8291,10 @@ var parseRuntimeEvidenceDeploymentSnapshot = (value) => {
 };
 var activeRuntimeEvidenceStrategies = (deployment) => deployment.enabled ? deployment.strategies.filter((strategy) => strategy.enabled) : [];
 var unwrapRuntimeEvidenceRows = (value, field) => (Array.isArray(value) ? value : []).map((candidate) => {
-  const record = isRecord2(candidate) ? candidate : null;
-  const nested = record && isRecord2(record[field]) ? record[field] : null;
-  return nested ?? record;
-}).filter((record) => record != null);
+  const record2 = isRecord2(candidate) ? candidate : null;
+  const nested = record2 && isRecord2(record2[field]) ? record2[field] : null;
+  return nested ?? record2;
+}).filter((record2) => record2 != null);
 var assertCurrentRuntimeEvidenceArtifact = (artifact) => {
   if (!isRecord2(artifact) || artifact.reportType !== "runtime-evidence") {
     throw new Error("Invalid runtime evidence artifact");
@@ -9032,8 +9036,169 @@ var verifyRuntimeFeedbackReplaySource = async ({
   });
   return { feedback, runtimeEvidence };
 };
+
+// src/diagnostics/mcpFeedbackContract.ts
+var MCP_FEEDBACK_CONTRACT = {
+  version: 1,
+  hostProtocolVersion: 2,
+  replayQueue: {
+    waitingStates: ["waiting_resources", "waiting_executor"],
+    automaticFailedRetries: false
+  },
+  artifactEncoding: "base64",
+  maximumChunkBytes: 48e3,
+  artifactFiles: ["payload", "manifest.json", ".complete", "replay.log"],
+  requiredTools: [
+    "tradejs_info",
+    "diagnostics_list_reports",
+    "diagnostics_get_report",
+    "artifact_get",
+    "job_get",
+    "job_get_logs"
+  ]
+};
+var assertMcpFeedbackContract = (version, tools) => {
+  if (version !== MCP_FEEDBACK_CONTRACT.version)
+    throw new Error("MCP feedback contract version mismatch");
+  for (const name of MCP_FEEDBACK_CONTRACT.requiredTools)
+    if (!tools.some((tool) => tool.name === name))
+      throw new Error(`MCP feedback requires tool ${name}`);
+  const properties = tools.find((tool) => tool.name === "artifact_get")?.inputSchema.properties;
+  if (!properties || !("file" in properties))
+    throw new Error(
+      "MCP feedback requires artifact_get.file; refresh the client tool schema"
+    );
+};
+
+// src/diagnostics/mcpBundleDownload.ts
+var import_node_crypto8 = require("crypto");
+var import_promises6 = __toESM(require("fs/promises"));
+var import_node_path6 = __toESM(require("path"));
+var McpReadTransportError = class extends Error {
+  constructor(message, retryAfterMs) {
+    super(message);
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var digest = (bytes) => (0, import_node_crypto8.createHash)("sha256").update(bytes).digest("hex");
+var exists = async (file) => import_promises6.default.lstat(file).catch((error) => {
+  if (error.code === "ENOENT") return void 0;
+  throw error;
+});
+var checkFile = async (file) => {
+  const stat = await exists(file);
+  if (stat && (!stat.isFile() || stat.isSymbolicLink()))
+    throw new Error("Invalid local bundle file");
+  return stat;
+};
+var downloadMcpBundle = async ({
+  descriptor,
+  root,
+  contractVersion,
+  tools,
+  readChunk,
+  wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+}) => {
+  assertMcpFeedbackContract(contractVersion, tools);
+  if (!/^[a-f0-9]{64}$/.test(descriptor.id))
+    throw new Error("Invalid artifact identity");
+  const required = ["payload", "manifest.json", ".complete"];
+  if (descriptor.kind === "runtime-feedback-replay")
+    required.push("replay.log");
+  for (const name of required) {
+    const matches = descriptor.files.filter((f) => f.file === name);
+    if (matches.length !== 1 || !matches[0].available || !Number.isSafeInteger(matches[0].bytes) || matches[0].bytes < 0 || !/^[a-f0-9]{64}$/.test(matches[0].sha256))
+      throw new Error(`Incomplete bundle descriptor: ${name}`);
+  }
+  const bundleDir = import_node_path6.default.join(root, descriptor.id);
+  await import_promises6.default.mkdir(bundleDir, { recursive: true });
+  const dir = await import_promises6.default.lstat(bundleDir);
+  if (dir.isSymbolicLink()) throw new Error("Invalid bundle directory");
+  const lock = import_node_path6.default.join(bundleDir, ".download-lock");
+  await import_promises6.default.mkdir(lock);
+  try {
+    for (const name of [
+      ...required.filter((f) => f !== ".complete"),
+      ".complete"
+    ]) {
+      const expected = descriptor.files.find((f) => f.file === name);
+      if (!expected) throw new Error("Missing bundle file");
+      const filename = name === "payload" ? descriptor.kind === "runtime-evidence" ? "runtime-evidence.json" : "replay-runtime-evidence.json" : name;
+      const target = import_node_path6.default.join(bundleDir, filename);
+      const verified = await checkFile(target);
+      if (verified) {
+        if (verified.size !== expected.bytes || digest(await import_promises6.default.readFile(target)) !== expected.sha256)
+          throw new Error("Local bundle checksum mismatch");
+        continue;
+      }
+      const partial = target + ".part";
+      const checkpoint = partial + ".json";
+      const identity = JSON.stringify({
+        artifactId: descriptor.id,
+        file: name,
+        bytes: expected.bytes,
+        sha256: expected.sha256
+      });
+      await checkFile(checkpoint);
+      const stat = await checkFile(partial);
+      if (stat) {
+        if (await import_promises6.default.readFile(checkpoint, "utf8") !== identity || stat.size > expected.bytes)
+          throw new Error("Artifact changed during download");
+      } else {
+        if (await checkFile(checkpoint)) {
+          if (await import_promises6.default.readFile(checkpoint, "utf8") !== identity)
+            throw new Error("Artifact changed during download");
+        } else await import_promises6.default.writeFile(checkpoint, identity, { flag: "wx" });
+      }
+      let offset = stat?.size ?? 0;
+      if (!stat) await import_promises6.default.writeFile(partial, Buffer.alloc(0), { flag: "wx" });
+      while (offset < expected.bytes) {
+        const request = {
+          artifactId: descriptor.id,
+          file: name,
+          offset,
+          length: MCP_FEEDBACK_CONTRACT.maximumChunkBytes
+        };
+        let response;
+        for (let attempt = 0; ; attempt++) {
+          try {
+            response = await readChunk(request);
+            break;
+          } catch (error) {
+            if (!(error instanceof McpReadTransportError) || attempt >= 3)
+              throw error;
+            await wait(
+              Math.max([2e3, 5e3, 1e4][attempt], error.retryAfterMs ?? 0)
+            );
+          }
+        }
+        if (!record(response) || response.id !== descriptor.id || response.file !== name || response.offset !== offset || response.bytes !== expected.bytes || response.sha256 !== expected.sha256 || response.encoding !== "base64" || typeof response.data !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+          response.data
+        ))
+          throw new Error("Invalid artifact chunk identity");
+        const bytes = Buffer.from(response.data, "base64");
+        const next = offset + bytes.length;
+        if (!bytes.length || bytes.length > request.length || next > expected.bytes || response.nextOffset !== (next === expected.bytes ? null : next))
+          throw new Error("Invalid artifact chunk range");
+        await import_promises6.default.appendFile(partial, bytes);
+        offset = next;
+      }
+      if (digest(await import_promises6.default.readFile(partial)) !== expected.sha256)
+        throw new Error("Downloaded bundle checksum mismatch");
+      await import_promises6.default.rename(partial, target);
+      await import_promises6.default.unlink(checkpoint);
+    }
+    const bundle = descriptor.kind === "runtime-evidence" ? await verifyRuntimeEvidenceBundle(bundleDir) : await verifyRuntimeFeedbackReplayBundle(bundleDir);
+    return bundle;
+  } finally {
+    await import_promises6.default.rmdir(lock);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MCP_FEEDBACK_CONTRACT,
+  McpReadTransportError,
   RUNTIME_EVIDENCE_COMPLETE_FILE,
   RUNTIME_EVIDENCE_MANIFEST_FILE,
   RUNTIME_EVIDENCE_PAYLOAD_FILE,
@@ -9043,8 +9208,10 @@ var verifyRuntimeFeedbackReplaySource = async ({
   RUNTIME_FEEDBACK_REPLAY_FILE,
   activeRuntimeEvidenceStrategies,
   assertCurrentRuntimeEvidenceArtifact,
+  assertMcpFeedbackContract,
   discoverRuntimeEvidenceBundles,
   discoverRuntimeFeedbackReplayBundles,
+  downloadMcpBundle,
   parseRuntimeEvidenceDeploymentSnapshot,
   parseRuntimeEvidenceProducer,
   publishRuntimeEvidenceBundle,

package/dist/diagnostics.mjs

@@ -95,10 +95,10 @@ var parseRuntimeEvidenceDeploymentSnapshot = (value) => {
 };
 var activeRuntimeEvidenceStrategies = (deployment) => deployment.enabled ? deployment.strategies.filter((strategy) => strategy.enabled) : [];
 var unwrapRuntimeEvidenceRows = (value, field) => (Array.isArray(value) ? value : []).map((candidate) => {
-  const record = isRecord(candidate) ? candidate : null;
-  const nested = record && isRecord(record[field]) ? record[field] : null;
-  return nested ?? record;
-}).filter((record) => record != null);
+  const record2 = isRecord(candidate) ? candidate : null;
+  const nested = record2 && isRecord(record2[field]) ? record2[field] : null;
+  return nested ?? record2;
+}).filter((record2) => record2 != null);
 var assertCurrentRuntimeEvidenceArtifact = (artifact) => {
   if (!isRecord(artifact) || artifact.reportType !== "runtime-evidence") {
     throw new Error("Invalid runtime evidence artifact");
@@ -840,7 +840,168 @@ var verifyRuntimeFeedbackReplaySource = async ({
   });
   return { feedback, runtimeEvidence };
 };
+
+// src/diagnostics/mcpFeedbackContract.ts
+var MCP_FEEDBACK_CONTRACT = {
+  version: 1,
+  hostProtocolVersion: 2,
+  replayQueue: {
+    waitingStates: ["waiting_resources", "waiting_executor"],
+    automaticFailedRetries: false
+  },
+  artifactEncoding: "base64",
+  maximumChunkBytes: 48e3,
+  artifactFiles: ["payload", "manifest.json", ".complete", "replay.log"],
+  requiredTools: [
+    "tradejs_info",
+    "diagnostics_list_reports",
+    "diagnostics_get_report",
+    "artifact_get",
+    "job_get",
+    "job_get_logs"
+  ]
+};
+var assertMcpFeedbackContract = (version, tools) => {
+  if (version !== MCP_FEEDBACK_CONTRACT.version)
+    throw new Error("MCP feedback contract version mismatch");
+  for (const name of MCP_FEEDBACK_CONTRACT.requiredTools)
+    if (!tools.some((tool) => tool.name === name))
+      throw new Error(`MCP feedback requires tool ${name}`);
+  const properties = tools.find((tool) => tool.name === "artifact_get")?.inputSchema.properties;
+  if (!properties || !("file" in properties))
+    throw new Error(
+      "MCP feedback requires artifact_get.file; refresh the client tool schema"
+    );
+};
+
+// src/diagnostics/mcpBundleDownload.ts
+import { createHash as createHash4 } from "crypto";
+import fs4 from "fs/promises";
+import path4 from "path";
+var McpReadTransportError = class extends Error {
+  constructor(message, retryAfterMs) {
+    super(message);
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var digest = (bytes) => createHash4("sha256").update(bytes).digest("hex");
+var exists = async (file) => fs4.lstat(file).catch((error) => {
+  if (error.code === "ENOENT") return void 0;
+  throw error;
+});
+var checkFile = async (file) => {
+  const stat = await exists(file);
+  if (stat && (!stat.isFile() || stat.isSymbolicLink()))
+    throw new Error("Invalid local bundle file");
+  return stat;
+};
+var downloadMcpBundle = async ({
+  descriptor,
+  root,
+  contractVersion,
+  tools,
+  readChunk,
+  wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+}) => {
+  assertMcpFeedbackContract(contractVersion, tools);
+  if (!/^[a-f0-9]{64}$/.test(descriptor.id))
+    throw new Error("Invalid artifact identity");
+  const required = ["payload", "manifest.json", ".complete"];
+  if (descriptor.kind === "runtime-feedback-replay")
+    required.push("replay.log");
+  for (const name of required) {
+    const matches = descriptor.files.filter((f) => f.file === name);
+    if (matches.length !== 1 || !matches[0].available || !Number.isSafeInteger(matches[0].bytes) || matches[0].bytes < 0 || !/^[a-f0-9]{64}$/.test(matches[0].sha256))
+      throw new Error(`Incomplete bundle descriptor: ${name}`);
+  }
+  const bundleDir = path4.join(root, descriptor.id);
+  await fs4.mkdir(bundleDir, { recursive: true });
+  const dir = await fs4.lstat(bundleDir);
+  if (dir.isSymbolicLink()) throw new Error("Invalid bundle directory");
+  const lock = path4.join(bundleDir, ".download-lock");
+  await fs4.mkdir(lock);
+  try {
+    for (const name of [
+      ...required.filter((f) => f !== ".complete"),
+      ".complete"
+    ]) {
+      const expected = descriptor.files.find((f) => f.file === name);
+      if (!expected) throw new Error("Missing bundle file");
+      const filename = name === "payload" ? descriptor.kind === "runtime-evidence" ? "runtime-evidence.json" : "replay-runtime-evidence.json" : name;
+      const target = path4.join(bundleDir, filename);
+      const verified = await checkFile(target);
+      if (verified) {
+        if (verified.size !== expected.bytes || digest(await fs4.readFile(target)) !== expected.sha256)
+          throw new Error("Local bundle checksum mismatch");
+        continue;
+      }
+      const partial = target + ".part";
+      const checkpoint = partial + ".json";
+      const identity = JSON.stringify({
+        artifactId: descriptor.id,
+        file: name,
+        bytes: expected.bytes,
+        sha256: expected.sha256
+      });
+      await checkFile(checkpoint);
+      const stat = await checkFile(partial);
+      if (stat) {
+        if (await fs4.readFile(checkpoint, "utf8") !== identity || stat.size > expected.bytes)
+          throw new Error("Artifact changed during download");
+      } else {
+        if (await checkFile(checkpoint)) {
+          if (await fs4.readFile(checkpoint, "utf8") !== identity)
+            throw new Error("Artifact changed during download");
+        } else await fs4.writeFile(checkpoint, identity, { flag: "wx" });
+      }
+      let offset = stat?.size ?? 0;
+      if (!stat) await fs4.writeFile(partial, Buffer.alloc(0), { flag: "wx" });
+      while (offset < expected.bytes) {
+        const request = {
+          artifactId: descriptor.id,
+          file: name,
+          offset,
+          length: MCP_FEEDBACK_CONTRACT.maximumChunkBytes
+        };
+        let response;
+        for (let attempt = 0; ; attempt++) {
+          try {
+            response = await readChunk(request);
+            break;
+          } catch (error) {
+            if (!(error instanceof McpReadTransportError) || attempt >= 3)
+              throw error;
+            await wait(
+              Math.max([2e3, 5e3, 1e4][attempt], error.retryAfterMs ?? 0)
+            );
+          }
+        }
+        if (!record(response) || response.id !== descriptor.id || response.file !== name || response.offset !== offset || response.bytes !== expected.bytes || response.sha256 !== expected.sha256 || response.encoding !== "base64" || typeof response.data !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+          response.data
+        ))
+          throw new Error("Invalid artifact chunk identity");
+        const bytes = Buffer.from(response.data, "base64");
+        const next = offset + bytes.length;
+        if (!bytes.length || bytes.length > request.length || next > expected.bytes || response.nextOffset !== (next === expected.bytes ? null : next))
+          throw new Error("Invalid artifact chunk range");
+        await fs4.appendFile(partial, bytes);
+        offset = next;
+      }
+      if (digest(await fs4.readFile(partial)) !== expected.sha256)
+        throw new Error("Downloaded bundle checksum mismatch");
+      await fs4.rename(partial, target);
+      await fs4.unlink(checkpoint);
+    }
+    const bundle = descriptor.kind === "runtime-evidence" ? await verifyRuntimeEvidenceBundle(bundleDir) : await verifyRuntimeFeedbackReplayBundle(bundleDir);
+    return bundle;
+  } finally {
+    await fs4.rmdir(lock);
+  }
+};
 export {
+  MCP_FEEDBACK_CONTRACT,
+  McpReadTransportError,
   RUNTIME_EVIDENCE_COMPLETE_FILE,
   RUNTIME_EVIDENCE_MANIFEST_FILE,
   RUNTIME_EVIDENCE_PAYLOAD_FILE,
@@ -850,8 +1011,10 @@ export {
   RUNTIME_FEEDBACK_REPLAY_FILE,
   activeRuntimeEvidenceStrategies,
   assertCurrentRuntimeEvidenceArtifact,
+  assertMcpFeedbackContract,
   discoverRuntimeEvidenceBundles,
   discoverRuntimeFeedbackReplayBundles,
+  downloadMcpBundle,
   parseRuntimeEvidenceDeploymentSnapshot,
   parseRuntimeEvidenceProducer,
   publishRuntimeEvidenceBundle,

package/dist/mcp.d.mts

@@ -12,7 +12,7 @@ declare const redactMcpJobLog: (line: string) => string;
 /** Offsets refer to the retained worker tail, which may shift while running. */
 declare const readMcpJobLogs: (principal: McpPrincipal, id: string, offset?: number, limit?: number) => Promise<{
     jobId: string;
-    status: "completed" | "failed" | "running" | "queued" | "cancelled";
+    status: "running" | "completed" | "failed" | "queued" | "waiting_resources" | "waiting_executor" | "cancelled";
     updatedAt: number;
     offset: number;
     nextOffset: number | null;
@@ -30,7 +30,7 @@ declare const publicMcpJob: (job: McpJob) => {
     userName: string;
     clientId: string;
     kind: "backtest" | "runtime-evidence" | "runtime-feedback-replay";
-    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    status: "queued" | "waiting_resources" | "waiting_executor" | "running" | "completed" | "failed" | "cancelled";
     createdAt: number;
     updatedAt: number;
     startedAt?: number;

package/dist/mcp.d.ts

@@ -12,7 +12,7 @@ declare const redactMcpJobLog: (line: string) => string;
 /** Offsets refer to the retained worker tail, which may shift while running. */
 declare const readMcpJobLogs: (principal: McpPrincipal, id: string, offset?: number, limit?: number) => Promise<{
     jobId: string;
-    status: "completed" | "failed" | "running" | "queued" | "cancelled";
+    status: "running" | "completed" | "failed" | "queued" | "waiting_resources" | "waiting_executor" | "cancelled";
     updatedAt: number;
     offset: number;
     nextOffset: number | null;
@@ -30,7 +30,7 @@ declare const publicMcpJob: (job: McpJob) => {
     userName: string;
     clientId: string;
     kind: "backtest" | "runtime-evidence" | "runtime-feedback-replay";
-    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    status: "queued" | "waiting_resources" | "waiting_executor" | "running" | "completed" | "failed" | "cancelled";
     createdAt: number;
     updatedAt: number;
     startedAt?: number;

package/dist/mcp.js

@@ -8912,7 +8912,10 @@ var cancelMcpJob = async (principal, id) => {
     const job = await readMcpJob(principal.userName, id);
     if (job.clientId !== principal.clientId)
       throw new Error("Only the submitting client can cancel this job");
-    if (!["queued", "running"].includes(job.status)) return job;
+    if (!["queued", "waiting_resources", "waiting_executor", "running"].includes(
+      job.status
+    ))
+      return job;
     const next = {
       ...job,
       cancelRequested: true,

package/dist/mcp.mjs

@@ -236,7 +236,10 @@ var cancelMcpJob = async (principal, id) => {
     const job = await readMcpJob(principal.userName, id);
     if (job.clientId !== principal.clientId)
       throw new Error("Only the submitting client can cancel this job");
-    if (!["queued", "running"].includes(job.status)) return job;
+    if (!["queued", "waiting_resources", "waiting_executor", "running"].includes(
+      job.status
+    ))
+      return job;
     const next = {
       ...job,
       cancelRequested: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tradejs/node",
-  "version": "3.1.29-beta.282",
+  "version": "3.1.29-beta.283",
   "description": "Node-only runtime for the TradeJS TypeScript framework: strategies, backtests, Pine strategy loading, and plugin registries.",
   "keywords": [
     "tradejs",
@@ -105,9 +105,9 @@
   "dependencies": {
     "@langchain/core": "^1.2.3",
     "@langchain/openai": "^1.5.5",
-    "@tradejs/core": "^3.1.29-beta.282",
-    "@tradejs/infra": "^3.1.29-beta.282",
-    "@tradejs/types": "^3.1.29-beta.282",
+    "@tradejs/core": "^3.1.29-beta.283",
+    "@tradejs/infra": "^3.1.29-beta.283",
+    "@tradejs/types": "^3.1.29-beta.283",
     "@types/node": "^24",
     "chalk": "4.1.2",
     "ioredis": "5.11.1",
@@ -120,7 +120,7 @@
     "typescript": "^5.9"
   },
   "devDependencies": {
-    "@tradejs/indicators": "^3.1.29-beta.282",
+    "@tradejs/indicators": "^3.1.29-beta.283",
     "@tradejs/strategy-adaptive-momentum-ribbon": "3.0.5",
     "@tradejs/strategy-hyperliquid-consensus": "3.0.5",
     "@tradejs/strategy-kit": "3.0.6",