surf-cli 2.19.0 → 2.20.0

package/native/semantic-core.cjs

@@ -0,0 +1,369 @@
+const { Buffer } = require("node:buffer");
+
+const SEMANTIC_POLICY = Object.freeze({
+  model: "jev-1.13.0",
+  timeoutMs: 5_000,
+  probabilitySumTolerance: 0.01,
+  thresholds: Object.freeze({ find: 0.7, filter: 0.65, verifyPositive: 0.85, verifyNegative: 0.85, prerequisiteSupported: 0.75, prerequisiteBlocked: 0.9, write: 0.95, exactRefWrite: 0.65 }),
+  limits: Object.freeze({
+    stateBytes: 24 * 1024,
+    candidates: 64,
+    actionChoices: 70, // Six fixed controls plus one action for every observed candidate.
+    chunks: 48,
+    questions: 50,
+    filterTop: 12,
+    inputSlots: 16,
+    inputValueBytes: 16 * 1024,
+    defaultSteps: 5,
+    maxSteps: 8,
+    defaultWallMs: 30_000,
+    maxWallMs: 60_000,
+    providerCalls: 17,
+    invalidActionDecisionRetries: 1,
+    directActionRetryChoices: 18,
+    invalidActionDecisionRegionTop: 2,
+    staleRefreshes: 2,
+    identicalObservationHashes: 2,
+  }),
+  waitsMs: Object.freeze([500, 1_500]),
+  scrolls: Object.freeze(["down_600", "up_600", "top", "bottom"]),
+});
+
+class SemanticError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "SemanticError";
+    this.code = code;
+  }
+}
+
+function fail(message) {
+  throw new SemanticError("semantic_invalid_request", message);
+}
+
+function providerInvalid(message) {
+  throw new SemanticError("provider_invalid_response", message);
+}
+
+function assertOpaqueId(value, field) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/.test(value)) {
+    fail(`${field} must be a bounded opaque identifier`);
+  }
+}
+
+function assertUniqueItems(items, maximum, label) {
+  if (!Array.isArray(items) || items.length > maximum) fail(`${label} exceeds its limit of ${maximum}`);
+  const ids = new Set();
+  for (const item of items) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) fail(`${label} entries must be objects`);
+    assertOpaqueId(item.id, `${label} id`);
+    if (ids.has(item.id)) fail(`${label} ids must be unique`);
+    ids.add(item.id);
+  }
+}
+
+function validateState(state) {
+  let encoded;
+  try {
+    encoded = JSON.stringify(state);
+  } catch {
+    fail("semantic state must be JSON serializable");
+  }
+  if (encoded === undefined) fail("semantic state must be JSON serializable");
+  if (Buffer.byteLength(encoded, "utf8") > SEMANTIC_POLICY.limits.stateBytes) {
+    fail(`semantic state exceeds ${SEMANTIC_POLICY.limits.stateBytes} UTF-8 bytes`);
+  }
+}
+
+function validateGoal(goal) {
+  if (typeof goal !== "string" || !goal.trim()) fail("goal must be a nonblank string");
+  if (Buffer.byteLength(goal, "utf8") > 4_096) fail("goal exceeds 4096 UTF-8 bytes");
+  return goal.trim();
+}
+
+function exactKeys(value, expected, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    providerInvalid(`${label} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    providerInvalid(`${label} keys do not match the request`);
+  }
+}
+
+function validateMetadata(response) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    providerInvalid("provider response must be an object");
+  }
+  exactKeys(response, ["answers", "model", "usage"], "provider response");
+  if (typeof response.model !== "string" || !response.model.trim()) providerInvalid("provider model is missing");
+  exactKeys(response.usage, ["input_tokens", "output_tokens"], "provider usage");
+  for (const key of ["input_tokens", "output_tokens"]) {
+    if (!Number.isSafeInteger(response.usage[key]) || response.usage[key] < 0) {
+      providerInvalid("provider usage must contain nonnegative integer token counts");
+    }
+  }
+  return { model: response.model, usage: { ...response.usage } };
+}
+
+function validateChoice(answer, labels) {
+  exactKeys(answer, ["choice", "confidence", "probabilities", "type"], "choice answer");
+  if (answer.type !== "choice") providerInvalid("provider answer must be a choice");
+  if (!labels.includes(answer.choice)) providerInvalid("provider selected an unknown label");
+  if (!Number.isFinite(answer.confidence) || answer.confidence < 0 || answer.confidence > 1) {
+    providerInvalid("provider confidence must be between zero and one");
+  }
+  exactKeys(answer.probabilities, labels, "choice probabilities");
+  let sum = 0;
+  let maximum = -1;
+  for (const label of labels) {
+    const probability = answer.probabilities[label];
+    if (!Number.isFinite(probability) || probability < 0 || probability > 1) {
+      providerInvalid("provider probabilities must be finite values between zero and one");
+    }
+    sum += probability;
+    maximum = Math.max(maximum, probability);
+  }
+  if (Math.abs(sum - 1) > SEMANTIC_POLICY.probabilitySumTolerance) {
+    providerInvalid("provider probabilities do not sum to one");
+  }
+  if (answer.probabilities[answer.choice] + Number.EPSILON < maximum) {
+    providerInvalid("provider selected label is inconsistent with its probabilities");
+  }
+  return {
+    label: answer.choice,
+    probability: answer.probabilities[answer.choice],
+    probabilities: { ...answer.probabilities },
+    confidence: answer.confidence,
+  };
+}
+
+function choiceQuestion(instructions, labels) {
+  return { type: "choice", instructions, criteria: Object.fromEntries(labels.map((label) => [label, null])) };
+}
+
+async function evaluatedChoices({ state, questions, evaluate }) {
+  validateState(state);
+  if (typeof evaluate !== "function") fail("evaluate must be a function");
+  const names = Object.keys(questions);
+  if (!names.length || names.length > SEMANTIC_POLICY.limits.questions) fail("question count is outside policy limits");
+  const response = await evaluate(state, questions, {});
+  const metadata = validateMetadata(response);
+  exactKeys(response.answers, names, "provider answers");
+  const decisions = {};
+  for (const name of names) decisions[name] = validateChoice(response.answers[name], Object.keys(questions[name].criteria));
+  return { decisions, ...metadata };
+}
+
+function candidateDescription(candidate) {
+  const parts = [candidate.role, candidate.name, candidate.text].filter((value) => typeof value === "string" && value);
+  return parts.join(" | ").slice(0, 1_024) || null;
+}
+
+function actionDescription(action, state) {
+  const ref = action.ref || action.concreteRef;
+  const candidate = ref && Array.isArray(state.candidates)
+    ? state.candidates.find((item) => item.id === ref)
+    : null;
+  const parts = [action.kind, candidate?.role, candidate?.name];
+  if (candidate?.state?.checked === true) parts.push("checked");
+  if (candidate?.state?.checked === false) parts.push("unchecked");
+  if (candidate?.state?.selected === true) parts.push("selected");
+  if (candidate?.state?.selected === false) parts.push("not selected");
+  if (action.kind === "scroll") parts.push(action.direction);
+  if (action.kind === "wait") parts.push(`${action.durationMs}ms`);
+  return parts.filter((value) => value !== undefined && value !== "").join(" | ").slice(0, 1_024) || null;
+}
+
+async function find({ state, goal, candidates, thresholds = {}, evaluate }) {
+  goal = validateGoal(goal);
+  assertUniqueItems(candidates, SEMANTIC_POLICY.limits.candidates, "candidates");
+  const labels = [...candidates.map((candidate) => candidate.id), "none"];
+  const criteria = Object.fromEntries(candidates.map((candidate) => [candidate.id, candidateDescription(candidate)]));
+  criteria.none = "No supplied candidate matches the goal";
+  const response = await evaluatedChoices({
+    state,
+    questions: { target: { type: "choice", instructions: `Select the supplied candidate that matches this goal: ${goal}`, criteria } },
+    evaluate,
+  });
+  const decision = response.decisions.target;
+  const appliedThreshold = thresholds.find ?? SEMANTIC_POLICY.thresholds.find;
+  const found = decision.label !== "none" && decision.probability >= appliedThreshold;
+  return {
+    status: found ? "found" : "uncertain",
+    candidate: found ? candidates.find((item) => item.id === decision.label) : null,
+    appliedThreshold,
+    decision,
+    model: response.model,
+    usage: response.usage,
+  };
+}
+
+async function verify({ state, outcome, evidence = [], thresholds = {}, evaluate }) {
+  outcome = validateGoal(outcome);
+  assertUniqueItems(evidence, SEMANTIC_POLICY.limits.chunks, "evidence");
+  const questions = {
+    verdict: choiceQuestion(`Does the supplied page state show this outcome: ${outcome}`, ["satisfied", "not_satisfied"]),
+  };
+  if (evidence.length) {
+    questions.evidence = choiceQuestion("Select the supplied evidence ID most relevant to the verdict", [
+      ...evidence.map((item) => item.id),
+      "none",
+    ]);
+  }
+  const response = await evaluatedChoices({ state, questions, evaluate });
+  const verdict = response.decisions.verdict;
+  const verifyPositive = thresholds.verifyPositive ?? SEMANTIC_POLICY.thresholds.verifyPositive;
+  const verifyNegative = thresholds.verifyNegative ?? SEMANTIC_POLICY.thresholds.verifyNegative;
+  const appliedThreshold = verdict.label === "satisfied" ? verifyPositive : verifyNegative;
+  let status = "uncertain";
+  if (verdict.label === "satisfied" && verdict.probability >= verifyPositive) status = "satisfied";
+  if (verdict.label === "not_satisfied" && verdict.probability >= verifyNegative) status = "not_satisfied";
+  const evidenceDecision = response.decisions.evidence;
+  const evidenceItem = evidenceDecision && evidenceDecision.label !== "none"
+    ? evidence.find((item) => item.id === evidenceDecision.label)
+    : null;
+  return { status, appliedThreshold, decision: verdict, evidence: evidenceItem || null, evidenceDecision: evidenceDecision || null, model: response.model, usage: response.usage };
+}
+
+async function filter({ state, goal, chunks, top = SEMANTIC_POLICY.limits.filterTop, thresholds = {}, evaluate }) {
+  goal = validateGoal(goal);
+  assertUniqueItems(chunks, SEMANTIC_POLICY.limits.chunks, "chunks");
+  if (!Number.isInteger(top) || top < 1 || top > SEMANTIC_POLICY.limits.filterTop) fail(`top must be between 1 and ${SEMANTIC_POLICY.limits.filterTop}`);
+  const appliedThreshold = thresholds.filter ?? SEMANTIC_POLICY.thresholds.filter;
+  if (!chunks.length) return { status: "uncertain", appliedThreshold, chunks: [], omittedCount: 0, decisions: {}, model: null, usage: null };
+  const questions = Object.fromEntries(chunks.map((chunk, index) => [
+    `chunk_${index}`,
+    choiceQuestion(`Is chunk ${chunk.id} relevant to this goal: ${goal}`, ["relevant", "not_relevant"]),
+  ]));
+  const response = await evaluatedChoices({ state, questions, evaluate });
+  const ranked = chunks
+    .map((chunk, index) => ({ chunk, decision: response.decisions[`chunk_${index}`], index }))
+    .filter((entry) => entry.decision.label === "relevant" && entry.decision.probability >= appliedThreshold)
+    .sort((left, right) => right.decision.probability - left.decision.probability || left.index - right.index)
+    .slice(0, top);
+  return {
+    status: ranked.length ? "filtered" : "uncertain",
+    appliedThreshold,
+    chunks: ranked.map(({ chunk, decision }) => ({ ...chunk, relevance: decision })),
+    omittedCount: chunks.length - ranked.length,
+    decisions: response.decisions,
+    model: response.model,
+    usage: response.usage,
+  };
+}
+
+function validateAction(action, options) {
+  const allowedKinds = ["navigate", "click", "scroll", "wait", "fill"];
+  if (!allowedKinds.includes(action.kind)) fail(`unsupported action kind for ${action.id}`);
+  if (action.kind === "wait" && !SEMANTIC_POLICY.waitsMs.includes(action.durationMs)) fail(`invalid wait action ${action.id}`);
+  if (action.kind === "scroll" && !SEMANTIC_POLICY.scrolls.includes(action.direction)) fail(`invalid scroll action ${action.id}`);
+  if (action.kind === "navigate") {
+    let url;
+    try { url = new URL(action.url); } catch { fail(`invalid navigation URL for ${action.id}`); }
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password || url.origin !== options.origin) fail(`navigation ${action.id} is not a safe same-origin HTTP(S) URL`);
+  }
+  if (action.kind === "click" || action.kind === "fill") {
+    assertOpaqueId(action.ref, `action ${action.id} ref`);
+    if (!options.allowWrite) return false;
+    if (options.allowRefs?.length && !options.allowRefs.includes(action.ref)) return false;
+  }
+  if (action.kind === "fill") {
+    assertOpaqueId(action.slot, `action ${action.id} slot`);
+    if (!options.inputSlots.includes(action.slot)) fail(`fill action ${action.id} references an unknown input slot`);
+  }
+  return true;
+}
+
+async function chooseAction({ state, goal, actions, origin, allowWrite = false, allowRefs = [], inputSlots = [], thresholds = {}, evaluate }) {
+  goal = validateGoal(goal);
+  assertUniqueItems(actions, SEMANTIC_POLICY.limits.actionChoices, "actions");
+  if (!Array.isArray(allowRefs)) fail("allowRefs must be an array");
+  if (!Array.isArray(inputSlots) || inputSlots.length > SEMANTIC_POLICY.limits.inputSlots) fail("inputSlots exceeds policy limits");
+  for (const value of [...allowRefs, ...inputSlots]) assertOpaqueId(value, "authorization identifier");
+  const eligible = actions.filter((action) => validateAction(action, { origin, allowWrite, allowRefs, inputSlots }));
+  const labels = [...eligible.map((action) => action.id), "stop"];
+  const actionCriteria = Object.fromEntries(eligible.map((action) => [action.id, actionDescription(action, state)]));
+  actionCriteria.stop = "The goal is already satisfied, or no supplied action can safely make progress";
+  const writeActions = eligible.filter((item) => item.kind === "click" || item.kind === "fill");
+  const questions = {
+    action: {
+      type: "choice",
+      instructions: `Choose the single next supplied action that safely advances this multi-step goal: ${goal}. The action only needs to make progress. Choose stop only if the goal is already satisfied or no supplied action can safely make progress.`,
+      criteria: actionCriteria,
+    },
+  };
+  const evidence = writeActions.length && Array.isArray(state.chunks) ? state.chunks : [];
+  if (writeActions.length) {
+    assertUniqueItems(evidence, SEMANTIC_POLICY.limits.chunks, "chunks");
+    questions.prerequisites = {
+      type: "choice",
+      instructions: `Before any mutation, determine whether the supplied page state explicitly supports every product or variant prerequisite in this goal: ${goal}`,
+      criteria: {
+        supported: "Every explicit product and variant prerequisite is already satisfied or visibly available through supplied controls",
+        blocked: "At least one explicit product or variant prerequisite is contradicted or absent from the supplied page state",
+        uncertain: "The supplied page state does not establish whether all explicit prerequisites are supported",
+      },
+    };
+    questions.prerequisite_evidence = choiceQuestion(
+      "Select the supplied page region most relevant to the prerequisite verdict",
+      [...evidence.map((chunk) => chunk.id), "none"],
+    );
+  }
+  const response = await evaluatedChoices({
+    state,
+    questions,
+    evaluate,
+  });
+  const decision = response.decisions.action;
+  const prerequisiteDecision = response.decisions.prerequisites || null;
+  const prerequisiteEvidenceDecision = response.decisions.prerequisite_evidence || null;
+  const prerequisiteSupported = thresholds.prerequisiteSupported ?? SEMANTIC_POLICY.thresholds.prerequisiteSupported;
+  const prerequisiteBlocked = thresholds.prerequisiteBlocked ?? SEMANTIC_POLICY.thresholds.prerequisiteBlocked;
+  let prerequisiteStatus = "not_applicable";
+  if (writeActions.length) {
+    prerequisiteStatus = "uncertain";
+    if (prerequisiteDecision.label === "supported" && prerequisiteDecision.probability >= prerequisiteSupported) prerequisiteStatus = "supported";
+    if (prerequisiteDecision.label === "blocked" && prerequisiteDecision.probability >= prerequisiteBlocked) prerequisiteStatus = "blocked";
+  }
+  const prerequisiteEvidenceThreshold = SEMANTIC_POLICY.thresholds.filter;
+  const prerequisiteEvidence = !prerequisiteEvidenceDecision || prerequisiteEvidenceDecision.label === "none" || prerequisiteEvidenceDecision.probability < prerequisiteEvidenceThreshold
+    ? null
+    : evidence.find((chunk) => chunk.id === prerequisiteEvidenceDecision.label) || null;
+  const action = eligible.find((item) => item.id === decision.label) || null;
+  const exactRefWrite = action && (action.kind === "click" || action.kind === "fill") &&
+    allowRefs.length === 1 && writeActions.length === 1 && writeActions[0].ref === allowRefs[0];
+  const appliedThreshold = action && (action.kind === "click" || action.kind === "fill")
+    ? exactRefWrite ? thresholds.exactRefWrite ?? SEMANTIC_POLICY.thresholds.exactRefWrite : thresholds.write ?? SEMANTIC_POLICY.thresholds.write
+    : thresholds.find ?? SEMANTIC_POLICY.thresholds.find;
+  const write = action && (action.kind === "click" || action.kind === "fill");
+  const blocked = prerequisiteStatus === "blocked" && (!action || write);
+  const selected = action && decision.probability >= appliedThreshold && (!write || prerequisiteStatus === "supported") ? action : null;
+  return {
+    status: blocked ? "blocked" : selected ? "selected" : "uncertain",
+    action: selected,
+    appliedThreshold,
+    decision,
+    logicalDecision: action ? {
+      id: action.id,
+      identity: action.logicalIdentity || action.id,
+      probability: decision.probability,
+    } : null,
+    concreteDecision: action ? {
+      id: action.id,
+      ...(action.ref || action.concreteRef ? { ref: action.ref || action.concreteRef } : {}),
+      probability: decision.probability,
+    } : null,
+    prerequisiteStatus,
+    prerequisiteThresholds: { supported: prerequisiteSupported, blocked: prerequisiteBlocked },
+    prerequisiteDecision,
+    prerequisiteEvidence,
+    prerequisiteEvidenceThreshold,
+    prerequisiteEvidenceDecision,
+    model: response.model,
+    usage: response.usage,
+  };
+}
+
+module.exports = { SEMANTIC_POLICY, SemanticError, chooseAction, filter, find, verify };

package/native/semantic-credentials.cjs

@@ -0,0 +1,207 @@
+const crypto = require("crypto");
+const os = require("os");
+const path = require("path");
+const {
+  atomicWriteJson,
+  readPrivateJson,
+  removePrivateFile,
+} = require("./private-state.cjs");
+
+const CREDENTIAL_VERSION = 1;
+const MAX_API_KEY_BYTES = 16 * 1024;
+const FINGERPRINT_LENGTH = 12;
+const TTY_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+function credentialLocation(env = process.env, { platform = process.platform, homeDir = os.homedir() } = {}) {
+  const windows = platform === "win32";
+  const pathApi = windows ? path.win32 : path;
+  const configRoot = windows
+    ? (typeof env.APPDATA === "string" && env.APPDATA.trim() ? env.APPDATA.trim() : pathApi.join(homeDir, "AppData", "Roaming"))
+    : (typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim() ? env.XDG_CONFIG_HOME.trim() : pathApi.join(homeDir, ".config"));
+  const root = pathApi.join(configRoot, windows ? "TypeSafe" : "typesafe");
+  return {
+    root,
+    filePath: pathApi.join(root, "credentials.json"),
+  };
+}
+
+function requireApiKey(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error("TypeSafe API key must not be blank");
+  }
+  if (Buffer.byteLength(value, "utf8") > MAX_API_KEY_BYTES) {
+    throw new Error(`TypeSafe API key exceeds ${MAX_API_KEY_BYTES} bytes`);
+  }
+  return value;
+}
+
+function fingerprintApiKey(apiKey) {
+  const digest = crypto.createHash("sha256").update(apiKey, "utf8").digest("hex");
+  return `sha256:${digest.slice(0, FINGERPRINT_LENGTH)}`;
+}
+
+function readStoredApiKey(env = process.env) {
+  const { root, filePath } = credentialLocation(env);
+  const value = readPrivateJson(filePath, null, { root });
+  if (value === null) return null;
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    value.version !== CREDENTIAL_VERSION ||
+    typeof value.apiKey !== "string"
+  ) {
+    throw new Error("stored TypeSafe credential is invalid");
+  }
+  try {
+    return requireApiKey(value.apiKey);
+  } catch {
+    throw new Error("stored TypeSafe credential is invalid");
+  }
+}
+
+function resolveTypeSafeCredential(env = process.env) {
+  if (typeof env.TYPESAFE_API_KEY === "string" && env.TYPESAFE_API_KEY.trim().length > 0) {
+    const apiKey = requireApiKey(env.TYPESAFE_API_KEY);
+    return { apiKey, source: "environment", fingerprint: fingerprintApiKey(apiKey) };
+  }
+  const apiKey = readStoredApiKey(env);
+  if (apiKey === null) return null;
+  return { apiKey, source: "shared-store", fingerprint: fingerprintApiKey(apiKey) };
+}
+
+function credentialStatus(env = process.env) {
+  const credential = resolveTypeSafeCredential(env);
+  if (!credential) return { source: "not-configured" };
+  return { source: credential.source, fingerprint: credential.fingerprint };
+}
+
+function storeTypeSafeCredential(apiKey, env = process.env) {
+  const validated = requireApiKey(apiKey);
+  const { root, filePath } = credentialLocation(env);
+  atomicWriteJson(filePath, { version: CREDENTIAL_VERSION, apiKey: validated }, { root });
+  return { source: "shared-store", fingerprint: fingerprintApiKey(validated) };
+}
+
+function clearStoredTypeSafeCredential(env = process.env) {
+  const { root, filePath } = credentialLocation(env);
+  return removePrivateFile(filePath, { root });
+}
+
+function readNonInteractiveLine(input) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    const cleanup = () => {
+      input.off("data", onData);
+      input.off("end", onEnd);
+      input.off("error", onError);
+    };
+    const fail = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onData = (chunk) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      bytes += buffer.length;
+      if (bytes > MAX_API_KEY_BYTES + 2) {
+        input.pause?.();
+        fail(new Error(`TypeSafe API key input exceeds ${MAX_API_KEY_BYTES} bytes`));
+        return;
+      }
+      chunks.push(buffer);
+    };
+    const onEnd = () => {
+      cleanup();
+      let value = Buffer.concat(chunks).toString("utf8");
+      if (value.endsWith("\n")) value = value.slice(0, -1);
+      if (value.endsWith("\r")) value = value.slice(0, -1);
+      if (value.includes("\n") || value.includes("\r")) {
+        reject(new Error("TypeSafe API key input must be one line"));
+        return;
+      }
+      try {
+        resolve(requireApiKey(value));
+      } catch (error) {
+        reject(error);
+      }
+    };
+    const onError = (error) => fail(error);
+    input.on("data", onData);
+    input.once("end", onEnd);
+    input.once("error", onError);
+    input.resume?.();
+  });
+}
+
+function readHiddenTtyLine(input, output, signalSource = process) {
+  return new Promise((resolve, reject) => {
+    let value = "";
+    let settled = false;
+    const previousRaw = input.isRaw === true;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      input.off("data", onData);
+      input.off("error", onError);
+      for (const signal of TTY_SIGNALS) signalSource.off(signal, signalHandlers[signal]);
+      try { input.setRawMode(previousRaw); } catch {}
+      input.pause?.();
+      output.write("\n");
+      if (error) reject(error);
+      else {
+        try { resolve(requireApiKey(value)); } catch (validationError) { reject(validationError); }
+      }
+    };
+    const signalHandlers = Object.fromEntries(
+      TTY_SIGNALS.map((signal) => [signal, () => finish(new Error(`TypeSafe API key input interrupted by ${signal}`))]),
+    );
+    const onError = (error) => finish(error);
+    const onData = (chunk) => {
+      for (const character of chunk.toString("utf8")) {
+        if (character === "\u0003") return finish(new Error("TypeSafe API key input cancelled"));
+        if (character === "\r" || character === "\n") return finish();
+        if (character === "\u007f" || character === "\b") value = value.slice(0, -1);
+        else value += character;
+        if (Buffer.byteLength(value, "utf8") > MAX_API_KEY_BYTES) {
+          return finish(new Error(`TypeSafe API key input exceeds ${MAX_API_KEY_BYTES} bytes`));
+        }
+      }
+    };
+    output.write("TypeSafe API key: ");
+    input.setRawMode(true);
+    input.on("data", onData);
+    input.once("error", onError);
+    for (const signal of TTY_SIGNALS) signalSource.once(signal, signalHandlers[signal]);
+    input.resume?.();
+  });
+}
+
+function readTypeSafeApiKey(options = {}) {
+  const { input = process.stdin, output = process.stderr, signalSource = process } = options;
+  if (input.isTTY) {
+    if (typeof input.setRawMode !== "function") {
+      return Promise.reject(new Error("hidden TypeSafe API key input is unavailable on this terminal"));
+    }
+    return readHiddenTtyLine(input, output, signalSource);
+  }
+  return readNonInteractiveLine(input);
+}
+
+async function setTypeSafeCredentialFromInput(options = {}) {
+  const apiKey = await readTypeSafeApiKey(options);
+  return storeTypeSafeCredential(apiKey, options.env || process.env);
+}
+
+module.exports = {
+  MAX_API_KEY_BYTES,
+  clearStoredTypeSafeCredential,
+  credentialLocation,
+  credentialStatus,
+  fingerprintApiKey,
+  readStoredApiKey,
+  readTypeSafeApiKey,
+  resolveTypeSafeCredential,
+  setTypeSafeCredentialFromInput,
+  storeTypeSafeCredential,
+};

package/native/semantic-provider.cjs

@@ -0,0 +1,61 @@
+const { SEMANTIC_POLICY, SemanticError } = require("./semantic-core.cjs");
+
+const BASE_URL = "https://api.typesafe.ai";
+
+function providerError(code, message, status) {
+  const error = new SemanticError(code, message);
+  if (status !== undefined) error.status = status;
+  return error;
+}
+
+function mapProviderError(error) {
+  const status = Number.isInteger(error?.status) ? error.status : undefined;
+  if (status === 401 || status === 403) return providerError("provider_authentication", "TypeSafe authentication failed", status);
+  if (status === 400 || status === 404 || status === 422) return providerError("provider_invalid_request", "TypeSafe rejected the semantic request", status);
+  if (status === 429) return providerError("provider_rate_limited", "TypeSafe rate limit exceeded", status);
+  if (status === 529 || (status !== undefined && status >= 500)) return providerError("provider_unavailable", "TypeSafe is unavailable", status);
+  if (error?.name === "APITimeoutError") return providerError("provider_timeout", "TypeSafe request timed out");
+  if (error?.name === "APIUserAbortError" || error?.name === "AbortError") return providerError("provider_cancelled", "TypeSafe request was cancelled");
+  if (error?.name === "APIConnectionError") return providerError("provider_unavailable", "TypeSafe connection failed");
+  return providerError("provider_error", "TypeSafe request failed");
+}
+
+function resolveModel(env) {
+  const override = env.SURF_JEV_MODEL;
+  return typeof override === "string" && override.trim() ? override.trim() : SEMANTIC_POLICY.model;
+}
+
+function createJevEvaluator({ apiKey, env = process.env, loadSdk = () => require("@typesafe-ai/sdk"), fetch } = {}) {
+  if (typeof apiKey !== "string" || !apiKey.trim()) {
+    throw providerError("provider_not_configured", "TypeSafe API key is not configured");
+  }
+  const model = resolveModel(env);
+  let client;
+
+  return async function evaluate(state, questions, options = {}) {
+    try {
+      if (!client) {
+        const sdk = loadSdk();
+        if (!sdk || typeof sdk.TypeSafeClient !== "function") throw new Error("invalid SDK module");
+        client = new sdk.TypeSafeClient({
+          apiKey: apiKey.trim(),
+          baseURL: BASE_URL,
+          defaultModel: model,
+          logLevel: "off",
+          retry: { maxRetries: 0 },
+          timeout: SEMANTIC_POLICY.timeoutMs,
+          ...(fetch ? { fetch } : {}),
+        });
+      }
+      return await client.systemOne(
+        { state, questions, model },
+        { signal: options.signal, timeout: SEMANTIC_POLICY.timeoutMs, retry: { maxRetries: 0 } },
+      );
+    } catch (error) {
+      if (error instanceof SemanticError) throw error;
+      throw mapProviderError(error);
+    }
+  };
+}
+
+module.exports = { BASE_URL, createJevEvaluator, mapProviderError, resolveModel };