theokit 0.47.0 → 0.48.0

package/dist/server/index.js

@@ -61,7 +61,7 @@ import {
   resolveTransformer,
   superjsonTransformer,
   validateRouteInput
-} from "../chunk-U3H53IIN.js";
+} from "../chunk-FO55VGMQ.js";
 import {
   ActionError,
   ActionInputError,
@@ -88,7 +88,7 @@ import {
   runMiddlewareAndContext,
   sendError,
   sendJson
-} from "../chunk-37ZO643S.js";
+} from "../chunk-XALU5LCU.js";
 import {
   DuplicateContextKeyError,
   createOutbox,
@@ -176,7 +176,7 @@ import {
   TheoError,
   fromUnknown,
   serverErrorToEnvelope
-} from "../chunk-7SABX4DJ.js";
+} from "../chunk-IZ3TIL6K.js";
 import {
   CodeModePermissionDeniedError,
   InProcessApprovalRequiredError,
@@ -191,13 +191,20 @@ import {
   parseChannelPath,
   serveMcpStdio,
   streamAgentTurnInProcess
-} from "../chunk-FZG3JYB3.js";
+} from "../chunk-7ZOQN7UH.js";
 import {
   buildResourceDescriptors,
   defineAppResource,
   extractAppResources,
   readAppResource
 } from "../chunk-YOIVCCZT.js";
+import {
+  listProviders,
+  registerProvider,
+  resetProviderRegistry,
+  resolveProvider,
+  tryResolveProvider
+} from "../chunk-6E5WKMDS.js";
 import {
   AuthRequiredError,
   _resetKeyCacheForTests,
@@ -239,9 +246,10 @@ import {
 } from "../chunk-JA2ZAT5Q.js";
 import {
   InMemoryUsageStorage,
+  InMemoryUsageStorage2,
   trackAgentRun,
   trackAgentTools
-} from "../chunk-SEELKQUM.js";
+} from "../chunk-Y2KHTD2W.js";
 import {
   CRON_MANIFEST_SCHEMA_VERSION,
   DuplicateCronNameError,
@@ -788,8 +796,8 @@ function createCacheEngine(opts) {
   function claimAndRun(key, fn, options, skipWrite) {
     let resolveOuter;
     let rejectOuter;
-    const outerPromise = new Promise((resolve2, reject) => {
-      resolveOuter = resolve2;
+    const outerPromise = new Promise((resolve3, reject) => {
+      resolveOuter = resolve3;
       rejectOuter = reject;
     });
     void outerPromise.catch(() => {
@@ -1178,6 +1186,458 @@ var CTX_WRITERS = {
   jobsQueue: "jobBackend"
 };
 
+// src/config/layered-config.ts
+import { foldLayers, verifyLayerOrdering } from "@theokit/agents";
+var LayerOutOfOrderError = class extends Error {
+  name = "LayerOutOfOrderError";
+};
+var LayeredConfig = {
+  /**
+   * Fold the chain, validate the result, and report where everything came from.
+   *
+   * The schema is applied AFTER folding, never per layer. Validating each layer separately would
+   * force every file to be complete, which defeats layering: a project override that sets one key
+   * would have to restate the whole config.
+   *
+   * @throws {LayerOutOfOrderError} when a layer does not outrank the one before it.
+   */
+  resolve(input) {
+    assertOrdering(input.layers);
+    const accumulating = input.accumulatingKeys ?? [];
+    const folded = foldLayers(input.layers, accumulating);
+    const value = input.schema.parse(folded);
+    return {
+      value,
+      provenancePerKey: buildProvenance(input.layers, accumulating),
+      precedenceReport: buildReport(input.layers)
+    };
+  }
+};
+function assertOrdering(layers) {
+  try {
+    verifyLayerOrdering(layers);
+  } catch (error) {
+    throw new LayerOutOfOrderError(error.message);
+  }
+}
+function contributorsOf(layers, key) {
+  return layers.filter((layer) => key in layer.values).map((layer) => layer.layer);
+}
+function buildProvenance(layers, accumulating) {
+  const keys = new Set(layers.flatMap((layer) => Object.keys(layer.values)));
+  const provenance = {};
+  for (const key of keys) {
+    const contributors = contributorsOf(layers, key);
+    const winner = contributors.at(-1);
+    if (winner === void 0) continue;
+    provenance[key] = accumulating.includes(key) ? contributors.join(", ") : winner;
+  }
+  return provenance;
+}
+function buildReport(layers) {
+  const declared = layers.map((layer) => layer.layer);
+  const contributed = new Set(
+    layers.filter((layer) => Object.keys(layer.values).length > 0).map((layer) => layer.layer)
+  );
+  const measured = declared.filter((name) => contributed.has(name));
+  const declaredButSilent = declared.filter((name) => !contributed.has(name));
+  return {
+    declared,
+    measured,
+    declaredButSilent,
+    diverges: declaredButSilent.length > 0
+  };
+}
+
+// src/config/trust-store.ts
+import { chmodSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { dirname } from "path";
+import { resolveTrustPosture } from "@theokit/agents";
+import { atomicWriteJson, withFileLock } from "@theokit/agents/persistence";
+var TrustStorePermissionsError = class extends Error {
+  constructor(file, mode) {
+    super(
+      `trust store ${file} is mode ${mode.toString(8)} \u2014 group or world writable. This file decides which directories may run shell hooks, so a writable store is a way to grant that to yourself. Refused rather than repaired: tightening it silently would hide that something changed the mode. Fix with \`chmod 600 ${file}\`.`
+    );
+    this.file = file;
+    this.mode = mode;
+  }
+  file;
+  mode;
+  name = "TrustStorePermissionsError";
+};
+var FORBIDDEN_WRITE_BITS = 18;
+var TrustStore = class {
+  constructor(file) {
+    this.file = file;
+  }
+  file;
+  /**
+   * Read the store, refusing a file other users can write.
+   *
+   * A missing store is not an error — it is a machine that has trusted nothing yet, which is the
+   * correct starting state and the safe one.
+   */
+  read() {
+    if (!existsSync2(this.file)) return [];
+    this.assertSafePermissions();
+    const parsed = JSON.parse(readFileSync2(this.file, "utf8"));
+    return parsed.records;
+  }
+  /**
+   * Record a decision about `path`, replacing any previous one for it.
+   *
+   * `decidedAt` and `decidedBy` are ARGUMENTS, not derived here (DIP): the clock and the identity
+   * belong to the caller, and baking `new Date()` in would make every assertion about the record
+   * depend on when the test ran.
+   *
+   * ASYNC because both `withFileLock` and `atomicWriteJson` are. Measured, not assumed: the first
+   * draft called them synchronously and `trust()` returned before the bytes landed, so an immediate
+   * `read()` saw an empty store. Same shape as the M71 pointer bug, and same cause — the SDK's
+   * `.d.ts` does not declare these, so nothing at compile time says they return a Promise
+   * (usetheodev/theokit-sdk#280).
+   */
+  async trust(record) {
+    mkdirSync(dirname(this.file), { recursive: true });
+    await withFileLock(
+      this.file,
+      async () => {
+        const existing = existsSync2(this.file) ? this.read() : [];
+        const records = [...existing.filter((r) => r.path !== record.path), record];
+        await atomicWriteJson(this.file, {
+          version: 1,
+          records
+        });
+        chmodSync(this.file, 384);
+      }
+    );
+  }
+  /**
+   * The recorded posture for `path`, or an UNTRUSTED posture when nothing was recorded.
+   *
+   * Absence resolves to untrusted, never to "unknown, proceed". A store that answered "I do not
+   * know" would push the decision back to the caller, and the caller asking is what the store
+   * exists to answer.
+   */
+  postureFor(path, capabilities) {
+    const record = this.read().find((r) => r.path === path);
+    return resolveTrustPosture({
+      capabilities: [...capabilities],
+      isTrusted: () => record?.trusted === true
+    });
+  }
+  assertSafePermissions() {
+    const mode = statSync2(this.file).mode & 511;
+    if ((mode & FORBIDDEN_WRITE_BITS) !== 0) {
+      throw new TrustStorePermissionsError(this.file, mode);
+    }
+  }
+};
+
+// src/config/custom-commands.ts
+import { readFileSync as readFileSync3, readdirSync, statSync as statSync3 } from "fs";
+import { basename, extname, join } from "path";
+
+// src/config/frontmatter.ts
+var FENCE = "---";
+function splitFrontmatter(raw) {
+  const lines = raw.split("\n");
+  if (lines[0]?.trim() !== FENCE) return { frontmatter: [], body: raw };
+  const closing = lines.indexOf(FENCE, 1);
+  if (closing === -1) return void 0;
+  return { frontmatter: lines.slice(1, closing), body: lines.slice(closing + 1).join("\n") };
+}
+function frontmatterValue(frontmatter, key) {
+  const prefix = `${key}:`;
+  for (const line of frontmatter) {
+    if (!line.startsWith(prefix)) continue;
+    const value = line.slice(prefix.length).trim();
+    const unquoted = /^(["'])(.*)\1$/.exec(value);
+    return unquoted?.[2] ?? value;
+  }
+  return void 0;
+}
+
+// src/config/custom-commands.ts
+var COMMANDS_DIR = join(".theokit", "commands");
+var IGNORE_WARNING = () => void 0;
+function loadCustomCommands(input) {
+  const warn = input.onWarn ?? IGNORE_WARNING;
+  const loaded = /* @__PURE__ */ new Map();
+  if (input.homeDir !== void 0) {
+    for (const command of readCommandsDir(join(input.homeDir, COMMANDS_DIR), "user", warn)) {
+      loaded.set(command.name, command);
+    }
+  }
+  if (input.projectDir !== void 0) {
+    if (!input.projectTrusted) {
+      const pending = readCommandsDir(
+        join(input.projectDir, COMMANDS_DIR),
+        "project",
+        IGNORE_WARNING
+      );
+      if (pending.length > 0) {
+        warn(
+          `${String(pending.length)} project command(s) found but the directory is not trusted \u2014 none were loaded. A command is a prompt that runs on your behalf.`
+        );
+      }
+    } else {
+      for (const command of readCommandsDir(
+        join(input.projectDir, COMMANDS_DIR),
+        "project",
+        warn
+      )) {
+        const shadowed = loaded.get(command.name);
+        if (shadowed !== void 0) {
+          warn(
+            `project command "${command.name}" overrides the user-level one at ${shadowed.path}.`
+          );
+        }
+        loaded.set(command.name, command);
+      }
+    }
+  }
+  const builtins = new Set(input.builtinNames ?? []);
+  const shadowedBuiltins = [...loaded.keys()].filter((name) => builtins.has(name));
+  for (const name of shadowedBuiltins) {
+    warn(
+      `custom command "${name}" has the same name as a builtin. This loader does not choose between them \u2014 the router decides, because only it knows what its builtins do.`
+    );
+  }
+  return {
+    // Project first in the returned order, matching the precedence a reader would expect.
+    commands: [...loaded.values()].sort(byProjectThenName),
+    shadowedBuiltins
+  };
+}
+function byProjectThenName(a, b) {
+  if (a.source !== b.source) return a.source === "project" ? -1 : 1;
+  return a.name.localeCompare(b.name);
+}
+function readCommandsDir(dir, source, warn) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  entries.sort((a, b) => a.localeCompare(b));
+  const commands = [];
+  for (const entry of entries) {
+    if (extname(entry) !== ".md") continue;
+    const path = join(dir, entry);
+    try {
+      if (!statSync3(path).isFile()) continue;
+    } catch {
+      continue;
+    }
+    const command = parseCommandFile(path, entry, source, warn);
+    if (command !== void 0) commands.push(command);
+  }
+  return commands;
+}
+function parseCommandFile(path, entry, source, warn) {
+  let raw;
+  try {
+    raw = readFileSync3(path, "utf8");
+  } catch {
+    return void 0;
+  }
+  const parsed = splitFrontmatter(raw);
+  if (parsed === void 0) {
+    warn(`command frontmatter never closes, file skipped: ${path}`);
+    return void 0;
+  }
+  const description = frontmatterValue(parsed.frontmatter, "description");
+  return {
+    name: basename(entry, ".md"),
+    ...description !== void 0 && { description },
+    body: parsed.body,
+    source,
+    path
+  };
+}
+
+// src/config/instruction-tree.ts
+import { readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync4 } from "fs";
+import { join as join2, relative, resolve as resolve2 } from "path";
+import { assertNoSymlinkEscape } from "@theokit/agents";
+var DEFAULT_FILE_NAMES = ["THEO.md", "AGENTS.md"];
+var IGNORE_WARNING2 = () => void 0;
+function loadInstructionTree(input) {
+  const warn = input.onWarn ?? IGNORE_WARNING2;
+  const fileNames = input.fileNames ?? DEFAULT_FILE_NAMES;
+  const cwd = resolve2(input.cwd);
+  const blocks = [];
+  const seenInodes = /* @__PURE__ */ new Set();
+  let chars = 0;
+  const visit = (dir, depth) => {
+    if (depth > input.budget.maxDepth) return false;
+    let entries;
+    try {
+      entries = readdirSync2(dir);
+    } catch {
+      return false;
+    }
+    for (const { entry, path, stats } of filesBeforeDirectories(dir, entries)) {
+      const inode = `${String(stats.dev)}:${String(stats.ino)}`;
+      if (seenInodes.has(inode)) continue;
+      seenInodes.add(inode);
+      if (stats.isDirectory()) {
+        if (visit(path, depth + 1)) return true;
+        continue;
+      }
+      if (!fileNames.includes(entry)) continue;
+      try {
+        ;
+        assertNoSymlinkEscape(path, cwd);
+      } catch {
+        warn(`instruction file escapes the project root and was skipped: ${relative(cwd, path)}`);
+        continue;
+      }
+      if (blocks.length >= input.budget.maxFiles) {
+        warn(`instruction budget: stopped at ${String(input.budget.maxFiles)} files`);
+        return true;
+      }
+      const parsed = parseInstructionFile(path, cwd, warn);
+      if (parsed === void 0) continue;
+      if (chars + parsed.content.length > input.budget.maxChars) {
+        warn(`instruction budget: stopped at ${String(input.budget.maxChars)} characters`);
+        return true;
+      }
+      chars += parsed.content.length;
+      blocks.push(parsed);
+    }
+    return false;
+  };
+  let truncated = false;
+  for (const root of input.roots) {
+    truncated = visit(resolve2(cwd, root), 0);
+    if (truncated) break;
+  }
+  return { blocks, truncated, count: blocks.length };
+}
+function filesBeforeDirectories(dir, entries) {
+  const found = [];
+  for (const entry of [...entries].sort((a, b) => a.localeCompare(b))) {
+    const path = join2(dir, entry);
+    try {
+      found.push({ entry, path, stats: statSync4(path) });
+    } catch {
+      continue;
+    }
+  }
+  return [
+    ...found.filter((item) => !item.stats.isDirectory()),
+    ...found.filter((item) => item.stats.isDirectory())
+  ];
+}
+function parseInstructionFile(path, cwd, warn) {
+  let raw;
+  try {
+    raw = readFileSync4(path, "utf8");
+  } catch {
+    return void 0;
+  }
+  const rel = relative(cwd, path);
+  const parsed = splitFrontmatter(raw);
+  if (parsed === void 0) {
+    warn(`instruction frontmatter never closes, file skipped: ${rel}`);
+    return void 0;
+  }
+  return {
+    path: rel,
+    content: parsed.body,
+    scopes: parsePathsScope(parsed.frontmatter)
+  };
+}
+function parsePathsScope(frontmatter) {
+  const scopes = [];
+  let inPaths = false;
+  for (const line of frontmatter) {
+    if (/^paths\s*:/.test(line)) {
+      inPaths = true;
+      const inline = line.slice(line.indexOf(":") + 1).trim();
+      if (inline.startsWith("[")) {
+        return inline.slice(1, inline.lastIndexOf("]")).split(",").map((item2) => item2.trim().replaceAll(/^["']|["']$/g, "")).filter((item2) => item2.length > 0);
+      }
+      continue;
+    }
+    if (!inPaths) continue;
+    const item = /^ {0,32}- {0,32}(\S.*)$/.exec(line);
+    if (item?.[1] === void 0) break;
+    scopes.push(item[1].trim().replaceAll(/^["']|["']$/g, ""));
+  }
+  return scopes;
+}
+
+// src/config/compose-instructions.ts
+var DEFAULT_SEPARATOR = "\n\n";
+var IGNORE_WARNING3 = () => void 0;
+function composeInstructions(base, sources, options) {
+  const warn = options.onWarn ?? IGNORE_WARNING3;
+  const separator = options.separator ?? DEFAULT_SEPARATOR;
+  if (base.length >= options.maxChars) {
+    warn(
+      `instruction budget: the base prompt alone is ${String(base.length)} characters against a ceiling of ${String(options.maxChars)}. It was truncated and every source was dropped.`
+    );
+    return {
+      text: base.slice(0, options.maxChars),
+      dropped: sources.map((source) => source.name),
+      trimmed: "base"
+    };
+  }
+  const kept = [...sources];
+  const dropped = [];
+  let trimmed;
+  const lengthOf = (list) => [base, ...list.map((source) => source.content)].join(separator).length;
+  while (kept.length > 0 && lengthOf(kept) > options.maxChars) {
+    const last = kept.at(-1);
+    if (last === void 0) break;
+    const withoutLast = kept.slice(0, -1);
+    const room = options.maxChars - lengthOf(withoutLast) - separator.length;
+    if (room > 0 && trimmed === void 0) {
+      kept[kept.length - 1] = { ...last, content: last.content.slice(0, room) };
+      trimmed = last.name;
+      warn(
+        `instruction budget: "${last.name}" was trimmed to ${String(room)} characters to fit the ${String(options.maxChars)}-character ceiling.`
+      );
+      break;
+    }
+    kept.pop();
+    dropped.push(last.name);
+    warn(`instruction budget: "${last.name}" was dropped to fit the ceiling.`);
+  }
+  return {
+    text: [base, ...kept.map((source) => source.content)].join(separator),
+    dropped,
+    ...trimmed !== void 0 && { trimmed }
+  };
+}
+
+// src/config/context-pressure.ts
+import { resolveEffectiveContextWindow } from "@theokit/agents";
+var DEFAULT_CONTEXT_PRESSURE_THRESHOLDS = {
+  warn: 0.75,
+  critical: 0.9
+};
+var ContextPressureThresholdError = class extends Error {
+  name = "ContextPressureThresholdError";
+};
+function contextPressure(usedTokens, effectiveWindow, thresholds = DEFAULT_CONTEXT_PRESSURE_THRESHOLDS) {
+  if (thresholds.warn >= thresholds.critical) {
+    throw new ContextPressureThresholdError(
+      `context pressure: \`warn\` (${String(thresholds.warn)}) must be below \`critical\` (${String(thresholds.critical)}), otherwise one of the two levels can never be reached.`
+    );
+  }
+  if (!Number.isFinite(effectiveWindow) || effectiveWindow <= 0) return "ok";
+  if (!Number.isFinite(usedTokens) || usedTokens <= 0) return "ok";
+  const ratio = usedTokens / effectiveWindow;
+  if (ratio >= thresholds.critical) return "critical";
+  if (ratio >= thresholds.warn) return "warn";
+  return "ok";
+}
+
 // src/server/index.ts
 if (typeof globalThis !== "undefined") {
   const WARN_KEY = "__theokit_server_umbrella_warn_emitted__";
@@ -1212,7 +1672,9 @@ export {
   ChannelManager,
   CodeModePermissionDeniedError,
   ConsoleObservabilityAdapter,
+  ContextPressureThresholdError,
   CsrfReadinessStore,
+  DEFAULT_CONTEXT_PRESSURE_THRESHOLDS,
   DEFAULT_CSP,
   DEFAULT_EXCLUDED_QUERY_PARAMS,
   DEFAULT_MAX_BODY_BYTES,
@@ -1233,7 +1695,10 @@ export {
   InvalidPluginShapeError,
   JOB_MANIFEST_SCHEMA_VERSION,
   JsonStdoutSink,
+  LayerOutOfOrderError,
+  LayeredConfig,
   MAX_ERROR_HTML_BYTES,
+  InMemoryUsageStorage2 as NeutralUsageStorage,
   NodeAcpTransport,
   NonRetryableError,
   NoopObservabilityAdapter,
@@ -1252,6 +1717,8 @@ export {
   TRACE_PARENT_HEADER,
   TheoCloudObservabilityAdapter,
   TheoError,
+  TrustStore,
+  TrustStorePermissionsError,
   _resetCacheEngine,
   _resetEnvCache,
   _resetKeyCacheForTests,
@@ -1272,6 +1739,8 @@ export {
   clearOidcCache,
   compilePattern,
   compileRouteRules,
+  composeInstructions,
+  contextPressure,
   convertToAwsCron,
   createACPTool,
   createCacheEngine,
@@ -1317,6 +1786,7 @@ export {
   deserializeResponse,
   discoverOidcProvider,
   dispatchWebhook,
+  resolveEffectiveContextWindow as effectiveContextWindow,
   encrypt,
   enforceCsrf,
   envelopeCodeToStatus,
@@ -1329,6 +1799,7 @@ export {
   extractUniversalIssues,
   findSuggestion,
   fromUnknown,
+  frontmatterValue,
   generateBackupCodes,
   generateManifest,
   generateNonce,
@@ -1356,8 +1827,11 @@ export {
   isInputError,
   jsonTransformer,
   levenshtein,
+  listProviders,
+  loadCustomCommands,
   loadCustomErrorPages,
   loadEnv,
+  loadInstructionTree,
   loadManifest,
   logRequest,
   matchDisallowed,
@@ -1376,8 +1850,11 @@ export {
   readAppResource,
   readRawBody,
   recordAttempt,
+  registerProvider,
   requireAuth,
+  resetProviderRegistry,
   resolveAdapter,
+  resolveProvider,
   resolveRouteRule,
   resolveTransformer,
   revalidatePath,
@@ -1405,6 +1882,7 @@ export {
   serveStaticFile,
   serverErrorToEnvelope,
   setCookie,
+  splitFrontmatter,
   streamAgentTurnInProcess,
   superjsonTransformer,
   timingSafeEqual,
@@ -1416,6 +1894,7 @@ export {
   translateCronToCloudflare,
   translateCronToDeno,
   translateCronToVercel,
+  tryResolveProvider,
   uiMessageStreamResponse,
   updateTag,
   useDatabase,