@theokit/sdk 2.0.1 → 2.2.0

package/dist/cron.d.cts

@@ -1,2 +1,2 @@
-import './run-DrwUpFxZ.cjs';
-export { I as Cron } from './cron-DFG9-W17.cjs';
+import './run-ekGKZlmg.cjs';
+export { I as Cron } from './cron-JSPSFczQ.cjs';

package/dist/cron.d.ts

@@ -1,2 +1,2 @@
-import './run-DrwUpFxZ.js';
-export { I as Cron } from './cron-Bj8-Aq1O.js';
+import './run-ekGKZlmg.js';
+export { I as Cron } from './cron-Aksw2Hy4.js';

package/dist/cron.js

@@ -20,6 +20,24 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/internal/default-retriable.ts
+function defaultRetriableForCode(code) {
+  switch (code) {
+    case "rate_limit":
+    case "timeout":
+    case "server_error":
+    case "network":
+    case "provider_unreachable":
+      return true;
+    default:
+      return false;
+  }
+}
+var init_default_retriable = __esm({
+  "src/internal/default-retriable.ts"() {
+  }
+});
+
 // src/internal/security/redact.ts
 function readEnvOnce() {
   const raw = process.env.THEOKIT_REDACT_SECRETS;
@@ -170,7 +188,8 @@ __export(errors_exports, {
   UnsupportedBudgetOperationError: () => UnsupportedBudgetOperationError,
   UnsupportedRunOperationError: () => UnsupportedRunOperationError,
   UnsupportedTaskOperationError: () => UnsupportedTaskOperationError,
-  coerceToKnownAgentRunErrorCode: () => coerceToKnownAgentRunErrorCode
+  coerceToKnownAgentRunErrorCode: () => coerceToKnownAgentRunErrorCode,
+  isTransientError: () => isTransientError
 });
 function coerceToKnownAgentRunErrorCode(code) {
   if (code !== void 0 && KNOWN_AGENT_RUN_ERROR_CODES.has(code)) {
@@ -202,21 +221,13 @@ function safeStringify(value) {
     return String(value);
   }
 }
-function defaultRetriableForCode(code) {
-  switch (code) {
-    case "rate_limit":
-    case "timeout":
-    case "server_error":
-    case "network":
-    case "provider_unreachable":
-      return true;
-    default:
-      return false;
-  }
+function isTransientError(err) {
+  return err instanceof TheokitAgentError && err.isRetryable === true;
 }
 var KNOWN_AGENT_RUN_ERROR_CODES, TheokitAgentError, AuthenticationError, RateLimitError, ConfigurationError, IntegrationNotConnectedError, NetworkError, UnknownAgentError, AgentRunError, UnsupportedRunOperationError, CredentialPoolExhaustedError, MemoryAdapterError, InvalidTaskIdError, TaskNotFoundError, UnsupportedTaskOperationError, BudgetExceededError, AgentDisposedError, UnsupportedBudgetOperationError;
 var init_errors = __esm({
   "src/errors.ts"() {
+    init_default_retriable();
     init_redact();
     KNOWN_AGENT_RUN_ERROR_CODES = /* @__PURE__ */ new Set([
       "rate_limit",
@@ -815,6 +826,49 @@ var init_async_local_storage = __esm({
   }
 });
 
+// src/internal/runtime/concurrency/async-semaphore.ts
+function createSemaphore(permits) {
+  if (!Number.isInteger(permits) || permits < 1) {
+    throw new ConfigurationError(
+      `async-semaphore: permits must be a positive integer, got ${permits}`,
+      { code: "invalid_concurrency" }
+    );
+  }
+  let active = 0;
+  const queue = [];
+  function tryGrant() {
+    if (active < permits && queue.length > 0) {
+      const resolve3 = queue.shift();
+      if (resolve3 !== void 0) {
+        active += 1;
+        resolve3();
+      }
+    }
+  }
+  return {
+    inFlight: () => active,
+    pending: () => queue.length + active,
+    async acquire() {
+      await new Promise((resolve3) => {
+        queue.push(resolve3);
+        tryGrant();
+      });
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        active -= 1;
+        tryGrant();
+      };
+    }
+  };
+}
+var init_async_semaphore = __esm({
+  "src/internal/runtime/concurrency/async-semaphore.ts"() {
+    init_errors();
+  }
+});
+
 // src/internal/llm/credential-pool-types.ts
 var COOLDOWN_MS, DEFAULT_COOLDOWN_MS;
 var init_credential_pool_types = __esm({
@@ -1466,49 +1520,6 @@ var init_task = __esm({
   }
 });
 
-// src/internal/runtime/concurrency/async-semaphore.ts
-function createSemaphore(permits) {
-  if (!Number.isInteger(permits) || permits < 1) {
-    throw new ConfigurationError(
-      `async-semaphore: permits must be a positive integer, got ${permits}`,
-      { code: "invalid_concurrency" }
-    );
-  }
-  let active = 0;
-  const queue = [];
-  function tryGrant() {
-    if (active < permits && queue.length > 0) {
-      const resolve3 = queue.shift();
-      if (resolve3 !== void 0) {
-        active += 1;
-        resolve3();
-      }
-    }
-  }
-  return {
-    inFlight: () => active,
-    pending: () => queue.length + active,
-    async acquire() {
-      await new Promise((resolve3) => {
-        queue.push(resolve3);
-        tryGrant();
-      });
-      let released = false;
-      return () => {
-        if (released) return;
-        released = true;
-        active -= 1;
-        tryGrant();
-      };
-    }
-  };
-}
-var init_async_semaphore = __esm({
-  "src/internal/runtime/concurrency/async-semaphore.ts"() {
-    init_errors();
-  }
-});
-
 // src/internal/task/ring-buffer.ts
 var RingBuffer;
 var init_ring_buffer = __esm({
@@ -3084,6 +3095,19 @@ function sanitizeIdentifier(input, options) {
   }
   return input.toLowerCase();
 }
+function safeFilenameForId(id, options) {
+  if (id.length === 0) {
+    throw new ConfigurationError("Filename id must be a non-empty string", {
+      code: "invalid_filename_id"
+    });
+  }
+  const maxLen = options?.maxLen;
+  const lower = id.toLowerCase();
+  if (lower.length <= maxLen && IDENTIFIER_PATTERN.test(lower)) {
+    return lower;
+  }
+  return `h-${createHash("sha256").update(id).digest("hex").slice(0, 16)}`;
+}
 
 // src/internal/runtime/config/default-model.ts
 var DEFAULT_AGENTIC_MODEL_ID = "google/gemini-2.0-flash-001";
@@ -4293,8 +4317,7 @@ var FixtureRunBase = class {
     if (status === "error" && this.script.errorDetail !== void 0) {
       base.error = this.script.errorDetail;
     }
-    if (this.script.usage !== void 0) base.usage = this.script.usage;
-    if (this.script.cost !== void 0) base.cost = this.script.cost;
+    applyScriptMetrics(base, this.script);
     return this.extendRunResult(applyExtraRunFields(base, this.script));
   }
   /** Subclasses override to attach runtime-specific fields (e.g. cloud git info). */
@@ -4328,6 +4351,11 @@ function makeNotifier() {
   });
   return { promise, resolve: resolve3 };
 }
+function applyScriptMetrics(base, script) {
+  if (script.usage !== void 0) base.usage = script.usage;
+  if (script.cost !== void 0) base.cost = script.cost;
+  if (script.stoppedAtIterationLimit === true) base.stoppedAtIterationLimit = true;
+}
 
 // src/internal/runtime/cloud/cloud-run.ts
 function createCloudRun(options) {
@@ -5796,10 +5824,7 @@ function sessionsDir(cwd) {
   return join(memoryDir(cwd), "sessions");
 }
 function sessionSummaryPath(cwd, runId) {
-  return join(sessionsDir(cwd), `${sanitizeRunId(runId)}.md`);
-}
-function sanitizeRunId(runId) {
-  return runId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128);
+  return join(sessionsDir(cwd), `${safeFilenameForId(runId, { maxLen: 128 })}.md`);
 }
 function truncate(text) {
   if (text.length <= MAX_TURN_CHARS) return text;
@@ -7963,6 +7988,9 @@ var LocalRun = class extends FixtureRunBase {
   }
 };
 
+// src/internal/runtime/local-agent/real-local-run.ts
+init_errors();
+
 // src/internal/runtime/budget/budget.ts
 var IterationBudget = class {
   #remaining;
@@ -8416,6 +8444,27 @@ async function emitTextDeltaCallback(inputs, text) {
 // src/internal/agent-loop/tool-dispatch.ts
 init_async_local_storage();
 
+// src/internal/runtime/concurrency/map-with-concurrency.ts
+init_async_semaphore();
+var NEVER_ABORT = new AbortController().signal;
+async function mapWithConcurrency(items, concurrency, fn, options) {
+  const semaphore = createSemaphore(concurrency);
+  const signal = NEVER_ABORT;
+  return Promise.all(
+    items.map(async (item, index) => {
+      const release = await semaphore.acquire();
+      try {
+        if (signal.aborted) {
+          throw signal.reason instanceof Error ? signal.reason : new Error("mapWithConcurrency: aborted");
+        }
+        return await fn(item, index, signal);
+      } finally {
+        release();
+      }
+    })
+  );
+}
+
 // src/internal/tool-dispatch/repair-middleware.ts
 var DECIMAL_RE = /^-?\d+(\.\d+)?$/;
 function repairToolCall(raw, registry) {
@@ -8590,38 +8639,12 @@ ${result.stderr}`.trim();
 // src/internal/agent-loop/tool-dispatch.ts
 async function dispatchTools(inputs, tools, toolCalls, events) {
   const maxConcurrent = inputs.maxConcurrentTools ?? 4;
-  return boundedParallel(
-    maxConcurrent,
+  return mapWithConcurrency(
     toolCalls,
+    maxConcurrent,
     (call) => dispatchSingleCall(inputs, tools, call, events)
   );
 }
-async function boundedParallel(max, items, fn) {
-  let running = 0;
-  const queue = [];
-  async function acquire() {
-    if (running < max) {
-      running++;
-      return;
-    }
-    await new Promise((resolve3) => queue.push(resolve3));
-    running++;
-  }
-  function release() {
-    running--;
-    if (queue.length > 0) queue.shift()();
-  }
-  return Promise.all(
-    items.map(async (item) => {
-      await acquire();
-      try {
-        return await fn(item);
-      } finally {
-        release();
-      }
-    })
-  );
-}
 async function dispatchSingleCall(inputs, tools, call, events) {
   const { call: workingCall, repairs } = applyRepairAndExtractCall(tools, call);
   const callId = generateCallId();
@@ -9192,6 +9215,7 @@ async function runAgentLoop(inputs) {
     const ctx = await initLoopContext(inputs);
     ctxRef = ctx;
     const budget = inputs.budget ?? new IterationBudget({ maxIterations: inputs.maxIterations ?? 8 });
+    let lastTurnDecision;
     while (budget.shouldContinue()) {
       if (inputs.budgetTracker !== void 0) {
         const decision2 = evaluateBudgetGate(inputs.budgetTracker);
@@ -9200,18 +9224,26 @@ async function runAgentLoop(inputs) {
           if (decision2.detail !== void 0) {
             ctx.error = { message: decision2.detail, code: decision2.reason ?? "budget" };
           }
+          if (decision2.reason === "iteration_limit") {
+            ctx.stoppedAtIterationLimit = true;
+          }
           break;
         }
       }
       const usingGrace = budget.remaining <= 0 && !budget.graceCallUsed;
       if (usingGrace) budget.useGraceCall();
       const decision = await runIteration(inputs, ctx);
+      lastTurnDecision = decision;
       if (decision === "done") break;
       if (decision === "error") {
         ctx.finalStatus = "error";
         break;
       }
       budget.consume();
+      inputs.budgetTracker?.nextIteration?.();
+    }
+    if (lastTurnDecision === "continue" && budget.shouldContinue() === false) {
+      ctx.stoppedAtIterationLimit = true;
     }
     if (budget.shouldContinue() === false && ctx.finalStatus === "finished" && ctx.finalText === "") {
       ctx.finalStatus = "error";
@@ -9242,7 +9274,8 @@ async function runAgentLoop(inputs) {
       conversation: ctx.conversation,
       ...usage !== void 0 ? { usage } : {},
       ...cost !== void 0 ? { cost } : {},
-      ...ctx.error !== void 0 ? { error: ctx.error } : {}
+      ...ctx.error !== void 0 ? { error: ctx.error } : {},
+      ...ctx.stoppedAtIterationLimit === true ? { stoppedAtIterationLimit: true } : {}
     };
   } finally {
     if (ctxRef !== void 0 && ctxRef.memoryProviderHandle !== void 0 && inputs.memoryProvider !== void 0) {
@@ -11555,6 +11588,16 @@ function resolveMcpCwd(configCwd) {
   return safePathJoin(process.cwd(), configCwd);
 }
 
+// src/internal/providers/register-plugin-providers.ts
+function registerPluginProviderProfiles(entries) {
+  let registered4 = 0;
+  for (const entry of entries) {
+    registerProvider(entry.profile);
+    registered4 += 1;
+  }
+  return registered4;
+}
+
 // src/internal/tool-registry/personality-filter.ts
 init_hooks_source();
 function applyPersonalityFilter(exposedTools, whitelist, opts) {
@@ -11631,12 +11674,34 @@ function createRealLocalRun(options) {
   registerRun(handle);
   return handle;
 }
-function buildLoopInputs(options, runId, userText) {
+var pluginProvidersAnnounced = false;
+function resolveRunProvider(options) {
   registerBuiltins();
+  const profiles = options.pluginManager?.aggregated.providerProfiles ?? [];
+  const registered4 = registerPluginProviderProfiles(profiles);
+  if (registered4 > 0 && !pluginProvidersAnnounced) {
+    pluginProvidersAnnounced = true;
+    const names = profiles.map((e) => e.profile.name).join(", ");
+    process.stderr.write(
+      `[theokit-sdk] registered ${registered4} plugin provider profile(s): ${names}
+`
+    );
+  }
   const parsedModel = parseModelId(options.model?.id);
   const inferredProvider = parsedModel.provider !== void 0 && getProviderProfile(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
   const primary = options.agentOptions.providers?.routes?.[0]?.provider ?? inferredProvider ?? detectPrimaryProvider();
   const effectiveModelId = inferredProvider !== void 0 ? parsedModel.name : options.model?.id ?? "claude-sonnet-4-6";
+  return { primary, effectiveModelId };
+}
+function buildLoopInputs(options, runId, userText) {
+  const maxIterations = options.sendOptions.maxIterations;
+  if (maxIterations !== void 0 && (!Number.isInteger(maxIterations) || maxIterations < 1)) {
+    throw new ConfigurationError(
+      `SendOptions.maxIterations must be a positive integer, got ${maxIterations}`,
+      { code: "invalid_max_iterations" }
+    );
+  }
+  const { primary, effectiveModelId } = resolveRunProvider(options);
   const fallback = options.agentOptions.providers?.fallback;
   const apiKeys = options.agentOptions.providers?.apiKeys;
   const credentialPoolStrategy = options.agentOptions.providers?.credentialPoolStrategy;
@@ -11674,6 +11739,9 @@ function buildLoopInputs(options, runId, userText) {
     // D318 — forward SendOptions.signal to the agent loop so streamLlmTurn
     // can attach it to the LLM `fetch({ signal })` call.
     ...options.sendOptions.signal !== void 0 ? { signal: options.sendOptions.signal } : {},
+    // M1-2: per-send iteration ceiling (validated above). The loop reads
+    // inputs.maxIterations (default 8 when unset).
+    ...maxIterations !== void 0 ? { maxIterations } : {},
     // D315-D317 — tool lifecycle hooks (cost tracking + audit + retry/alert)
     ...options.agentOptions.onToolStart !== void 0 ? { onToolStart: options.agentOptions.onToolStart } : {},
     ...options.agentOptions.onToolEnd !== void 0 ? { onToolEnd: options.agentOptions.onToolEnd } : {},
@@ -11805,6 +11873,7 @@ var RealLocalRun = class extends FixtureRunBase {
     if (output.result.length > 0) this.script.result = output.result;
     if (output.usage !== void 0) this.script.usage = output.usage;
     if (output.cost !== void 0) this.script.cost = output.cost;
+    if (output.stoppedAtIterationLimit === true) this.script.stoppedAtIterationLimit = true;
     if (output.error !== void 0 && this.script.errorDetail === void 0) {
       this.script.errorDetail = {
         message: output.error.message,
@@ -12254,7 +12323,7 @@ async function embedTexts(input) {
       pending
     });
   }
-  await runBatches(input, pending, results);
+  await embedInBoundedBatches(input, pending, results);
   return results.map((v) => v ?? new Array(dimension).fill(0));
 }
 function classifyEntry(args) {
@@ -12273,45 +12342,34 @@ function classifyEntry(args) {
   args.pending.push({ index: args.index, text: args.text, key });
 }
 var MAX_CONCURRENT_BATCHES = 3;
-async function runBatches(input, pending, results) {
+async function embedInBoundedBatches(input, pending, results) {
   const batches = [];
   for (let offset = 0; offset < pending.length; offset += MAX_BATCH) {
     batches.push(pending.slice(offset, offset + MAX_BATCH));
   }
-  let running = 0;
-  const queue = [];
-  await Promise.all(batches.map((batch) => processBatch(input, batch, results, acquire, release)));
-  async function acquire() {
-    if (running >= MAX_CONCURRENT_BATCHES) await new Promise((r) => queue.push(r));
-    running++;
-  }
-  function release() {
-    running--;
-    if (queue.length > 0) queue.shift()();
-  }
+  await mapWithConcurrency(
+    batches,
+    MAX_CONCURRENT_BATCHES,
+    (batch) => processBatch(input, batch, results)
+  );
 }
-async function processBatch(input, batch, results, acquire, release) {
-  await acquire();
-  try {
-    const vectors = await embedBatch({
-      apiKey: input.apiKey,
-      baseUrl: input.baseUrl,
-      embeddingsPath: input.embeddingsPath,
-      model: input.model,
-      inputs: batch.map((b) => b.text),
-      fetchImpl: input.fetchImpl,
-      stats: input.stats,
-      providerId: input.providerId
-    });
-    for (let j = 0; j < batch.length; j++) {
-      const slot = batch[j];
-      const vector = vectors[j];
-      if (slot === void 0 || vector === void 0) continue;
-      results[slot.index] = vector;
-      input.cache.set(slot.key, vector);
-    }
-  } finally {
-    release();
+async function processBatch(input, batch, results) {
+  const vectors = await embedBatch({
+    apiKey: input.apiKey,
+    baseUrl: input.baseUrl,
+    embeddingsPath: input.embeddingsPath,
+    model: input.model,
+    inputs: batch.map((b) => b.text),
+    fetchImpl: input.fetchImpl,
+    stats: input.stats,
+    providerId: input.providerId
+  });
+  for (let j = 0; j < batch.length; j++) {
+    const slot = batch[j];
+    const vector = vectors[j];
+    if (slot === void 0 || vector === void 0) continue;
+    results[slot.index] = vector;
+    input.cache.set(slot.key, vector);
   }
 }
 async function embedBatch(opts) {
@@ -12744,7 +12802,7 @@ function sanitizeFts5Query(query) {
   return text.trim();
 }
 
-// src/internal/memory/index-db.ts
+// src/internal/persistence/sqlite-open.ts
 init_errors();
 
 // src/internal/persistence/sqlite-wal.ts
@@ -12772,6 +12830,57 @@ function logFallback(label, reason) {
   );
 }
 
+// src/internal/persistence/sqlite-open.ts
+async function openSqliteResilient(options) {
+  await mkdir(dirname(options.filePath), { recursive: true });
+  try {
+    return await openConcrete(options);
+  } catch (cause) {
+    if (options.recoverCorrupt !== false && isCorruptionError(cause)) {
+      await renameAside(options.filePath, options.label ?? "sqlite");
+      return await openConcrete(options);
+    }
+    throw cause;
+  }
+}
+async function openConcrete(options) {
+  const db = await loadDriver(options.filePath);
+  applyWalWithFallback(db, options.label ?? "sqlite");
+  await options.onOpen?.(db);
+  return db;
+}
+async function loadDriver(filePath) {
+  try {
+    const mod = await import('better-sqlite3');
+    const Ctor = mod.default ?? mod;
+    if (typeof Ctor !== "function") {
+      throw new Error(`better-sqlite3 export is not a constructor (got ${typeof Ctor})`);
+    }
+    return new Ctor(filePath);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new ConfigurationError(
+      `Failed to load SQLite driver. Install \`better-sqlite3\` or run on Node 22.5+ for built-in \`node:sqlite\`. Cause: ${message}`,
+      { code: "sqlite_driver_unavailable", cause }
+    );
+  }
+}
+function isCorruptionError(cause) {
+  if (!(cause instanceof Error)) return false;
+  const msg = cause.message.toLowerCase();
+  return msg.includes("malformed") || msg.includes("not a database") || msg.includes("encrypted") || msg.includes("disk image is malformed");
+}
+async function renameAside(filePath, label) {
+  const asidePath = `${filePath}.corrupt-${Date.now()}`;
+  await rename(filePath, asidePath).catch(() => void 0);
+  await rename(`${filePath}-wal`, `${asidePath}-wal`).catch(() => void 0);
+  await rename(`${filePath}-shm`, `${asidePath}-shm`).catch(() => void 0);
+  process.stderr.write(
+    `[theokit-sdk] ${label} database corrupt; renamed aside to ${asidePath} and rebuilt schema
+`
+  );
+}
+
 // src/internal/memory/index-schema.ts
 var SCHEMA_STATEMENTS = [
   `CREATE TABLE IF NOT EXISTS files (
@@ -12815,52 +12924,15 @@ var PRAGMA_STATEMENTS = [
 
 // src/internal/memory/index-db.ts
 async function openMemoryDb(opts) {
-  await mkdir(dirname(opts.filePath), { recursive: true });
-  try {
-    return await openConcrete(opts.filePath);
-  } catch (cause) {
-    if (opts.recoverCorrupt !== false && isCorruptionError(cause)) {
-      await renameAside(opts.filePath);
-      return await openConcrete(opts.filePath);
+  return openSqliteResilient({
+    filePath: opts.filePath,
+    label: "memory-index",
+    recoverCorrupt: opts.recoverCorrupt,
+    onOpen: (db) => {
+      for (const pragma of PRAGMA_STATEMENTS) db.exec(pragma);
+      for (const stmt of SCHEMA_STATEMENTS) db.exec(stmt);
     }
-    throw cause;
-  }
-}
-async function openConcrete(filePath) {
-  const db = await loadDriver(filePath);
-  applyWalWithFallback(db, "memory-index");
-  for (const pragma of PRAGMA_STATEMENTS) db.exec(pragma);
-  for (const stmt of SCHEMA_STATEMENTS) db.exec(stmt);
-  return db;
-}
-async function loadDriver(filePath) {
-  try {
-    const mod = await import('better-sqlite3');
-    const Ctor = mod.default ?? mod;
-    const db = new Ctor(filePath);
-    return db;
-  } catch (cause) {
-    const message = cause instanceof Error ? cause.message : String(cause);
-    throw new ConfigurationError(
-      `Failed to load SQLite driver. Install \`better-sqlite3\` or run on Node 22.5+ for built-in \`node:sqlite\`. Cause: ${message}`,
-      { code: "sqlite_driver_unavailable", cause }
-    );
-  }
-}
-function isCorruptionError(cause) {
-  if (!(cause instanceof Error)) return false;
-  const msg = cause.message.toLowerCase();
-  return msg.includes("malformed") || msg.includes("not a database") || msg.includes("encrypted") || msg.includes("disk image is malformed");
-}
-async function renameAside(filePath) {
-  const asidePath = `${filePath}.corrupt-${Date.now()}`;
-  await rename(filePath, asidePath).catch(() => void 0);
-  await rename(`${filePath}-wal`, `${asidePath}-wal`).catch(() => void 0);
-  await rename(`${filePath}-shm`, `${asidePath}-shm`).catch(() => void 0);
-  process.stderr.write(
-    `[theokit-sdk] memory index corrupt; renamed aside to ${asidePath} and rebuilt schema
-`
-  );
+  });
 }
 function defaultIndexPath(cwd) {
   return join(cwd, ".theokit", "memory", ".index", "memory.sqlite");