@vecteur/cli 0.5.5 → 0.5.6

package/bin/vecteur.js

@@ -9,9 +9,9 @@ import {
 import {
   clearCredentials, credentialsPath, readCredentials, setCurrentOrigin, writeCredentials, selectProject,
 } from "../src/credentials.js";
-import { downloadArtifact } from "../src/download.js";
+import { downloadArtifact, downloadProjection } from "../src/download.js";
 import { humanProjects, resolveNamed, resolveRunProject, resolveWorkspace } from "../src/projects.js";
-import { canonicalJson, human, humanCost, progress } from "../src/format.js";
+import { canonicalJson, currentTransferTables, human, humanCost, progress } from "../src/format.js";
 
 function manifest() {
   return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -43,7 +43,7 @@ function refuseOldNode() {
 
 function helpText(version) {
   return `vecteur ${version}
-  login | logout | whoami | project list | project create <name> [--workspace <name-or-id>] | project use <name-or-id> | project get <id> | run submit [-p <id>] -a <ask> | run get <id> | run events <id> | artifact get <id> [--output <path>] [-p <id>] | mcp
+  login | logout | whoami | project list | project create <name> [--workspace <name-or-id>] | project use <name-or-id> | project get <id> | run submit [-p <id>] -a <ask> | run get <id> | run events <id> | artifact get <id> [--output <path>] [-p <id>] | projection get <run-id> <projection-id> [--output <path>] [-p <id>] | mcp
   --help  --version  --json  --origin <url>  --no-browser  --local  -p/--project  -a/--ask  --output <path>
 `;
 }
@@ -156,6 +156,10 @@ function parseCommand(argv) {
       && ask === undefined) {
     return { kind: "artifact_get", id: args[2], projectId, output, origin, json };
   }
+  if (args.length === 4 && args[0] === "projection" && args[1] === "get"
+      && value(args[2]) && value(args[3]) && ask === undefined) {
+    return { kind: "projection_get", runId: args[2], id: args[3], projectId, output, origin, json };
+  }
   throw new CliError("usage_invalid", "Invalid command grammar");
 }
 
@@ -319,11 +323,23 @@ async function main() {
       : `Downloaded ${value.bytes} bytes to ${value.path} (${value.content_type})\n`);
     return;
   }
+  else if (command.kind === "projection_get") {
+    const projectId = await resolveRunProject(client, command.projectId);
+    const run = await client.runGet(command.runId);
+    const matches = run.events.filter(event => event.kind === "engineering_projection"
+      && event.payload?.projection_id === command.id && event.payload?.kind === "transfer_table");
+    if (matches.length !== 1) throw new CliError("projection_invalid", "Run has no unique transfer table projection");
+    value = await downloadProjection(client, projectId, command.runId, matches[0].payload, command.output);
+    process.stdout.write(command.json ? canonicalJson(value)
+      : `Downloaded ${value.bytes} bytes to ${value.path} (${value.content_type}; ${value.disposition})\n`);
+    return;
+  }
   else if (command.kind === "run_submit") {
     const projectId = await resolveRunProject(client, command.projectId);
     value = await client.runSubmit(projectId, command.ask, onEvent);
     if (!command.json) {
-      process.stdout.write(human(value, { projectId }));
+      const currentTransferIds = await verifiedTransferIds(client, value);
+      process.stdout.write(human(value, { projectId, currentTransferIds }));
       try {
         const cost = await client.customerCost(projectId);
         process.stdout.write(`\n${humanCost(cost)}`);
@@ -341,9 +357,23 @@ async function main() {
   if (!command.json && !renderOptions.projectId && config.projectId) {
     renderOptions = { projectId: config.projectId };
   }
+  if (!command.json && Array.isArray(value?.events)) {
+    renderOptions.currentTransferIds = await verifiedTransferIds(client, value);
+  }
   process.stdout.write(command.json ? canonicalJson(value) : human(value, renderOptions));
 }
 
+async function verifiedTransferIds(client, run) {
+  const ids = new Set();
+  for (const projection of currentTransferTables(run.events ?? [])) {
+    const read = await client.projectionGet(
+      projection.project_id, run.run_id, projection, async () => {},
+    );
+    if (read.disposition === "current") ids.add(projection.projection_id);
+  }
+  return ids;
+}
+
 main().catch((error) => {
   const code = error instanceof CliError ? error.code : "internal_error";
   process.stderr.write(`${code}: ${redact(error?.message ?? "CLI failed")}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vecteur/cli",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "type": "module",
   "bin": {
     "vecteur": "bin/vecteur.js"

package/src/client.js

@@ -535,6 +535,56 @@ export class VecteurClient {
     }
   }
 
+  async projectionGet(projectId, runId, projection, onChunk, signal = undefined) {
+    const ref = projection?.payload_ref;
+    if (typeof projectId !== "string" || !projectId || typeof runId !== "string" || !runId
+        || projection?.kind !== "transfer_table" || projection?.run_id !== runId
+        || projection?.project_id !== projectId
+        || !/^projection-[0-9a-f]{64}$/.test(projection?.projection_id ?? "")
+        || ref?.schema !== "vecteur.owner-transfer-table.v1"
+        || ref?.media_type !== "application/vnd.vecteur.owner-transfer-table+json"
+        || !/^[0-9a-f]{64}$/.test(ref?.payload_sha256 ?? "")
+        || typeof onChunk !== "function") {
+      throw new CliError("projection_invalid", "projection get requires a sealed transfer table on this Run");
+    }
+    const route = `/api/projects/${encodeURIComponent(projectId)}/runs/${encodeURIComponent(runId)}`
+      + `/projections/${encodeURIComponent(projection.projection_id)}/payload`;
+    const response = await this.request("GET", route, {
+      accept: ref.media_type, acceptEncoding: "identity", signal,
+    });
+    try {
+      if (response.headers.get("content-type")?.split(";", 1)[0] !== ref.media_type
+          || (response.headers.get("content-encoding") ?? "identity").toLowerCase() !== "identity") {
+        throw new CliError("projection_invalid", "Server returned the wrong projection media type");
+      }
+      const disposition = response.headers.get("x-vecteur-projection-disposition");
+      if (disposition !== "current" && disposition !== "historical") {
+        throw new CliError("projection_invalid", "Server returned no valid projection disposition");
+      }
+      const declared = response.headers.get("content-length");
+      if (declared === null || !/^(?:0|[1-9][0-9]*)$/.test(declared)
+          || Number(declared) > 256 * 1024 || !response.body) {
+        throw new CliError("projection_invalid", "Projection byte length is invalid");
+      }
+      const digest = createHash("sha256");
+      let bytes = 0;
+      for await (const chunk of response.body) {
+        response[RESPONSE_ACTIVITY]?.();
+        bytes += chunk.byteLength;
+        if (bytes > Number(declared)) throw new CliError("projection_invalid", "Projection exceeds its declared size");
+        digest.update(chunk);
+        await onChunk(chunk);
+      }
+      if (bytes !== Number(declared) || digest.digest("hex") !== ref.payload_sha256) {
+        throw new CliError("projection_invalid", "Projection bytes differ from RunWire");
+      }
+      return { projection_id: projection.projection_id, project_id: projectId,
+        run_id: runId, content_type: ref.media_type, bytes, disposition };
+    } finally {
+      response[RELEASE_TIMEOUT]?.();
+    }
+  }
+
   async runSubmit(projectId, ask, onEvent = null, signal = undefined) {
     const value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/runs`, {
       body: { ask, attachments: [], parent_state_hash: null, ui_context: null },

package/src/contract.js

@@ -1,9 +1,10 @@
 // GENERATED by scripts/gen-contract.mjs from owner TypeScript projections.
-export const OWNER_CONTRACT_IDENTITY = "api-sha256:642fb8f171f5b1ea89188ca730ef37f5f6611b4c5439b57c388333ab342b94d2;run-wire-sha256:ea1a9b7b5867f56968246f9e5fdad6af45095d6b478c3dfdca09d8234ea1eb6a";
+export const OWNER_CONTRACT_IDENTITY = "api-sha256:8f81ea544eecd9e81da3fd56ad816ac24991cb0e68f3b1cb45180711eaf16056;run-wire-sha256:823acb39f2ff5bca7ea54db4beb4589d681bedc5673867a6e6dcdf5c212cf7db";
 export const RECOVERY_ACTIONS = Object.freeze({"delete_project":{"label":"Delete a project","href":"/projects"},"upgrade_plan":{"label":"Upgrade your plan","href":"/dashboard/billing"},"wait_for_reset":{"label":"Wait until the UTC reset","href":null}});
-export const EVENT_KINDS = Object.freeze(["source","step_started","step_finished","tool_call","tool_result","synthesis","artifact","terminal","heartbeat","assistant_delta","knowledge_binding","engineering_projection","provider_attempt","clarification","input_rows"]);
+export const EVENT_KINDS = Object.freeze(["source","step_started","step_finished","tool_call","tool_result","synthesis","artifact","terminal","heartbeat","assistant_delta","knowledge_binding","engineering_projection","provider_attempt","clarification","clarification_evidence","input_rows"]);
 export const RETIRED_EVENT_KINDS = Object.freeze(["context_frame","cta","step_label"]);
 export const TERMINAL_FIELDS = Object.freeze(["answer","defect","deliverable_asked","evidence_dag","instruction_source","intent","missing_input_need","missing_inputs","provider_retry_offer","recovery","refusal_unfounded","state","steps","unmet_wanted"]);
+export const TERMINAL_STATES = Object.freeze(["ok","partial","blocked","refused","infeasible_physics","capability_gap"]);
 export const ARTIFACT_MEDIA_TYPES = Object.freeze({"binary":"application/octet-stream","code":"text/plain","csv":"text/csv","docx":"application/vnd.openxmlformats-officedocument.wordprocessingml.document","drive":"application/vnd.google-drive","html":"text/html","jpeg":"image/jpeg","json":"application/json","md":"text/markdown","pdf":"application/pdf","png":"image/png","svg":"image/svg+xml","xlsx":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"});
 export const TERMINAL_RECOVERY_DECLARATIONS = Object.freeze({"answer_now":[["start_run",["project_id"]]],"artifact_publication_missing":[["start_run",["project_id"]]],"artifact_store_unavailable":[["start_run",["project_id"]]],"budget_exhausted":[["start_run",["project_id"]]],"cancelled":[["start_run",["project_id"]]],"cause_unrecorded":[["start_run",["project_id"]]],"clarification_custody_invalid":[["start_run",["project_id"]]],"clarification_custody_lost":[["start_run",["project_id"]]],"clarification_resume_invalid":[["start_run",["project_id"]]],"clarification_unpersisted":[["start_run",["project_id"]]],"context_unselected":[["start_run",["project_id"]]],"credential_class_disclosure":[["start_run",["project_id"]]],"deliverable_missing":[["start_run",["project_id"]]],"design_state_missing":[["start_run",["project_id"]]],"evidence_admission_invalid":[["start_run",["project_id"]]],"evidence_artifact_invalid":[["start_run",["project_id"]]],"evidence_artifact_unbound":[["start_run",["project_id"]]],"evidence_binding_unresolved":[["start_run",["project_id"]]],"evidence_context_invalid":[["start_run",["project_id"]]],"evidence_extract_unreached":[["start_run",["project_id"]]],"evidence_missing":[["start_run",["project_id"]]],"evidence_owner_receipt_mismatch":[["start_run",["project_id"]]],"evidence_owner_receipt_missing":[["start_run",["project_id"]]],"evidence_payload_invalid":[["start_run",["project_id"]]],"evidence_reached_invalid":[["start_run",["project_id"]]],"evidence_replay_invalid":[["start_run",["project_id"]]],"evidence_run_mismatch":[["start_run",["project_id"]]],"evidence_seal_collision":[["start_run",["project_id"]]],"evidence_selected_unreached":[["start_run",["project_id"]]],"execution_route_invalid":[["start_run",["project_id"]]],"executor_root_invalid":[["start_run",["project_id"]]],"extraction_offer_invalid":[["start_run",["project_id"]]],"extraction_offer_tampered":[["start_run",["project_id"]]],"fact_support_unread":[["start_run",["project_id"]]],"harness_arm_invalid":[["start_run",["project_id"]]],"harness_event_unmapped":[["start_run",["project_id"]]],"harness_exited":[["start_run",["project_id"]]],"harness_mapping_failed":[["start_run",["project_id"]]],"harness_session_invalid":[["start_run",["project_id"]]],"harness_session_missing":[["start_run",["project_id"]]],"harness_timeout":[["start_run",["project_id"]]],"infeasible_physics":[["start_run",["project_id"]]],"lab_denied":[["start_run",["project_id"]]],"lab_failed":[["start_run",["project_id"]]],"lab_not_reproduced":[["start_run",["project_id"]]],"lease_interval_invalid":[["start_run",["project_id"]]],"ledger_malformed":[["start_run",["project_id"]]],"max_tokens":[["start_run",["project_id"]]],"no_facts":[["start_run",["project_id"]]],"not_a_decision_i_can_make":[["start_run",["project_id"]]],"out_of_physics":[["start_run",["project_id"]]],"profile_eligibility_changed":[["start_run",["project_id"]]],"prompt_provenance_unavailable":[["start_run",["project_id"]]],"provider_budget_exhausted":[["start_run",["project_id"]]],"provider_budget_missing":[["start_run",["project_id"]]],"provider_budget_unavailable":[["start_run",["project_id"]]],"provider_relay_absent":[["start_run",["project_id"]]],"provider_route_control_invalid":[["start_run",["project_id"]]],"provider_route_exhausted":[["start_run",["project_id"]],["retry_run",["source_run_id","offer_id","generation"]]],"provider_route_failure_unobserved":[["start_run",["project_id"]]],"provider_route_reconciliation_invalid":[["start_run",["project_id"]]],"provider_route_restart_terminal":[["start_run",["project_id"]]],"provider_training_opted_in":[["start_run",["project_id"]]],"publish_seal_missing":[["start_run",["project_id"]]],"refusal_unfounded":[["start_run",["project_id"]]],"replay_capture_digest_mismatch":[["start_run",["project_id"]]],"replay_capture_invalid":[["start_run",["project_id"]]],"replay_config_incomplete":[["start_run",["project_id"]]],"replay_failed":[["start_run",["project_id"]]],"replay_no_requests":[["start_run",["project_id"]]],"replay_patch_invalid":[["start_run",["project_id"]]],"replay_plugin_absent":[["start_run",["project_id"]]],"replay_provider_socket":[["start_run",["project_id"]]],"replay_receipt_invalid":[["start_run",["project_id"]]],"replay_receipt_owner_chown":[["start_run",["project_id"]]],"replay_receipt_owner_incomplete":[["start_run",["project_id"]]],"replay_receipt_owner_invalid":[["start_run",["project_id"]]],"replay_request_observation_count":[["start_run",["project_id"]]],"replay_request_observation_invalid":[["start_run",["project_id"]]],"replay_request_observation_missing":[["start_run",["project_id"]]],"replay_request_owner_chown":[["start_run",["project_id"]]],"replay_socket_observation_invalid":[["start_run",["project_id"]]],"replay_socket_observation_missing":[["start_run",["project_id"]]],"replay_socket_owner_chown":[["start_run",["project_id"]]],"row_budget":[["start_run",["project_id"]]],"run_database_capability_refused":[["start_run",["project_id"]]],"runtime_unavailable":[["start_run",["project_id"]]],"sealed_contract_violated":[["start_run",["project_id"]]],"sealed_file_missing":[["start_run",["project_id"]]],"seat_patch_absent":[["start_run",["project_id"]]],"seat_patch_drift":[["start_run",["project_id"]]],"selection_admission_invalid":[["start_run",["project_id"]]],"selection_context_invalid":[["start_run",["project_id"]]],"selection_receipt_conflict":[["start_run",["project_id"]]],"selection_receipt_invalid":[["start_run",["project_id"]]],"selection_receipt_missing":[["start_run",["project_id"]]],"selection_required":[["start_run",["project_id"]]],"state_corrupt":[["start_run",["project_id"]]],"state_file_invalid":[["start_run",["project_id"]]],"state_invalid":[["start_run",["project_id"]]],"state_payload_overflow":[["start_run",["project_id"]]],"state_unencodable":[["start_run",["project_id"]]],"state_version_unknown":[["start_run",["project_id"]]],"unreceipted_numbers":[["start_run",["project_id"]]],"usage_egress_mismatch":[["start_run",["project_id"]]],"wall_budget":[["start_run",["project_id"]]],"wanted_not_computed":[["start_run",["project_id"]]]});
 export const ORIGIN_KINDS = Object.freeze(["user","hypothesis","derived","knowledge","file","catalog","default"]);
@@ -47,6 +48,6 @@ const dimension=(v)=>shape(v,["uncached_input","cache_read","cache_write","outpu
 const usage=(v)=>exact(v,["coverage","provider_id","model_id","observed_at","billable_dimensions"])&&["complete","incomplete"].includes(v.coverage)&&[v.provider_id,v.model_id].every(text)&&integer(v.observed_at)&&v.observed_at>=0&&Array.isArray(v.billable_dimensions)&&v.billable_dimensions.length>0&&v.billable_dimensions.every(dimension);
 const control=v=>ownerRunControl(v)&&/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(v.id)&&integer(v.sequence)&&v.sequence>=1&&v.sequence<=32&&(v.kind==="steer"?typeof v.text==="string"&&v.text.trim().length>0&&Buffer.byteLength(v.text,"utf8")<=8192:v.text===undefined||v.text===null)&&((v.attempt===null&&v.step===null)||(integer(v.attempt)&&v.attempt>=0&&integer(v.step)&&v.step>0))&&(v.egress===null||(integer(v.egress.candidate)&&v.egress.candidate>=0&&integer(v.egress.call)&&v.egress.call>=0))&&(v.state==="queued"?v.attempt===null&&v.egress===null:v.state==="claimed"?v.attempt!==null&&v.egress===null:v.state==="dispatched"?v.attempt!==null&&v.egress!==null:v.egress===null);
 const controls=v=>Array.isArray(v)&&v.length<=32&&v.every(control)&&new Set(v.map(x=>x.id)).size===v.length&&v.every((x,i)=>i===0||v[i-1].sequence<x.sequence);
-export const validateAdmitted=(v)=>shape(v,["run_id","state_hash","result_hash","requested_route_id","profile","terminal","usage","events","controls"],["duration_seconds"])&&[v.run_id,v.state_hash,v.result_hash,v.requested_route_id,v.profile].every(text)&&["ok","partial","blocked","refused","infeasible_physics","capability_gap"].includes(v.terminal)&&usage(v.usage)&&Array.isArray(v.events)&&controls(v.controls)&&(v.duration_seconds===undefined||v.duration_seconds===null||(integer(v.duration_seconds)&&v.duration_seconds>=0));
+export const validateAdmitted=(v)=>shape(v,["run_id","state_hash","result_hash","requested_route_id","profile","terminal","usage","events","controls"],["duration_seconds"])&&[v.run_id,v.state_hash,v.requested_route_id,v.profile].every(text)&&((v.terminal===""&&v.result_hash===""&&Array.isArray(v.events)&&(v.events.length===0||v.events.at(-1)?.kind!=="terminal"))||(TERMINAL_STATES.includes(v.terminal)&&text(v.result_hash)))&&usage(v.usage)&&Array.isArray(v.events)&&controls(v.controls)&&(v.duration_seconds===undefined||v.duration_seconds===null||(integer(v.duration_seconds)&&v.duration_seconds>=0));
 export const validatePatCreated=(v)=>exact(v,["id","name","token","prefix","project_id","scopes","created_at","expires_at"])&&[v.id,v.name,v.token,v.prefix].every(text)&&(v.project_id===null||text(v.project_id))&&Array.isArray(v.scopes)&&v.scopes.every(s=>["project:read","project:execute"].includes(s))&&integer(v.created_at)&&integer(v.expires_at);
 export const validateDeviceAuthorization=(v)=>exact(v,["device_code","user_code","verification_uri","verification_uri_complete","expires_at","interval"])&&[v.device_code,v.user_code,v.verification_uri,v.verification_uri_complete].every(text)&&integer(v.expires_at)&&integer(v.interval)&&v.interval>=0;

package/src/download.js

@@ -14,12 +14,22 @@ function defaultName(casRef) {
  * a digest-derived basename, so traversal and shell metacharacters cannot arrive from RunWire.
  */
 export async function downloadArtifact(client, casRef, projectId, output) {
-  const target = resolve(output ?? defaultName(casRef));
+  return downloadTo(output ?? defaultName(casRef),
+    chunk => client.artifactGet(casRef, projectId, chunk));
+}
+
+export async function downloadProjection(client, projectId, runId, projection, output) {
+  return downloadTo(output ?? `transfer-table-${projection.projection_id.slice(11, 23)}.json`,
+    chunk => client.projectionGet(projectId, runId, projection, chunk));
+}
+
+async function downloadTo(filename, fetchBytes) {
+  const target = resolve(filename);
   const temporary = resolve(dirname(target), `.vecteur-${basename(target)}-${randomUUID()}.part`);
   let handle;
   try {
     handle = await open(temporary, "wx", 0o600);
-    const result = await client.artifactGet(casRef, projectId, chunk => handle.writeFile(chunk));
+    const result = await fetchBytes(chunk => handle.writeFile(chunk));
     await handle.sync();
     await handle.close();
     handle = undefined;

package/src/format.js

@@ -207,8 +207,30 @@ function recoveryLine(action) {
   return `Recovery: ${action.capability}${args ? ` ${args}` : ""}`;
 }
 
-export function humanRun(value, { projectId, cost } = {}) {
-  const terminal = terminalPresentation(value);
+export function currentTransferTables(events) {
+  const candidates = new Map();
+  const cleared = new Map();
+  for (const event of events) {
+    if (event.kind !== "engineering_projection") continue;
+    const projection = event.payload;
+    if (projection?.kind === "projection_clear" && projection.clear_kind === "transfer_table") {
+      const ids = cleared.get(projection.node_id) ?? new Set();
+      ids.add(projection.execution_id);
+      cleared.set(projection.node_id, ids);
+    } else if (projection?.kind === "transfer_table") {
+      const rows = candidates.get(projection.node_id) ?? [];
+      rows.push(projection);
+      candidates.set(projection.node_id, rows);
+    }
+  }
+  return [...candidates.entries()].flatMap(([node, rows]) => {
+    const current = [...rows].reverse().find(row => !cleared.get(node)?.has(row.execution_id));
+    return current ? [current] : [];
+  });
+}
+
+export function humanRun(value, { projectId, cost, currentTransferIds } = {}) {
+  const terminal = value.terminal === "" ? null : terminalPresentation(value);
   const origins = value.events.flatMap(event => event.kind === "step_finished"
     ? inputLines(event.payload?.step?.inputs ?? event.payload?.inputs) : []);
   const artifacts = value.events.filter(event => event.kind === "artifact").map(event => event.payload);
@@ -217,11 +239,25 @@ export function humanRun(value, { projectId, cost } = {}) {
   }
   const tasks = taskLines(value.events);
   const assumptions = assumptionLines(value.events);
+  const currentTables = currentTransferTables(value.events).filter(projection =>
+    currentTransferIds?.has(projection.projection_id));
   const lines = [];
-  if (terminal.answer !== undefined) lines.push(terminal.answer, "");
+  if (terminal?.answer !== undefined) lines.push(terminal.answer, "");
   if (tasks.length) lines.push("Steps:", ...tasks, "");
   if (origins.length) lines.push("Inputs and origins:", ...origins, "");
   if (assumptions.length) lines.push("Assumptions:", ...assumptions, "");
+  for (const projection of currentTables) {
+    if (typeof projection.search_status !== "string" || projection.origin !== "unattributed"
+        || typeof projection.validation_status !== "string" || typeof projection.withheld !== "boolean") {
+      throw new CliError("projection_invalid", "Transfer table metadata is malformed");
+    }
+    lines.push(`Transfer table: ${plainLine(projection.search_status)} · input origins ${projection.origin}`
+      + ` · validation ${plainLine(projection.validation_status)}`
+      + ` · path ${projection.withheld ? "withheld" : "shown"}`);
+    const project = projectId ? ` --project ${shellQuote(projectId)}` : "";
+    lines.push(`  vecteur projection get ${shellQuote(value.run_id)} ${shellQuote(projection.projection_id)}`
+      + ` --output ${shellQuote("transfer-table.json")}${project}`, "");
+  }
   if (artifacts.length) {
     lines.push("Artifacts:");
     for (const artifact of artifacts) {
@@ -231,9 +267,12 @@ export function humanRun(value, { projectId, cost } = {}) {
     }
     lines.push("");
   }
-  lines.push(`Run: ${plainLine(value.run_id)}`, `Terminal: ${terminal.state}`);
-  if (terminal.defect !== undefined) lines.push(`Cause: ${terminal.defect}`);
-  lines.push(...terminal.recovery.map(recoveryLine));
+  lines.push(`Run: ${plainLine(value.run_id)}`);
+  if (terminal) {
+    lines.push(`Terminal: ${terminal.state}`);
+    if (terminal.defect !== undefined) lines.push(`Cause: ${terminal.defect}`);
+    lines.push(...terminal.recovery.map(recoveryLine));
+  }
   if (cost) lines.push("", humanCost(cost).trimEnd());
   return `${lines.join("\n")}\n`;
 }

package/src/mcp.js

@@ -3,7 +3,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
 
 import { CliError, VecteurClient, redact } from "./client.js";
-import { EVENT_KINDS, RETIRED_EVENT_KINDS } from "./contract.js";
+import { EVENT_KINDS, RETIRED_EVENT_KINDS, TERMINAL_STATES } from "./contract.js";
 import { canonicalJson } from "./format.js";
 
 const projectInput = z.object({ project_id: z.string().min(1) }).strict();
@@ -53,9 +53,9 @@ const runControlOutput = z.object({
   text: z.string().nullable().optional(),
 }).strict();
 const admittedOutput = z.object({
-  run_id: z.string().min(1), state_hash: z.string().min(1), result_hash: z.string().min(1),
+  run_id: z.string().min(1), state_hash: z.string().min(1), result_hash: z.string(),
   requested_route_id: z.string().min(1), profile: z.string().min(1),
-  terminal: z.enum(["ok", "partial", "blocked", "refused", "infeasible_physics", "capability_gap"]),
+  terminal: z.union([z.enum([...TERMINAL_STATES]), z.literal("")]),
   duration_seconds: z.number().int().safe().nonnegative().nullable().optional(),
   usage: z.object({
     coverage: z.enum(["complete", "incomplete"]), provider_id: z.string().min(1),
@@ -64,7 +64,9 @@ const admittedOutput = z.object({
   }).strict(),
   events: z.array(eventOutput),
   controls: z.array(runControlOutput),
-}).strict();
+}).strict().refine(value => value.terminal === ""
+  ? value.result_hash === "" && value.events.at(-1)?.kind !== "terminal"
+  : value.result_hash.length > 0, "Run terminal and result hash are not paired");
 
 function success(value) {
   return {
@@ -114,7 +116,7 @@ export function createVecteurMcpServer(client = new VecteurClient(), shutdownSig
       return client.runSubmit(projectId, ask, onEvent, signal(context));
     });
 
-  tool(server, "vecteur_run_get", "Get one terminal Vecteur run record.", runInput, admittedOutput,
+  tool(server, "vecteur_run_get", "Get one Vecteur run record, including an open run.", runInput, admittedOutput,
     ({ run_id: runId }, context) => client.runGet(runId, signal(context)));
 
   tool(server, "vecteur_run_events", "Validate run events against its direct record.", runInput,