@runtypelabs/sdk 5.4.0 → 5.6.0

package/dist/index.mjs

@@ -1887,315 +1887,755 @@ function resolveBatchExecutionId(pausedTools) {
   return "";
 }
 
-// src/flows-ensure.ts
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function normalizeConfigForHash(config) {
-  if (!isPlainObject(config)) return {};
-  const normalized = {};
-  for (const key of Object.keys(config).sort()) {
-    const value = config[key];
-    if (value === void 0) continue;
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      normalized[key] = normalizeConfigForHash(value);
-    } else if (Array.isArray(value)) {
-      normalized[key] = value.map((item) => {
-        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
-          return normalizeConfigForHash(item);
+// src/evals-ensure.ts
+var CHECK_GRADER_KINDS = /* @__PURE__ */ new Set([
+  "contains",
+  "not_contains",
+  "matches_expected",
+  "regex",
+  "valid_json",
+  "json_field",
+  "length",
+  "latency",
+  "no_error",
+  // Trace checks.
+  "called_tool",
+  "not_called_tool",
+  "used_no_tools",
+  "max_tool_calls",
+  "tool_order",
+  "ran_step",
+  "step_order",
+  "completed",
+  "cost"
+]);
+function gradeable(data) {
+  const obj = { ...data };
+  const rebuild = (patch) => gradeable({ ...obj, ...patch });
+  Object.defineProperty(obj, "gate", {
+    value: () => rebuild({ severity: "gate" }),
+    enumerable: false
+  });
+  Object.defineProperty(obj, "soft", {
+    value: () => rebuild({ severity: "soft" }),
+    enumerable: false
+  });
+  if (data.kind === "ai") {
+    Object.defineProperty(obj, "atLeast", {
+      value: (threshold) => {
+        if (typeof threshold !== "number" || !Number.isFinite(threshold) || threshold < 1 || threshold > 5) {
+          throw new Error("atLeast() requires a numeric judge threshold between 1 and 5");
         }
-        return item;
-      });
-    } else {
-      normalized[key] = value;
-    }
+        return rebuild({ threshold });
+      },
+      enumerable: false
+    });
   }
-  return normalized;
+  return obj;
 }
-function normalizeStepForHash(step) {
-  const stepObj = isPlainObject(step) ? step : {};
-  return {
-    type: typeof stepObj.type === "string" ? stepObj.type : "",
-    name: typeof stepObj.name === "string" ? stepObj.name : "",
-    enabled: stepObj.enabled !== false,
-    ...typeof stepObj.when === "string" ? { when: stepObj.when } : {},
-    config: normalizeConfigForHash(stepObj.config),
-    order: typeof stepObj.order === "number" ? stepObj.order : 0
-  };
+function contains(value, opts) {
+  return gradeable({
+    kind: "contains",
+    value,
+    ...opts?.caseSensitive ? { caseSensitive: true } : {}
+  });
 }
-async function computeFlowContentHash(steps) {
-  const normalized = [...steps].sort((a, b) => {
-    const orderA = isPlainObject(a) && typeof a.order === "number" ? a.order : 0;
-    const orderB = isPlainObject(b) && typeof b.order === "number" ? b.order : 0;
-    return orderA - orderB;
-  }).map(normalizeStepForHash);
-  const serialized = JSON.stringify(normalized);
-  const encoded = new TextEncoder().encode(serialized);
-  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
-  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+function notContains(value, opts) {
+  return gradeable({
+    kind: "not_contains",
+    value,
+    ...opts?.caseSensitive ? { caseSensitive: true } : {}
+  });
 }
-var DEFINE_FLOW_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "steps"]);
-var DEFINE_FLOW_STEP_KEYS = /* @__PURE__ */ new Set([
-  "type",
-  "name",
-  "order",
-  "enabled",
-  "when",
-  "config"
-]);
-function collectStepNonPortableToolRefs(config, path) {
-  const found = [];
-  const tools = config.tools;
-  const isAccountScoped = (ref) => typeof ref === "string" && ref.startsWith("tool_");
-  const isRawId = (ref, prefix) => typeof ref === "string" && ref.startsWith(prefix);
-  const scanArray = (value, subPath) => {
-    if (!Array.isArray(value)) return;
-    value.forEach((ref, i) => {
-      if (isAccountScoped(ref)) found.push(`${subPath}[${i}]`);
-    });
-  };
-  const scanKeys = (value, subPath) => {
-    if (!isPlainObject(value)) return;
-    for (const key of Object.keys(value)) {
-      if (isAccountScoped(key)) found.push(`${subPath}.${key}`);
-    }
-  };
-  if (isPlainObject(tools)) {
-    scanArray(tools.toolIds, `${path}.tools.toolIds`);
-    scanKeys(tools.toolConfigs, `${path}.tools.toolConfigs`);
-    scanKeys(tools.perToolLimits, `${path}.tools.perToolLimits`);
-    if (isPlainObject(tools.approval)) {
-      scanArray(tools.approval.require, `${path}.tools.approval.require`);
-    }
-    if (isPlainObject(tools.subagentConfig)) {
-      scanArray(tools.subagentConfig.toolPool, `${path}.tools.subagentConfig.toolPool`);
-    }
-    if (isPlainObject(tools.codeModeConfig)) {
-      scanArray(tools.codeModeConfig.toolPool, `${path}.tools.codeModeConfig.toolPool`);
-    }
-    if (Array.isArray(tools.runtimeTools)) {
-      tools.runtimeTools.forEach((runtimeTool, i) => {
-        if (!isPlainObject(runtimeTool) || !isPlainObject(runtimeTool.config)) return;
-        const base = `${path}.tools.runtimeTools[${i}].config`;
-        const rtConfig = runtimeTool.config;
-        if (runtimeTool.toolType === "subagent" && isRawId(rtConfig.agentId, "agent_")) {
-          found.push(`${base}.agentId`);
-        } else if (runtimeTool.toolType === "flow" && isRawId(rtConfig.flowId, "flow_")) {
-          found.push(`${base}.flowId`);
-        }
-      });
-    }
-  }
-  if (isAccountScoped(config.toolId)) {
-    found.push(`${path}.toolId`);
-  }
-  if (isRawId(config.agentId, "agent_")) {
-    found.push(`${path}.agentId`);
-  }
-  for (const branch of ["trueSteps", "falseSteps"]) {
-    const nested = config[branch];
-    if (!Array.isArray(nested)) continue;
-    nested.forEach((nestedStep, i) => {
-      if (isPlainObject(nestedStep) && isPlainObject(nestedStep.config)) {
-        found.push(
-          ...collectStepNonPortableToolRefs(
-            nestedStep.config,
-            `${path}.${branch}[${i}].config`
-          )
-        );
-      }
-    });
-  }
-  return found;
+function matchesExpected() {
+  return gradeable({ kind: "matches_expected" });
 }
-function defineFlow(input) {
-  if (!input || typeof input !== "object") {
-    throw new Error("defineFlow requires a definition object");
+function regex(pattern, flags) {
+  return gradeable({ kind: "regex", pattern, ...flags ? { flags } : {} });
+}
+function validJson() {
+  return gradeable({ kind: "valid_json" });
+}
+function jsonField(path, opts) {
+  return gradeable({
+    kind: "json_field",
+    path,
+    ...opts && "equals" in opts && opts.equals !== void 0 ? { equals: opts.equals } : {},
+    ...opts && typeof opts.exists === "boolean" ? { exists: opts.exists } : {}
+  });
+}
+function length(opts) {
+  if (!opts || opts.minChars === void 0 && opts.maxChars === void 0) {
+    throw new Error("length() requires at least one of minChars or maxChars");
   }
-  if (typeof input.name !== "string" || input.name.length === 0) {
-    throw new Error('defineFlow requires a non-empty string "name"');
+  return gradeable({
+    kind: "length",
+    ...opts.minChars !== void 0 ? { minChars: opts.minChars } : {},
+    ...opts.maxChars !== void 0 ? { maxChars: opts.maxChars } : {}
+  });
+}
+function latency(maxMs) {
+  if (!Number.isFinite(maxMs) || maxMs <= 0) {
+    throw new Error("latency() requires a positive maxMs");
   }
-  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_FLOW_TOP_LEVEL_KEYS.has(key));
-  if (unknownKeys.length > 0) {
-    throw new Error(
-      `defineFlow: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name and steps. (Description is not part of the v1 ensure surface.)`
-    );
+  return gradeable({ kind: "latency", maxMs });
+}
+function noError() {
+  return gradeable({ kind: "no_error" });
+}
+function calledTool(name, opts) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("calledTool() requires a non-empty tool name");
   }
-  if (!Array.isArray(input.steps) || input.steps.length === 0) {
-    throw new Error('defineFlow requires a non-empty "steps" array');
+  if (opts?.times !== void 0 && (!Number.isInteger(opts.times) || opts.times <= 0)) {
+    throw new Error('calledTool() "times" must be a positive integer');
   }
-  const steps = input.steps.map((step, index) => {
-    if (!isPlainObject(step)) {
-      throw new Error(`defineFlow: steps[${index}] must be an object`);
-    }
-    if (typeof step.type !== "string" || step.type.length === 0) {
-      throw new Error(`defineFlow: steps[${index}] requires a non-empty string "type"`);
-    }
-    if (typeof step.name !== "string" || step.name.length === 0) {
-      throw new Error(`defineFlow: steps[${index}] requires a non-empty string "name"`);
-    }
-    const unknownStepKeys = Object.keys(step).filter((key) => !DEFINE_FLOW_STEP_KEYS.has(key));
-    if (unknownStepKeys.length > 0) {
-      throw new Error(
-        `defineFlow: steps[${index}] has unknown field(s): ${unknownStepKeys.join(", ")}. Allowed step fields are type, name, order, enabled, when, config. (Step ids are server artifacts and not part of a portable definition.)`
-      );
-    }
-    const config = isPlainObject(step.config) ? step.config : void 0;
-    if (config) {
-      const nonPortable = collectStepNonPortableToolRefs(config, `steps[${index}].config`);
-      if (nonPortable.length > 0) {
-        throw new Error(
-          `defineFlow: account-scoped reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026/agent_\u2026/flow_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references, or reference a saved resource by name \u2014 tool:<name>, agent:<name>, or flow:<name> instead.`
-        );
-      }
-    }
-    return {
-      type: step.type,
-      name: step.name,
-      // Explicit 1-based order (the flow builder's convention) so the local
-      // probe hash agrees with the server's persisted step order.
-      order: typeof step.order === "number" ? step.order : index + 1,
-      ...step.enabled !== void 0 ? { enabled: step.enabled } : {},
-      ...typeof step.when === "string" ? { when: step.when } : {},
-      ...config ? { config } : {}
-    };
+  return gradeable({
+    kind: "called_tool",
+    name,
+    ...opts && "input" in opts && opts.input !== void 0 ? { input: opts.input } : {},
+    ...opts && "output" in opts && opts.output !== void 0 ? { output: opts.output } : {},
+    ...opts && typeof opts.isError === "boolean" ? { isError: opts.isError } : {},
+    ...opts?.times !== void 0 ? { times: opts.times } : {}
   });
-  return { name: input.name, steps };
 }
-var FlowEnsureConflictError = class extends Error {
-  constructor(body) {
-    super(body.error ?? `Flow ensure conflict: ${body.code}`);
-    this.name = "FlowEnsureConflictError";
-    this.code = body.code;
-    this.lastModifiedSource = body.lastModifiedSource;
-    this.modifiedAt = body.modifiedAt;
-    this.currentHash = body.currentHash;
+function notCalledTool(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("notCalledTool() requires a non-empty tool name");
   }
-};
-var FlowDriftError = class extends Error {
-  constructor(plan) {
-    super(
-      `Flow "${plan.flowId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.flows.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
-    );
-    this.name = "FlowDriftError";
-    this.plan = plan;
+  return gradeable({ kind: "not_called_tool", name });
+}
+function usedNoTools() {
+  return gradeable({ kind: "used_no_tools" });
+}
+function maxToolCalls(max) {
+  if (!Number.isInteger(max) || max < 0) {
+    throw new Error("maxToolCalls() requires a non-negative integer");
   }
-};
-function parseRequestError(err) {
-  if (!(err instanceof Error)) return { status: null, body: null };
-  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
-  if (!match) return { status: null, body: null };
-  try {
-    return { status: Number(match[1]), body: JSON.parse(match[2]) };
-  } catch {
-    return { status: Number(match[1]), body: null };
+  return gradeable({ kind: "max_tool_calls", max });
+}
+function toolOrder(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) {
+    throw new Error("toolOrder() requires a non-empty array of tool names");
   }
+  return gradeable({ kind: "tool_order", tools });
 }
-function toConflictError(err) {
-  const { status, body } = parseRequestError(err);
-  if (status !== 409 || !isPlainObject(body)) return null;
-  const code = body.code;
-  if (code !== "external_modification" && code !== "remote_changed") return null;
-  return new FlowEnsureConflictError(
-    body
-  );
+function ranStep(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("ranStep() requires a non-empty step name");
+  }
+  return gradeable({ kind: "ran_step", name });
 }
-var serverHashMemo = /* @__PURE__ */ new WeakMap();
-function memoFor(client) {
-  let memo = serverHashMemo.get(client);
-  if (!memo) {
-    memo = /* @__PURE__ */ new Map();
-    serverHashMemo.set(client, memo);
+function stepOrder(steps) {
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw new Error("stepOrder() requires a non-empty array of step names");
   }
-  return memo;
+  return gradeable({ kind: "step_order", steps });
 }
-function memoize(memo, memoKey, result) {
-  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+function completed() {
+  return gradeable({ kind: "completed" });
 }
-async function request(client, body) {
-  try {
-    return await client.post(
-      "/flows/ensure",
-      body
-    );
-  } catch (err) {
-    const conflict = toConflictError(err);
-    if (conflict) throw conflict;
-    throw err;
+function cost(maxUsd) {
+  if (!Number.isFinite(maxUsd) || maxUsd <= 0) {
+    throw new Error("cost() requires a positive maxUsd");
   }
+  return gradeable({ kind: "cost", maxUsd });
 }
-async function ensureFlow(client, definition, options = {}) {
-  const { dryRun, onConflict, release, expectedRemoteHash, expectNoChanges } = options;
-  const passthrough = {
-    ...onConflict ? { onConflict } : {},
-    ...release ? { release } : {},
-    ...expectedRemoteHash ? { expectedRemoteHash } : {}
-  };
-  if (dryRun || expectNoChanges) {
-    const plan = await request(client, {
-      name: definition.name,
-      definition,
-      dryRun: true,
-      ...passthrough
+function judge(criteria, opts) {
+  if (typeof criteria !== "string" || criteria.trim().length === 0) {
+    throw new Error("judge() requires non-empty criteria");
+  }
+  return gradeable({
+    kind: "ai",
+    criteria,
+    ...opts?.preset ? { preset: opts.preset } : {},
+    ...opts?.useExpected ? { useExpected: true } : {},
+    ...opts?.model ? { model: opts.model } : {},
+    ...opts?.threshold !== void 0 ? { threshold: opts.threshold } : {}
+  });
+}
+var judges = {
+  answersQuestion: () => judge(
+    "The response directly addresses what the user asked, without dodging or answering a different question.",
+    { preset: "answersQuestion" }
+  ),
+  matchesExpected: () => judge(
+    "The response conveys the same facts and conclusion as the expected answer. Wording may differ.",
+    { preset: "matchesExpected", useExpected: true }
+  ),
+  followsInstructions: () => judge(
+    "The response obeys every instruction in the system prompt (format, tone, constraints, refusals).",
+    { preset: "followsInstructions" }
+  ),
+  grounded: () => judge(
+    "Every factual claim in the response is supported by the provided context or the expected answer. Flag anything invented.",
+    { preset: "grounded" }
+  ),
+  rightTone: (voice = "{describe the voice you want}") => judge(`The response matches this voice: ${voice}.`, { preset: "rightTone" }),
+  safeToSend: () => judge(
+    "The response contains nothing embarrassing to show a customer: no leaked internals, no hostile tone, no policy violations.",
+    { preset: "safeToSend" }
+  )
+};
+var DEFINE_EVAL_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "target",
+  "graders",
+  "cases",
+  "virtual"
+]);
+var DEFINE_EVAL_CASE_KEYS = /* @__PURE__ */ new Set(["name", "input", "expected", "expect"]);
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeTarget(target) {
+  if (!isPlainObject(target)) {
+    throw new Error('defineEval requires a "target" object: { flow: name } or { agent: name }');
+  }
+  const hasFlow = typeof target.flow === "string" && target.flow.length > 0;
+  const hasAgent = typeof target.agent === "string" && target.agent.length > 0;
+  if (hasFlow === hasAgent) {
+    throw new Error(
+      'defineEval "target" must name exactly one of flow or agent: { flow: "name" } XOR { agent: "name" }'
+    );
+  }
+  const extraKeys = Object.keys(target).filter((k) => k !== "flow" && k !== "agent");
+  if (extraKeys.length > 0) {
+    throw new Error(`defineEval "target" has unknown field(s): ${extraKeys.join(", ")}`);
+  }
+  return hasFlow ? { flow: target.flow } : { agent: target.agent };
+}
+function validateGrader(grader, where) {
+  if (!isPlainObject(grader) || typeof grader.kind !== "string") {
+    throw new Error(`defineEval: ${where} must be a grader object with a string "kind"`);
+  }
+  if (grader.kind === "ai") {
+    if (typeof grader.criteria !== "string" || grader.criteria.trim().length === 0) {
+      throw new Error(`defineEval: ${where} is an AI grader and requires non-empty "criteria"`);
+    }
+    return grader;
+  }
+  if (!CHECK_GRADER_KINDS.has(grader.kind)) {
+    throw new Error(
+      `defineEval: ${where} has unknown grader kind "${grader.kind}". Known kinds: ${[...CHECK_GRADER_KINDS].join(", ")}, ai.`
+    );
+  }
+  return grader;
+}
+function normalizeCaseInput(input, where) {
+  if (input === void 0) return {};
+  if (!isPlainObject(input)) {
+    throw new Error(`defineEval: ${where} "input" must be an object`);
+  }
+  const out = {};
+  if (input.variables !== void 0) {
+    if (!isPlainObject(input.variables)) {
+      throw new Error(`defineEval: ${where} "input.variables" must be an object`);
+    }
+    out.variables = input.variables;
+  }
+  if (input.messages !== void 0) {
+    if (!Array.isArray(input.messages)) {
+      throw new Error(`defineEval: ${where} "input.messages" must be an array`);
+    }
+    out.messages = input.messages.map((m, i) => {
+      if (!isPlainObject(m) || typeof m.role !== "string" || typeof m.content !== "string") {
+        throw new Error(`defineEval: ${where} "input.messages[${i}]" must be { role, content }`);
+      }
+      return { role: m.role, content: m.content };
     });
-    if (plan.result !== "plan") {
-      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+  }
+  return out;
+}
+function defineEval(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineEval requires a definition object");
+  }
+  const unknownKeys = Object.keys(input).filter((k) => !DEFINE_EVAL_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineEval: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are target, graders, cases, virtual.`
+    );
+  }
+  const target = normalizeTarget(input.target);
+  if (input.name !== void 0 && (typeof input.name !== "string" || input.name.length === 0)) {
+    throw new Error('defineEval "name" must be a non-empty string when provided');
+  }
+  const name = input.name ?? ("flow" in target ? `flow:${target.flow}` : `agent:${target.agent}`);
+  const suiteGraders = (input.graders ?? []).map((g, i) => validateGrader(g, `graders[${i}]`));
+  if (!Array.isArray(input.cases) || input.cases.length === 0) {
+    throw new Error('defineEval requires a non-empty "cases" array');
+  }
+  const seenNames = /* @__PURE__ */ new Set();
+  const cases = input.cases.map((c, index) => {
+    if (!isPlainObject(c)) {
+      throw new Error(`defineEval: cases[${index}] must be an object`);
     }
-    if (expectNoChanges && plan.changes !== "none") {
-      throw new FlowDriftError(plan);
+    if (typeof c.name !== "string" || c.name.length === 0) {
+      throw new Error(`defineEval: cases[${index}] requires a non-empty string "name"`);
     }
-    return plan;
+    if (seenNames.has(c.name)) {
+      throw new Error(`defineEval: duplicate case name "${c.name}" (case names are the identity)`);
+    }
+    seenNames.add(c.name);
+    const unknownCaseKeys = Object.keys(c).filter((k) => !DEFINE_EVAL_CASE_KEYS.has(k));
+    if (unknownCaseKeys.length > 0) {
+      throw new Error(
+        `defineEval: cases[${index}] ("${c.name}") has unknown field(s): ${unknownCaseKeys.join(
+          ", "
+        )}. Allowed case fields are name, input, expected, expect.`
+      );
+    }
+    const caseGraders = (c.expect ?? []).map(
+      (g, i) => validateGrader(g, `cases[${index}].expect[${i}]`)
+    );
+    const expect = [...suiteGraders, ...caseGraders];
+    if (expect.length === 0) {
+      throw new Error(
+        `defineEval: cases[${index}] ("${c.name}") has no graders. Add suite-level "graders" or case-level "expect" so there is something to score.`
+      );
+    }
+    if (c.expected !== void 0 && !isPlainObject(c.expected)) {
+      throw new Error(`defineEval: cases[${index}] ("${c.name}") "expected" must be an object`);
+    }
+    return {
+      name: c.name,
+      input: normalizeCaseInput(c.input, `cases[${index}] ("${c.name}")`),
+      ...c.expected !== void 0 ? { expected: c.expected } : {},
+      expect
+    };
+  });
+  return { name, target, cases, virtual: input.virtual === true };
+}
+function normalizeForHash(value) {
+  if (Array.isArray(value)) return value.map(normalizeForHash);
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const v = value[key];
+      if (v === void 0) continue;
+      out[key] = normalizeForHash(v);
+    }
+    return out;
+  }
+  return value;
+}
+async function computeEvalContentHash(definition) {
+  const canonical = {
+    target: normalizeForHash(definition.target),
+    virtual: definition.virtual,
+    cases: [...definition.cases].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map((c) => ({
+      name: c.name,
+      input: normalizeForHash(c.input),
+      ...c.expected !== void 0 ? { expected: normalizeForHash(c.expected) } : {},
+      // Grader order preserved on purpose (it maps to the result index).
+      expect: c.expect.map((g) => normalizeForHash(g))
+    }))
+  };
+  const serialized = JSON.stringify(canonical);
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var serverHashMemo = /* @__PURE__ */ new WeakMap();
+function memoFor(client) {
+  let memo = serverHashMemo.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo.set(client, memo);
+  }
+  return memo;
+}
+async function ensureEval(client, definition) {
+  if (definition.virtual) {
+    throw new Error(
+      "Cannot ensure a virtual eval: virtual evals are ephemeral (nothing is persisted to converge). Remove `virtual: true` to converge a durable suite, or run it directly."
+    );
   }
   const memo = memoFor(client);
-  const localHash = await computeFlowContentHash(definition.steps);
+  const localHash = await computeEvalContentHash(definition);
   const memoKey = `${definition.name} ${localHash}`;
   const contentHash = memo.get(memoKey) ?? localHash;
-  const probe = await request(client, {
-    name: definition.name,
-    contentHash,
-    ...passthrough
-  });
+  const probe = await client.post(
+    "/eval/ensure",
+    { name: definition.name, contentHash }
+  );
   if (probe.result !== "definitionRequired") {
-    memoize(memo, memoKey, probe);
+    memo.set(memoKey, probe.contentHash);
     return probe;
   }
-  const converged = await request(client, {
-    name: definition.name,
-    definition,
-    ...passthrough
-  });
+  const converged = await client.post(
+    "/eval/ensure",
+    { name: definition.name, definition }
+  );
   if (converged.result === "definitionRequired") {
     throw new Error("Server reported definitionRequired for a full-definition request");
   }
-  memoize(memo, memoKey, converged);
+  memo.set(memoKey, converged.contentHash);
   return converged;
 }
-async function pullFlow(client, name) {
-  return client.get("/flows/pull", { name });
+async function pullEval(client, name) {
+  return client.get("/eval/pull", { name });
+}
+async function runEvalSuite(client, input) {
+  return client.post("/eval/run", input);
 }
 
-// src/flows-namespace.ts
-var FlowsNamespace = class {
-  constructor(getClient) {
-    this.getClient = getClient;
-  }
-  /**
-   * Create or update a flow by name (upsert mode)
-   *
-   * The recommended pattern for code-first flow management when you want to
-   * save AND run in one dispatch. For a deploy-time, non-executing converge
-   * (CI/CD config-as-code), use {@link ensure} instead — upsert and ensure
-   * are siblings, not versions of each other: upsert is the runtime verb
-   * (save-and-run), ensure is the deploy verb (converge only).
-   *
-   * @example
-   * ```typescript
-   * const result = await Runtype.flows.upsert({
-   *   name: 'My Flow',
-   *   createVersionOnChange: true
-   * })
-   *   .prompt({ name: 'Analyze', model: 'gpt-4o', userPrompt: '...' })
-   *   .stream()
+// src/flows-ensure.ts
+function isPlainObject2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeConfigForHash(config) {
+  if (!isPlainObject2(config)) return {};
+  const normalized = {};
+  for (const key of Object.keys(config).sort()) {
+    const value = config[key];
+    if (value === void 0) continue;
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      normalized[key] = normalizeConfigForHash(value);
+    } else if (Array.isArray(value)) {
+      normalized[key] = value.map((item) => {
+        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+          return normalizeConfigForHash(item);
+        }
+        return item;
+      });
+    } else {
+      normalized[key] = value;
+    }
+  }
+  return normalized;
+}
+function normalizeStepForHash(step) {
+  const stepObj = isPlainObject2(step) ? step : {};
+  return {
+    type: typeof stepObj.type === "string" ? stepObj.type : "",
+    name: typeof stepObj.name === "string" ? stepObj.name : "",
+    enabled: stepObj.enabled !== false,
+    ...typeof stepObj.when === "string" ? { when: stepObj.when } : {},
+    config: normalizeConfigForHash(stepObj.config),
+    order: typeof stepObj.order === "number" ? stepObj.order : 0
+  };
+}
+async function computeFlowContentHash(steps) {
+  const normalized = [...steps].sort((a, b) => {
+    const orderA = isPlainObject2(a) && typeof a.order === "number" ? a.order : 0;
+    const orderB = isPlainObject2(b) && typeof b.order === "number" ? b.order : 0;
+    return orderA - orderB;
+  }).map(normalizeStepForHash);
+  const serialized = JSON.stringify(normalized);
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_FLOW_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "steps", "evals"]);
+var DEFINE_FLOW_STEP_KEYS = /* @__PURE__ */ new Set([
+  "type",
+  "name",
+  "order",
+  "enabled",
+  "when",
+  "config"
+]);
+function collectStepNonPortableToolRefs(config, path) {
+  const found = [];
+  const tools = config.tools;
+  const isAccountScoped = (ref) => typeof ref === "string" && ref.startsWith("tool_");
+  const isRawId = (ref, prefix) => typeof ref === "string" && ref.startsWith(prefix);
+  const scanArray = (value, subPath) => {
+    if (!Array.isArray(value)) return;
+    value.forEach((ref, i) => {
+      if (isAccountScoped(ref)) found.push(`${subPath}[${i}]`);
+    });
+  };
+  const scanKeys = (value, subPath) => {
+    if (!isPlainObject2(value)) return;
+    for (const key of Object.keys(value)) {
+      if (isAccountScoped(key)) found.push(`${subPath}.${key}`);
+    }
+  };
+  if (isPlainObject2(tools)) {
+    scanArray(tools.toolIds, `${path}.tools.toolIds`);
+    scanKeys(tools.toolConfigs, `${path}.tools.toolConfigs`);
+    scanKeys(tools.perToolLimits, `${path}.tools.perToolLimits`);
+    if (isPlainObject2(tools.approval)) {
+      scanArray(tools.approval.require, `${path}.tools.approval.require`);
+    }
+    if (isPlainObject2(tools.subagentConfig)) {
+      scanArray(tools.subagentConfig.toolPool, `${path}.tools.subagentConfig.toolPool`);
+    }
+    if (isPlainObject2(tools.codeModeConfig)) {
+      scanArray(tools.codeModeConfig.toolPool, `${path}.tools.codeModeConfig.toolPool`);
+    }
+    if (Array.isArray(tools.runtimeTools)) {
+      tools.runtimeTools.forEach((runtimeTool, i) => {
+        if (!isPlainObject2(runtimeTool) || !isPlainObject2(runtimeTool.config)) return;
+        const base = `${path}.tools.runtimeTools[${i}].config`;
+        const rtConfig = runtimeTool.config;
+        if (runtimeTool.toolType === "subagent" && isRawId(rtConfig.agentId, "agent_")) {
+          found.push(`${base}.agentId`);
+        } else if (runtimeTool.toolType === "flow" && isRawId(rtConfig.flowId, "flow_")) {
+          found.push(`${base}.flowId`);
+        }
+      });
+    }
+  }
+  if (isAccountScoped(config.toolId)) {
+    found.push(`${path}.toolId`);
+  }
+  if (isRawId(config.agentId, "agent_")) {
+    found.push(`${path}.agentId`);
+  }
+  for (const branch of ["trueSteps", "falseSteps"]) {
+    const nested = config[branch];
+    if (!Array.isArray(nested)) continue;
+    nested.forEach((nestedStep, i) => {
+      if (isPlainObject2(nestedStep) && isPlainObject2(nestedStep.config)) {
+        found.push(
+          ...collectStepNonPortableToolRefs(nestedStep.config, `${path}.${branch}[${i}].config`)
+        );
+      }
+    });
+  }
+  return found;
+}
+function defineFlow(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineFlow requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineFlow requires a non-empty string "name"');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_FLOW_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineFlow: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name, steps, and evals. (Description is not part of the v1 ensure surface.)`
+    );
+  }
+  if (!Array.isArray(input.steps) || input.steps.length === 0) {
+    throw new Error('defineFlow requires a non-empty "steps" array');
+  }
+  const steps = input.steps.map((step, index) => {
+    if (!isPlainObject2(step)) {
+      throw new Error(`defineFlow: steps[${index}] must be an object`);
+    }
+    if (typeof step.type !== "string" || step.type.length === 0) {
+      throw new Error(`defineFlow: steps[${index}] requires a non-empty string "type"`);
+    }
+    if (typeof step.name !== "string" || step.name.length === 0) {
+      throw new Error(`defineFlow: steps[${index}] requires a non-empty string "name"`);
+    }
+    const unknownStepKeys = Object.keys(step).filter((key) => !DEFINE_FLOW_STEP_KEYS.has(key));
+    if (unknownStepKeys.length > 0) {
+      throw new Error(
+        `defineFlow: steps[${index}] has unknown field(s): ${unknownStepKeys.join(", ")}. Allowed step fields are type, name, order, enabled, when, config. (Step ids are server artifacts and not part of a portable definition.)`
+      );
+    }
+    const config = isPlainObject2(step.config) ? step.config : void 0;
+    if (config) {
+      const nonPortable = collectStepNonPortableToolRefs(config, `steps[${index}].config`);
+      if (nonPortable.length > 0) {
+        throw new Error(
+          `defineFlow: account-scoped reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026/agent_\u2026/flow_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references, or reference a saved resource by name \u2014 tool:<name>, agent:<name>, or flow:<name> instead.`
+        );
+      }
+    }
+    return {
+      type: step.type,
+      name: step.name,
+      // Explicit 1-based order (the flow builder's convention) so the local
+      // probe hash agrees with the server's persisted step order.
+      order: typeof step.order === "number" ? step.order : index + 1,
+      ...step.enabled !== void 0 ? { enabled: step.enabled } : {},
+      ...typeof step.when === "string" ? { when: step.when } : {},
+      ...config ? { config } : {}
+    };
+  });
+  let evals;
+  if (input.evals !== void 0) {
+    if (!Array.isArray(input.evals)) {
+      throw new Error('defineFlow: "evals" must be an array');
+    }
+    const seenEvalNames = /* @__PURE__ */ new Set();
+    evals = input.evals.map((evalInput, i) => {
+      if (!isPlainObject2(evalInput)) {
+        throw new Error(`defineFlow: evals[${i}] must be an object`);
+      }
+      if (evalInput.virtual === true) {
+        throw new Error(
+          `defineFlow: evals[${i}] cannot be virtual (inline evals converge with the flow; run a virtual eval directly instead).`
+        );
+      }
+      const withTarget = evalInput.target === void 0 ? { ...evalInput, target: { flow: input.name } } : evalInput;
+      let def;
+      try {
+        def = defineEval(withTarget);
+      } catch (err) {
+        throw new Error(
+          `defineFlow: evals[${i}] \u2014 ${err instanceof Error ? err.message : String(err)}`,
+          { cause: err }
+        );
+      }
+      if (seenEvalNames.has(def.name)) {
+        throw new Error(
+          `defineFlow: evals[${i}] resolves to the duplicate suite name "${def.name}". Inline eval suites must have distinct names \u2014 give each a \`name\` (two unnamed evals targeting the same flow both default to the same name and would overwrite each other).`
+        );
+      }
+      seenEvalNames.add(def.name);
+      return def;
+    });
+  }
+  return {
+    name: input.name,
+    steps,
+    ...evals && evals.length > 0 ? { evals } : {}
+  };
+}
+var FlowEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Flow ensure conflict: ${body.code}`);
+    this.name = "FlowEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var FlowDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Flow "${plan.flowId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.flows.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "FlowDriftError";
+    this.plan = plan;
+  }
+};
+function parseRequestError(err) {
+  if (!(err instanceof Error)) return { status: null, body: null };
+  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
+  if (!match) return { status: null, body: null };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError(err) {
+  const { status, body } = parseRequestError(err);
+  if (status !== 409 || !isPlainObject2(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new FlowEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo2 = /* @__PURE__ */ new WeakMap();
+function memoFor2(client) {
+  let memo = serverHashMemo2.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo2.set(client, memo);
+  }
+  return memo;
+}
+function memoize(memo, memoKey, result) {
+  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+}
+async function request(client, body) {
+  try {
+    return await client.post(
+      "/flows/ensure",
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureFlow(client, definition, options = {}) {
+  const { dryRun, onConflict, release, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...release ? { release } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  const wireDefinition = { name: definition.name, steps: definition.steps };
+  if (dryRun || expectNoChanges) {
+    const plan = await request(client, {
+      name: definition.name,
+      definition: wireDefinition,
+      dryRun: true,
+      ...passthrough
+    });
+    if (plan.result !== "plan") {
+      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+    }
+    if (expectNoChanges && plan.changes !== "none") {
+      throw new FlowDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor2(client);
+  const localHash = await computeFlowContentHash(definition.steps);
+  const memoKey = `${definition.name} ${localHash}`;
+  const contentHash = memo.get(memoKey) ?? localHash;
+  const probe = await request(client, {
+    name: definition.name,
+    contentHash,
+    ...passthrough
+  });
+  if (probe.result !== "definitionRequired") {
+    memoize(memo, memoKey, probe);
+    return convergeInlineEvals(client, definition, probe);
+  }
+  const converged = await request(client, {
+    name: definition.name,
+    definition: wireDefinition,
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize(memo, memoKey, converged);
+  return convergeInlineEvals(client, definition, converged);
+}
+async function convergeInlineEvals(client, definition, result) {
+  if (result.result === "plan" || !definition.evals?.length) {
+    return result;
+  }
+  const evals = [];
+  for (const evalDef of definition.evals) {
+    evals.push(await ensureEval(client, evalDef));
+  }
+  return { ...result, evals };
+}
+async function pullFlow(client, name) {
+  return client.get("/flows/pull", { name });
+}
+
+// src/flows-namespace.ts
+var FlowsNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  /**
+   * Create or update a flow by name (upsert mode)
+   *
+   * The recommended pattern for code-first flow management when you want to
+   * save AND run in one dispatch. For a deploy-time, non-executing converge
+   * (CI/CD config-as-code), use {@link ensure} instead — upsert and ensure
+   * are siblings, not versions of each other: upsert is the runtime verb
+   * (save-and-run), ensure is the deploy verb (converge only).
+   *
+   * @example
+   * ```typescript
+   * const result = await Runtype.flows.upsert({
+   *   name: 'My Flow',
+   *   createVersionOnChange: true
+   * })
+   *   .prompt({ name: 'Analyze', model: 'gpt-4o', userPrompt: '...' })
+   *   .stream()
    * ```
    */
   upsert(config) {
@@ -2207,11 +2647,19 @@ var FlowsNamespace = class {
    * the steady state is one tiny probe request. Creates an immutable version
    * snapshot on every change; never deletes; never executes the flow.
    *
+   * When the definition carries inline `evals`, each suite is converged via
+   * `/eval/ensure` after the flow itself (real converge path only — not on
+   * dryRun/`expectNoChanges`), and the outcomes are returned as `result.evals`.
+   *
    * @example
    * ```typescript
-   * const def = defineFlow({ name: 'Onboarding Digest', steps: [...] })
+   * const def = defineFlow({
+   *   name: 'Onboarding Digest',
+   *   steps: [...],
+   *   evals: [{ cases: [{ name: 'smoke', input: {...}, expect: [contains('ok')] }] }],
+   * })
    *
-   * // Converge (CI/deploy).
+   * // Converge the flow AND its inline eval suites (CI/deploy).
    * const result = await Runtype.flows.ensure(def)
    *
    * // PR drift gate.
@@ -3045,530 +3493,236 @@ var RuntypeFlowBuilder = class {
     const flowMode = this.mode === "existing" ? "existing" : this.mode;
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
     const request6 = { flow };
-    if (this.recordConfig) {
-      request6.record = this.recordConfig;
-    }
-    if (this.messagesConfig) {
-      request6.messages = this.messagesConfig;
-    }
-    if (this.inputsConfig) {
-      request6.inputs = this.inputsConfig;
-    }
-    const options = {
-      flowMode,
-      ...this.dispatchOptions
-    };
-    if (this.recordConfig && !this.dispatchOptions.recordMode) {
-      if (this.recordConfig.id) {
-        options.recordMode = "existing";
-      } else if (this.recordConfig.name || this.recordConfig.type) {
-        options.recordMode = "create";
-      } else {
-        options.recordMode = "virtual";
-      }
-    }
-    if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
-      options.upsertOptions = this.upsertOptions;
-    }
-    request6.options = options;
-    return request6;
-  }
-  /**
-   * Validate this prospective flow against the public validation endpoint
-   * (`POST /v1/public/flows/validate`) WITHOUT creating it, using the bound
-   * client. Returns the same `errors` / `warnings` / `recommendations` envelope
-   * the API, dashboard, and MCP `validate_flow` tool use, so structural issues,
-   * the upsert-record JSON foot-gun, undeclared-variable warnings, and
-   * sub-optimal model selections surface at author time. The bound client
-   * carries authentication; an authenticated client additionally runs
-   * account-scoped checks (`result.context` reports whether they ran). Mirrors
-   * {@link FlowBuilder.validate}.
-   *
-   * Only valid for prospective flows (`Runtype.flows.virtual(...)` /
-   * `Runtype.flows.upsert(...)`). An existing-flow builder
-   * (`Runtype.flows.use(id)`) has no inline steps to validate, so this throws —
-   * the validation endpoint validates a `{ name, steps }` payload, not a saved
-   * flow by id (which was already validated at create time).
-   *
-   * @example
-   * ```typescript
-   * const result = await Runtype.flows.virtual({ name: 'Temp Flow' })
-   *   .prompt({ name: 'Process', model: 'gpt-5-mini', userPrompt: '...' })
-   *   .validate()
-   *
-   * if (!result.valid) console.error(result.errors)
-   * ```
-   */
-  async validate() {
-    return validateInlineFlow(
-      this.getClient(),
-      { name: this.flowConfig.name, steps: this.steps, existingFlowId: this.existingFlowId },
-      "Use Runtype.flows.virtual(...) or Runtype.flows.upsert(...) with inline steps to validate a flow before saving."
-    );
-  }
-  // ============================================================================
-  // Private Helpers
-  // ============================================================================
-  /**
-   * Persisted flow protocol (APQ-style): send hash-only first, retry with
-   * full definition on FLOW_DEFINITION_REQUIRED. For non-upsert modes,
-   * dispatches directly.
-   */
-  async dispatchWithPersistedFlow(client, config) {
-    if (this.mode !== "upsert" || !this.steps.length) {
-      return client.dispatch(config);
-    }
-    const contentHash = await this.computeContentHash();
-    const hashOnlyConfig = {
-      ...config,
-      flow: { name: config.flow.name, contentHash }
-    };
-    try {
-      return await client.dispatch(hashOnlyConfig);
-    } catch (err) {
-      const is422 = err != null && typeof err === "object" && "statusCode" in err && err.statusCode === 422 || err instanceof Error && /\b422\b/.test(err.message);
-      if (!is422) {
-        throw err;
-      }
-    }
-    const fullConfig = {
-      ...config,
-      flow: { ...config.flow, contentHash }
-    };
-    return client.dispatch(fullConfig);
-  }
-  async computeContentHash() {
-    return computeFlowContentHash(this.steps);
-  }
-  addRawStep(type, config) {
-    const { name, enabled, when, ...stepConfig } = config;
-    this.addStep(type, name, stepConfig, enabled, when);
-    return this;
-  }
-  addStep(type, name, config, enabled = true, when) {
-    this.stepCounter++;
-    const cleanConfig = {};
-    for (const [key, value] of Object.entries(config)) {
-      if (value !== void 0) {
-        cleanConfig[key] = value;
-      }
-    }
-    this.steps.push({
-      id: `step-${this.stepCounter}`,
-      type,
-      name,
-      order: this.stepCounter,
-      enabled,
-      ...when ? { when } : {},
-      config: cleanConfig
-    });
-  }
-};
-
-// src/batches-namespace.ts
-var BatchesNamespace = class {
-  constructor(getClient) {
-    this.getClient = getClient;
-  }
-  /**
-   * Schedule a batch operation
-   *
-   * Creates and schedules a batch to run a flow on all records of a type.
-   * By default, runs immediately. Use `at` to schedule for a specific time.
-   *
-   * @example
-   * ```typescript
-   * // Run immediately
-   * const batch = await Runtype.batches.schedule({
-   *   flowId: 'flow_123',
-   *   recordType: 'customers',
-   * })
-   *
-   * // Schedule for later
-   * const batch = await Runtype.batches.schedule({
-   *   flowId: 'flow_123',
-   *   recordType: 'customers',
-   *   at: new Date('2024-01-15T09:00:00Z'),
-   * })
-   *
-   * // With options
-   * const batch = await Runtype.batches.schedule({
-   *   flowId: 'flow_123',
-   *   recordType: 'customers',
-   *   concurrency: 5,
-   *   continueOnError: true,
-   *   filter: { status: 'active' },
-   *   limit: 100,
-   * })
-   * ```
-   */
-  async schedule(config) {
-    const client = this.getClient();
-    const payload = {
-      flowId: config.flowId,
-      recordType: config.recordType
-    };
-    if (config.at) {
-      payload.scheduledAt = config.at.toISOString();
+    if (this.recordConfig) {
+      request6.record = this.recordConfig;
     }
-    const options = {};
-    if (config.async !== void 0) options.async = config.async;
-    if (config.concurrency !== void 0) options.concurrency = config.concurrency;
-    if (config.continueOnError !== void 0) options.continueOnError = config.continueOnError;
-    if (config.storeResults !== void 0) options.storeResults = config.storeResults;
-    if (config.modelOverride !== void 0) options.modelOverride = config.modelOverride;
-    if (Object.keys(options).length > 0) {
-      payload.options = options;
+    if (this.messagesConfig) {
+      request6.messages = this.messagesConfig;
     }
-    if (config.filter) {
-      payload.filter = config.filter;
+    if (this.inputsConfig) {
+      request6.inputs = this.inputsConfig;
     }
-    if (config.limit !== void 0) {
-      payload.limit = config.limit;
+    const options = {
+      flowMode,
+      ...this.dispatchOptions
+    };
+    if (this.recordConfig && !this.dispatchOptions.recordMode) {
+      if (this.recordConfig.id) {
+        options.recordMode = "existing";
+      } else if (this.recordConfig.name || this.recordConfig.type) {
+        options.recordMode = "create";
+      } else {
+        options.recordMode = "virtual";
+      }
     }
-    return client.post("/batches", payload);
-  }
-  /**
-   * Get batch status by ID
-   *
-   * @example
-   * ```typescript
-   * const status = await Runtype.batches.get('batch_456')
-   * console.log(status.status, status.processedRecords, '/', status.totalRecords)
-   * ```
-   */
-  async get(batchId) {
-    const client = this.getClient();
-    return client.get(`/batches/${batchId}`);
+    if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
+      options.upsertOptions = this.upsertOptions;
+    }
+    request6.options = options;
+    return request6;
   }
   /**
-   * Cancel a batch operation
-   *
-   * Cancels a queued or running batch. Records already processed are not rolled back.
+   * Validate this prospective flow against the public validation endpoint
+   * (`POST /v1/public/flows/validate`) WITHOUT creating it, using the bound
+   * client. Returns the same `errors` / `warnings` / `recommendations` envelope
+   * the API, dashboard, and MCP `validate_flow` tool use, so structural issues,
+   * the upsert-record JSON foot-gun, undeclared-variable warnings, and
+   * sub-optimal model selections surface at author time. The bound client
+   * carries authentication; an authenticated client additionally runs
+   * account-scoped checks (`result.context` reports whether they ran). Mirrors
+   * {@link FlowBuilder.validate}.
    *
-   * @example
-   * ```typescript
-   * await Runtype.batches.cancel('batch_456')
-   * ```
-   */
-  async cancel(batchId) {
-    const client = this.getClient();
-    return client.post(`/batches/${batchId}/cancel`);
-  }
-  /**
-   * List batch operations
+   * Only valid for prospective flows (`Runtype.flows.virtual(...)` /
+   * `Runtype.flows.upsert(...)`). An existing-flow builder
+   * (`Runtype.flows.use(id)`) has no inline steps to validate, so this throws —
+   * the validation endpoint validates a `{ name, steps }` payload, not a saved
+   * flow by id (which was already validated at create time).
    *
    * @example
    * ```typescript
-   * // List all batches
-   * const batches = await Runtype.batches.list()
-   *
-   * // Filter by status
-   * const running = await Runtype.batches.list({ status: 'running' })
+   * const result = await Runtype.flows.virtual({ name: 'Temp Flow' })
+   *   .prompt({ name: 'Process', model: 'gpt-5-mini', userPrompt: '...' })
+   *   .validate()
    *
-   * // Filter by flow
-   * const flowBatches = await Runtype.batches.list({ flowId: 'flow_123' })
+   * if (!result.valid) console.error(result.errors)
    * ```
    */
-  async list(params) {
-    const client = this.getClient();
-    return client.get("/batches", params);
-  }
-};
-
-// src/evals-ensure.ts
-var CHECK_GRADER_KINDS = /* @__PURE__ */ new Set([
-  "contains",
-  "not_contains",
-  "matches_expected",
-  "regex",
-  "valid_json",
-  "json_field",
-  "length",
-  "latency",
-  "no_error"
-]);
-function contains(value, opts) {
-  return { kind: "contains", value, ...opts?.caseSensitive ? { caseSensitive: true } : {} };
-}
-function notContains(value, opts) {
-  return { kind: "not_contains", value, ...opts?.caseSensitive ? { caseSensitive: true } : {} };
-}
-function matchesExpected() {
-  return { kind: "matches_expected" };
-}
-function regex(pattern, flags) {
-  return { kind: "regex", pattern, ...flags ? { flags } : {} };
-}
-function validJson() {
-  return { kind: "valid_json" };
-}
-function jsonField(path, opts) {
-  return {
-    kind: "json_field",
-    path,
-    ...opts && "equals" in opts && opts.equals !== void 0 ? { equals: opts.equals } : {},
-    ...opts && typeof opts.exists === "boolean" ? { exists: opts.exists } : {}
-  };
-}
-function length(opts) {
-  if (!opts || opts.minChars === void 0 && opts.maxChars === void 0) {
-    throw new Error("length() requires at least one of minChars or maxChars");
-  }
-  return {
-    kind: "length",
-    ...opts.minChars !== void 0 ? { minChars: opts.minChars } : {},
-    ...opts.maxChars !== void 0 ? { maxChars: opts.maxChars } : {}
-  };
-}
-function latency(maxMs) {
-  if (!Number.isFinite(maxMs) || maxMs <= 0) {
-    throw new Error("latency() requires a positive maxMs");
-  }
-  return { kind: "latency", maxMs };
-}
-function noError() {
-  return { kind: "no_error" };
-}
-function judge(criteria, opts) {
-  if (typeof criteria !== "string" || criteria.trim().length === 0) {
-    throw new Error("judge() requires non-empty criteria");
-  }
-  return {
-    kind: "ai",
-    criteria,
-    ...opts?.preset ? { preset: opts.preset } : {},
-    ...opts?.useExpected ? { useExpected: true } : {},
-    ...opts?.model ? { model: opts.model } : {},
-    ...opts?.threshold !== void 0 ? { threshold: opts.threshold } : {}
-  };
-}
-var judges = {
-  answersQuestion: () => judge(
-    "The response directly addresses what the user asked, without dodging or answering a different question.",
-    { preset: "answersQuestion" }
-  ),
-  matchesExpected: () => judge(
-    "The response conveys the same facts and conclusion as the expected answer. Wording may differ.",
-    { preset: "matchesExpected", useExpected: true }
-  ),
-  followsInstructions: () => judge(
-    "The response obeys every instruction in the system prompt (format, tone, constraints, refusals).",
-    { preset: "followsInstructions" }
-  ),
-  grounded: () => judge(
-    "Every factual claim in the response is supported by the provided context or the expected answer. Flag anything invented.",
-    { preset: "grounded" }
-  ),
-  rightTone: (voice = "{describe the voice you want}") => judge(`The response matches this voice: ${voice}.`, { preset: "rightTone" }),
-  safeToSend: () => judge(
-    "The response contains nothing embarrassing to show a customer: no leaked internals, no hostile tone, no policy violations.",
-    { preset: "safeToSend" }
-  )
-};
-var DEFINE_EVAL_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
-  "name",
-  "target",
-  "graders",
-  "cases",
-  "virtual"
-]);
-var DEFINE_EVAL_CASE_KEYS = /* @__PURE__ */ new Set(["name", "input", "expected", "expect"]);
-function isPlainObject2(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function normalizeTarget(target) {
-  if (!isPlainObject2(target)) {
-    throw new Error('defineEval requires a "target" object: { flow: name } or { agent: name }');
-  }
-  const hasFlow = typeof target.flow === "string" && target.flow.length > 0;
-  const hasAgent = typeof target.agent === "string" && target.agent.length > 0;
-  if (hasFlow === hasAgent) {
-    throw new Error(
-      'defineEval "target" must name exactly one of flow or agent: { flow: "name" } XOR { agent: "name" }'
-    );
-  }
-  const extraKeys = Object.keys(target).filter((k) => k !== "flow" && k !== "agent");
-  if (extraKeys.length > 0) {
-    throw new Error(`defineEval "target" has unknown field(s): ${extraKeys.join(", ")}`);
-  }
-  return hasFlow ? { flow: target.flow } : { agent: target.agent };
-}
-function validateGrader(grader, where) {
-  if (!isPlainObject2(grader) || typeof grader.kind !== "string") {
-    throw new Error(`defineEval: ${where} must be a grader object with a string "kind"`);
-  }
-  if (grader.kind === "ai") {
-    if (typeof grader.criteria !== "string" || grader.criteria.trim().length === 0) {
-      throw new Error(`defineEval: ${where} is an AI grader and requires non-empty "criteria"`);
-    }
-    return grader;
-  }
-  if (!CHECK_GRADER_KINDS.has(grader.kind)) {
-    throw new Error(
-      `defineEval: ${where} has unknown grader kind "${grader.kind}". Known kinds: ${[...CHECK_GRADER_KINDS].join(", ")}, ai. (Trace graders such as called_tool/step_order are not available yet.)`
+  async validate() {
+    return validateInlineFlow(
+      this.getClient(),
+      { name: this.flowConfig.name, steps: this.steps, existingFlowId: this.existingFlowId },
+      "Use Runtype.flows.virtual(...) or Runtype.flows.upsert(...) with inline steps to validate a flow before saving."
     );
   }
-  return grader;
-}
-function normalizeCaseInput(input, where) {
-  if (input === void 0) return {};
-  if (!isPlainObject2(input)) {
-    throw new Error(`defineEval: ${where} "input" must be an object`);
-  }
-  const out = {};
-  if (input.variables !== void 0) {
-    if (!isPlainObject2(input.variables)) {
-      throw new Error(`defineEval: ${where} "input.variables" must be an object`);
-    }
-    out.variables = input.variables;
-  }
-  if (input.messages !== void 0) {
-    if (!Array.isArray(input.messages)) {
-      throw new Error(`defineEval: ${where} "input.messages" must be an array`);
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+  /**
+   * Persisted flow protocol (APQ-style): send hash-only first, retry with
+   * full definition on FLOW_DEFINITION_REQUIRED. For non-upsert modes,
+   * dispatches directly.
+   */
+  async dispatchWithPersistedFlow(client, config) {
+    if (this.mode !== "upsert" || !this.steps.length) {
+      return client.dispatch(config);
     }
-    out.messages = input.messages.map((m, i) => {
-      if (!isPlainObject2(m) || typeof m.role !== "string" || typeof m.content !== "string") {
-        throw new Error(`defineEval: ${where} "input.messages[${i}]" must be { role, content }`);
+    const contentHash = await this.computeContentHash();
+    const hashOnlyConfig = {
+      ...config,
+      flow: { name: config.flow.name, contentHash }
+    };
+    try {
+      return await client.dispatch(hashOnlyConfig);
+    } catch (err) {
+      const is422 = err != null && typeof err === "object" && "statusCode" in err && err.statusCode === 422 || err instanceof Error && /\b422\b/.test(err.message);
+      if (!is422) {
+        throw err;
       }
-      return { role: m.role, content: m.content };
-    });
+    }
+    const fullConfig = {
+      ...config,
+      flow: { ...config.flow, contentHash }
+    };
+    return client.dispatch(fullConfig);
   }
-  return out;
-}
-function defineEval(input) {
-  if (!input || typeof input !== "object") {
-    throw new Error("defineEval requires a definition object");
+  async computeContentHash() {
+    return computeFlowContentHash(this.steps);
   }
-  const unknownKeys = Object.keys(input).filter((k) => !DEFINE_EVAL_TOP_LEVEL_KEYS.has(k));
-  if (unknownKeys.length > 0) {
-    throw new Error(
-      `defineEval: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are target, graders, cases, virtual.`
-    );
+  addRawStep(type, config) {
+    const { name, enabled, when, ...stepConfig } = config;
+    this.addStep(type, name, stepConfig, enabled, when);
+    return this;
   }
-  const target = normalizeTarget(input.target);
-  if (input.name !== void 0 && (typeof input.name !== "string" || input.name.length === 0)) {
-    throw new Error('defineEval "name" must be a non-empty string when provided');
+  addStep(type, name, config, enabled = true, when) {
+    this.stepCounter++;
+    const cleanConfig = {};
+    for (const [key, value] of Object.entries(config)) {
+      if (value !== void 0) {
+        cleanConfig[key] = value;
+      }
+    }
+    this.steps.push({
+      id: `step-${this.stepCounter}`,
+      type,
+      name,
+      order: this.stepCounter,
+      enabled,
+      ...when ? { when } : {},
+      config: cleanConfig
+    });
   }
-  const name = input.name ?? ("flow" in target ? `flow:${target.flow}` : `agent:${target.agent}`);
-  const suiteGraders = (input.graders ?? []).map((g, i) => validateGrader(g, `graders[${i}]`));
-  if (!Array.isArray(input.cases) || input.cases.length === 0) {
-    throw new Error('defineEval requires a non-empty "cases" array');
+};
+
+// src/batches-namespace.ts
+var BatchesNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
   }
-  const seenNames = /* @__PURE__ */ new Set();
-  const cases = input.cases.map((c, index) => {
-    if (!isPlainObject2(c)) {
-      throw new Error(`defineEval: cases[${index}] must be an object`);
-    }
-    if (typeof c.name !== "string" || c.name.length === 0) {
-      throw new Error(`defineEval: cases[${index}] requires a non-empty string "name"`);
-    }
-    if (seenNames.has(c.name)) {
-      throw new Error(`defineEval: duplicate case name "${c.name}" (case names are the identity)`);
-    }
-    seenNames.add(c.name);
-    const unknownCaseKeys = Object.keys(c).filter((k) => !DEFINE_EVAL_CASE_KEYS.has(k));
-    if (unknownCaseKeys.length > 0) {
-      throw new Error(
-        `defineEval: cases[${index}] ("${c.name}") has unknown field(s): ${unknownCaseKeys.join(
-          ", "
-        )}. Allowed case fields are name, input, expected, expect.`
-      );
+  /**
+   * Schedule a batch operation
+   *
+   * Creates and schedules a batch to run a flow on all records of a type.
+   * By default, runs immediately. Use `at` to schedule for a specific time.
+   *
+   * @example
+   * ```typescript
+   * // Run immediately
+   * const batch = await Runtype.batches.schedule({
+   *   flowId: 'flow_123',
+   *   recordType: 'customers',
+   * })
+   *
+   * // Schedule for later
+   * const batch = await Runtype.batches.schedule({
+   *   flowId: 'flow_123',
+   *   recordType: 'customers',
+   *   at: new Date('2024-01-15T09:00:00Z'),
+   * })
+   *
+   * // With options
+   * const batch = await Runtype.batches.schedule({
+   *   flowId: 'flow_123',
+   *   recordType: 'customers',
+   *   concurrency: 5,
+   *   continueOnError: true,
+   *   filter: { status: 'active' },
+   *   limit: 100,
+   * })
+   * ```
+   */
+  async schedule(config) {
+    const client = this.getClient();
+    const payload = {
+      flowId: config.flowId,
+      recordType: config.recordType
+    };
+    if (config.at) {
+      payload.scheduledAt = config.at.toISOString();
     }
-    const caseGraders = (c.expect ?? []).map(
-      (g, i) => validateGrader(g, `cases[${index}].expect[${i}]`)
-    );
-    const expect = [...suiteGraders, ...caseGraders];
-    if (expect.length === 0) {
-      throw new Error(
-        `defineEval: cases[${index}] ("${c.name}") has no graders. Add suite-level "graders" or case-level "expect" so there is something to score.`
-      );
+    const options = {};
+    if (config.async !== void 0) options.async = config.async;
+    if (config.concurrency !== void 0) options.concurrency = config.concurrency;
+    if (config.continueOnError !== void 0) options.continueOnError = config.continueOnError;
+    if (config.storeResults !== void 0) options.storeResults = config.storeResults;
+    if (config.modelOverride !== void 0) options.modelOverride = config.modelOverride;
+    if (Object.keys(options).length > 0) {
+      payload.options = options;
     }
-    if (c.expected !== void 0 && !isPlainObject2(c.expected)) {
-      throw new Error(`defineEval: cases[${index}] ("${c.name}") "expected" must be an object`);
+    if (config.filter) {
+      payload.filter = config.filter;
     }
-    return {
-      name: c.name,
-      input: normalizeCaseInput(c.input, `cases[${index}] ("${c.name}")`),
-      ...c.expected !== void 0 ? { expected: c.expected } : {},
-      expect
-    };
-  });
-  return { name, target, cases, virtual: input.virtual === true };
-}
-function normalizeForHash(value) {
-  if (Array.isArray(value)) return value.map(normalizeForHash);
-  if (isPlainObject2(value)) {
-    const out = {};
-    for (const key of Object.keys(value).sort()) {
-      const v = value[key];
-      if (v === void 0) continue;
-      out[key] = normalizeForHash(v);
+    if (config.limit !== void 0) {
+      payload.limit = config.limit;
     }
-    return out;
-  }
-  return value;
-}
-async function computeEvalContentHash(definition) {
-  const canonical = {
-    target: normalizeForHash(definition.target),
-    virtual: definition.virtual,
-    cases: [...definition.cases].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map((c) => ({
-      name: c.name,
-      input: normalizeForHash(c.input),
-      ...c.expected !== void 0 ? { expected: normalizeForHash(c.expected) } : {},
-      // Grader order preserved on purpose (it maps to the result index).
-      expect: c.expect.map((g) => normalizeForHash(g))
-    }))
-  };
-  const serialized = JSON.stringify(canonical);
-  const encoded = new TextEncoder().encode(serialized);
-  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
-  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-var serverHashMemo2 = /* @__PURE__ */ new WeakMap();
-function memoFor2(client) {
-  let memo = serverHashMemo2.get(client);
-  if (!memo) {
-    memo = /* @__PURE__ */ new Map();
-    serverHashMemo2.set(client, memo);
+    return client.post("/batches", payload);
   }
-  return memo;
-}
-async function ensureEval(client, definition) {
-  if (definition.virtual) {
-    throw new Error(
-      "Cannot ensure a virtual eval: virtual evals are ephemeral (nothing is persisted to converge). Remove `virtual: true` to converge a durable suite, or run it directly."
-    );
+  /**
+   * Get batch status by ID
+   *
+   * @example
+   * ```typescript
+   * const status = await Runtype.batches.get('batch_456')
+   * console.log(status.status, status.processedRecords, '/', status.totalRecords)
+   * ```
+   */
+  async get(batchId) {
+    const client = this.getClient();
+    return client.get(`/batches/${batchId}`);
   }
-  const memo = memoFor2(client);
-  const localHash = await computeEvalContentHash(definition);
-  const memoKey = `${definition.name} ${localHash}`;
-  const contentHash = memo.get(memoKey) ?? localHash;
-  const probe = await client.post(
-    "/eval/ensure",
-    { name: definition.name, contentHash }
-  );
-  if (probe.result !== "definitionRequired") {
-    memo.set(memoKey, probe.contentHash);
-    return probe;
+  /**
+   * Cancel a batch operation
+   *
+   * Cancels a queued or running batch. Records already processed are not rolled back.
+   *
+   * @example
+   * ```typescript
+   * await Runtype.batches.cancel('batch_456')
+   * ```
+   */
+  async cancel(batchId) {
+    const client = this.getClient();
+    return client.post(`/batches/${batchId}/cancel`);
   }
-  const converged = await client.post(
-    "/eval/ensure",
-    { name: definition.name, definition }
-  );
-  if (converged.result === "definitionRequired") {
-    throw new Error("Server reported definitionRequired for a full-definition request");
+  /**
+   * List batch operations
+   *
+   * @example
+   * ```typescript
+   * // List all batches
+   * const batches = await Runtype.batches.list()
+   *
+   * // Filter by status
+   * const running = await Runtype.batches.list({ status: 'running' })
+   *
+   * // Filter by flow
+   * const flowBatches = await Runtype.batches.list({ flowId: 'flow_123' })
+   * ```
+   */
+  async list(params) {
+    const client = this.getClient();
+    return client.get("/batches", params);
   }
-  memo.set(memoKey, converged.contentHash);
-  return converged;
-}
-async function pullEval(client, name) {
-  return client.get("/eval/pull", { name });
-}
-async function runEvalSuite(client, input) {
-  return client.post("/eval/run", input);
-}
+};
 
 // src/evals-namespace.ts
 var EvalRunner = class {
@@ -5848,7 +6002,7 @@ var Runtype = class {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "5.4.0".length > 0 ? "5.4.0" : FALLBACK_VERSION;
+var SDK_VERSION = "5.6.0".length > 0 ? "5.6.0" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 
@@ -13558,7 +13712,9 @@ export {
   buildLedgerOffloadReference,
   buildPolicyGuidance,
   buildSendViewOffloadMarker,
+  calledTool,
   compileWorkflowConfig,
+  completed,
   computeAgentContentHash,
   computeEvalContentHash,
   computeFlowContentHash,
@@ -13568,6 +13724,7 @@ export {
   computeSurfaceContentHash,
   computeToolContentHash,
   contains,
+  cost,
   createAgentEventTranslator,
   createClient,
   createExternalTool,
@@ -13605,6 +13762,7 @@ export {
   length,
   listWorkflowHooks,
   matchesExpected,
+  maxToolCalls,
   noError,
   normalizeAgentDefinition,
   normalizeCandidatePath,
@@ -13613,6 +13771,7 @@ export {
   normalizeSkillDefinition,
   normalizeSurfaceDefinition,
   normalizeToolDefinition,
+  notCalledTool,
   notContains,
   parseFinalBuffer,
   parseLedgerArtifactRelativePath,
@@ -13621,6 +13780,7 @@ export {
   processStream,
   pullEval,
   pullFpo,
+  ranStep,
   regex,
   registerWorkflowHook,
   resolveStallStopAfter,
@@ -13629,8 +13789,11 @@ export {
   sanitizeTaskSlug,
   shouldInjectEmptySessionNudge,
   shouldRequestModelEscalation,
+  stepOrder,
   streamEvents,
+  toolOrder,
   unregisterWorkflowHook,
+  usedNoTools,
   validJson,
   withUnifiedEvents
 };