@odla-ai/ai 0.2.1 → 0.3.0

package/dist/index.js

@@ -1,29 +1,410 @@
 import {
   AuthError,
+  CancelledError,
   CapabilityError,
   ConfigError,
   ContextWindowError,
+  DeadlineExceededError,
   InvalidRequestError,
   OdlaAIError,
   ProviderError,
   RateLimitError,
+  ToolInputError,
   addUsage,
-  blocksOf,
   emptyUsage,
-  extractText,
-  extractToolUses,
-  isAudioBlock,
-  isDocumentBlock,
-  isImageBlock,
-  isTextBlock,
-  isThinkingBlock,
-  isToolResultBlock,
-  isToolUseBlock,
-  normalizeError
-} from "./chunk-LANGYP65.js";
+  normalizeError,
+  signalWithDeadline,
+  throwIfAborted
+} from "./chunk-PXXCN2EU.js";
+
+// src/shape/helpers.ts
+function isTextBlock(b) {
+  return b.type === "text";
+}
+function isImageBlock(b) {
+  return b.type === "image";
+}
+function isAudioBlock(b) {
+  return b.type === "audio";
+}
+function isDocumentBlock(b) {
+  return b.type === "document";
+}
+function isToolUseBlock(b) {
+  return b.type === "tool_use";
+}
+function isToolResultBlock(b) {
+  return b.type === "tool_result";
+}
+function isThinkingBlock(b) {
+  return b.type === "thinking";
+}
+function blocksOf(content) {
+  return typeof content === "string" ? [{ type: "text", text: content }] : content;
+}
+function extractText(content) {
+  return content.filter(isTextBlock).map((b) => b.text).join("");
+}
+function extractToolUses(content) {
+  return content.filter(isToolUseBlock);
+}
+
+// src/shape/json-schema-shape.ts
+var ANNOTATION_KEYS = /* @__PURE__ */ new Set([
+  "$schema",
+  "$id",
+  "$anchor",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "format"
+]);
+var SUPPORTED_KEYS = /* @__PURE__ */ new Set([
+  ...ANNOTATION_KEYS,
+  "$ref",
+  "$defs",
+  "definitions",
+  "type",
+  "enum",
+  "const",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "not",
+  "properties",
+  "required",
+  "additionalProperties",
+  "minProperties",
+  "maxProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf"
+]);
+var ALLOWED_TYPES = /* @__PURE__ */ new Set([
+  "null",
+  "boolean",
+  "object",
+  "array",
+  "number",
+  "integer",
+  "string"
+]);
+function validateSchemaShape(schema, path, root, issues) {
+  if (typeof schema === "boolean") return;
+  if (!isRecord(schema)) {
+    issue(issues, path, "schema must be an object or boolean");
+    return;
+  }
+  for (const key of Object.keys(schema)) {
+    if (!SUPPORTED_KEYS.has(key)) issue(issues, path, `schema uses unsupported keyword "${key}"`);
+  }
+  if (typeof schema.$ref === "string" && resolveLocalRef(root, schema.$ref) === void 0) {
+    issue(issues, path, `schema reference "${schema.$ref}" could not be resolved`);
+  } else if (schema.$ref !== void 0 && typeof schema.$ref !== "string") {
+    issue(issues, path, "schema $ref must be a string");
+  }
+  const types = typeof schema.type === "string" ? [schema.type] : Array.isArray(schema.type) ? schema.type : [];
+  if (schema.type !== void 0 && (types.length === 0 || !types.every((type) => typeof type === "string" && ALLOWED_TYPES.has(type)))) {
+    issue(issues, path, "schema type contains an unsupported JSON type");
+  }
+  if (schema.enum !== void 0 && !Array.isArray(schema.enum)) {
+    issue(issues, path, "schema enum must be an array");
+  }
+  if (schema.required !== void 0 && (!Array.isArray(schema.required) || !schema.required.every((key) => typeof key === "string"))) {
+    issue(issues, path, "schema required must be a string array");
+  }
+  validateConstraintShapes(schema, path, issues);
+  validateChildSchemas(schema, path, root, issues);
+}
+function validateChildSchemas(schema, path, root, issues) {
+  for (const key of ["properties", "$defs", "definitions"]) {
+    const group = schema[key];
+    if (group === void 0) continue;
+    if (!isRecord(group)) {
+      issue(issues, path, `schema ${key} must be an object`);
+      continue;
+    }
+    for (const [name, child] of Object.entries(group)) {
+      validateSchemaShape(child, `${path}.${key}.${name}`, root, issues);
+    }
+  }
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    const group = schema[key];
+    if (group === void 0) continue;
+    if (!Array.isArray(group) || group.length === 0) {
+      issue(issues, path, `schema ${key} must be a non-empty array`);
+      continue;
+    }
+    group.forEach((child, index2) => validateSchemaShape(child, `${path}.${key}[${index2}]`, root, issues));
+  }
+  for (const key of ["items", "not", "additionalProperties"]) {
+    const child = schema[key];
+    if (child !== void 0) validateSchemaShape(child, `${path}.${key}`, root, issues);
+  }
+}
+function validateConstraintShapes(schema, path, issues) {
+  for (const key of ["minLength", "maxLength", "minItems", "maxItems", "minProperties", "maxProperties"]) {
+    const value = schema[key];
+    if (value !== void 0 && (!Number.isInteger(value) || value < 0)) {
+      issue(issues, path, `schema ${key} must be a non-negative integer`);
+    }
+  }
+  for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"]) {
+    const value = schema[key];
+    if (value !== void 0 && !isFiniteNumber(value)) {
+      issue(issues, path, `schema ${key} must be a finite number`);
+    }
+  }
+  if (schema.multipleOf !== void 0 && (!isFiniteNumber(schema.multipleOf) || schema.multipleOf <= 0)) {
+    issue(issues, path, "schema multipleOf must be a finite number greater than zero");
+  }
+  if (schema.uniqueItems !== void 0 && typeof schema.uniqueItems !== "boolean") {
+    issue(issues, path, "schema uniqueItems must be a boolean");
+  }
+  validatePatternShape(schema.pattern, path, issues);
+}
+function validatePatternShape(value, path, issues) {
+  if (value === void 0) return;
+  if (typeof value !== "string") {
+    issue(issues, path, "schema pattern must be a string");
+    return;
+  }
+  try {
+    new RegExp(value, "u");
+  } catch {
+    issue(issues, path, `schema pattern "${value}" is invalid`);
+  }
+}
+function resolveLocalRef(root, ref) {
+  if (ref === "#") return root;
+  if (!ref.startsWith("#/")) return void 0;
+  let current = root;
+  for (const raw of ref.slice(2).split("/")) {
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (!isRecord(current) || !Object.hasOwn(current, key)) return void 0;
+    current = current[key];
+  }
+  return current;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function issue(issues, path, message) {
+  issues.push({ path, message });
+}
+
+// src/shape/json-schema.ts
+function validateJsonSchema(schema, value) {
+  const issues = [];
+  validateSchemaShape(schema, "$", schema, issues);
+  if (issues.length > 0) return { valid: false, issues };
+  visit(schema, value, "$", schema, issues, /* @__PURE__ */ new Set());
+  return { valid: issues.length === 0, issues };
+}
+function visit(schema, value, path, root, issues, refs) {
+  if (schema === true) return;
+  if (schema === false) {
+    issue2(issues, path, "is rejected by the schema");
+    return;
+  }
+  if (!isRecord2(schema)) {
+    issue2(issues, path, "schema must be an object or boolean");
+    return;
+  }
+  for (const key of Object.keys(schema)) {
+    if (!SUPPORTED_KEYS.has(key)) {
+      issue2(issues, path, `schema uses unsupported keyword "${key}"`);
+      return;
+    }
+  }
+  if (typeof schema.$ref === "string") {
+    const target = resolveLocalRef2(root, schema.$ref);
+    if (target === void 0) {
+      issue2(issues, path, `schema reference "${schema.$ref}" could not be resolved`);
+      return;
+    }
+    if (refs.has(schema.$ref)) {
+      issue2(issues, path, `cyclic schema reference "${schema.$ref}" is unsupported`);
+      return;
+    }
+    const nextRefs = new Set(refs);
+    nextRefs.add(schema.$ref);
+    visit(target, value, path, root, issues, nextRefs);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => jsonEqual(candidate, value))) {
+    issue2(issues, path, "must equal one of the allowed enum values");
+  }
+  if (Object.hasOwn(schema, "const") && !jsonEqual(schema.const, value)) {
+    issue2(issues, path, "must equal the constant value");
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const child of schema.allOf) visit(child, value, path, root, issues, refs);
+  }
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some((child) => matches(child, value, root, refs))) {
+    issue2(issues, path, "must match at least one anyOf schema");
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matchesCount = schema.oneOf.filter((child) => matches(child, value, root, refs)).length;
+    if (matchesCount !== 1) issue2(issues, path, "must match exactly one oneOf schema");
+  }
+  if (schema.not !== void 0 && matches(schema.not, value, root, refs)) {
+    issue2(issues, path, "must not match the forbidden schema");
+  }
+  const types = typeof schema.type === "string" ? [schema.type] : Array.isArray(schema.type) && schema.type.every((t) => typeof t === "string") ? schema.type : void 0;
+  if (schema.type !== void 0 && !types) {
+    issue2(issues, path, "schema type must be a string or string array");
+    return;
+  }
+  if (types && !types.some((type) => isType(value, type))) {
+    issue2(issues, path, `must be ${types.join(" or ")}`);
+    return;
+  }
+  if (typeof value === "string") validateString(schema, value, path, issues);
+  if (typeof value === "number") validateNumber(schema, value, path, issues);
+  if (Array.isArray(value)) validateArray(schema, value, path, root, issues, refs);
+  if (isRecord2(value)) validateObject(schema, value, path, root, issues, refs);
+}
+function validateString(schema, value, path, issues) {
+  if (isFiniteNumber2(schema.minLength) && [...value].length < schema.minLength) issue2(issues, path, `must have at least ${schema.minLength} characters`);
+  if (isFiniteNumber2(schema.maxLength) && [...value].length > schema.maxLength) issue2(issues, path, `must have at most ${schema.maxLength} characters`);
+  if (typeof schema.pattern === "string") {
+    try {
+      if (!new RegExp(schema.pattern, "u").test(value)) issue2(issues, path, `must match pattern ${schema.pattern}`);
+    } catch {
+      issue2(issues, path, `schema pattern "${schema.pattern}" is invalid`);
+    }
+  }
+}
+function validateNumber(schema, value, path, issues) {
+  if (!Number.isFinite(value)) {
+    issue2(issues, path, "must be a finite number");
+    return;
+  }
+  if (isFiniteNumber2(schema.minimum) && value < schema.minimum) issue2(issues, path, `must be >= ${schema.minimum}`);
+  if (isFiniteNumber2(schema.maximum) && value > schema.maximum) issue2(issues, path, `must be <= ${schema.maximum}`);
+  if (isFiniteNumber2(schema.exclusiveMinimum) && value <= schema.exclusiveMinimum) issue2(issues, path, `must be > ${schema.exclusiveMinimum}`);
+  if (isFiniteNumber2(schema.exclusiveMaximum) && value >= schema.exclusiveMaximum) issue2(issues, path, `must be < ${schema.exclusiveMaximum}`);
+  if (isFiniteNumber2(schema.multipleOf) && schema.multipleOf > 0) {
+    const quotient = value / schema.multipleOf;
+    if (Math.abs(quotient - Math.round(quotient)) > Number.EPSILON * Math.max(1, Math.abs(quotient))) {
+      issue2(issues, path, `must be a multiple of ${schema.multipleOf}`);
+    }
+  }
+}
+function validateArray(schema, value, path, root, issues, refs) {
+  if (isFiniteNumber2(schema.minItems) && value.length < schema.minItems) issue2(issues, path, `must contain at least ${schema.minItems} items`);
+  if (isFiniteNumber2(schema.maxItems) && value.length > schema.maxItems) issue2(issues, path, `must contain at most ${schema.maxItems} items`);
+  if (schema.uniqueItems === true) {
+    for (let i = 0; i < value.length; i++) {
+      if (value.slice(0, i).some((other) => jsonEqual(other, value[i]))) {
+        issue2(issues, `${path}[${i}]`, "must be unique");
+        break;
+      }
+    }
+  }
+  if (schema.items !== void 0) {
+    for (let i = 0; i < value.length; i++) visit(schema.items, value[i], `${path}[${i}]`, root, issues, refs);
+  }
+}
+function validateObject(schema, value, path, root, issues, refs) {
+  const keys = Object.keys(value);
+  if (isFiniteNumber2(schema.minProperties) && keys.length < schema.minProperties) issue2(issues, path, `must contain at least ${schema.minProperties} properties`);
+  if (isFiniteNumber2(schema.maxProperties) && keys.length > schema.maxProperties) issue2(issues, path, `must contain at most ${schema.maxProperties} properties`);
+  if (schema.required !== void 0 && (!Array.isArray(schema.required) || !schema.required.every((key) => typeof key === "string"))) {
+    issue2(issues, path, "schema required must be a string array");
+    return;
+  }
+  for (const key of schema.required ?? []) {
+    if (!Object.hasOwn(value, key)) issue2(issues, childPath(path, key), "is required");
+  }
+  const properties = isRecord2(schema.properties) ? schema.properties : {};
+  for (const [key, child] of Object.entries(properties)) {
+    if (Object.hasOwn(value, key)) visit(child, value[key], childPath(path, key), root, issues, refs);
+  }
+  const extras = keys.filter((key) => !Object.hasOwn(properties, key));
+  if (schema.additionalProperties === false) {
+    for (const key of extras) issue2(issues, childPath(path, key), "is not an allowed property");
+  } else if (schema.additionalProperties !== void 0 && schema.additionalProperties !== true) {
+    for (const key of extras) visit(schema.additionalProperties, value[key], childPath(path, key), root, issues, refs);
+  }
+}
+function matches(schema, value, root, refs) {
+  const nested = [];
+  visit(schema, value, "$", root, nested, refs);
+  return nested.length === 0;
+}
+function resolveLocalRef2(root, ref) {
+  if (ref === "#") return root;
+  if (!ref.startsWith("#/")) return void 0;
+  let current = root;
+  for (const raw of ref.slice(2).split("/")) {
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (!isRecord2(current) || !Object.hasOwn(current, key)) return void 0;
+    current = current[key];
+  }
+  return current;
+}
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isType(value, type) {
+  switch (type) {
+    case "null":
+      return value === null;
+    case "boolean":
+      return typeof value === "boolean";
+    case "object":
+      return isRecord2(value);
+    case "array":
+      return Array.isArray(value);
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "string":
+      return typeof value === "string";
+    default:
+      return false;
+  }
+}
+function isFiniteNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function jsonEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => jsonEqual(v, b[i]));
+  if (isRecord2(a) && isRecord2(b)) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    return aKeys.length === bKeys.length && aKeys.every((key) => Object.hasOwn(b, key) && jsonEqual(a[key], b[key]));
+  }
+  return false;
+}
+function childPath(path, key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function issue2(issues, path, message) {
+  issues.push({ path, message });
+}
 
 // src/shape/capabilities.ts
-function chatCapabilities(overrides = {}) {
+function chatCapabilities(overrides2 = {}) {
   return {
     kind: "chat",
     textIn: true,
@@ -36,7 +417,7 @@ function chatCapabilities(overrides = {}) {
     streaming: true,
     structuredOutput: true,
     webSearch: false,
-    ...overrides
+    ...overrides2
   };
 }
 function validateRequest(spec, req) {
@@ -125,6 +506,15 @@ var OPENAI_MODELS = [
     capabilities: chatCapabilities({ effort: true }),
     contextWindow: 4e5
   },
+  {
+    // Compact GPT-5.4 reasoning model (effort knob), same 400K context as the
+    // rest of the GPT-5 line. The default for odla-o11y AI triage.
+    id: "gpt-5.4-mini",
+    provider: "openai",
+    nativeId: "gpt-5.4-mini",
+    capabilities: chatCapabilities({ effort: true }),
+    contextWindow: 4e5
+  },
   {
     id: "gpt-5",
     provider: "openai",
@@ -242,37 +632,60 @@ function providersInCatalog(catalog) {
 }
 
 // src/providers/registry.ts
+var CLIENT_TTL_MS = 6e4;
 var cache = /* @__PURE__ */ new Map();
+var inflight = /* @__PURE__ */ new Map();
+var overrides = /* @__PURE__ */ new Map();
 async function getProvider(id, apiKey) {
-  const cacheKey = `${id}:${apiKey}`;
-  const existing = cache.get(cacheKey);
-  if (existing) return existing;
+  const override = overrides.get(id);
+  if (override?.apiKey === apiKey) return override.provider;
+  const fingerprint = await fingerprintKey(apiKey);
+  const existing = cache.get(id);
+  if (existing?.fingerprint === fingerprint && existing.expiresAt > Date.now()) return existing.provider;
+  if (existing) cache.delete(id);
+  const pending = inflight.get(id);
+  if (pending?.fingerprint === fingerprint) return pending.promise;
+  const promise = createProvider(id, apiKey).then((provider) => {
+    cache.set(id, { fingerprint, provider, expiresAt: Date.now() + CLIENT_TTL_MS });
+    return provider;
+  }).finally(() => {
+    if (inflight.get(id)?.promise === promise) inflight.delete(id);
+  });
+  inflight.set(id, { fingerprint, promise });
+  return promise;
+}
+async function createProvider(id, apiKey) {
   let provider;
   switch (id) {
     case "anthropic": {
-      const { AnthropicProvider } = await import("./anthropic-JXDXR7O7.js");
+      const { AnthropicProvider } = await import("./anthropic-2NPMHJZT.js");
       provider = new AnthropicProvider(apiKey);
       break;
     }
     case "openai": {
-      const { OpenAIProvider } = await import("./openai-XZRXMKCC.js");
+      const { OpenAIProvider } = await import("./openai-NTQCF577.js");
       provider = new OpenAIProvider(apiKey);
       break;
     }
     case "google": {
-      const { GoogleProvider } = await import("./google-3TFOFIQO.js");
+      const { GoogleProvider } = await import("./google-3XV2VWVB.js");
       provider = new GoogleProvider(apiKey);
       break;
     }
   }
-  cache.set(cacheKey, provider);
   return provider;
 }
+async function fingerprintKey(apiKey) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(apiKey));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 function registerProvider(id, apiKey, provider) {
-  cache.set(`${id}:${apiKey}`, provider);
+  overrides.set(id, { apiKey, provider });
 }
 function clearProviderCache() {
   cache.clear();
+  inflight.clear();
+  overrides.clear();
 }
 
 // src/client/keys.ts
@@ -342,7 +755,9 @@ function init(opts = {}) {
       messages: [{ role: "user", content: c.user }],
       tools: [{ name: c.tool.name, description: c.tool.description ?? "", inputSchema: c.tool.parameters }],
       toolChoice: { type: "tool", name: c.tool.name },
-      maxTokens: c.maxTokens ?? 4096
+      maxTokens: c.maxTokens ?? 4096,
+      signal: c.signal,
+      deadline: c.deadline
     };
     const { spec, provider } = await resolveProviderFor(model);
     validateRequest(spec, req);
@@ -351,6 +766,11 @@ function init(opts = {}) {
     if (!block || block.type !== "tool_use") {
       throw new ProviderError(`Model "${model}" did not return the forced tool call "${c.tool.name}".`);
     }
+    const validation = validateJsonSchema(c.tool.parameters, block.input);
+    if (!validation.valid) {
+      const detail = validation.issues.slice(0, 5).map((i) => `${i.path} ${i.message}`).join("; ");
+      throw new ToolInputError(`Tool "${c.tool.name}" returned invalid input: ${detail}`, { tool: c.tool.name });
+    }
     return { value: block.input, usage: res.usage };
   };
   const search = async (c) => {
@@ -360,7 +780,9 @@ function init(opts = {}) {
       system: c.system,
       messages: [{ role: "user", content: c.user }],
       webSearch: true,
-      maxTokens: c.maxTokens ?? 8192
+      maxTokens: c.maxTokens ?? 8192,
+      signal: c.signal,
+      deadline: c.deadline
     };
     const { spec, provider } = await resolveProviderFor(model);
     validateRequest(spec, req);
@@ -386,16 +808,20 @@ function generateLlmsTxt(catalog = DEFAULT_CATALOG) {
   const models = Object.values(catalog).map((s) => `- \`${s.id}\` (${s.provider}) \u2014 ${capsSummary(s.capabilities)}`).join("\n");
   return `# @odla-ai/ai \u2014 LLM context
 
+> EARLY ACCESS \u2014 pre-1.0. Agents work from bounded runbooks; humans approve
+> credentials, production changes, releases, and merges. APIs and exact package
+> availability can change. Review documented guarantees and limitations; this
+> software is MIT-licensed and provided without warranty.
+
 One general-purpose interface for AI inference across Anthropic (Claude), OpenAI
 (GPT), and Google (Gemini) \u2014 text, image, and audio \u2014 plus a tool-use agent
 engine and an eval harness. Library-only: import in-process, bring your own keys.
-Isomorphic (Node 20+, Cloudflare Workers, browser). Provider SDKs are lazy-loaded.
+Targets Node 20+ and Cloudflare Workers. Provider adapters are runtime-lazy, but
+all provider SDKs are package dependencies. Never expose long-lived keys in a browser.
 
 ## Install
 
     npm i @odla-ai/ai
-    # provider SDKs are peer-lazy-loaded; install those you use:
-    #   @anthropic-ai/sdk  openai  @google/genai
     # optional, for odla-db-backed storage + secrets:
     #   @odla-ai/db
 
@@ -409,7 +835,8 @@ Isomorphic (Node 20+, Cloudflare Workers, browser). Provider SDKs are lazy-loade
 - \`ai.stream(input)\` \u2192 async iterable of normalized events: message_start \u2192
   content_block_start \u2192 content_block_delta {text_delta|thinking_delta|input_json_delta}
   \u2192 content_block_stop \u2192 message_delta \u2192 message_stop (plus \`error\`).
-- \`ai.extract<T>({ model, user, tool })\` \u2192 forced tool call; returns a parsed object.
+- \`ai.extract<T>({ model, user, tool })\` \u2192 forced tool call; returns an object
+  validated against the declared JSON Schema. Unsupported assertions fail closed.
 - \`ai.search({ model, user })\` \u2192 web-search-grounded prose.
 
 ## Content blocks (multimodal)
@@ -428,7 +855,15 @@ audio block to a Claude model throws CapabilityError before any network call.
     // run.finalText, run.toolCalls, run.usage, run.steps, run.stoppedReason
 
 Tools may carry taint labels (outputTaint / acceptsTaint) for a CaMeL-style
-prompt-injection gate. Personas may carry a MemoryScope.
+prompt-injection gate. Personas may carry a MemoryScope. Tool inputs are schema-
+validated before handlers run. Pass signal/deadline and a run budget
+({maxInputTokens,maxOutputTokens,maxTotalTokens,maxToolCalls}) to bound follow-up
+effects and requested output. Input and total limits are post-turn ceilings:
+provider usage is unavailable before the first response, so they cannot
+tokenizer-bound the first prompt. Output and remaining-total limits cap the next
+request's maxTokens. Token limits must be positive integers; maxToolCalls may be
+zero. Budget exits pair every requested tool_use with an error tool_result before
+memory is persisted.
 
 ## Skills
 
@@ -455,14 +890,17 @@ device-authorization handshake for a scoped, revocable token, then provisions.
     import { requestToken, init as odlaInit } from "@odla-ai/db";
     import { provisionAgentApp, odlaDbKeyResolver, OdlaDbMemory, persistRun, init } from "@odla-ai/ai";
 
-    // 1. Handshake: the human supplies the endpoint and approves a short code in odla-db Studio.
-    const { token } = await requestToken({ endpoint: ODLA_URL, onCode: ({ userCode }) => show(userCode) });
+    const ODLA_PLATFORM = "https://odla.ai";
+    const ODLA_DB_URL = "https://db.odla.ai";
+
+    // 1. Handshake: the human approves a short code at odla.ai.
+    const { token } = await requestToken({ endpoint: ODLA_PLATFORM, onCode: ({ userCode }) => show(userCode) });
 
     // 2. Provision: create app, mint app key, push agent schema, store BYO provider keys as secrets.
-    const { appId, appKey } = await provisionAgentApp({ endpoint: ODLA_URL, token, providerKeys: { openai: OPENAI_KEY } });
+    const { appId, appKey } = await provisionAgentApp({ endpoint: ODLA_PLATFORM, token, providerKeys: { openai: OPENAI_KEY } });
 
     // 3. Runtime: read keys from odla-db secrets; persist memory + run traces.
-    const db = odlaInit({ appId, adminToken: appKey, endpoint: ODLA_URL });
+    const db = odlaInit({ appId, adminToken: appKey, endpoint: ODLA_DB_URL });
     const ai = init({ resolveKey: odlaDbKeyResolver(db) });
     const persona = { name: "assistant", model: "gpt-5", memory: new OdlaDbMemory({ db, sessionId: "user-42" }) };
     const run = await runAgent(ai, persona, { input: "hello" });
@@ -488,16 +926,22 @@ env's odla-db tenant secrets, write-only for operators). One call reads both:
       platform: "https://odla.ai", appId: APP_ID, env: "prod", db });
     // ai.chat / ai.stream / ai.extract \u2014 provider/model from public-config
     // (cached ~60s, so Studio changes apply without redeploys); the key is
-    // fetched from the vault at call time via odlaDbKeyResolver.
+    // fetched from the vault via a finite-TTL odlaDbKeyResolver.
 
 The only secret the Worker carries is its odla-db app key. Rotating the LLM
-key = writing the secret again; switching provider/model = a Studio edit.
+key = writing the secret again; the default warm-isolate key TTL is 60 seconds
+and cacheVersion provides immediate invalidation. Provider SDK clients are
+fingerprinted, bounded to one generation per provider, and expire after 60
+seconds. The platform provider is enforced: models from other providers are
+absent from the facade catalog. If no default model is configured, each call
+must name a model for that provider. Only public config is shared; tenant-bound
+Ai facades are not cached globally.
 
 ## Errors
 
 Every error is an OdlaAIError subclass with a stable \`code\` \u2014 branch on err.code:
 config, auth, rate_limit, capability_unsupported, context_window, invalid_request,
-tool_input_invalid, provider_error.
+tool_input_invalid, cancelled, deadline_exceeded, provider_error.
 
 ## Models
 
@@ -547,6 +991,7 @@ function assertSinkAcceptsTaint(sink, allowed, actual) {
 
 // src/agent/loop.ts
 async function runAgent(inference, persona, input) {
+  validateRunLimits(persona.maxSteps, input.budget);
   const { system, tools } = composeSkills(persona.system, persona.tools, persona.skills);
   const handlerByName = /* @__PURE__ */ new Map();
   for (const t of tools) if (t.handler) handlerByName.set(t.name, t);
@@ -558,21 +1003,26 @@ async function runAgent(inference, persona, input) {
   const toolCalls = [];
   const accumulatedTaint = /* @__PURE__ */ new Set(["llm_inherited"]);
   const maxSteps = persona.maxSteps ?? 8;
+  const runSignal = signalWithDeadline(input.signal, input.deadline);
   let response;
   let stoppedReason = "max_steps";
   let steps = 0;
+  let attemptedToolCalls = 0;
   while (steps < maxSteps) {
     steps++;
+    const remainingOutput = remainingOutputTokens(usage, input.budget);
     response = await inference.chat({
       model: persona.model,
       system,
       messages,
       tools: tools.length > 0 ? tools.map(toOracleTool) : void 0,
-      maxTokens: persona.maxTokens ?? 4096,
+      maxTokens: Math.min(persona.maxTokens ?? 4096, remainingOutput ?? Number.POSITIVE_INFINITY),
       effort: persona.effort,
       thinking: persona.thinking,
       temperature: persona.temperature,
-      webSearch: persona.webSearch
+      webSearch: persona.webSearch,
+      signal: runSignal,
+      deadline: input.deadline
     });
     addUsage(usage, response.usage);
     messages.push({ role: "assistant", content: response.content });
@@ -585,8 +1035,22 @@ async function runAgent(inference, persona, input) {
       stoppedReason = "end_turn";
       break;
     }
+    if (budgetExceeded(usage, input.budget)) {
+      stoppedReason = "budget_exhausted";
+      messages.push({
+        role: "user",
+        content: toolUses.map((toolUse) => errorResult(toolUse.id, "Run budget exhausted before tool execution."))
+      });
+      break;
+    }
     const resultBlocks = [];
     for (const toolUse of toolUses) {
+      if (input.budget?.maxToolCalls !== void 0 && attemptedToolCalls >= input.budget.maxToolCalls) {
+        stoppedReason = "budget_exhausted";
+        resultBlocks.push(errorResult(toolUse.id, "Run tool-call budget exhausted before execution."));
+        continue;
+      }
+      attemptedToolCalls++;
       const def = handlerByName.get(toolUse.name);
       if (!def || !def.handler) {
         resultBlocks.push(errorResult(toolUse.id, `No local handler for tool "${toolUse.name}".`));
@@ -594,16 +1058,26 @@ async function runAgent(inference, persona, input) {
       }
       if (def.acceptsTaint) assertSinkAcceptsTaint(def.name, def.acceptsTaint, accumulatedTaint);
       let output;
-      try {
-        output = await def.handler(toolUse.input, { taint: new Set(accumulatedTaint), signal: input.signal });
-      } catch (err) {
-        output = { content: `Tool "${toolUse.name}" threw: ${err.message}`, isError: true };
+      const validation = validateJsonSchema(def.inputSchema, toolUse.input);
+      if (!validation.valid) {
+        const detail = validation.issues.slice(0, 5).map((i) => `${i.path} ${i.message}`).join("; ");
+        output = { content: `Tool "${toolUse.name}" input is invalid: ${detail}`, isError: true };
+      } else {
+        throwIfAborted(runSignal);
+        try {
+          output = await def.handler(toolUse.input, { taint: new Set(accumulatedTaint), signal: runSignal });
+        } catch (error) {
+          if (error instanceof CancelledError || error instanceof DeadlineExceededError) throw error;
+          throwIfAborted(runSignal);
+          output = { content: `Tool "${toolUse.name}" failed.`, isError: true };
+        }
       }
       toolCalls.push({ toolUse, output });
       resultBlocks.push({ type: "tool_result", toolUseId: toolUse.id, content: output.content, isError: output.isError });
       for (const label of def.outputTaint ?? []) accumulatedTaint.add(label);
     }
     messages.push({ role: "user", content: resultBlocks });
+    if (stoppedReason === "budget_exhausted") break;
   }
   if (!response) throw new Error("runAgent: maxSteps must be at least 1");
   if (persona.memory) await persona.memory.append(messages.slice(runStartIndex));
@@ -617,6 +1091,36 @@ async function runAgent(inference, persona, input) {
     stoppedReason
   };
 }
+function budgetExceeded(usage, budget) {
+  if (!budget) return false;
+  if (budget.maxInputTokens !== void 0 && usage.inputTokens >= budget.maxInputTokens) return true;
+  if (budget.maxOutputTokens !== void 0 && usage.outputTokens >= budget.maxOutputTokens) return true;
+  if (budget.maxTotalTokens !== void 0 && usage.inputTokens + usage.outputTokens >= budget.maxTotalTokens) return true;
+  return false;
+}
+function remainingOutputTokens(usage, budget) {
+  if (!budget) return void 0;
+  const remaining = [
+    budget.maxOutputTokens === void 0 ? void 0 : budget.maxOutputTokens - usage.outputTokens,
+    budget.maxTotalTokens === void 0 ? void 0 : budget.maxTotalTokens - usage.inputTokens - usage.outputTokens
+  ].filter((value) => value !== void 0);
+  return remaining.length === 0 ? void 0 : Math.max(1, Math.min(...remaining));
+}
+function validateRunLimits(maxSteps, budget) {
+  if (maxSteps !== void 0 && (!Number.isInteger(maxSteps) || maxSteps < 1)) {
+    throw new ConfigError("persona.maxSteps must be a positive integer.");
+  }
+  if (!budget) return;
+  for (const key of ["maxInputTokens", "maxOutputTokens", "maxTotalTokens"]) {
+    const value = budget[key];
+    if (value !== void 0 && (!Number.isInteger(value) || value < 1)) {
+      throw new ConfigError(`budget.${key} must be a positive integer.`);
+    }
+  }
+  if (budget.maxToolCalls !== void 0 && (!Number.isInteger(budget.maxToolCalls) || budget.maxToolCalls < 0)) {
+    throw new ConfigError("budget.maxToolCalls must be a non-negative integer.");
+  }
+}
 function errorResult(toolUseId, message) {
   return { type: "tool_result", toolUseId, content: message, isError: true };
 }
@@ -919,22 +1423,32 @@ var DEFAULT_SECRET_NAMES = {
 };
 function odlaDbKeyResolver(db, opts = {}) {
   const nameFor = opts.secretName ?? ((p) => DEFAULT_SECRET_NAMES[p]);
-  const useCache = opts.cache ?? true;
+  const ttlMs = opts.cache === false ? 0 : Math.max(0, opts.ttlMs ?? 6e4);
   const cache3 = /* @__PURE__ */ new Map();
   return async (provider) => {
-    if (useCache) {
+    const version = typeof opts.cacheVersion === "function" ? opts.cacheVersion(provider) : opts.cacheVersion ?? "";
+    if (ttlMs > 0) {
       const hit = cache3.get(provider);
-      if (hit !== void 0) return hit;
+      if (hit?.version === version && hit.expiresAt > Date.now()) return hit.value;
+      cache3.delete(provider);
     }
     try {
       const key = await db.secrets.get(nameFor(provider));
-      if (useCache) cache3.set(provider, key);
+      if (ttlMs > 0) cache3.set(provider, { version, value: key, expiresAt: Date.now() + ttlMs });
       return key;
-    } catch {
-      return void 0;
+    } catch (error) {
+      if (isMissingSecret(error)) return void 0;
+      throw error;
     }
   };
 }
+function isMissingSecret(error) {
+  if (!error || typeof error !== "object") return false;
+  const rec = error;
+  if (rec.status === 404 || rec.statusCode === 404 || rec.code === "not_found") return true;
+  const message = error instanceof Error ? error.message : "";
+  return /\b404\b/.test(message);
+}
 
 // src/store/platform.ts
 var cache2 = /* @__PURE__ */ new Map();
@@ -965,19 +1479,22 @@ async function initFromPlatform(opts) {
   const key = `${opts.platform}|${opts.appId}|${opts.env}`;
   const now = Date.now();
   const hit = ttl > 0 ? cache2.get(key) : void 0;
-  if (hit && hit.expiresAt > now) return hit.value;
-  const { provider, model } = await fetchAiConfig(opts);
-  if (hit && hit.value.provider === provider && hit.value.model === model) {
-    hit.expiresAt = now + ttl;
-    return hit.value;
-  }
+  const config = hit && hit.expiresAt > now ? hit.value : await fetchAiConfig(opts);
+  const { provider, model } = config;
+  if (ttl > 0 && (!hit || hit.expiresAt <= now)) cache2.set(key, { value: config, expiresAt: now + ttl });
+  const sourceCatalog = opts.initOptions?.catalog ?? DEFAULT_CATALOG;
+  const catalog = Object.fromEntries(
+    Object.entries(sourceCatalog).filter(([, spec]) => spec.provider === provider)
+  );
+  const defaultModel = model ?? opts.initOptions?.defaultModel;
+  if (defaultModel) resolveModel(catalog, defaultModel);
   const ai = init({
     ...opts.initOptions,
-    resolveKey: odlaDbKeyResolver(opts.db),
-    defaultModel: model ?? opts.initOptions?.defaultModel
+    catalog,
+    resolveKey: odlaDbKeyResolver(opts.db, opts.keyResolverOptions),
+    defaultModel
   });
   const value = { ai, provider, ...model ? { model } : {} };
-  if (ttl > 0) cache2.set(key, { value, expiresAt: now + ttl });
   return value;
 }
 
@@ -1170,11 +1687,13 @@ export {
   AGENT_SCHEMA,
   ANTHROPIC_MODELS,
   AuthError,
+  CancelledError,
   CapabilityError,
   ConfigError,
   ContextWindowError,
   DEFAULT_CATALOG,
   DEFAULT_SECRET_NAMES,
+  DeadlineExceededError,
   GOOGLE_MODELS,
   InMemoryScope,
   InvalidRequestError,
@@ -1185,6 +1704,7 @@ export {
   ProviderError,
   RateLimitError,
   TaintError,
+  ToolInputError,
   addUsage,
   assertSinkAcceptsTaint,
   blocksOf,
@@ -1230,6 +1750,7 @@ export {
   structuredMatch,
   taint,
   toOracleTool,
+  validateJsonSchema,
   validateRequest
 };
 //# sourceMappingURL=index.js.map