@theokit/agents 8.5.2 → 8.7.0

package/dist/config.js

@@ -0,0 +1,655 @@
+import {
+  __name
+} from "./chunk-Z4QWC7IK.js";
+
+// src/config/layered-config.ts
+import { foldLayers, verifyLayerOrdering } from "@theokit/sdk";
+import { TheokitAgentError } from "@theokit/sdk/errors";
+var LayerOutOfOrderError = class extends TheokitAgentError {
+  static {
+    __name(this, "LayerOutOfOrderError");
+  }
+  name = "LayerOutOfOrderError";
+  constructor(message) {
+    super(message, {
+      code: "config_layer_out_of_order",
+      isRetryable: false
+    });
+  }
+};
+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);
+  }
+}
+__name(assertOrdering, "assertOrdering");
+function contributorsOf(layers, key) {
+  return layers.filter((layer) => key in layer.values).map((layer) => layer.layer);
+}
+__name(contributorsOf, "contributorsOf");
+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;
+}
+__name(buildProvenance, "buildProvenance");
+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
+  };
+}
+__name(buildReport, "buildReport");
+
+// src/config/trust-store.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "fs";
+import { dirname, resolve } from "path";
+import { resolveTrustPosture } from "@theokit/sdk";
+import { TheokitAgentError as TheokitAgentError2 } from "@theokit/sdk/errors";
+import { atomicWriteJson, withFileLock } from "@theokit/sdk/persistence";
+var TrustStorePermissionsError = class extends TheokitAgentError2 {
+  static {
+    __name(this, "TrustStorePermissionsError");
+  }
+  file;
+  mode;
+  name = "TrustStorePermissionsError";
+  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}\`.`,
+      // Refusing, not repairing: a permission that another user can set is not a transient fault.
+      {
+        code: "trust_store_insecure_mode",
+        isRetryable: false
+      }
+    ), this.file = file, this.mode = mode;
+  }
+};
+var FORBIDDEN_WRITE_BITS = 18;
+function canonicalDir(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+__name(canonicalDir, "canonicalDir");
+var TrustStore = class {
+  static {
+    __name(this, "TrustStore");
+  }
+  file;
+  constructor(file) {
+    this.file = file;
+  }
+  /**
+  * Whether `path` carries a recorded decision to trust it.
+  *
+  * Denies on anything else — never recorded, recorded as refused, or unresolvable. A refusal on
+  * record (`trusted: false`) is a different fact from "never asked", and neither is trust.
+  */
+  isTrusted(path) {
+    const key = canonicalDir(path);
+    return this.read().some((r) => canonicalDir(r.path) === key && r.trusted);
+  }
+  /**
+  * 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 (!existsSync(this.file)) return [];
+    this.assertSafePermissions();
+    const parsed = JSON.parse(readFileSync(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 = existsSync(this.file) ? this.read() : [];
+      const key = canonicalDir(record.path);
+      const records = [
+        ...existing.filter((r) => canonicalDir(r.path) !== key),
+        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: /* @__PURE__ */ __name(() => record?.trusted === true, "isTrusted")
+    });
+  }
+  assertSafePermissions() {
+    const mode = statSync(this.file).mode & 511;
+    if ((mode & FORBIDDEN_WRITE_BITS) !== 0) {
+      throw new TrustStorePermissionsError(this.file, mode);
+    }
+  }
+};
+
+// src/config/instruction-imports.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync as realpathSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+var MAX_IMPORT_DEPTH = 4;
+var IMPORT_REGEX = /(?<![\w`])@([\w~./-]+\.md)\b/g;
+function maskCodeSpans(text) {
+  return text.replace(/```[\s\S]*?(```|$)/g, (m) => m.replace(/[^\n]/g, " ")).replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length));
+}
+__name(maskCodeSpans, "maskCodeSpans");
+function insideRoot(target, rootDir) {
+  try {
+    const real = realpathSync2(target);
+    const realRoot = realpathSync2(rootDir);
+    return real === realRoot || real.startsWith(`${realRoot}/`);
+  } catch {
+    return false;
+  }
+}
+__name(insideRoot, "insideRoot");
+function importTarget(name, filePath, rootDir, visited, warn) {
+  if (name.startsWith("~/")) {
+    warn(`instruction import @${name} in ${filePath} is outside the project root \u2014 kept literal`);
+    return void 0;
+  }
+  const target = resolve2(dirname2(filePath), name);
+  if (!existsSync2(target)) {
+    warn(`instruction import @${name} in ${filePath} was not found \u2014 kept literal`);
+    return void 0;
+  }
+  if (!insideRoot(target, rootDir)) {
+    warn(`instruction import @${name} in ${filePath} is outside the project root \u2014 kept literal`);
+    return void 0;
+  }
+  return visited.has(target) ? void 0 : target;
+}
+__name(importTarget, "importTarget");
+function expandInstructionImports(input) {
+  return expand(input.text, input.filePath, {
+    rootDir: input.rootDir,
+    warn: input.onWarn,
+    // Seeded with what the caller already read, so a file its walk loaded is not inlined a second
+    // time by an import that names it.
+    visited: new Set(input.alreadyLoaded ?? []),
+    depth: 0,
+    ...input.wrap === void 0 ? {} : {
+      wrap: input.wrap
+    }
+  });
+}
+__name(expandInstructionImports, "expandInstructionImports");
+function expand(text, filePath, ctx) {
+  const masked = maskCodeSpans(text);
+  const matches = [
+    ...masked.matchAll(IMPORT_REGEX)
+  ];
+  if (matches.length === 0) return text;
+  if (ctx.depth >= MAX_IMPORT_DEPTH) {
+    ctx.warn(`instruction import depth cap (${String(MAX_IMPORT_DEPTH)}) reached in ${filePath} \u2014 deeper imports kept literal`);
+    return text;
+  }
+  const out = [];
+  let cursor = 0;
+  for (const match of matches) {
+    const name = match[1];
+    out.push(text.slice(cursor, match.index));
+    cursor = match.index + match[0].length;
+    const target = importTarget(name, filePath, ctx.rootDir, ctx.visited, ctx.warn);
+    if (target === void 0) {
+      out.push(match[0]);
+      continue;
+    }
+    ctx.visited.add(target);
+    let content;
+    try {
+      content = readFileSync2(target, "utf8");
+    } catch {
+      ctx.warn(`instruction import @${name} in ${filePath} could not be read \u2014 kept literal`);
+      out.push(match[0]);
+      continue;
+    }
+    const expanded = expand(content, target, {
+      ...ctx,
+      depth: ctx.depth + 1
+    });
+    out.push(ctx.wrap === void 0 ? expanded : ctx.wrap(name, expanded));
+  }
+  out.push(text.slice(cursor));
+  return out.join("");
+}
+__name(expand, "expand");
+
+// src/config/instruction-tree.ts
+import { readFileSync as readFileSync3, readdirSync, statSync as statSync2 } from "fs";
+import { join, relative, resolve as resolve3 } from "path";
+import { assertNoSymlinkEscape } from "@theokit/sdk/path-safety";
+
+// 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")
+  };
+}
+__name(splitFrontmatter, "splitFrontmatter");
+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;
+}
+__name(frontmatterValue, "frontmatterValue");
+
+// src/config/instruction-tree.ts
+var DEFAULT_FILE_NAMES = [
+  "THEO.md",
+  "AGENTS.md"
+];
+var IGNORE_WARNING = /* @__PURE__ */ __name(() => void 0, "IGNORE_WARNING");
+function loadInstructionTree(input) {
+  const warn = input.onWarn ?? IGNORE_WARNING;
+  const fileNames = input.fileNames ?? DEFAULT_FILE_NAMES;
+  const cwd = resolve3(input.cwd);
+  const blocks = [];
+  const seenInodes = /* @__PURE__ */ new Set();
+  let chars = 0;
+  const visit = /* @__PURE__ */ __name((dir, depth) => {
+    if (depth > input.budget.maxDepth) return false;
+    let entries;
+    try {
+      entries = readdirSync(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;
+  }, "visit");
+  let truncated = false;
+  for (const root of input.roots) {
+    truncated = visit(resolve3(cwd, root), 0);
+    if (truncated) break;
+  }
+  return {
+    blocks,
+    truncated,
+    count: blocks.length
+  };
+}
+__name(loadInstructionTree, "loadInstructionTree");
+function filesBeforeDirectories(dir, entries) {
+  const found = [];
+  for (const entry of [
+    ...entries
+  ].sort((a, b) => a.localeCompare(b))) {
+    const path = join(dir, entry);
+    try {
+      found.push({
+        entry,
+        path,
+        stats: statSync2(path)
+      });
+    } catch {
+      continue;
+    }
+  }
+  return [
+    ...found.filter((item) => !item.stats.isDirectory()),
+    ...found.filter((item) => item.stats.isDirectory())
+  ];
+}
+__name(filesBeforeDirectories, "filesBeforeDirectories");
+function parseInstructionFile(path, cwd, warn) {
+  let raw;
+  try {
+    raw = readFileSync3(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,
+    // Imports expand AFTER the frontmatter split, so an `@ref` inside a frontmatter block is not one
+    // — that block is metadata about the file, not content of the prompt.
+    content: expandInstructionImports({
+      text: parsed.body,
+      filePath: path,
+      rootDir: cwd,
+      onWarn: warn
+    }),
+    scopes: parsePathsScope(parsed.frontmatter)
+  };
+}
+__name(parseInstructionFile, "parseInstructionFile");
+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;
+}
+__name(parsePathsScope, "parsePathsScope");
+
+// src/config/compose-instructions.ts
+var DEFAULT_SEPARATOR = "\n\n";
+var IGNORE_WARNING2 = /* @__PURE__ */ __name(() => void 0, "IGNORE_WARNING");
+function composeInstructions(base, sources, options) {
+  const warn = options.onWarn ?? IGNORE_WARNING2;
+  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 = /* @__PURE__ */ __name((list) => [
+    base,
+    ...list.map((source) => source.content)
+  ].join(separator).length, "lengthOf");
+  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
+    }
+  };
+}
+__name(composeInstructions, "composeInstructions");
+
+// src/config/custom-commands.ts
+import { readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
+import { basename, extname, join as join2 } from "path";
+var COMMANDS_DIR = join2(".theokit", "commands");
+var IGNORE_WARNING3 = /* @__PURE__ */ __name(() => void 0, "IGNORE_WARNING");
+function loadCustomCommands(input) {
+  const warn = input.onWarn ?? IGNORE_WARNING3;
+  const loaded = /* @__PURE__ */ new Map();
+  if (input.homeDir !== void 0) {
+    for (const command of readCommandsDir(join2(input.homeDir, COMMANDS_DIR), "user", warn)) {
+      loaded.set(command.name, command);
+    }
+  }
+  if (input.projectDir !== void 0) {
+    if (!input.projectTrusted) {
+      const pending = readCommandsDir(join2(input.projectDir, COMMANDS_DIR), "project", IGNORE_WARNING3);
+      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(join2(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
+  };
+}
+__name(loadCustomCommands, "loadCustomCommands");
+function byProjectThenName(a, b) {
+  if (a.source !== b.source) return a.source === "project" ? -1 : 1;
+  return a.name.localeCompare(b.name);
+}
+__name(byProjectThenName, "byProjectThenName");
+function readCommandsDir(dir, source, warn) {
+  let entries;
+  try {
+    entries = readdirSync2(dir);
+  } catch {
+    return [];
+  }
+  entries.sort((a, b) => a.localeCompare(b));
+  const commands = [];
+  for (const entry of entries) {
+    if (extname(entry) !== ".md") continue;
+    const path = join2(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;
+}
+__name(readCommandsDir, "readCommandsDir");
+function parseCommandFile(path, entry, source, warn) {
+  let raw;
+  try {
+    raw = readFileSync4(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
+  };
+}
+__name(parseCommandFile, "parseCommandFile");
+
+// src/config/context-pressure.ts
+import { resolveEffectiveContextWindow } from "@theokit/sdk/compaction";
+import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
+var DEFAULT_CONTEXT_PRESSURE_THRESHOLDS = {
+  warn: 0.75,
+  critical: 0.9
+};
+var ContextPressureThresholdError = class extends TheokitAgentError3 {
+  static {
+    __name(this, "ContextPressureThresholdError");
+  }
+  name = "ContextPressureThresholdError";
+  constructor(message) {
+    super(message, {
+      code: "context_pressure_thresholds_unordered",
+      isRetryable: false
+    });
+  }
+};
+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";
+}
+__name(contextPressure, "contextPressure");
+export {
+  ContextPressureThresholdError,
+  DEFAULT_CONTEXT_PRESSURE_THRESHOLDS,
+  LayerOutOfOrderError,
+  LayeredConfig,
+  TrustStore,
+  TrustStorePermissionsError,
+  composeInstructions,
+  contextPressure,
+  resolveEffectiveContextWindow as effectiveContextWindow,
+  expandInstructionImports,
+  frontmatterValue,
+  loadCustomCommands,
+  loadInstructionTree,
+  splitFrontmatter
+};
+//# sourceMappingURL=config.js.map