@vecteur/cli 0.6.0 → 0.6.2

package/README.md

@@ -34,6 +34,16 @@ With `VECTEUR_TOKEN`, runs require `--project ID` and `project use` requires a p
 Project PATs retain their server-defined scope; listing and creating Projects require an account
 login. `project list --json` preserves `{projects, active_projects, selected_project_id}`.
 
+`run submit` continues the Project's conversation: it reads the Project's current head (the newest
+Run's `state_hash`) and submits the next turn on it, so two submits in a row are two turns of one
+study, exactly as in the web app. A new Project's first turn has no head. `--parent STATE_HASH`
+skips the read and admits the turn only if that hash is still the head. The CLI never forks a
+Project and never retries: a moved head exits `state_fork` naming the current head, and a Project
+whose Run is still open exits `state_busy` naming that Run (and, when it waits on a question, the
+web address where it can be answered). Nothing is admitted in either case. Once a turn is admitted,
+any later failure names the Run: check it with `vecteur run get RUN_ID` instead of submitting
+again, which would start another turn. Start a fresh study with `vecteur project create`.
+
 `run events` validates dense SSE sequence and returns the canonical direct record only when its
 embedded events match the stream. Redirects, secret-shaped responses, malformed responses and
 timeouts fail nonzero. `--json` sorts object keys for deterministic machine output.

package/bin/vecteur.js

@@ -3,8 +3,8 @@ import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 
 import {
-  CliError, VecteurClient, configuration, isTokenShaped, redact, requestTimeout, resolveOrigin,
-  shouldOpenBrowser, waitForDeviceAuthorization,
+  CliError, VecteurClient, admittedFailure, configuration, isStateHash, isTokenShaped, redact,
+  requestTimeout, resolveOrigin, shouldOpenBrowser, waitForDeviceAuthorization,
 } from "../src/client.js";
 import {
   clearCredentials, credentialsPath, readCredentials, setCurrentOrigin, writeCredentials, selectProject,
@@ -43,8 +43,9 @@ 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>] | projection get <run-id> <projection-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> [--parent <state-hash>] | 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>
+  run submit continues the Project's current head; --parent <state-hash> admits it only if that is still the head
 `;
 }
 
@@ -101,6 +102,10 @@ function parseCommand(argv) {
   const ask = takeOption("--ask", "-a");
   const workspace = takeOption("--workspace");
   const output = takeOption("--output");
+  const parent = takeOption("--parent");
+  if (parent !== undefined && (!isStateHash(parent) || args[0] !== "run" || args[1] !== "submit")) {
+    throw new CliError("usage_invalid", "Invalid command grammar");
+  }
   if (args.some((arg) => typeof arg === "string" && arg.startsWith("-"))) {
     throw new CliError("usage_invalid", "Invalid command grammar");
   }
@@ -142,7 +147,7 @@ function parseCommand(argv) {
   }
   if (args.length === 2 && args[0] === "run" && args[1] === "submit"
       && (projectId === undefined || value(projectId)) && value(ask) && output === undefined) {
-    return { kind: "run_submit", projectId, ask, origin, json };
+    return { kind: "run_submit", projectId, ask, parent, origin, json };
   }
   if (args.length === 3 && args[0] === "run" && args[1] === "get" && value(args[2])
       && projectId === undefined && ask === undefined && output === undefined) {
@@ -336,19 +341,15 @@ async function main() {
   }
   else if (command.kind === "run_submit") {
     const projectId = await resolveRunProject(client, command.projectId);
-    value = await client.runSubmit(projectId, command.ask, onEvent);
+    value = await client.runSubmit(projectId, command.ask, onEvent, undefined, command.parent);
     if (!command.json) {
-      const currentTransferIds = await verifiedTransferIds(client, value);
-      process.stdout.write(human(value, { projectId, currentTransferIds }));
       try {
+        const currentTransferIds = await verifiedTransferIds(client, value);
+        process.stdout.write(human(value, { projectId, currentTransferIds }));
         const cost = await client.customerCost(projectId);
         process.stdout.write(`\n${humanCost(cost)}`);
       } catch (error) {
-        if (error instanceof CliError && error.code === "pat_expired") {
-          throw new CliError("pat_expired",
-            `credential expired after Run ${value.run_id} was admitted; next: vecteur login; then: vecteur run get ${value.run_id}`);
-        }
-        throw error;
+        throw admittedFailure(error, value.run_id);
       }
       return;
     }

package/package.json

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

package/src/client.js

@@ -23,8 +23,28 @@ const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 const MAX_FRAME_BYTES = 1024 * 1024;
 const MAX_EVENTS = 10_000;
 const CAS_REF_SHAPE = /^sha256:([0-9a-f]{64})$/;
+const STATE_HASH_SHAPE = /^[0-9a-f]{64}$/;
 
 
+/** The one shape of a design head, so `--parent` and the head read cannot disagree. */
+export function isStateHash(value) {
+  return typeof value === "string" && STATE_HASH_SHAPE.test(value);
+}
+
+/**
+ * A failure after the acknowledgement names the admitted Run, which may still be running:
+ * retrying the submit would now continue its head and admit a second, billable turn.
+ */
+export function admittedFailure(error, runId) {
+  if (!(error instanceof CliError)) return error;
+  if (error.code === "pat_expired") {
+    return new CliError("pat_expired",
+      `credential expired after Run ${runId} was admitted; next: vecteur login; then: vecteur run get ${runId}`);
+  }
+  return new CliError(error.code,
+    `Run ${runId} was admitted and may still be running; next: vecteur run get ${runId}`);
+}
+
 export function redact(value) {
   return String(value).replace(TOKEN_PATTERN, "[REDACTED]");
 }
@@ -585,24 +605,83 @@ export class VecteurClient {
     }
   }
 
-  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 },
-      idempotencyKey: randomUUID(),
-      signal,
-    });
+  /**
+   * The Project's newest Run from the owner page — the record the web chains on
+   * (`CanvasPage.vue` designHead). Its public `state_hash` is the design head once the Run is
+   * terminal. An empty page with a cursor is a newest Run this login may not see, not an empty
+   * Project, so it refuses rather than let the caller guess null.
+   */
+  async projectNewestRun(projectId, signal = undefined) {
+    const page = await this.#json("GET",
+      `/api/projects/${encodeURIComponent(projectId)}/runs?limit=1`, { signal });
+    const newest = page?.runs?.[0];
+    if (!exactKeys(page, ["runs", "next_before"]) || !Array.isArray(page.runs) || page.runs.length > 1
+        || (page.next_before !== null && typeof page.next_before !== "string")
+        || (newest !== undefined && (newest?.request?.project_id !== projectId
+          || !validateAdmitted(newest.response) || !isStateHash(newest.response.state_hash)))) {
+      throw new CliError("project_runs_invalid", "Server returned malformed Project run history");
+    }
+    if (!newest && page.next_before !== null) {
+      throw new CliError("project_head_hidden",
+        `the newest Run in Project ${projectId} is not visible to this login; nothing was submitted; `
+        + "next: continue in the web app, or pass --parent <state-hash>");
+    }
+    return newest?.response ?? null;
+  }
+
+  /**
+   * One turn, chained onto the Project's design head (OPE admits null only on a Project with no
+   * head, otherwise only the exact head). `parentStateHash` pins a compare-and-swap instead of
+   * reading the head. A 409 is re-read ONCE to name the head or the open Run, and never
+   * re-posted: the Idempotency-Key is per invocation, so a second POST is a second billable
+   * admission, written against a head the ask never saw.
+   */
+  async runSubmit(projectId, ask, onEvent = null, signal = undefined, parentStateHash = undefined) {
+    const parent = parentStateHash === undefined
+      ? (await this.projectNewestRun(projectId, signal))?.state_hash ?? null
+      : parentStateHash;
+    let value;
+    try {
+      value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/runs`, {
+        body: { ask, attachments: [], parent_state_hash: parent, ui_context: null },
+        idempotencyKey: randomUUID(),
+        signal,
+      });
+    } catch (error) {
+      if (error instanceof CliError && (error.code === "state_fork" || error.code === "state_busy")) {
+        throw await this.#admissionRefused(error.code, projectId, parent, signal);
+      }
+      throw error;
+    }
     if (!validateRunAck(value)) {
       throw new CliError("run_ack_invalid", "Server returned malformed run acknowledgement");
     }
     try {
       return await this.runEvents(value.run_id, onEvent, signal);
     } catch (error) {
-      if (error instanceof CliError && error.code === "pat_expired") {
-        throw new CliError("pat_expired",
-          `credential expired after Run ${value.run_id} was admitted; next: vecteur login; then: vecteur run get ${value.run_id}`);
-      }
-      throw error;
+      throw admittedFailure(error, value.run_id);
+    }
+  }
+
+  async #admissionRefused(code, projectId, sent, signal) {
+    let newest;
+    try { newest = await this.projectNewestRun(projectId, signal); } catch { newest = undefined; }
+    if (code === "state_busy" && newest?.terminal === "") {
+      const run = newest.run_id;
+      const question = newest.events.filter((event) => event.kind === "clarification").at(-1);
+      const waiting = question?.payload?.state === "requested"
+        ? ` [waiting for an answer: ${this.config.origin}/dashboard/${encodeURIComponent(projectId)}?run=${encodeURIComponent(run)}]`
+        : "";
+      return new CliError(code, `Run ${run} is still open in Project ${projectId}${waiting}; `
+        + `nothing was admitted; next: vecteur run get ${run}`);
+    }
+    if (code === "state_fork" && newest !== undefined) {
+      const moved = newest?.state_hash ?? null;
+      return new CliError(code, `Project ${projectId} head is ${moved}, this submit sent ${sent}; `
+        + "nothing was admitted; next: " + (moved === null ? "submit again without --parent"
+          : `submit again to continue ${moved}, or pass --parent ${moved}`));
     }
+    return new CliError(code, `nothing was admitted to Project ${projectId}; next: submit again`);
   }
 
   async runGet(runId, signal = undefined) {

package/src/contract.js

@@ -1,5 +1,5 @@
 // GENERATED by scripts/gen-contract.mjs from owner TypeScript projections.
-export const OWNER_CONTRACT_IDENTITY = "api-sha256:8f81ea544eecd9e81da3fd56ad816ac24991cb0e68f3b1cb45180711eaf16056;run-wire-sha256:eee3443d89c0f32e3949fa8832dde769a37d4d92f99b0016777ef0c44eda5d5c";
+export const OWNER_CONTRACT_IDENTITY = "api-sha256:8f81ea544eecd9e81da3fd56ad816ac24991cb0e68f3b1cb45180711eaf16056;run-wire-sha256:03db13f2f5305ded2432fdd33c0db2f1459938584dce250bced24c218eda63ea";
 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","clarification_evidence","input_rows"]);
 export const RETIRED_EVENT_KINDS = Object.freeze(["context_frame","cta","step_label"]);

package/src/mcp.js

@@ -102,7 +102,8 @@ export function createVecteurMcpServer(client = new VecteurClient(), shutdownSig
   tool(server, "vecteur_project_get", "Get one PAT-bound Vecteur project.", projectInput, projectOutput,
     ({ project_id: projectId }, context) => client.projectGet(projectId, signal(context)));
 
-  tool(server, "vecteur_run_submit", "Submit one project turn and return its terminal record.",
+  tool(server, "vecteur_run_submit",
+    "Submit one project turn that continues the Project's current head and return its terminal record.",
     submitInput, admittedOutput, async ({ project_id: projectId, ask }, context) => {
       const progressToken = context.mcpReq._meta?.progressToken;
       const onEvent = progressToken === undefined ? null : (event) => context.mcpReq.notify({