@theokit/agents 8.5.2 → 8.7.0

package/dist/config.d.ts

@@ -0,0 +1,534 @@
+import { TheokitAgentError } from '@theokit/sdk/errors';
+import { z } from 'zod';
+import { TrustPosture } from '@theokit/sdk';
+export { resolveEffectiveContextWindow as effectiveContextWindow } from '@theokit/sdk/compaction';
+
+/**
+ * M73 — layered configuration, as a parameterised machine.
+ *
+ * ## The gap this closes
+ *
+ * The config module answered "load my framework's config file". It published no layering engine, did
+ * not let the SDK's through, and said nothing about directory trust. The evidence that this was a
+ * real gap and not a scope decision: a repository whose README forbids importing `@theokit/sdk`
+ * directly broke its own rule **six times**, and all six reach for config/trust/wiring primitives. A
+ * team that breaks its own rule rather than reimplement is the strongest signal that the door, not
+ * the willingness, was what was missing.
+ *
+ * ## What is policy and what is machine
+ *
+ * The VOCABULARY — which keys exist, which capabilities they grant, TOML or TS — is legitimately
+ * policy and stays with the product. The chain machine, the profile merge, the precedence report and
+ * the floor are identical in every agent product.
+ *
+ * The milestone's named risk was generalising too early and freezing another product's vocabulary.
+ * The mitigation is structural: **the layer chain is a parameter, never a constant.** No layer name
+ * from any consumer appears in this file, and a test asserts it by resolving a chain of names this
+ * repository has never heard of.
+ *
+ * ## Why it composes rather than implements
+ *
+ * `foldLayers` and `verifyLayerOrdering` are the SDK's, crossed by M67. Re-deriving the fold here
+ * would give two answers to "which layer wins", and the two would diverge silently — the exact
+ * defect this whole initiative exists to remove. What this adds is what the SDK deliberately does
+ * not: provenance per key, and the measured-vs-declared precedence report.
+ */
+/** One layer of configuration, with the values it contributes. */
+interface ConfigLayer {
+    readonly layer: string;
+    /** Higher wins. Omit across the whole chain to mean "this array is already the order". */
+    readonly precedence?: number;
+    readonly values: Readonly<Record<string, unknown>>;
+}
+/**
+ * Where each resolved key came from.
+ *
+ * For an overwritten key this is the winning layer's name. For an ACCUMULATED key it is every
+ * contributing layer, comma-separated — a union has no single winner, and naming only the last one
+ * would be a lie about where the other members came from.
+ */
+type ProvenancePerKey = Readonly<Record<string, string>>;
+/**
+ * Declared order versus the order the values actually proved.
+ *
+ * The consumer wrote this check by hand (`measuredPrecedenceChain`) because the engine did not offer
+ * it. A layer that declares high precedence and never wins a key is a config nobody is reading —
+ * usually a path that does not exist. Silence there is how a broken override survives for months.
+ */
+interface PrecedenceReport {
+    /** The chain as the caller wrote it. */
+    readonly declared: readonly string[];
+    /**
+     * The layers that actually contributed at least one key, in chain order.
+     *
+     * PARTICIPATION, not victory. The first draft measured which layers WON a key, and a base
+     * `defaults` layer whose every value is later overridden then reported as absent from the measured
+     * chain — flagging the most normal arrangement in layered config as a divergence. Being
+     * overridden is what a defaults layer is for.
+     */
+    readonly measured: readonly string[];
+    /**
+     * Layers declared in the chain that contributed NO key at all.
+     *
+     * Not the same as "was overridden": being superseded is the normal fate of a defaults layer and
+     * says nothing is wrong. Contributing nothing usually means a path that does not exist — a config
+     * file nobody is reading — and that is the silence this report exists to break.
+     */
+    readonly declaredButSilent: readonly string[];
+    readonly diverges: boolean;
+}
+interface LayeredConfigInput<TSchema extends z.ZodType> {
+    readonly layers: readonly ConfigLayer[];
+    /** Validated AFTER folding — see {@link LayeredConfig.resolve}. */
+    readonly schema: TSchema;
+    /**
+     * Keys whose values UNION across layers instead of being overwritten.
+     *
+     * Opt-in per key, deliberately: some keys are lists a layer adds to (tools, plugins, allowlists)
+     * and overwriting them discards what a lower layer contributed — but defaulting to union would
+     * silently merge something the caller meant to replace.
+     */
+    readonly accumulatingKeys?: readonly string[];
+}
+interface LayeredConfigResult<TValue> {
+    readonly value: TValue;
+    readonly provenancePerKey: ProvenancePerKey;
+    readonly precedenceReport: PrecedenceReport;
+}
+/**
+ * Raised when a chain is built out of order.
+ *
+ * Refusing beats sorting silently: a caller who wrote the chain in the wrong order holds a belief
+ * about precedence that is wrong, and sorting it for them leaves the belief intact until it produces
+ * a surprise somewhere else.
+ */
+declare class LayerOutOfOrderError extends TheokitAgentError {
+    readonly name = "LayerOutOfOrderError";
+    constructor(message: string);
+}
+/**
+ * The layering engine.
+ *
+ * A class with one static rather than a free function: it is the namespace the config surface hangs
+ * from (`LayeredConfig.resolve`), matching the `X.create()` shape the rest of this codebase uses, and
+ * it leaves room for the trust-store companion to join the same namespace without a second import.
+ */
+declare const 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<TSchema extends z.ZodType>(input: LayeredConfigInput<TSchema>): LayeredConfigResult<z.infer<TSchema>>;
+};
+
+/**
+ * M73 — the per-directory trust store: a trust decision that survives the process.
+ *
+ * ## Why persisting it matters
+ *
+ * M68 made `settingSources`' `project` root require a `TrustPosture` — evidence, not a claim. But a
+ * posture computed fresh on every run is a question asked over and over, and a question asked every
+ * run is a question users learn to answer without reading.
+ *
+ * Persisting turns the stamp into a DECISION: recorded once, auditable afterwards, and answerable by
+ * "who trusted this directory, when, and on what basis" rather than by re-deriving it.
+ *
+ * ## Why the file permission is checked on READ
+ *
+ * This file decides whether a directory may run shell hooks. A store any other user can write is a
+ * store any other user can use to grant themselves that. Checking at write time only would leave a
+ * file whose mode was loosened afterwards looking fine — so the check is where the value is
+ * consumed, and a loose mode is REFUSED rather than repaired: silently tightening it hides that
+ * something changed the mode, which is the fact worth knowing.
+ */
+/** What was decided about one directory. */
+interface TrustRecord {
+    /** Absolute path of the trusted directory. */
+    readonly path: string;
+    /** ISO-8601 stamp of the decision. Injected by the caller — see {@link TrustStore.trust}. */
+    readonly decidedAt: string;
+    /** Free-form provenance: who or what decided (a username, a CI job, `--trust` on the CLI). */
+    readonly decidedBy: string;
+    readonly trusted: boolean;
+}
+/** Raised when the store's file mode would let another user grant themselves trust. */
+declare class TrustStorePermissionsError extends TheokitAgentError {
+    readonly file: string;
+    readonly mode: number;
+    readonly name = "TrustStorePermissionsError";
+    constructor(file: string, mode: number);
+}
+declare class TrustStore {
+    private readonly file;
+    constructor(file: string);
+    /**
+     * 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: string): boolean;
+    /**
+     * 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(): readonly TrustRecord[];
+    /**
+     * 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).
+     */
+    trust(record: TrustRecord): Promise<void>;
+    /**
+     * 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<K extends string>(path: string, capabilities: readonly K[]): TrustPosture<K>;
+    private assertSafePermissions;
+}
+
+interface ExpandImportsInput {
+    readonly text: string;
+    /** Absolute path of the file `text` came from — imports resolve relative to its directory. */
+    readonly filePath: string;
+    /** Containment boundary. An import resolving outside it is kept literal. */
+    readonly rootDir: string;
+    readonly onWarn: (message: string) => void;
+    /**
+     * Frame imported content — e.g. `--- import: x ---` markers around it.
+     *
+     * Presentation belongs to the caller: these markers end up in the model's prompt, and a loader
+     * that dictated them would silently change what a product sends. Absent means the content is
+     * inlined bare, which is what every caller saw before this seam existed.
+     *
+     * @param name    the reference as written, without the `@`
+     * @param content the imported file's content, already expanded
+     */
+    readonly wrap?: (name: string, content: string) => string;
+    /**
+     * Files the CALLER already read, which must not be inlined again.
+     *
+     * A walk that collects its files first and expands second — the ancestor-chain convention, where a
+     * product climbs from the working directory to the repository root — has already loaded some of
+     * the files an import may name. Without this, such a file lands in the prompt twice.
+     */
+    readonly alreadyLoaded?: readonly string[];
+}
+/**
+ * Replace every `@file.md` reference with that file's content, recursively.
+ *
+ * A reference that cannot be expanded — missing, outside the root, too deep, already visited — is
+ * left exactly as written. Keeping it literal rather than dropping it is what lets a user SEE that
+ * something did not expand; a silently deleted line reads as content nobody wrote.
+ */
+declare function expandInstructionImports(input: ExpandImportsInput): string;
+
+/**
+ * M74 — load a tree of project instruction files, with explicit ceilings.
+ *
+ * ## Why `compileProjectContext` does not cover this
+ *
+ * It reads ONE fixed file through the SDK: no depth or file budget, no frontmatter, no cycle guard,
+ * no truncation policy, no warning channel. A product that wants project-scoped instructions writes
+ * roughly 720 lines of mechanism — all of it identical between products, none of it about their
+ * domain.
+ *
+ * ## The containment check is a security control
+ *
+ * A symlink inside a project directory can point anywhere. Following one lets a repository the user
+ * just cloned inject the contents of `~/.ssh/config`, or any other readable file, straight into the
+ * model's system prompt. That is prompt injection with the filesystem as the vector, and every
+ * consumer that writes this loader by hand reintroduces it.
+ *
+ * `assertNoSymlinkEscape` is the SDK's, crossed in M67. Composing it is what makes the check the
+ * same one everywhere instead of four subtly different `realpath` comparisons.
+ *
+ * ## Failure is per FILE, not per tree
+ *
+ * A malformed frontmatter skips that file and warns. Failing the whole load would let one bad file
+ * in a deep tree silently disable every instruction the user wrote — the loudest possible failure
+ * producing the quietest possible outcome.
+ */
+/** One loaded instruction file. */
+interface InstructionBlock {
+    /** Path relative to `cwd`, for messages a human can act on. */
+    readonly path: string;
+    /** File body with the frontmatter removed. */
+    readonly content: string;
+    /** `paths:` from the frontmatter — the scopes this block applies to. Empty means unscoped. */
+    readonly scopes: readonly string[];
+}
+interface InstructionTreeBudget {
+    /** How deep below each root to descend. */
+    readonly maxDepth: number;
+    /** How many files to load in total. */
+    readonly maxFiles: number;
+    /** Total characters across all blocks. */
+    readonly maxChars: number;
+}
+interface LoadInstructionTreeInput {
+    readonly cwd: string;
+    /** Directories to walk, relative to `cwd` or absolute. Order is the caller's. */
+    readonly roots: readonly string[];
+    readonly budget: InstructionTreeBudget;
+    /**
+     * Where a skipped file, a refused symlink or an exhausted budget is reported.
+     *
+     * A channel rather than a throw: none of these should stop a load, and none of them should be
+     * silent either. Silence here is how a user's instruction file stops being read without anybody
+     * noticing.
+     */
+    readonly onWarn?: (message: string) => void;
+    /** File names to load. Defaults to the conventional two. */
+    readonly fileNames?: readonly string[];
+}
+interface InstructionTree {
+    readonly blocks: readonly InstructionBlock[];
+    /** True when a ceiling stopped the walk — the caller is seeing a partial tree. */
+    readonly truncated: boolean;
+    readonly count: number;
+}
+/**
+ * Walk `roots` and load the instruction files found, stopping at the declared ceilings.
+ *
+ * Cycles are broken by INODE, not by path: a symlink loop produces infinitely many distinct paths
+ * for the same file, so a path-keyed `seen` set never terminates. The inode is what identifies the
+ * file the OS would actually read.
+ */
+declare function loadInstructionTree(input: LoadInstructionTreeInput): InstructionTree;
+
+/**
+ * M74 — compose a base prompt with instruction sources under a character ceiling.
+ *
+ * ## Why the truncation LADDER is mechanism and the ORDER is policy
+ *
+ * When the composed text does not fit, something has to go — and which thing goes is a product
+ * decision. A coding agent drops repository conventions before user rules; a support agent may do
+ * the opposite. Baking that preference into the framework would be absorbing one product's taste as
+ * everyone's law, which is the milestone's named risk.
+ *
+ * So the caller passes `sources` ALREADY ORDERED, most important first, and this function walks that
+ * order backwards when it needs room. The framework supplies the cutting mechanism; the product
+ * supplies the preference. No source NAME appears in this file.
+ *
+ * ## Why it truncates rather than refusing
+ *
+ * A prompt that does not fit is a run that cannot start, and refusing outright would make a long
+ * instruction file a hard failure at the worst moment. Dropping the least important source and
+ * SAYING SO is the behaviour that keeps the agent usable while keeping the user informed — which is
+ * why `onWarn` is not optional in practice even though it is optional in the signature.
+ */
+/** One named block of instructions the caller wants composed. */
+interface InstructionSource {
+    /** The product's own label, used only in warnings. Never interpreted here. */
+    readonly name: string;
+    readonly content: string;
+}
+interface ComposeInstructionsOptions {
+    /** Ceiling for the whole composed string, base included. */
+    readonly maxChars: number;
+    /** Where a dropped or trimmed source is reported. Silence here loses the user's instructions. */
+    readonly onWarn?: (message: string) => void;
+    /** Separator between blocks. */
+    readonly separator?: string;
+}
+interface ComposedInstructions {
+    readonly text: string;
+    /** Names of sources that were dropped entirely, in the order they were dropped. */
+    readonly dropped: readonly string[];
+    /** Name of the source that was cut in half to fit, when one was. */
+    readonly trimmed?: string;
+}
+/**
+ * Compose `base` with `sources`, cutting from the END of the list until it fits.
+ *
+ * The base is never dropped: it is the agent's own identity, and an agent without it is a different
+ * agent. If the base alone exceeds the ceiling the result is the base, TRUNCATED, with a warning —
+ * returning an empty string would be a silent lobotomy, and throwing would make a long system prompt
+ * an unrecoverable configuration error.
+ */
+declare function composeInstructions(base: string, sources: readonly InstructionSource[], options: ComposeInstructionsOptions): ComposedInstructions;
+
+/**
+ * M76 — load custom commands from `.theokit/commands/`.
+ *
+ * ## Why this gap was worse than a missing feature
+ *
+ * The framework OWNS the `.theokit/` convention and already loads `skills/`, `agents/` and
+ * `hooks.json` from it. `commands/` — the one directory every product-facing agent surface wants —
+ * had no loader at all. So a consumer wrote markdown-with-frontmatter scanning **against the
+ * framework's own directory**: reimplementing the reading of a convention the framework defines.
+ *
+ * A convention with a hole in it is worse than no convention. It teaches the reader that `.theokit/`
+ * is the framework's, then makes them write the loader themselves for one subdirectory, and their
+ * loader inevitably disagrees with ours about frontmatter, precedence and trust.
+ *
+ * ## Trust, and why project commands are gated
+ *
+ * A command is a prompt the user can invoke by name. A project-level one comes from the working
+ * directory — which, for an agent pointed at a repository the user just cloned, is
+ * attacker-controlled content. Same decision as M68: `projectTrusted` false means project commands
+ * do not load. User-level commands under `homeDir` need no gate — that is the operator's own
+ * machine.
+ *
+ * ## Warns, never decides
+ *
+ * On a name collision this loader REPORTS and moves on. Which command wins when a custom one shadows
+ * a builtin is the product's router to decide (M83) — it is the only layer that knows what its
+ * builtins are. A loader that silently dropped one would make that decision invisibly, on behalf of
+ * a product it cannot see.
+ */
+/** One command loaded from disk. */
+interface CustomCommand {
+    /** Invocation name, derived from the file name without its extension. */
+    readonly name: string;
+    /** One-line summary from `description:` in the frontmatter, when present. */
+    readonly description?: string;
+    /** The prompt body, frontmatter removed. */
+    readonly body: string;
+    /** Which layer it came from. `project` beats `user` — see {@link loadCustomCommands}. */
+    readonly source: 'project' | 'user';
+    /** Absolute path, for messages a human can act on. */
+    readonly path: string;
+}
+interface LoadCustomCommandsInput {
+    /** Project root. Its `.theokit/commands/` is read only when `projectTrusted`. */
+    readonly projectDir?: string;
+    /** Operator home. Its `.theokit/commands/` needs no trust gate. */
+    readonly homeDir?: string;
+    /**
+     * Whether the project directory is trusted (M68/M73).
+     *
+     * REQUIRED, like `approved` on the hook engine and for the same reason: an optional security gate
+     * is a gate somebody forgets, and forgetting this one loads prompts written by whoever wrote the
+     * repository.
+     */
+    readonly projectTrusted: boolean;
+    /** Names the product already uses, so a shadow can be reported rather than discovered later. */
+    readonly builtinNames?: readonly string[];
+    /** Where a shadow, a duplicate, or a malformed file is reported. */
+    readonly onWarn?: (message: string) => void;
+}
+interface CustomCommandsResult {
+    /** Loaded commands, project-level first. Names are unique — see the precedence note. */
+    readonly commands: readonly CustomCommand[];
+    /** Names that also exist as builtins. Reported, never resolved here. */
+    readonly shadowedBuiltins: readonly string[];
+}
+/**
+ * Load `.theokit/commands/*.md` from the project and the user, project winning.
+ *
+ * Precedence is project-over-user because the project is the more specific scope: a repository that
+ * ships a `review` command means *its* review, and having the operator's generic one silently take
+ * precedence would make the repository's own configuration the weaker statement.
+ */
+declare function loadCustomCommands(input: LoadCustomCommandsInput): CustomCommandsResult;
+
+/**
+ * Split a markdown file into frontmatter lines and body.
+ *
+ * ## Why this is shared rather than duplicated
+ *
+ * Two loaders need it — the M74 instruction tree and the M76 command loader — and they need the SAME
+ * answer to the same question: where does the metadata stop and the content begin, and what happens
+ * when the fence never closes. That is one piece of knowledge (`G12`), not two similar-looking
+ * functions.
+ *
+ * What is NOT shared is which KEYS each loader reads. `paths:` matters to instructions and
+ * `description:` matters to commands, and folding those together would build a vocabulary neither
+ * one asked for.
+ */
+interface ParsedFrontmatter {
+    /** Lines between the fences, excluding them. Empty when the file has no frontmatter. */
+    readonly frontmatter: readonly string[];
+    /** Everything after the closing fence — or the whole file when there is no frontmatter. */
+    readonly body: string;
+}
+/**
+ * Split `raw`, or return `undefined` when the frontmatter opens and never closes.
+ *
+ * `undefined` rather than a best guess: a file whose fence never closes is malformed in a way that
+ * makes its metadata unknowable, and guessing whether the rest is body or metadata feeds the caller
+ * either the wrong text or the wrong settings. Both callers treat that as "skip this file, warn,
+ * keep going" — failure is per file, never per tree.
+ */
+declare function splitFrontmatter(raw: string): ParsedFrontmatter | undefined;
+/**
+ * Read one scalar key from frontmatter lines.
+ *
+ * Deliberately not a YAML parser. Both callers read a handful of known keys, and pulling in a parser
+ * to do that would be a dependency for a feature nobody asked for (parsimony rungs 4 → 1). An
+ * unrecognised key is ignored rather than rejected — a product may put its own metadata there.
+ */
+declare function frontmatterValue(frontmatter: readonly string[], key: string): string | undefined;
+
+/**
+ * M74 — context pressure: the fraction of the window a run has consumed.
+ *
+ * ## Why this had no counterpart
+ *
+ * The framework shipped the DENOMINATOR (`resolveEffectiveContextWindow`, crossed in M67) and the
+ * NUMERATOR (token usage, on every `done` event) and never put them together. So every product that
+ * wanted to warn a user before a run hit the wall computed the ratio itself, and each picked its own
+ * thresholds.
+ *
+ * The arithmetic is trivial; publishing it is not about saving a division. It is about there being
+ * ONE answer to "is this run in trouble", so a warning in the CLI and a badge in a dashboard agree.
+ */
+/** How close a run is to its context limit. */
+type ContextPressure = 'ok' | 'warn' | 'critical';
+/**
+ * Fractions of the effective window at which each level begins.
+ *
+ * Defaults chosen to leave room to act: `warn` at 75% is early enough that compacting still helps,
+ * `critical` at 90% is where the next turn may not fit. Configurable because a product with long
+ * tool outputs legitimately wants an earlier warning than one with short chat turns.
+ */
+interface ContextPressureThresholds {
+    readonly warn: number;
+    readonly critical: number;
+}
+declare const DEFAULT_CONTEXT_PRESSURE_THRESHOLDS: ContextPressureThresholds;
+/** Raised when thresholds are ordered in a way that makes a level unreachable. */
+declare class ContextPressureThresholdError extends TheokitAgentError {
+    readonly name = "ContextPressureThresholdError";
+    constructor(message: string);
+}
+/**
+ * Classify a run's context pressure.
+ *
+ * @param usedTokens tokens the run has consumed
+ * @param effectiveWindow the window it is consuming from — typically
+ * `resolveEffectiveContextWindow(...)`, re-exported here so a caller reaches both through one import
+ * (see {@link effectiveContextWindow}).
+ *
+ * An `effectiveWindow` of zero or less returns `'ok'` rather than dividing: an unknown window is not
+ * evidence of pressure, and `Infinity`/`NaN` reaching a UI as a percentage is worse than saying
+ * nothing. Missing evidence is not evidence — the same rule the transcript collector applies to a
+ * missing mtime.
+ *
+ * @throws {ContextPressureThresholdError} when `warn` is not below `critical` — a caller who
+ * inverted them holds a belief about their own thresholds that is wrong, and silently sorting them
+ * would leave that belief intact.
+ */
+declare function contextPressure(usedTokens: number, effectiveWindow: number, thresholds?: ContextPressureThresholds): ContextPressure;
+
+export { type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type ParsedFrontmatter, type PrecedenceReport, type ProvenancePerKey, type TrustRecord, TrustStore, TrustStorePermissionsError, composeInstructions, contextPressure, expandInstructionImports, frontmatterValue, loadCustomCommands, loadInstructionTree, splitFrontmatter };