@uchibeke/gallivant 0.2.0 → 0.3.0

package/lib/task_model_config.mjs

@@ -0,0 +1,99 @@
+// Operator configuration for the APort-funded intake model route. Pure: no
+// imports, no environment reads at module level, no provider knowledge beyond
+// the two documented request shapes. Nothing here is task-selectable.
+//
+// config.json:
+//   "intake_model": {
+//     "adapter": "openai-chat" | "anthropic-messages",
+//     "model": "<provider model id>",
+//     "endpoint": "https://.../v1/chat/completions" | "https://.../v1/messages",
+//     "credential_env": "NAME_OF_ENV_VAR_HOLDING_THE_KEY",
+//     "budget": { "max_calls": 3, "max_input_tokens": 50000, "max_output_tokens": 6000,
+//                 "allowance_usd": 0.10, "input_usd_per_million": 0.25, "output_usd_per_million": 2 },
+//     "timeout_ms": 60000
+//   }
+// Ceilings below are absolute: configuration can lower them, never raise them.
+export const MODEL_ROUTE_CEILINGS = Object.freeze({ maxCalls: 12, maxInputTokens: 100_000, maxOutputTokens: 16_000, allowanceUsd: 10, timeoutMs: 300_000 });
+export const MODEL_ROUTE_ADAPTERS = Object.freeze(["openai-chat", "anthropic-messages"]);
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+const localHost = host => {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  if (h.startsWith("[")) return true;
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(h)) {
+    const [a, b] = h.split(".").map(Number);
+    return a === 0 || a === 10 || a === 127 || a >= 224 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 100 && b >= 64 && b <= 127;
+  }
+  return !h.includes(".") || /(?:^|\.)(?:localhost|local|internal|test|invalid|example|home\.arpa|onion)$/.test(h);
+};
+
+export function intakeModelProblems(raw) {
+  const problems = [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return ["intake_model must be an object (adapter, model, endpoint, credential_env, budget, timeout_ms)"];
+  const extra = Object.keys(raw).filter(key => !["adapter", "model", "endpoint", "credential_env", "budget", "timeout_ms"].includes(key));
+  if (extra.length) problems.push(`intake_model has unknown key${extra.length === 1 ? "" : "s"} ${extra.join(", ")}`);
+  if (!MODEL_ROUTE_ADAPTERS.includes(raw.adapter)) problems.push(`intake_model.adapter must be one of ${MODEL_ROUTE_ADAPTERS.join(", ")}`);
+  if (typeof raw.model !== "string" || !/^[\w.:/-]{1,128}$/.test(raw.model)) problems.push("intake_model.model must be the provider's model identifier (letters, digits, . : / _ -)");
+  let endpoint = null;
+  try { endpoint = new URL(raw.endpoint); } catch { /* reported below */ }
+  if (!endpoint || endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) problems.push("intake_model.endpoint must be an HTTPS URL without credentials, query or fragment");
+  else if (localHost(endpoint.hostname)) problems.push("intake_model.endpoint must name a public provider host, not a local or private address");
+  if (typeof raw.credential_env !== "string" || !/^[A-Z][A-Z0-9_]{2,63}$/.test(raw.credential_env)) problems.push("intake_model.credential_env must name the environment variable holding the API key (for example OPENAI_API_KEY); keys never belong in config.json");
+  const budget = raw.budget;
+  if (!budget || typeof budget !== "object" || Array.isArray(budget)) problems.push("intake_model.budget must set max_calls, max_input_tokens, max_output_tokens, allowance_usd, input_usd_per_million and output_usd_per_million");
+  else {
+    const integer = (key, ceiling) => { const value = budget[key]; if (!Number.isSafeInteger(value) || value < 1 || value > ceiling) problems.push(`intake_model.budget.${key} must be an integer from 1 to ${ceiling}`); };
+    integer("max_calls", MODEL_ROUTE_CEILINGS.maxCalls);
+    integer("max_input_tokens", MODEL_ROUTE_CEILINGS.maxInputTokens);
+    integer("max_output_tokens", MODEL_ROUTE_CEILINGS.maxOutputTokens);
+    if (!Number.isFinite(budget.allowance_usd) || budget.allowance_usd <= 0 || budget.allowance_usd > MODEL_ROUTE_CEILINGS.allowanceUsd) problems.push(`intake_model.budget.allowance_usd must be above 0 and at most ${MODEL_ROUTE_CEILINGS.allowanceUsd}`);
+    for (const key of ["input_usd_per_million", "output_usd_per_million"]) if (!Number.isFinite(budget[key]) || budget[key] < 0) problems.push(`intake_model.budget.${key} must be the provider's list price per million tokens (0 or more); spend is estimated from it`);
+    const extraBudget = Object.keys(budget).filter(key => !["max_calls", "max_input_tokens", "max_output_tokens", "allowance_usd", "input_usd_per_million", "output_usd_per_million"].includes(key));
+    if (extraBudget.length) problems.push(`intake_model.budget has unknown key${extraBudget.length === 1 ? "" : "s"} ${extraBudget.join(", ")}`);
+  }
+  if (raw.timeout_ms !== undefined && (!Number.isSafeInteger(raw.timeout_ms) || raw.timeout_ms < 1000 || raw.timeout_ms > MODEL_ROUTE_CEILINGS.timeoutMs)) problems.push(`intake_model.timeout_ms must be an integer from 1000 to ${MODEL_ROUTE_CEILINGS.timeoutMs}`);
+  return problems;
+}
+
+export function validateIntakeModelConfig(raw) {
+  const problems = intakeModelProblems(raw);
+  if (problems.length) throw Object.assign(new Error(problems.join("; ")), { code: "TASK_MODEL_ROUTE" });
+  return Object.freeze({ adapter: raw.adapter, model: raw.model, endpoint: raw.endpoint, credentialEnv: raw.credential_env, timeoutMs: raw.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+    budget: Object.freeze({ maxCalls: raw.budget.max_calls, maxInputTokens: raw.budget.max_input_tokens, maxOutputTokens: raw.budget.max_output_tokens, allowanceUsd: raw.budget.allowance_usd, inputUsdPerMillion: raw.budget.input_usd_per_million, outputUsdPerMillion: raw.budget.output_usd_per_million }) });
+}
+
+// The selection a task pins at creation: everything later turns execute
+// against, minus the credential, which is always read from the environment.
+export function pinnedModelRoute(route) {
+  return { adapter: route.adapter, model: route.model, endpoint: route.endpoint, endpointHost: new URL(route.endpoint).hostname, credentialEnv: route.credentialEnv, timeoutMs: route.timeoutMs, budget: { ...route.budget } };
+}
+// Reconstruct and revalidate a saved selection, so a later turn cannot run
+// against fields outside the documented shape or above the ceilings.
+export function savedModelRoute(pinned) {
+  if (!pinned || typeof pinned !== "object") throw Object.assign(new Error("the task has no pinned model route; prepare a new task"), { code: "TASK_MODEL_ROUTE" });
+  const budget = pinned.budget || {};
+  return validateIntakeModelConfig({ adapter: pinned.adapter, model: pinned.model, endpoint: pinned.endpoint, credential_env: pinned.credentialEnv, timeout_ms: pinned.timeoutMs,
+    budget: { max_calls: budget.maxCalls, max_input_tokens: budget.maxInputTokens, max_output_tokens: budget.maxOutputTokens, allowance_usd: budget.allowanceUsd, input_usd_per_million: budget.inputUsdPerMillion, output_usd_per_million: budget.outputUsdPerMillion } });
+}
+
+// Route availability without secrets. The credential value is never returned;
+// only whether the named variable is present in the operator environment.
+export function intakeModelRoute(config, env = {}) {
+  const raw = config?.intake_model;
+  if (raw === undefined || raw === null) return { enabled: false, reason: "intake_model is not configured; add it to config.json to enable the APort-funded model route", route: null };
+  let route;
+  try { route = validateIntakeModelConfig(raw); }
+  catch (error) { return { enabled: false, reason: `intake_model configuration is invalid: ${error.message}`, route: null }; }
+  const credentialPresent = typeof env?.[route.credentialEnv] === "string" && env[route.credentialEnv].trim().length > 0;
+  if (!credentialPresent) return { enabled: false, reason: `export ${route.credentialEnv} in the operator environment to enable the configured ${route.adapter} model route; the key is read at call time and never saved`, route };
+  return { enabled: true, reason: null, route };
+}
+
+// Public summary for capability discovery and task views: no endpoint secrets,
+// no credential names beyond the variable the operator chose to configure.
+export function intakeModelRouteSummary(config, env = {}) {
+  const selection = intakeModelRoute(config, env);
+  const host = selection.route ? new URL(selection.route.endpoint).hostname : null;
+  return { enabled: selection.enabled, reason: selection.reason, adapter: selection.route?.adapter || null, model: selection.route?.model || null, endpointHost: host,
+    budget: selection.route ? { ...selection.route.budget } : null, ceilings: { ...MODEL_ROUTE_CEILINGS }, tools: [], source: "operator-configuration" };
+}

package/lib/task_model_route.mjs

@@ -0,0 +1,243 @@
+// The APort-funded intake model route: one bounded, tool-free text request per
+// planning turn against an operator-configured endpoint. It drafts; it never
+// implements, reads the repository, runs commands or publishes. Budget ceilings
+// are absolute and checked before a call is started; spend is reported from
+// provider usage at configured list prices or labelled unknown, never zero.
+import { draftPrompt, MAX_PREPARATION_PROMPT_BYTES } from "./task_contract.mjs";
+import { taskError } from "./task_store.mjs";
+import { redact } from "./execution_io.mjs";
+import { savedModelRoute, MODEL_ROUTE_CEILINGS } from "./task_model_config.mjs";
+
+export const MODEL_ROUTE_PROVIDER = "aport-model";
+export const MODEL_ROUTE_BOUNDARY = "aport-model-text-only-v1";
+export const MODEL_ROUTE_LIMITS = Object.freeze({ responseBytes: 1_048_576 });
+// Per-request protocol tokens (role markers, message boundaries) that the
+// serialized body cannot show; counted on top of the byte bound.
+export const MODEL_ROUTE_FRAMING_TOKENS = 64;
+// The smallest deadline worth starting a call with; the configured timeout's
+// own floor. Less remaining task runtime than this refuses before the request.
+export const MODEL_ROUTE_MIN_TIMEOUT_MS = 1000;
+// A receipt qualifies only for the task it was issued to and the route that
+// task pinned, so an attempt copied or restored from another task (or produced
+// by a different adapter/model) can never authorize readiness or dispatch here.
+export const isModelRouteReceipt = (receipt, task = null) => Boolean(receipt && receipt.version === 1 && receipt.provider === MODEL_ROUTE_PROVIDER && receipt.account === "operator"
+  && receipt.boundary === MODEL_ROUTE_BOUNDARY && receipt.authority === "text-only" && Array.isArray(receipt.tools) && receipt.tools.length === 0
+  && (task === null || (receipt.taskId === `intake/${task.id}` && task.route === "model" && receipt.adapter === task.modelRoute?.adapter && receipt.model === task.modelRoute?.model)));
+
+// A true upper bound, not an estimate: byte-level BPE fallback can spend one
+// token per UTF-8 byte on emoji, rare scripts or identifier-heavy text, so the
+// pre-call token and spend checks assume exactly that. Reported usage replaces
+// the bound after the call; a provider that reports more than the ceiling is
+// rejected (see below), so the ceiling holds in both directions.
+export const estimateTokens = text => Buffer.byteLength(text);
+export const estimateUsd = (budget, inputTokens, outputTokens) => (inputTokens * budget.inputUsdPerMillion + outputTokens * budget.outputUsdPerMillion) / 1_000_000;
+const usd = value => `$${value.toFixed(4)}`;
+const SYSTEM = "You prepare requirements for a repository task. Reply with exactly one JSON object and nothing else. You have no tools, no repository access and no ability to perform actions; describe, map and ask, never execute.";
+
+// Usage must be a pair of non-negative safe integers. Absent usage is honest
+// uncertainty; present but malformed usage (negative, fractional, non-numeric)
+// is a malformed response, never a spend record that could offset the allowance.
+const tokenCount = value => Number.isSafeInteger(value) && value >= 0;
+function usageFrom(usage, inputKey, outputKey) {
+  if (usage === undefined || usage === null) return { usage: null };
+  if (typeof usage !== "object" || Array.isArray(usage) || !tokenCount(usage[inputKey]) || !tokenCount(usage[outputKey])) return { usage: null, usageError: `provider usage is malformed (${inputKey}/${outputKey} must be non-negative integers)` };
+  return { usage: { inputTokens: usage[inputKey], outputTokens: usage[outputKey] } };
+}
+
+// Two documented request shapes. Neither admits tools, functions, web search or
+// file access; the request body is built here and only here.
+const ADAPTERS = {
+  "openai-chat": {
+    request: ({ route, key, prompt }) => ({ headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: { model: route.model, messages: [{ role: "system", content: SYSTEM }, { role: "user", content: prompt }], max_tokens: route.budget.maxOutputTokens, temperature: 0 } }),
+    parse: json => ({ text: json?.choices?.[0]?.message?.content, finish: json?.choices?.[0]?.finish_reason ?? null, truncated: json?.choices?.[0]?.finish_reason === "length",
+      ...usageFrom(json?.usage, "prompt_tokens", "completion_tokens") }),
+  },
+  "anthropic-messages": {
+    request: ({ route, key, prompt }) => ({ headers: { "x-api-key": key, "anthropic-version": "2023-06-01", "Content-Type": "application/json" },
+      body: { model: route.model, max_tokens: route.budget.maxOutputTokens, system: SYSTEM, messages: [{ role: "user", content: prompt }] } }),
+    parse: json => ({ text: Array.isArray(json?.content) ? json.content.filter(block => block?.type === "text" && typeof block.text === "string").map(block => block.text).join("") : undefined, finish: json?.stop_reason ?? null, truncated: json?.stop_reason === "max_tokens",
+      ...usageFrom(json?.usage, "input_tokens", "output_tokens") }),
+  },
+};
+
+const failed = attempt => taskError(attempt.errorCode || "TASK_MODEL_ROUTE", attempt.error || "saved model route call failed");
+
+// Cancelling a body is awaited only until the deadline: a provider stream
+// whose cancel() never settles must not hold the preparation lock past the
+// configured timeout. A synchronous throw or a non-promise counts as settled.
+async function cancelWithin(cancel, signal) {
+  let pending;
+  try { pending = cancel(); } catch { return; }
+  if (!pending || typeof pending.then !== "function" || signal?.aborted) return;
+  await new Promise(resolve => {
+    const done = () => { signal?.removeEventListener("abort", done); resolve(); };
+    signal?.addEventListener("abort", done, { once: true });
+    pending.then(done, done);
+  });
+}
+
+// The response limit is enforced while the body streams, so a chunked or
+// unlabelled oversized reply is cancelled at the limit instead of buffered.
+// Reading happens under the caller's abort signal, so the configured timeout
+// still covers a provider that sends headers and then stalls.
+async function boundedJson(response, signal) {
+  const limit = MODEL_ROUTE_LIMITS.responseBytes;
+  const oversized = () => new Error("provider response exceeds the bounded limit");
+  if (Number(response.headers?.get?.("content-length") || 0) > limit) { await cancelWithin(() => response.body?.cancel?.(), signal); throw oversized(); }
+  let text;
+  const reader = typeof response.body?.getReader === "function" ? response.body.getReader() : null;
+  if (reader) {
+    const chunks = [];
+    let size = 0;
+    const abort = () => reader.cancel().catch(() => {});
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      for (;;) {
+        const aborted = () => { throw Object.assign(new Error("aborted"), { name: "AbortError" }); };
+        if (signal?.aborted) aborted();
+        const { value, done } = await reader.read();
+        // Cancelling the reader at the deadline resolves the pending read as
+        // done; a body that never completed must never parse as complete.
+        if (signal?.aborted) aborted();
+        if (done) break;
+        size += value.length;
+        if (size > limit) throw oversized();
+        chunks.push(value);
+      }
+      if (signal?.aborted) throw Object.assign(new Error("aborted"), { name: "AbortError" });
+      text = Buffer.concat(chunks).toString("utf8");
+    } finally {
+      signal?.removeEventListener("abort", abort);
+      await cancelWithin(() => reader.cancel(), signal);
+      reader.releaseLock();
+    }
+  } else {
+    text = typeof response.text === "function" ? await response.text() : "";
+    if (Buffer.byteLength(text) > limit) throw oversized();
+  }
+  try { return JSON.parse(text); } catch { throw new Error("provider returned invalid JSON"); }
+}
+
+// Same contract as prepareTurn: returns the planner's final message, records
+// usage and cost on the attempt, and throws bounded task errors. An attempt is
+// persisted before the request so a crash cannot purchase a second call.
+export async function prepareModelTurn(ctx, task, store, failures, { fetcher = ctx.fetch ?? globalThis.fetch, clock = Date } = {}) {
+  const env = ctx.env ?? process.env;
+  delete task.preflightFailure; // A fresh failure must earn its own pre-call marker.
+  // Later turns execute against the route pinned when the task was created,
+  // so an operator configuration change applies to new tasks and the review
+  // describes the route that produced the current draft. Only the credential
+  // is read live, from the variable the pinned route names.
+  let route;
+  try { route = savedModelRoute(task.modelRoute); }
+  catch (error) { throw taskError("TASK_MODEL_ROUTE", `${error.message}; no model call was made`); }
+  let attempt = task.attempts.at(-1);
+  if (attempt?.settled && !attempt.consumed) {
+    if (!attempt.ok) throw failed(attempt);
+    if (attempt.route !== "model" || !isModelRouteReceipt(attempt.receipt, task)) throw taskError("TASK_PREPARATION_BOUNDARY", "saved output was not produced by this task's text-only model route; it cannot authorize readiness; inspect the saved attempt and prepare a new task");
+    return attempt.message;
+  }
+  if (attempt && !attempt.settled) throw taskError("TASK_PREPARATION_UNKNOWN", "a model route call is recorded without a settled result; inspect the saved attempt before retrying; no new model call was made");
+  // Only a new request needs the credential. Replaying settled output above
+  // never does, so a temporarily absent variable cannot block recovery.
+  if (typeof env?.[route.credentialEnv] !== "string" || !env[route.credentialEnv].trim()) {
+    // This known local preflight owns no new request or spend. Explicit resume
+    // may retry it; submitted, failed and unsettled calls never get this marker.
+    task.preflightFailure = { code: "TASK_MODEL_ROUTE", stage: "model-credential", attemptCount: task.attempts.length, validationFailures: [...failures] };
+    store.save(task);
+    throw taskError("TASK_MODEL_ROUTE", `export ${route.credentialEnv} in the operator environment to continue this task's pinned ${route.adapter} model route, then explicitly resume it; the key is read at call time and never saved; no model call was made`);
+  }
+  const calls = task.attempts.filter(a => a.route === "model");
+  if (calls.length >= route.budget.maxCalls || calls.length >= MODEL_ROUTE_CEILINGS.maxCalls) throw taskError("TASK_ALLOWANCE", `the model route allows ${Math.min(route.budget.maxCalls, MODEL_ROUTE_CEILINGS.maxCalls)} calls per task and ${calls.length} were used; inspect the saved draft and its validation failures, then answer, clarify or prepare a new task; no further model call was made`);
+  // The task's runtime allowance bounds this call as well as its dollars: the
+  // deadline is capped to what remains, and a remainder too small for any
+  // call refuses before the request rather than overrunning the allowance.
+  const usedMs = task.attempts.reduce((sum, a) => sum + (a.elapsedMs || 0), 0);
+  const remainingMs = (task.allowance?.runtimeMs ?? Infinity) - usedMs;
+  if (remainingMs < MODEL_ROUTE_MIN_TIMEOUT_MS) throw taskError("TASK_ALLOWANCE", `the task runtime allowance has ${Math.max(0, Math.floor(remainingMs))} ms left, below the ${MODEL_ROUTE_MIN_TIMEOUT_MS} ms a model call needs; no model call was made; inspect the saved evidence or prepare a new task with a larger allowance`);
+  const timeoutMs = Math.min(route.timeoutMs, Math.floor(remainingMs));
+  const prompt = draftPrompt(task, failures);
+  if (Buffer.byteLength(prompt) > MAX_PREPARATION_PROMPT_BYTES) throw taskError("TASK_INPUT", `serialized preparation prompt exceeds ${MAX_PREPARATION_PROMPT_BYTES} bytes; select fewer or smaller context files, or prepare a smaller task; saved requirements were retained`);
+  const key = env[route.credentialEnv];
+  const endpointHost = new URL(route.endpoint).hostname;
+  const adapter = ADAPTERS[route.adapter];
+  const { headers, body } = adapter.request({ route, key, prompt });
+  // Bound the complete billed request: the serialized body covers the system
+  // message, the prompt and every framing field, and a fixed margin covers the
+  // provider's per-message protocol tokens that are not in the body at all.
+  const inputTokens = estimateTokens(JSON.stringify(body)) + MODEL_ROUTE_FRAMING_TOKENS;
+  if (inputTokens > route.budget.maxInputTokens) throw taskError("TASK_INPUT", `the intake prompt is about ${inputTokens} tokens; the model route input limit is ${route.budget.maxInputTokens} (ceiling ${MODEL_ROUTE_CEILINGS.maxInputTokens}); select fewer or smaller documents or prepare a smaller task; no model call was made`);
+  const reservedUsd = estimateUsd(route.budget, inputTokens, route.budget.maxOutputTokens);
+  // A reported cost replaces its pre-call reservation; an unknown cost keeps
+  // the reservation as the conservative bound.
+  const spent = calls.reduce((sum, a) => sum + (a.cost ?? a.reservedUsd ?? 0), 0);
+  const allowance = Math.min(route.budget.allowanceUsd, MODEL_ROUTE_CEILINGS.allowanceUsd, task.allowance?.budgetUsd ?? Infinity);
+  if (spent + reservedUsd > allowance) throw taskError("TASK_ALLOWANCE", `the next model call could cost up to ${usd(reservedUsd)} at the configured list prices (about ${inputTokens} input and up to ${route.budget.maxOutputTokens} output tokens); ${usd(spent)} of the ${usd(allowance)} model allowance is already spent or reserved, so the call was not started. Select less context, split the request, or raise intake_model.budget.allowance_usd up to ${usd(MODEL_ROUTE_CEILINGS.allowanceUsd)}. Estimates are not provider invoices.`);
+  const receipt = { version: 1, provider: MODEL_ROUTE_PROVIDER, account: "operator", boundary: MODEL_ROUTE_BOUNDARY, authority: "text-only", tools: [], adapter: route.adapter, model: route.model, taskId: `intake/${task.id}` };
+  attempt = { name: `model-${task.attempts.length + 1}`, route: "model", adapter: route.adapter, model: route.model, endpointHost, receipt, boundary: MODEL_ROUTE_BOUNDARY, reservedUsd,
+    estimate: { inputTokens, outputTokens: route.budget.maxOutputTokens, usd: reservedUsd, basis: "configured list prices; not a provider invoice" },
+    startedAt: clock.now(), deadline: clock.now() + timeoutMs, timeoutMs, settled: false, consumed: false, ok: null, cost: null, usage: null, spend: { status: "reserved", usd: reservedUsd, basis: "pre-call reservation at configured list prices" } };
+  task.attempts.push(attempt);
+  task.status = "preparing";
+  store.save(task); // Intent precedes the request; an unknown outcome never buys a second call.
+  const settle = (ok, patch) => { Object.assign(attempt, patch, { ok, settled: true, endedAt: clock.now() }); attempt.elapsedMs = Math.max(0, attempt.endedAt - attempt.startedAt); store.save(task); };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  // One deadline covers the request and the whole response body: a provider
+  // that answers headers and then stalls mid-stream is aborted like a connect
+  // timeout, so the preparation mutation and its task lock cannot hang.
+  const timedOut = error => error?.name === "AbortError" || controller.signal.aborted;
+  let response;
+  try {
+    response = await fetcher(route.endpoint, { method: "POST", headers, body: JSON.stringify(body), signal: controller.signal, redirect: "error" });
+  } catch (error) {
+    clearTimeout(timer);
+    settle(false, { errorCode: "TASK_MODEL_ROUTE", error: `model route request to ${endpointHost} failed: ${timedOut(error) ? `timed out after ${timeoutMs} ms` : redact(String(error?.message || error), [key])}; billing for this call is unknown and its reservation of ${usd(reservedUsd)} is retained`, spend: { status: "unknown", usd: null, reservedUsd, reason: "no provider usage was received" } });
+    throw failed(attempt);
+  }
+  if (!response?.ok) {
+    // The error body's cancellation runs under the same deadline, so a
+    // provider whose cancel() never settles cannot hold the task lock.
+    try { await cancelWithin(() => response?.body?.cancel?.(), controller.signal); } finally { clearTimeout(timer); }
+    settle(false, { errorCode: "TASK_MODEL_ROUTE", error: `model route HTTP ${response?.status ?? "unknown"} from ${endpointHost}; check intake_model.endpoint, intake_model.model and ${route.credentialEnv}; billing for this call is unknown and its reservation of ${usd(reservedUsd)} is retained`, spend: { status: "unknown", usd: null, reservedUsd, reason: `HTTP ${response?.status ?? "unknown"}` } });
+    throw failed(attempt);
+  }
+  let parsed;
+  try { parsed = adapter.parse(await boundedJson(response, controller.signal)); }
+  catch (error) {
+    // A body error keeps its own reason even when the deadline passed while its
+    // cancellation was being abandoned; only an aborted read is a timeout.
+    const reason = error?.name === "AbortError" ? `the response body did not complete within ${timeoutMs} ms` : error.message;
+    settle(false, { errorCode: "TASK_MODEL_ROUTE", error: `model route response from ${endpointHost} was unusable: ${reason}; billing for this call is unknown and its reservation of ${usd(reservedUsd)} is retained`, spend: { status: "unknown", usd: null, reservedUsd, reason } });
+    throw failed(attempt);
+  } finally { clearTimeout(timer); }
+  if (parsed.usageError) {
+    settle(false, { errorCode: "TASK_MODEL_ROUTE", error: `model route response from ${endpointHost} was unusable: ${parsed.usageError}; billing for this call is unknown and its reservation of ${usd(reservedUsd)} is retained`, spend: { status: "unknown", usd: null, reservedUsd, reason: parsed.usageError } });
+    throw failed(attempt);
+  }
+  const usage = parsed.usage;
+  const cost = usage ? estimateUsd(route.budget, usage.inputTokens, usage.outputTokens) : null;
+  const spend = usage ? { status: "reported", usd: cost, usage, basis: "provider-reported usage at configured list prices; not a provider invoice" } : { status: "unknown", usd: null, reservedUsd, reason: "the provider reported no usage; the pre-call reservation remains the spend bound" };
+  if (usage && usage.outputTokens > route.budget.maxOutputTokens) {
+    settle(false, { usage, cost, spend, errorCode: "TASK_MODEL_ROUTE", error: `the provider reported ${usage.outputTokens} output tokens, above the configured limit of ${route.budget.maxOutputTokens}; the draft was rejected` });
+    throw failed(attempt);
+  }
+  if (usage && usage.inputTokens > route.budget.maxInputTokens) {
+    settle(false, { usage, cost, spend, errorCode: "TASK_MODEL_ROUTE", error: `the provider reported ${usage.inputTokens} input tokens, above the configured limit of ${route.budget.maxInputTokens} despite the pre-call byte bound; the draft was rejected and the route needs operator review` });
+    throw failed(attempt);
+  }
+  if (typeof parsed.text !== "string" || !parsed.text.trim()) {
+    settle(false, { usage, cost, spend, errorCode: "TASK_MODEL_ROUTE", error: "the provider returned no text draft; the call is recorded and no implementation was started" });
+    throw failed(attempt);
+  }
+  if (parsed.truncated) {
+    settle(false, { usage, cost, spend, errorCode: "TASK_MODEL_ROUTE", error: `the draft stopped at the configured output limit of ${route.budget.maxOutputTokens} tokens and is incomplete; prepare a smaller intake or select fewer documents` });
+    throw failed(attempt);
+  }
+  // Valid reported usage replaces the pre-call reservation: the implementation
+  // allowance follows the reported spend, not the ceiling that was held while
+  // the call was in flight (that ceiling stays on `estimate` for the record).
+  settle(true, { usage, cost, ...(usage ? { spend: { ...spend, releasedReservationUsd: reservedUsd }, reservedUsd: null } : { spend }), finish: parsed.finish, message: redact(parsed.text, [key]), error: null });
+  return attempt.message;
+}

package/lib/task_prepare.mjs

@@ -7,15 +7,24 @@ import { taskRoot, taskError } from "./task_store.mjs";
 import { draftPrompt, MAX_TURNS, MAX_PREPARATION_PROMPT_BYTES } from "./task_contract.mjs";
 import { executionRunner } from "./execution.mjs";
 import { redact } from "./execution_io.mjs";
+import { isModelRouteReceipt } from "./task_model_route.mjs";
 
 export const PREPARATION_PENDING = Symbol("preparation-pending");
-// Only this pre-submit call site may issue this recovery marker. A transport
-// timeout after submit has uncertain ownership and must reconcile its saved run.
-export const preparationPreflightRetryable = task => task.errorCode === "EXECUTION_DEADLINE"
-  && task.preflightFailure?.attemptCount === task.attempts.length
-  && task.preflightFailure?.code === "EXECUTION_DEADLINE"
-  && task.attempts.every(attempt => attempt.settled && attempt.consumed)
-  && !task.dispatchIntent && !task.implementation;
+// Only known pre-submit deadline, availability or credential failures carry a recovery
+// marker. A timeout after submit has uncertain ownership and must reconcile.
+export const preparationPreflightRetryable = task => {
+  const marker = task.preflightFailure;
+  const marked = Boolean(marker && marker.code === task.errorCode && marker.attemptCount === task.attempts.length);
+  const model = task.route === "model" && task.errorCode === "TASK_MODEL_ROUTE"
+    && ((marked && marker.stage === "model-credential")
+      // Older pre-call failures have no marker. Successful, consumed receipts
+      // prove there is no provider outcome to replay or uncertain call to retry.
+      || (!marker && task.attempts.every(a => a.ok && isModelRouteReceipt(a.receipt, task))));
+  const implementation = marked && task.errorCode === "EXECUTION_UNAVAILABLE" && marker.stage === "implementation-availability";
+  return ((marked && task.errorCode === "EXECUTION_DEADLINE") || model || implementation)
+    && task.attempts.every(attempt => attempt.settled && attempt.consumed)
+    && !task.dispatchIntent && !task.implementation;
+};
 export const preparationCancellationPending = task => {
   const attempt = task.attempts.at(-1);
   return !!attempt && ((attempt.cancellation && !["confirmed", "terminal"].includes(attempt.cancellation.status)) ||
@@ -40,7 +49,11 @@ const failed = attempt => {
 };
 
 const boundaryFailure = () => taskError("TASK_PREPARATION_BOUNDARY", "saved preparation used an unverified tool boundary; its output cannot authorize readiness or dispatch; use a hand-authored PRD with ready/start until an isolated preparation adapter is supported");
-const safeAttempt = (task, attempt, capabilities, account) => isPreparationReceipt(task.harness, attempt.receipt ?? attempt.boundary, capabilities, account)
+// Model-route attempts carry their own text-only receipt; they never borrow a
+// harness boundary, and a harness attempt never qualifies through the route.
+const safeAttempt = (task, attempt, capabilities, account) => attempt.route === "model"
+  ? isModelRouteReceipt(attempt.receipt, task)
+  : isPreparationReceipt(task.harness, attempt.receipt ?? attempt.boundary, capabilities, account)
   && (!attempt.receipt?.taskId || attempt.receipt.taskId === `intake/${task.id}`);
 export function assertPreparationBoundary(task, ctx = {}) {
   const capabilities = ctx.capabilitiesFor?.(task.harness) || capabilitiesFor(task.harness);