@tuned-tensor/cli 0.9.0 → 0.9.1

package/dist/index.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import {
+  assertLocalRunInputReady,
+  loadLocalRunInput,
+  loadLocalRunnerConfig,
+  runLocalPipeline
+} from "./chunk-DAP2Z7EZ.js";
 
 // src/cli.ts
 import { spawn as spawn4 } from "child_process";
@@ -235,6 +241,135 @@ function canonicalizeSpecBaseModel(body) {
   return body;
 }
 
+// src/pipeline.ts
+var PIPELINE_VERSION = 1;
+var PIPELINE_TARGETS = ["local", "cloud"];
+var PIPELINE_USES = ["train", "evaluate", "compare"];
+var OUTPUTS = {
+  train: ["model"],
+  evaluate: ["report"],
+  compare: ["comparison"]
+};
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function ref(value) {
+  return isRecord(value) && typeof value.from === "string" ? { from: value.from } : void 0;
+}
+function parseRef(value) {
+  const match = /^([A-Za-z][A-Za-z0-9_-]*)\.([A-Za-z][A-Za-z0-9_-]*)$/.exec(value.from);
+  return match ? { stepId: match[1], output: match[2] } : void 0;
+}
+function references(step) {
+  if (step.uses === "evaluate") return [{ field: "model", value: step.with?.model, expected: "model" }];
+  if (step.uses === "compare") return [
+    { field: "before", value: step.with?.before, expected: "report" },
+    { field: "after", value: step.with?.after, expected: "report" }
+  ];
+  return [];
+}
+function resolvedTarget(step, pipeline2) {
+  return step.target ?? pipeline2.target;
+}
+function validatePipeline(pipeline2) {
+  const errors = [];
+  if (!isRecord(pipeline2)) return ["Pipeline must be an object."];
+  if (pipeline2.version !== PIPELINE_VERSION) errors.push("Pipeline version must be 1.");
+  if (pipeline2.target !== void 0 && !PIPELINE_TARGETS.includes(pipeline2.target)) {
+    errors.push("Pipeline target must be local or cloud.");
+  }
+  const typedPipeline = pipeline2;
+  if (!Array.isArray(pipeline2.steps) || pipeline2.steps.length === 0) return [...errors, "Pipeline must contain at least one step."];
+  const seen = /* @__PURE__ */ new Map();
+  let trainCount = 0;
+  for (const rawStep of pipeline2.steps) {
+    if (!isRecord(rawStep)) {
+      errors.push("Each pipeline step must be an object.");
+      continue;
+    }
+    const step = rawStep;
+    if (typeof step.id !== "string" || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(step.id)) {
+      errors.push("Step id must start with a letter and contain only letters, numbers, _ or -.");
+      continue;
+    }
+    if (seen.has(step.id)) errors.push(`Duplicate step id: ${step.id}.`);
+    if (!PIPELINE_USES.includes(step.uses)) errors.push(`Step ${step.id} uses an unsupported component: ${String(step.uses)}.`);
+    if (step.uses === "train" && ++trainCount > 1) errors.push("Pipeline v1 supports at most one train step because local model artifacts are run-scoped.");
+    if (step.uses === "evaluate" && step.with?.evaluator !== void 0 && step.with.evaluator !== "behavior") {
+      errors.push(`Step ${step.id} evaluator must be behavior.`);
+    }
+    if (step.target !== void 0 && !PIPELINE_TARGETS.includes(step.target)) errors.push(`Step ${step.id} target must be local or cloud.`);
+    if (!resolvedTarget(step, typedPipeline)) errors.push(`Step ${step.id} needs a target or a pipeline default target.`);
+    for (const input of references(step)) {
+      if (step.uses === "evaluate" && input.value === "base") continue;
+      const source = ref(input.value);
+      if (!source) {
+        errors.push(`Step ${step.id} ${input.field} must be ${step.uses === "evaluate" ? "base or " : ""}a { from: "step.output" } reference.`);
+        continue;
+      }
+      const parsed = parseRef(source);
+      if (!parsed) {
+        errors.push(`Step ${step.id} has an invalid reference: ${source.from}.`);
+        continue;
+      }
+      const producer = seen.get(parsed.stepId);
+      if (!producer) {
+        const existsLater = pipeline2.steps.some((candidate) => isRecord(candidate) && candidate.id === parsed.stepId);
+        errors.push(`Step ${step.id} has a ${existsLater ? "forward" : "missing"} reference to ${parsed.stepId}.`);
+      } else if (!OUTPUTS[producer.uses]?.includes(parsed.output)) {
+        errors.push(`Step ${parsed.stepId} does not produce ${parsed.output} for step ${step.id}; it produces ${OUTPUTS[producer.uses]?.join(", ") ?? "no outputs"}.`);
+      } else if (parsed.output !== input.expected) {
+        errors.push(`Step ${step.id} ${input.field} requires a ${input.expected} reference, not ${source.from}.`);
+      }
+    }
+    seen.set(step.id, step);
+  }
+  return errors;
+}
+function canonicalPipeline(target = "local") {
+  return {
+    version: PIPELINE_VERSION,
+    name: `default-${target}`,
+    target,
+    steps: [
+      { id: "baseline", uses: "evaluate", target, with: { model: "base", evaluator: "behavior" } },
+      { id: "train", uses: "train", target },
+      { id: "candidate", uses: "evaluate", target, with: { model: { from: "train.model" }, evaluator: "behavior" } },
+      { id: "compare", uses: "compare", target, with: { before: { from: "baseline.report" }, after: { from: "candidate.report" } } }
+    ]
+  };
+}
+function createExecutionPlan(pipeline2, selection = {}) {
+  const errors = validatePipeline(pipeline2);
+  if (errors.length) throw new Error(`Invalid pipeline:
+- ${errors.join("\n- ")}`);
+  const allIds = new Set(pipeline2.steps.map((step) => step.id));
+  for (const id of [...selection.only ?? [], ...selection.skip ?? []]) {
+    if (!allIds.has(id)) throw new Error(`Unknown pipeline step: ${id}.`);
+  }
+  const only = selection.only?.length ? new Set(selection.only) : void 0;
+  const skip = new Set(selection.skip ?? []);
+  const steps = pipeline2.steps.filter((step) => (!only || only.has(step.id)) && !skip.has(step.id));
+  if (!steps.length) throw new Error("Selection leaves no pipeline steps to run.");
+  const retained = new Map(steps.map((step) => [step.id, step]));
+  const resolved = steps.map((step) => {
+    const target = resolvedTarget(step, pipeline2);
+    const transfers = [];
+    for (const input of references(step)) {
+      const source = ref(input.value);
+      if (!source) continue;
+      const parsed = parseRef(source);
+      const producer = retained.get(parsed.stepId);
+      if (!producer) throw new Error(`Step ${step.id} has a dependency on ${parsed.stepId}, which was omitted by --only or --skip.`);
+      const fromTarget = resolvedTarget(producer, pipeline2);
+      if (fromTarget !== target) transfers.push({ from: source.from, from_target: fromTarget, to_target: target });
+    }
+    const normalized = step.uses === "evaluate" ? { ...step, with: { ...step.with, evaluator: step.with?.evaluator ?? "behavior" } } : step;
+    return { ...normalized, target, transfers };
+  });
+  return { version: PIPELINE_VERSION, ...pipeline2.name ? { name: pipeline2.name } : {}, steps: resolved };
+}
+
 // src/agent-tools.ts
 var MAX_TOOL_OUTPUT = 32e3;
 var MAX_PREPARED_ACTION = 24e3;
@@ -283,6 +418,17 @@ var RunBody = Type.Object({
 var BaseModel = Type.Union(
   SUPPORTED_BASE_MODELS.map((model) => Type.Literal(model))
 );
+var PipelineDocument = Type.Object({
+  version: Type.Literal(1),
+  name: Type.Optional(Type.String({ minLength: 1, maxLength: 255 })),
+  target: Type.Optional(Type.Union([Type.Literal("local"), Type.Literal("cloud")])),
+  steps: Type.Array(Type.Object({
+    id: Type.String({ minLength: 1, maxLength: 128 }),
+    uses: Type.Union([Type.Literal("train"), Type.Literal("evaluate"), Type.Literal("compare")]),
+    target: Type.Optional(Type.Union([Type.Literal("local"), Type.Literal("cloud")])),
+    with: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
+  }, { additionalProperties: false }), { minItems: 1, maxItems: 100 })
+}, { additionalProperties: false });
 var Example = Type.Object({
   input: Type.String({ minLength: 1, maxLength: 1e5 }),
   output: Type.String({ minLength: 1, maxLength: 1e5 })
@@ -460,7 +606,18 @@ function createTunedTensorTools(api) {
     }, { additionalProperties: false }), async (p) => await api.get("/billing/transactions", {
       page: p.page ?? 1,
       per_page: p.per_page ?? 10
-    }))
+    })),
+    define("describe_pipeline", "Describe pipeline", "Describe the built-in v1 pipeline contract and canonical recipe. This never executes anything.", Type.Object({
+      target: Type.Optional(Type.Union([Type.Literal("local"), Type.Literal("cloud")]))
+    }, { additionalProperties: false }), async (p) => ({
+      version: 1,
+      components: ["train", "evaluate", "compare"],
+      canonical: canonicalPipeline(p.target ?? "local")
+    })),
+    define("validate_pipeline", "Validate pipeline", "Validate an ordered pipeline and resolve targets/transfers without filesystem, network, or execution side effects.", Type.Object({ pipeline: PipelineDocument }, { additionalProperties: false }), async (p) => {
+      const errors = validatePipeline(p.pipeline);
+      return { valid: errors.length === 0, errors, ...errors.length ? {} : { plan: createExecutionPlan(p.pipeline) } };
+    })
   ];
   const mutations = [
     define("prepare_create_spec", "Prepare create spec", "Prepare creating a spec. This never mutates; /approve is required.", Type.Object({
@@ -480,6 +637,19 @@ function createTunedTensorTools(api) {
         changes: p.changes,
         expected_spec_updated_at: current.updated_at
       }));
+    }),
+    define("prepare_pipeline_run", "Prepare pipeline run", "Prepare a pipeline action for review only. It never executes a step, transfers an artifact, or reserves credits.", Type.Object({
+      pipeline: PipelineDocument,
+      dry_run: Type.Optional(Type.Boolean())
+    }, { additionalProperties: false }), async (p) => {
+      const errors = validatePipeline(p.pipeline);
+      if (errors.length) throw new Error(`Invalid pipeline:
+- ${errors.join("\n- ")}`);
+      const plan = createExecutionPlan(p.pipeline);
+      return await api.propose(proposal("run_pipeline", "Run pipeline", "Review the resolved pipeline before any separate execution approval flow.", {
+        pipeline: p.pipeline,
+        dry_run: p.dry_run ?? true
+      }, { plan, execution: "not started" }));
     })
   ];
   return [...reads, ...mutations];
@@ -692,7 +862,7 @@ var DEFAULT_MAX_CLAIMS = 1e3;
 function assertThreadId(id) {
   if (!UUID.test(id)) throw new Error("Invalid local agent thread ID.");
 }
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function scrub(value, secrets) {
@@ -703,7 +873,7 @@ function scrub(value, secrets) {
     );
   }
   if (Array.isArray(value)) return value.map((entry) => scrub(entry, secrets));
-  if (isRecord(value)) {
+  if (isRecord2(value)) {
     return Object.fromEntries(
       Object.entries(value).map(([key, entry]) => [key, scrub(entry, secrets)])
     );
@@ -852,7 +1022,7 @@ var LocalAgentStore = class {
       throw new Error("Invalid local agent thread file.");
     }
     const parsed = JSON.parse(await readFile(path, "utf8"));
-    if (!isRecord(parsed) || !isRecord(parsed.thread) || parsed.thread.id !== id || !Array.isArray(parsed.messages) || !Array.isArray(parsed.actions)) {
+    if (!isRecord2(parsed) || !isRecord2(parsed.thread) || parsed.thread.id !== id || !Array.isArray(parsed.messages) || !Array.isArray(parsed.actions)) {
       throw new Error("Local agent thread file is malformed.");
     }
     return parsed;
@@ -2218,7 +2388,7 @@ var StreamingTerminalMarkdown = class {
 var accent3 = chalk3.hex("#8B5CF6");
 var successMark2 = () => chalk3.green("\u2713");
 var errorMark2 = () => chalk3.red("\u2717");
-function isRecord2(value) {
+function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function stringValue(value) {
@@ -2259,7 +2429,7 @@ function formatThread(thread, activeId) {
   return `${active} ${chalk3.dim(thread.id.slice(0, 8))}  ${sanitizeTerminalText2(thread.title)}  ${chalk3.dim(dateLabel)}`;
 }
 function actionFromPayload(payload) {
-  const value = isRecord2(payload.action) ? payload.action : isRecord2(payload.approval) ? payload.approval : payload;
+  const value = isRecord3(payload.action) ? payload.action : isRecord3(payload.approval) ? payload.approval : payload;
   const id = stringValue(value.id);
   const title = stringValue(value.title);
   if (!id || !title) return null;
@@ -2392,7 +2562,7 @@ ${chalk3.yellow.bold("Approval required")}  ${chalk3.dim(action.id.slice(0, 8))}
     if (event.type === "tool_call") {
       this.flushResponse();
       this.endOpenLine();
-      const name = stringValue(payload.name) ?? stringValue(isRecord2(payload.tool_call) ? payload.tool_call.name : null) ?? "tool";
+      const name = stringValue(payload.name) ?? stringValue(isRecord3(payload.tool_call) ? payload.tool_call.name : null) ?? "tool";
       this.options.io.write(chalk3.dim(`  \u25CB ${name}
 `));
       return;
@@ -2646,8 +2816,9 @@ ${chalk3.yellow.bold("Approval required")}  ${chalk3.dim(action.id.slice(0, 8))}
 // src/local-runner.ts
 import { constants as osConstants } from "os";
 import { randomUUID as randomUUID4 } from "crypto";
-import { createRequire } from "module";
 import { spawn } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { fileURLToPath } from "url";
 import {
   readFile as readFile3,
   rm,
@@ -2820,7 +2991,7 @@ function shortId(id) {
 }
 
 // src/local-output.ts
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function text(value) {
@@ -2834,10 +3005,10 @@ function number(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function record3(value) {
-  return isRecord3(value) ? value : void 0;
+  return isRecord4(value) ? value : void 0;
 }
 function rows(value) {
-  return Array.isArray(value) ? value.filter(isRecord3) : [];
+  return Array.isArray(value) ? value.filter(isRecord4) : [];
 }
 function displayId(value) {
   const id = text(value);
@@ -3125,19 +3296,19 @@ function renderServePlan(value) {
 function renderKnownJson(args2, value) {
   const command = args2[0];
   const subcommand = args2[1];
-  if (command === "doctor" && isRecord3(value)) {
+  if (command === "doctor" && isRecord4(value)) {
     renderDoctor(value);
     return true;
   }
-  if (command === "init" && isRecord3(value)) {
+  if (command === "init" && isRecord4(value)) {
     renderInit(value);
     return true;
   }
-  if (command === "validate" && isRecord3(value)) {
+  if (command === "validate" && isRecord4(value)) {
     renderValidate(value);
     return true;
   }
-  if (command === "run" && isRecord3(value)) {
+  if (command === "run" && isRecord4(value)) {
     renderRun(value);
     return true;
   }
@@ -3150,15 +3321,15 @@ function renderKnownJson(args2, value) {
       renderRunEvents(value);
       return true;
     }
-    if (subcommand === "get" && isRecord3(value)) {
+    if (subcommand === "get" && isRecord4(value)) {
       renderRunRecord(value);
       return true;
     }
-    if (subcommand === "report" && isRecord3(value)) {
+    if (subcommand === "report" && isRecord4(value)) {
       renderRunReport(value);
       return true;
     }
-    if (subcommand === "compare" && isRecord3(value)) {
+    if (subcommand === "compare" && isRecord4(value)) {
       renderRunComparison(value);
       return true;
     }
@@ -3168,25 +3339,25 @@ function renderKnownJson(args2, value) {
       renderModelsList(value);
       return true;
     }
-    if ((subcommand === "get" || subcommand === "verify") && isRecord3(value)) {
+    if ((subcommand === "get" || subcommand === "verify") && isRecord4(value)) {
       if (subcommand === "verify") printSuccess("Local model artifact is valid");
       renderModelRecord(value);
       return true;
     }
-    if ((subcommand === "prefetch" || subcommand === "verify-base") && isRecord3(value)) {
+    if ((subcommand === "prefetch" || subcommand === "verify-base") && isRecord4(value)) {
       renderModelPrefetch(value);
       return true;
     }
-    if (["active", "activate", "rollback"].includes(subcommand ?? "") && isRecord3(value)) {
+    if (["active", "activate", "rollback"].includes(subcommand ?? "") && isRecord4(value)) {
       renderActiveModel(value);
       return true;
     }
-    if (subcommand === "serve" && isRecord3(value)) {
+    if (subcommand === "serve" && isRecord4(value)) {
       renderServePlan(value);
       return true;
     }
   }
-  if (command === "serve" && isRecord3(value)) {
+  if (command === "serve" && isRecord4(value)) {
     renderServePlan(value);
     return true;
   }
@@ -3274,7 +3445,6 @@ function renderLocalOutput(payload, options = {}) {
 }
 
 // src/local-runner.ts
-var localRequire = createRequire(import.meta.url);
 var DEFAULT_SPEC_NAME = "tunedtensor.json";
 var VALUE_OPTIONS = /* @__PURE__ */ new Set([
   "--config",
@@ -3460,14 +3630,13 @@ async function projectSpecArguments(originalArgs, cwd) {
   };
 }
 function resolveLocalCliEntrypoint() {
-  try {
-    return localRequire.resolve("@tuned-tensor/local");
-  } catch (error) {
+  const entrypoint = fileURLToPath(new URL("./local-runtime.js", import.meta.url));
+  if (!existsSync2(entrypoint)) {
     throw new Error(
-      "TT Local is not installed. Reinstall @tuned-tensor/cli with its local runtime dependency.",
-      { cause: error }
+      "The bundled local runtime is missing. Rebuild or reinstall @tuned-tensor/cli."
     );
   }
+  return entrypoint;
 }
 function localCommandStreamsStdout(args2) {
   const serves = args2[0] === "serve" || args2[0] === "models" && args2[1] === "serve";
@@ -4527,7 +4696,7 @@ Eval Results (${data3._evals.length}):`);
 }
 
 // src/commands/datasets.ts
-import { existsSync as existsSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 var DOCUMENT_OCR_MIME_TYPES = /* @__PURE__ */ new Set(["image/png", "image/jpeg", "image/webp"]);
 function formatBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
@@ -4783,7 +4952,7 @@ function registerDatasetsCommands(parent) {
   });
   datasets.command("upload").description("Upload a JSONL dataset file").argument("<file>", "Path to JSONL file").option("-n, --name <name>", "Dataset name (defaults to filename)").option("-d, --description <desc>", "Dataset description").option("--format <format>", "Dataset format: jsonl or document_ocr_jsonl").action(async (file, cmdOpts) => {
     const opts = parent.opts();
-    if (!existsSync2(file)) {
+    if (!existsSync3(file)) {
       printError(`File not found: ${file}`);
       process.exit(1);
     }
@@ -4834,12 +5003,12 @@ function registerDatasetsCommands(parent) {
 }
 
 // src/commands/label.ts
-import { existsSync as existsSync3, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
 function formatCents2(cents) {
   return `$${(cents / 100).toFixed(2)}`;
 }
 function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 function parseCsvHeader(line) {
   const fields = [];
@@ -5006,7 +5175,7 @@ function registerLabelCommands(parent) {
   const label = parent.command("label").description("Teacher-label real data into training datasets");
   label.command("upload").description("Upload unlabeled inputs (.jsonl or .csv) and start a labeling job").argument("<file>", 'Path to JSONL ({"input": ...} per line) or CSV file').requiredOption("-s, --spec <id>", "Behaviour spec the teacher labels under").option("-c, --input-column <name>", "CSV column that holds the input text").option("-n, --name <name>", "Job name (defaults to filename)").option("--watch", "Block and show progress until labeling finishes").action(async (file, cmdOpts) => {
     const opts = parent.opts();
-    if (!existsSync3(file)) {
+    if (!existsSync4(file)) {
       printError(`File not found: ${file}`);
       process.exit(1);
     }
@@ -5235,7 +5404,7 @@ function registerLabelCommands(parent) {
 import { spawn as spawn3, execFileSync } from "child_process";
 import { createHash } from "crypto";
 import {
-  existsSync as existsSync5,
+  existsSync as existsSync6,
   mkdirSync as mkdirSync3,
   statSync as statSync4,
   createWriteStream,
@@ -5251,7 +5420,7 @@ import { Readable, Transform } from "stream";
 import { pipeline } from "stream/promises";
 
 // src/commands/init.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
 import { resolve as resolve4 } from "path";
 var DEFAULT_SPEC_FILE = "tunedtensor.json";
 var SCAFFOLD = {
@@ -5272,7 +5441,7 @@ var SCAFFOLD = {
 function registerInitCommand(parent) {
   parent.command("init").description("Create a behaviour spec project file").option("-n, --name <name>", "Spec name").option("--model <model>", "Base model ID").option("-f, --file <path>", "Output file path", DEFAULT_SPEC_FILE).action(async (cmdOpts) => {
     const filePath = resolve4(cmdOpts.file);
-    if (existsSync4(filePath)) {
+    if (existsSync5(filePath)) {
       if (isJsonMode()) {
         printJson({ created: false, path: filePath });
         return;
@@ -5301,7 +5470,7 @@ function registerInitCommand(parent) {
 }
 function loadSpec(filePath) {
   const resolved = resolve4(filePath || DEFAULT_SPEC_FILE);
-  if (!existsSync4(resolved)) {
+  if (!existsSync5(resolved)) {
     printError(
       `Spec file not found: ${filePath || DEFAULT_SPEC_FILE}
 Run \`tt init\` to create one.`
@@ -5324,13 +5493,13 @@ function parsePositiveInteger(value, fallback) {
   return Number.isInteger(value) && value >= 0 ? value : fallback;
 }
 function sleep2(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 function readRequestBody(req) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const chunks = [];
     req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
-    req.on("end", () => resolve7(Buffer.concat(chunks)));
+    req.on("end", () => resolve8(Buffer.concat(chunks)));
     req.on("error", reject);
   });
 }
@@ -5398,7 +5567,7 @@ function errorSummary(response, fallback) {
   return typeof message === "string" ? message : fallback;
 }
 async function allocatePort(host) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const server = createNetServer();
     server.on("error", reject);
     server.listen(0, host, () => {
@@ -5408,7 +5577,7 @@ async function allocatePort(host) {
         return;
       }
       const port = address.port;
-      server.close(() => resolve7(port));
+      server.close(() => resolve8(port));
     });
   });
 }
@@ -5448,11 +5617,11 @@ var ManagedModelServer = class {
         sendJson(res, 500, { error: { message: err instanceof Error ? err.message : String(err) } });
       });
     });
-    await new Promise((resolve7, reject) => {
+    await new Promise((resolve8, reject) => {
       this.server?.once("error", reject);
       this.server?.listen(this.options.publicPort, this.options.publicHost, () => {
         this.server?.off("error", reject);
-        resolve7();
+        resolve8();
       });
     });
   }
@@ -5462,15 +5631,15 @@ var ManagedModelServer = class {
     if (!this.server) return;
     const server = this.server;
     this.server = null;
-    await new Promise((resolve7, reject) => {
-      server.close((err) => err ? reject(err) : resolve7());
+    await new Promise((resolve8, reject) => {
+      server.close((err) => err ? reject(err) : resolve8());
     });
   }
   async run() {
     await this.start();
-    await new Promise((resolve7, reject) => {
+    await new Promise((resolve8, reject) => {
       this.server?.once("error", reject);
-      this.server?.once("close", resolve7);
+      this.server?.once("close", resolve8);
     });
   }
   async handle(req, res) {
@@ -5644,7 +5813,7 @@ var ManagedModelServer = class {
     try {
       child.kill("SIGTERM");
       await Promise.race([
-        new Promise((resolve7) => child.once("exit", () => resolve7())),
+        new Promise((resolve8) => child.once("exit", () => resolve8())),
         sleep2(5e3).then(() => {
           if (child.exitCode == null && child.signalCode == null) child.kill("SIGKILL");
         })
@@ -6269,7 +6438,7 @@ if __name__ == "__main__":
 `;
 function resolveOutputPath(output, filename) {
   if (!output) return filename;
-  if (existsSync5(output) && statSync4(output).isDirectory()) {
+  if (existsSync6(output) && statSync4(output).isDirectory()) {
     return join6(output, filename);
   }
   return output;
@@ -6390,7 +6559,7 @@ function runtimePythonPath(cacheDir) {
 function resolveServePython(cacheDir, explicitPython) {
   if (explicitPython) return explicitPython;
   const managedPython = runtimePythonPath(cacheDir);
-  return existsSync5(managedPython) ? managedPython : "python3";
+  return existsSync6(managedPython) ? managedPython : "python3";
 }
 function commandExists(command) {
   try {
@@ -6469,7 +6638,7 @@ function safeSegment(value) {
   return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "model";
 }
 function directoryHasFiles(path) {
-  return existsSync5(path) && statSync4(path).isDirectory() && readdirSync(path).length > 0;
+  return existsSync6(path) && statSync4(path).isDirectory() && readdirSync(path).length > 0;
 }
 function validateArchiveEntryPath(entry) {
   const normalized = normalize(entry).replace(/^[\\/]+/, "");
@@ -6490,7 +6659,7 @@ function validateArchiveEntries(archivePath) {
 function extractArchive(archivePath, targetDir, force) {
   if (directoryHasFiles(targetDir) && !force) return targetDir;
   validateArchiveEntries(archivePath);
-  if (existsSync5(targetDir)) rmSync(targetDir, { recursive: true, force: true });
+  if (existsSync6(targetDir)) rmSync(targetDir, { recursive: true, force: true });
   mkdirSync3(targetDir, { recursive: true });
   execFileSync("tar", ["-xzf", archivePath, "-C", targetDir], { stdio: "inherit" });
   return targetDir;
@@ -6517,7 +6686,7 @@ function findSpecPath(explicitPath, modelPath) {
   const candidates = explicitPath ? [explicitPath] : [join6(process.cwd(), DEFAULT_SPEC_FILE), join6(modelPath, DEFAULT_SPEC_FILE)];
   for (const candidate of candidates) {
     const resolved = resolve5(candidate);
-    if (existsSync5(resolved) && statSync4(resolved).isFile()) return resolved;
+    if (existsSync6(resolved) && statSync4(resolved).isFile()) return resolved;
   }
   return null;
 }
@@ -6527,7 +6696,7 @@ function loadSystemPromptFromSpec(specPath) {
 }
 function loadJsonSchemaForServe(schemaPath) {
   const resolved = resolve5(schemaPath);
-  if (!existsSync5(resolved) || !statSync4(resolved).isFile()) {
+  if (!existsSync6(resolved) || !statSync4(resolved).isFile()) {
     throw new Error(`JSON schema file not found: ${schemaPath}`);
   }
   try {
@@ -6545,7 +6714,7 @@ function writeReferenceServerScript(cacheDir) {
   return scriptPath;
 }
 async function resolveServeTarget(target, opts, cacheDir, forceDownload) {
-  if (existsSync5(target)) {
+  if (existsSync6(target)) {
     const resolved = resolve5(target);
     const stats = statSync4(resolved);
     if (stats.isDirectory()) {
@@ -6571,7 +6740,7 @@ async function resolveServeTarget(target, opts, cacheDir, forceDownload) {
   const modelCacheDir = join6(cacheDir, fullId);
   const archivePath = join6(modelCacheDir, data3.filename);
   const extractDir = join6(modelCacheDir, "model");
-  if (!existsSync5(archivePath) || forceDownload) {
+  if (!existsSync6(archivePath) || forceDownload) {
     await downloadUrlToFile(data3.url, archivePath);
   }
   extractArchive(archivePath, extractDir, forceDownload);
@@ -6675,7 +6844,7 @@ function ollamaSlug(name) {
 }
 function firstExisting(candidates) {
   for (const candidate of candidates) {
-    if (candidate && existsSync5(candidate) && statSync4(candidate).isFile()) {
+    if (candidate && existsSync6(candidate) && statSync4(candidate).isFile()) {
       return resolve5(candidate);
     }
   }
@@ -6687,7 +6856,7 @@ function llamaCppDir(explicit) {
 function resolveConvertScript(opts, required) {
   if (opts.convertScript) {
     const resolved = resolve5(opts.convertScript);
-    if (required && !existsSync5(resolved)) {
+    if (required && !existsSync6(resolved)) {
       throw new Error(`Conversion script not found: ${opts.convertScript}`);
     }
     return resolved;
@@ -6706,7 +6875,7 @@ function resolveConvertScript(opts, required) {
 function resolveQuantizeBin(opts, required) {
   if (opts.quantizeBin) {
     const resolved = resolve5(opts.quantizeBin);
-    if (required && !existsSync5(resolved)) {
+    if (required && !existsSync6(resolved)) {
       throw new Error(`llama-quantize binary not found: ${opts.quantizeBin}`);
     }
     return resolved;
@@ -6841,7 +7010,7 @@ function registerModelsCommands(parent) {
       opts
     );
     const outputPath = resolveOutputPath(cmdOpts.output, data3.filename);
-    if (existsSync5(outputPath) && !cmdOpts.force) {
+    if (existsSync6(outputPath) && !cmdOpts.force) {
       throw new Error(`Output file already exists: ${outputPath}. Use --force to overwrite.`);
     }
     const bytes = await downloadUrlToFile(data3.url, outputPath);
@@ -6950,7 +7119,7 @@ function registerModelsCommands(parent) {
       ollama: ollamaInfo
     };
     if (printOnly) return printExportPlan(plan);
-    if (existsSync5(finalPath) && !cmdOpts.force) {
+    if (existsSync6(finalPath) && !cmdOpts.force) {
       throw new Error(`Output already exists: ${finalPath}. Use --force to overwrite.`);
     }
     mkdirSync3(outputDir, { recursive: true });
@@ -6971,7 +7140,7 @@ function registerModelsCommands(parent) {
         finalPath,
         quantPlan.quantizeType
       ]);
-      if (!cmdOpts.keepIntermediate && intermediatePath && existsSync5(intermediatePath)) {
+      if (!cmdOpts.keepIntermediate && intermediatePath && existsSync6(intermediatePath)) {
         rmSync(intermediatePath, { force: true });
       }
     }
@@ -7024,10 +7193,10 @@ function registerModelsCommands(parent) {
       ]);
       return;
     }
-    if (existsSync5(venvDir) && cmdOpts.force) {
+    if (existsSync6(venvDir) && cmdOpts.force) {
       rmSync(venvDir, { recursive: true, force: true });
     }
-    if (!existsSync5(venvPython)) {
+    if (!existsSync6(venvPython)) {
       mkdirSync3(cacheDir, { recursive: true });
       execFileSync(commands[0][0], commands[0].slice(1), { stdio: "inherit" });
     }
@@ -7639,6 +7808,81 @@ function registerAgentCommands(parent, options) {
   });
 }
 
+// src/commands/pipeline.ts
+import { existsSync as existsSync7, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
+import { resolve as resolve7 } from "path";
+var DEFAULT_PIPELINE_FILE = "tunedtensor.pipeline.json";
+function parseList(value) {
+  if (!value) return void 0;
+  const ids = value.split(",").map((id) => id.trim()).filter(Boolean);
+  if (!ids.length) throw new Error("Step selection must name at least one step.");
+  return ids;
+}
+function loadPipeline(path) {
+  const resolved = resolve7(path);
+  if (!existsSync7(resolved)) throw new Error(`Pipeline file not found: ${path}. Run \`tt pipeline init\` to create one.`);
+  try {
+    return JSON.parse(readFileSync9(resolved, "utf8"));
+  } catch (error) {
+    throw new Error(`Pipeline file must be JSON: ${error.message}`);
+  }
+}
+function outputPlan(plan) {
+  if (isJsonMode()) return printJson(plan);
+  const typed = plan;
+  for (const step of typed.steps) {
+    console.log(`${step.id.padEnd(16)} ${step.uses.padEnd(10)} ${step.target}`);
+    for (const transfer of step.transfers) console.log(`  transfer ${transfer.from}: ${transfer.from_target} -> ${transfer.to_target}`);
+  }
+}
+function registerPipelineCommands(parent) {
+  const pipeline2 = parent.command("pipeline").description("Create, validate, inspect, and safely dry-run ordered pipeline recipes");
+  pipeline2.command("init").description("Write a canonical v1 pipeline recipe").option("-f, --file <path>", "Output file", DEFAULT_PIPELINE_FILE).option("--target <target>", "Default target: local or cloud", "local").action((options) => {
+    if (!PIPELINE_TARGETS.includes(options.target)) throw new Error("--target must be local or cloud.");
+    const path = resolve7(options.file);
+    if (existsSync7(path)) throw new Error(`Pipeline file already exists: ${options.file}.`);
+    const recipe = canonicalPipeline(options.target);
+    writeFileSync5(path, `${JSON.stringify(recipe, null, 2)}
+`);
+    if (isJsonMode()) return printJson({ created: true, path, pipeline: recipe });
+    printSuccess(`Created ${options.file}`);
+  });
+  pipeline2.command("validate").description("Validate a pipeline without any execution or transfer").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).action((options) => {
+    const errors = validatePipeline(loadPipeline(options.file));
+    const result2 = { valid: errors.length === 0, errors };
+    if (isJsonMode()) return printJson(result2);
+    if (errors.length) throw new Error(`Invalid pipeline:
+- ${errors.join("\n- ")}`);
+    printSuccess("Pipeline is valid.");
+  });
+  pipeline2.command("plan").description("Resolve step targets and required artifact transfers").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action((options) => {
+    outputPlan(createExecutionPlan(loadPipeline(options.file), { only: parseList(options.only), skip: parseList(options.skip) }));
+  });
+  pipeline2.command("run").description("Run an ordered local pipeline, or safely preview any pipeline").option("--dry-run", "Resolve and display only; never execute, transfer, or reserve credits").option("-f, --file <path>", "Pipeline file", DEFAULT_PIPELINE_FILE).option("--spec <path>", "Local behavior spec", "tunedtensor.json").option("--config <path>", "Local runtime config").option("--only <ids>", "Comma-separated step IDs to include").option("--skip <ids>", "Comma-separated step IDs to omit").action(async (options) => {
+    const plan = createExecutionPlan(loadPipeline(options.file), { only: parseList(options.only), skip: parseList(options.skip) });
+    if (options.dryRun) {
+      if (isJsonMode()) return printJson({ dry_run: true, ...plan });
+      console.log("Dry run only \u2014 no execution, artifact transfer, or credit reservation will occur.");
+      return outputPlan(plan);
+    }
+    const remote = plan.steps.find((step) => step.target !== "local");
+    if (remote) {
+      throw new Error(`Step "${remote.id}" targets cloud execution. Hosted and mixed pipeline execution is not enabled by this CLI build; use --dry-run.`);
+    }
+    const input = await loadLocalRunInput(resolve7(options.spec));
+    assertLocalRunInputReady(input.request);
+    const config = await loadLocalRunnerConfig(options.config ? resolve7(options.config) : void 0);
+    const localPipeline = {
+      version: 1,
+      ...plan.name ? { name: plan.name } : {},
+      steps: plan.steps.map(({ transfers: _transfers, ...step }) => step)
+    };
+    const result2 = await runLocalPipeline({ request: input.request, config, pipeline: localPipeline });
+    if (isJsonMode()) return printJson(result2);
+    printSuccess(`Pipeline completed with status ${result2.status}.`);
+  });
+}
+
 // src/cli.ts
 async function createDefaultAgentClient(runtime, env, cloud) {
   const selection = getAgentSelection(env);
@@ -7681,7 +7925,16 @@ async function createDefaultAgentClient(runtime, env, cloud) {
 }
 function createLazyDefaultAgentClient(runtime, env, cloud) {
   let pending;
-  const client = () => pending ??= createDefaultAgentClient(runtime, env, cloud);
+  const client = () => {
+    if (!pending) {
+      const attempt = createDefaultAgentClient(runtime, env, cloud);
+      pending = attempt;
+      attempt.catch(() => {
+        if (pending === attempt) pending = void 0;
+      });
+    }
+    return pending;
+  };
   return {
     createThread: async () => await (await client()).createThread(),
     listThreads: async () => await (await client()).listThreads(),
@@ -7696,7 +7949,7 @@ async function runSelfCommand(args2, options = {}) {
   if (!entrypoint) {
     throw new Error("Cannot locate the tt CLI entrypoint.");
   }
-  return await new Promise((resolve7, reject) => {
+  return await new Promise((resolve8, reject) => {
     const child = spawn4(process.execPath, [entrypoint, ...args2], {
       cwd: options.cwd,
       env: options.env ?? process.env,
@@ -7732,7 +7985,7 @@ async function runSelfCommand(args2, options = {}) {
     child.once("close", (exitCode, signal) => {
       cleanup();
       const signalNumber = signal ? osConstants2.signals[signal] : void 0;
-      resolve7({
+      resolve8({
         exitCode: exitCode ?? (typeof signalNumber === "number" ? 128 + signalNumber : 1),
         signal
       });
@@ -7836,6 +8089,7 @@ function createProgram(version, runtime = {}) {
   registerInitCommand(program);
   registerEvalCommand(program);
   registerPushCommand(program);
+  registerPipelineCommands(program);
   registerAgentCommands(program, {
     env,
     output: runtime.stdout ?? process.stdout,
@@ -7993,7 +8247,7 @@ async function runCli(version, runtime = {}) {
 }
 
 // src/index.ts
-runCli("0.9.0").catch((err) => {
+runCli("0.9.1").catch((err) => {
   reportError(err);
   process.exit(1);
 });