@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/compaction.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Public compaction / context-management helpers (M2-1, extended V3-3).
+ *
+ * Promotes the SDK's compaction capability to a public surface so consumers can
+ * compact a transcript, mark/filter conversation checkpoints, and detect
+ * context-overflow — without reaching into `internal/`.
+ *
+ * Two recent-window modes (V3-3):
+ *  - `keepRecent` (turn-count, default) — keeps the last N turns verbatim and
+ *    always preserves leading system PROMPTS; reuses the internal
+ *    `selectCompressionWindow` (no second algorithm).
+ *  - `keepTokens` (token-budget) — keeps the trailing turns whose accumulated
+ *    `estimateTokens` fits the budget (theocode `splitTranscript` semantics). In
+ *    this mode leading system prompts are NOT special-cased (D6).
+ *
+ * Summarization is delegated to a caller-supplied callback (which receives the
+ * older window + the summary template). With `failSafe`, a thrown summarizer
+ * returns the ORIGINAL transcript + a structured warn (compaction is an
+ * optimization, never a cause of data loss); without it, the error propagates.
+ *
+ * Public from the `@theokit/sdk/compaction` sub-path.
+ */
+import { TheokitAgentError } from "./errors.js";
+/**
+ * Minimal message shape for compaction/compression input. THE canonical public origin (leaf type —
+ * rollup-plugin-dts cannot re-export types from internal modules into entry bundles; M42 lesson).
+ *
+ * @public
+ */
+export interface CompressibleMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * Sentinel prefix marking a conversation checkpoint turn. A visible, structured,
+ * prose-unlikely token (no invisible/control bytes — safe to persist and to read
+ * in source). Only {@link buildCheckpoint} should produce content beginning with it.
+ */
+export declare const CHECKPOINT_MARKER = "[[theokit:checkpoint]] ";
+/**
+ * The 7-section summary template handed to the `summarize` callback (theocode
+ * parity shape). Every header is always present so the summarizer cannot silently
+ * drop a category; the model is told to preserve file paths, commands, and error
+ * text verbatim. Override per-call via {@link CompactTranscriptOptions.summaryTemplate}.
+ */
+export declare const SUMMARY_TEMPLATE = "Summarize the conversation so far into these sections (keep every header even if empty):\n\n## Goal\nWhat the user is ultimately trying to achieve.\n\n## Constraints\nHard requirements, conventions, and rules stated.\n\n## Progress\nWhat has been done so far.\n\n## Decisions\nChoices made and their rationale.\n\n## Next\nThe immediate next steps.\n\n## Critical\nAnything that MUST NOT be forgotten (preserve verbatim: error messages, exact values).\n\n## Files\nFile paths touched or referenced (verbatim).";
+/** Options for {@link compactTranscript}. */
+export interface CompactTranscriptOptions {
+    /** Trailing turns preserved verbatim by COUNT (default 6). Ignored when `keepTokens` is set. */
+    keepRecent?: number;
+    /**
+     * Trailing turns preserved verbatim by TOKEN BUDGET (theocode mode). When set,
+     * takes precedence over `keepRecent` and disables system-prompt preservation (D6).
+     */
+    keepTokens?: number;
+    /** Checkpoint marker (default {@link CHECKPOINT_MARKER}). Must be non-empty. */
+    marker?: string;
+    /** Summary template passed to `summarize` (default {@link SUMMARY_TEMPLATE}). */
+    summaryTemplate?: string;
+    /** Summarize the older window into one turn; if omitted, the older window is dropped. */
+    summarize?: (older: CompressibleMessage[], template: string) => Promise<CompressibleMessage>;
+    /**
+     * When true, a thrown `summarize` returns the ORIGINAL transcript + a structured
+     * warn (compaction never loses data). Default false: the error propagates.
+     */
+    failSafe?: boolean;
+}
+/**
+ * Compact a transcript. In `keepRecent` mode (default) the last `keepRecent` turns
+ * are kept verbatim and leading system PROMPTS preserved; in `keepTokens` mode the
+ * trailing turns within the token budget are kept (no system special-casing, D6).
+ * The older window is summarized (via `summarize`, receiving the template) or
+ * dropped. Never mutates the input.
+ */
+export declare function compactTranscript(messages: CompressibleMessage[], options?: CompactTranscriptOptions): Promise<CompressibleMessage[]>;
+/**
+ * Build a checkpoint marker turn (a `system` turn whose content starts with
+ * `marker`, default {@link CHECKPOINT_MARKER}). `marker` must be non-empty.
+ */
+export declare function buildCheckpoint(label?: string, marker?: string): CompressibleMessage;
+/** Options for {@link filterFromLatestCheckpoint}. */
+export interface FilterCheckpointOptions {
+    /** Marker to scan for (default {@link CHECKPOINT_MARKER}). */
+    marker?: string;
+    /**
+     * `'after'` (default, M2) returns turns AFTER the latest marker (exclusive);
+     * `'from'` (theocode) returns turns FROM the latest marker (inclusive).
+     */
+    include?: "after" | "from";
+}
+/**
+ * Return the turns relative to the most recent checkpoint marker (all turns if
+ * none). `include: 'after'` (default) excludes the checkpoint; `'from'` includes
+ * it (the summary stands in for the pruned head). Never mutates the input.
+ */
+export declare function filterFromLatestCheckpoint(messages: CompressibleMessage[], options?: FilterCheckpointOptions): CompressibleMessage[];
+/**
+ * True iff `err` is a {@link TheokitAgentError} (or subclass) reporting a
+ * context-window-exceeded condition (the typed `context_too_long` code). Reads
+ * both `code` (set by provider mappers) and `metadata.code` (the preferred field)
+ * — never a brittle message regex.
+ */
+export declare function isContextOverflowError(err: unknown): boolean;
+/**
+ * M77 — the margin is outside `(0, 1]`. Typed, because a margin > 1 would GROW the assumed window,
+ * which is the unsafe direction: `shouldCompact` is monotonically decreasing in `contextWindow`, so
+ * overestimating it makes the trigger fire too late and the context overflow.
+ */
+export declare class ContextWindowMarginError extends TheokitAgentError {
+    readonly margin: number;
+    constructor(margin: number);
+}
+/**
+ * M77 — default safety margin on the context window.
+ *
+ * `0.95` is not a guess: it is the single reference's value. Codex ships
+ * `effective_context_window_percent: 95` (`models-manager/src/model_info.rs:158`) and never budgets
+ * against 100% of a window. Being MULTIPLICATIVE, it stays conservative at any window size, which a
+ * fixed subtraction would not.
+ */
+export declare const CONTEXT_WINDOW_MARGIN = 0.95;
+/**
+ * M77 — the floor used ONLY when neither the catalog nor the caller knows the window.
+ *
+ * Honest about its own weakness. This number has **one** source (the M77 milestone text); the search
+ * for a second one failed, because the reference has no fallback at all — Codex returns `Option` and
+ * its callers early-return (`core/src/session/turn_context.rs:213`, `core/src/compact_remote.rs:374`).
+ *
+ * It is conservative only UPWARD. For a model whose real window is larger, budgeting against 128k
+ * compacts early — wasteful but safe. For a model whose real window is SMALLER (an 8k or 32k model
+ * absent from the catalog), it compacts too late and the context still overflows. That residual risk
+ * is real and is why {@link resolveEffectiveContextWindow} never lets this floor compete with a known
+ * catalog value, and why the `compaction_fallback` event exists: a surface can show that the budget is
+ * a guess instead of the user finding out when the provider rejects the request.
+ */
+export declare const CONTEXT_WINDOW_FLOOR = 128000;
+/** Where the effective window came from — carried into the M77 structured event. */
+export type ContextWindowSource = "override" | "catalog" | "fallback";
+/** Input to {@link resolveEffectiveContextWindow}. */
+export interface EffectiveContextWindowInput {
+    /** Caller-supplied window, in tokens. Clamped by `catalog` when both are present. */
+    readonly override?: number | undefined;
+    /** The model's window from the catalog, in tokens. Absent when the model is unknown. */
+    readonly catalog?: number | undefined;
+    /** Safety margin in `(0, 1]`. Codex uses 0.95 (`model_info.rs:158`). */
+    readonly margin: number;
+    /** Conservative floor used ONLY when neither `override` nor `catalog` is available. */
+    readonly floor?: number | undefined;
+}
+/** Result of {@link resolveEffectiveContextWindow}. */
+export interface EffectiveContextWindow {
+    /** The window to budget against, after clamp and margin. */
+    readonly window: number;
+    /** Which input won — `"fallback"` means neither override nor catalog was available. */
+    readonly source: ContextWindowSource;
+    /** `true` when an `override` above the catalog window was clamped down to it. */
+    readonly clamped: boolean;
+}
+/**
+ * Absolute cap on a declared context window, applied when no catalog entry exists to compare against.
+ *
+ * **10M**, not 2M. The first version used 2M on the rationale that it sat "comfortably above the
+ * largest published window" — adversarial review measured the opposite: Llama 4 Scout publishes
+ * **10M**, and it arrives precisely via OpenRouter, the provider **without** a catalog, which is the
+ * case this cap exists to cover. The user would have silently lost 80% of the declared window.
+ *
+ * The cap still serves what motivates it — one extra zero on 400k gives 4M, which passes; two zeros
+ * give 40M, which does not. A limit that rejects legitimate configuration is worse than no limit,
+ * because failing OPEN is visible when it happens and silently losing 80% is not.
+ */
+export declare const ABSOLUTE_CONTEXT_WINDOW_CAP = 10000000;
+/**
+ * Resolve the window to budget against — the fail-SAFE replacement for reading the catalog directly.
+ *
+ * Today `post-run-lifecycle.ts` reads `getCatalogModelInfo(model)?.limit?.context` and, when that is
+ * `undefined`, auto-compaction simply never fires. That is fail-OPEN: the context grows until the
+ * provider rejects the request. (The comment there calls it "fail-safe" — M77 corrects it.)
+ *
+ * Three techniques, two of them borrowed from the single reference:
+ *
+ *  1. **Override, CLAMPED by the catalog** — Codex `models-manager/src/model_info.rs:26-31` lets
+ *     config override the window but limits it with `context_window.min(max_context_window)`.
+ *     Without the clamp, declaring 999k on a 200k model reopens the overflow through another door.
+ *  2. **Multiplicative margin** — Codex `model_info.rs:158` (`effective_context_window_percent: 95`)
+ *     never budgets against 100% of the window. Being multiplicative, it is conservative for ANY
+ *     window size.
+ *  3. **Floor, only when nothing is known** — deliberately NOT a blanket default. A fixed floor is
+ *     conservative only upward: applied to a small model it would inflate the assumed window and
+ *     reproduce the very fail-open this function exists to close. Hence the floor never competes
+ *     with a known catalog value.
+ *
+ * Pure — no catalog lookup, no I/O. The caller supplies the numbers, mirroring `shouldCompact`.
+ */
+export declare function resolveEffectiveContextWindow(input: EffectiveContextWindowInput): EffectiveContextWindow;
+/** Input to {@link shouldCompact}: an estimate, the model's window, and reserved headroom. */
+export interface ShouldCompactInput {
+    /** Estimated token count of the next request (e.g. from {@link estimateTokens}). */
+    readonly estimated: number;
+    /** The model's total context window, in tokens. */
+    readonly contextWindow: number;
+    /** Tokens to reserve as headroom (output + safety margin). */
+    readonly buffer: number;
+    /**
+     * Tokens reserved for the model's response generation, SEPARATE from `buffer`.
+     * Default 0 — omitting it preserves the legacy
+     * `estimated >= contextWindow - buffer` result.
+     */
+    readonly maxOutput?: number;
+}
+/**
+ * Characters per token in the tokenizer-free estimate below.
+ *
+ * Exported so the ratio has ONE owner. It used to be a named constant in `built-in-processors.ts`
+ * and an inlined `4` here, with both `estimateTokens` functions `@public` from two different package
+ * entry points — so tuning the ratio, or switching to code points instead of UTF-16 units (the
+ * caveat both docblocks already carried), would have silently diverged them.
+ *
+ * @public
+ */
+export declare const CHARS_PER_TOKEN = 4;
+/**
+ * Tokenizer-free token estimate via the conventional ~4-chars-per-token
+ * heuristic: `ceil(text.length / CHARS_PER_TOKEN)`. `""` → 0; any non-empty text → ≥ 1.
+ * A cheap PRE-CALL gate for {@link shouldCompact} — NOT exact tokenization
+ * (a consumer needing exactness supplies their own tokenizer). Uses UTF-16
+ * `.length` (code units), so multibyte text is approximate.
+ *
+ * `built-in-processors.ts` re-exports this under the same name, so both entry points keep working
+ * and there is one implementation behind them.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Decide BEFORE sending whether to compact: `true` when the `estimated` token
+ * count leaves less than `buffer` headroom in the `contextWindow`
+ * (`estimated >= contextWindow - buffer`). A `buffer >= contextWindow`
+ * (non-positive threshold) always returns `true`. Pure — the caller supplies
+ * the window (e.g. from `resolveModelCapabilities`), keeping this decoupled
+ * from the per-model catalog.
+ */
+export declare function shouldCompact(input: ShouldCompactInput): boolean;

package/dist/compaction.js

@@ -0,0 +1,5 @@
+export { ABSOLUTE_CONTEXT_WINDOW_CAP, CHARS_PER_TOKEN, CHECKPOINT_MARKER, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN, ContextWindowMarginError, SUMMARY_TEMPLATE, buildCheckpoint, compactTranscript, estimateTokens, filterFromLatestCheckpoint, isContextOverflowError, resolveEffectiveContextWindow, shouldCompact } from './chunk-6M2OIS4Y.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=compaction.js.map
+//# sourceMappingURL=compaction.js.map

package/dist/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"compaction.js"}

package/dist/concurrency.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var chunkI2PWY7VM_cjs = require('./chunk-I2PWY7VM.cjs');
+var chunkKTTHHYEW_cjs = require('./chunk-KTTHHYEW.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+// src/concurrency.ts
+var Semaphore = class {
+  constructor() {
+  }
+  static create(permits) {
+    return chunkKTTHHYEW_cjs.createSemaphore(permits);
+  }
+};
+
+Object.defineProperty(exports, "mapWithConcurrency", {
+  enumerable: true,
+  get: function () { return chunkI2PWY7VM_cjs.mapWithConcurrency; }
+});
+exports.Semaphore = Semaphore;
+//# sourceMappingURL=concurrency.cjs.map
+//# sourceMappingURL=concurrency.cjs.map

package/dist/concurrency.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/concurrency.ts"],"names":["createSemaphore"],"mappings":";;;;;;;;AAoBO,IAAM,YAAN,MAAgB;AAAA,EACb,WAAA,GAAc;AAAA,EAAC;AAAA,EACvB,OAAO,OAAO,OAAA,EAAiC;AAC7C,IAAA,OAAOA,kCAAgB,OAAO,CAAA;AAAA,EAChC;AACF","file":"concurrency.cjs","sourcesContent":["/**\n * Public concurrency primitives (plan m0-foundation-expose-primitives, M0-2).\n *\n * Thin re-export of the in-house concurrency helpers (ADR D135 — no\n * `p-limit`/`p-map` dependency). Split into its own top-level module so\n * `tsup` builds a dedicated `@theokit/sdk/concurrency` sub-path entry,\n * mirroring the `path-safety` pattern.\n *\n *   - `createSemaphore(permits)` — N-permit async-aware counting semaphore.\n *   - `mapWithConcurrency(items, concurrency, fn, opts?)` — ordered bounded map.\n */\n\nimport { type AsyncSemaphore, createSemaphore } from \"./internal/concurrency/async-semaphore.js\";\n\nexport type { AsyncSemaphore };\n\n/** SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015). @public  *\n * `Semaphore.create` returns an **`AsyncSemaphore`** — the class is the namespace and\n * `AsyncSemaphore` is the type callers hold.\n */\nexport class Semaphore {\n  private constructor() {}\n  static create(permits: number): AsyncSemaphore {\n    return createSemaphore(permits);\n  }\n}\nexport { mapWithConcurrency } from \"./internal/concurrency/map-with-concurrency.js\";\n"]}

package/dist/concurrency.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Public concurrency primitives (plan m0-foundation-expose-primitives, M0-2).
+ *
+ * Thin re-export of the in-house concurrency helpers (ADR D135 — no
+ * `p-limit`/`p-map` dependency). Split into its own top-level module so
+ * `tsup` builds a dedicated `@theokit/sdk/concurrency` sub-path entry,
+ * mirroring the `path-safety` pattern.
+ *
+ *   - `createSemaphore(permits)` — N-permit async-aware counting semaphore.
+ *   - `mapWithConcurrency(items, concurrency, fn, opts?)` — ordered bounded map.
+ */
+import { type AsyncSemaphore } from "./internal/concurrency/async-semaphore.js";
+export type { AsyncSemaphore };
+/** SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015). @public  *
+ * `Semaphore.create` returns an **`AsyncSemaphore`** — the class is the namespace and
+ * `AsyncSemaphore` is the type callers hold.
+ */
+export declare class Semaphore {
+    private constructor();
+    static create(permits: number): AsyncSemaphore;
+}
+export { mapWithConcurrency } from "./internal/concurrency/map-with-concurrency.js";

package/dist/concurrency.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Public concurrency primitives (plan m0-foundation-expose-primitives, M0-2).
+ *
+ * Thin re-export of the in-house concurrency helpers (ADR D135 — no
+ * `p-limit`/`p-map` dependency). Split into its own top-level module so
+ * `tsup` builds a dedicated `@theokit/sdk/concurrency` sub-path entry,
+ * mirroring the `path-safety` pattern.
+ *
+ *   - `createSemaphore(permits)` — N-permit async-aware counting semaphore.
+ *   - `mapWithConcurrency(items, concurrency, fn, opts?)` — ordered bounded map.
+ */
+import { type AsyncSemaphore } from "./internal/concurrency/async-semaphore.js";
+export type { AsyncSemaphore };
+/** SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015). @public  *
+ * `Semaphore.create` returns an **`AsyncSemaphore`** — the class is the namespace and
+ * `AsyncSemaphore` is the type callers hold.
+ */
+export declare class Semaphore {
+    private constructor();
+    static create(permits: number): AsyncSemaphore;
+}
+export { mapWithConcurrency } from "./internal/concurrency/map-with-concurrency.js";

package/dist/concurrency.js

@@ -0,0 +1,17 @@
+export { mapWithConcurrency } from './chunk-4MMWFSCD.js';
+import { createSemaphore } from './chunk-G7BLGBRN.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+
+// src/concurrency.ts
+var Semaphore = class {
+  constructor() {
+  }
+  static create(permits) {
+    return createSemaphore(permits);
+  }
+};
+
+export { Semaphore };
+//# sourceMappingURL=concurrency.js.map
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/concurrency.ts"],"names":[],"mappings":";;;;;;AAoBO,IAAM,YAAN,MAAgB;AAAA,EACb,WAAA,GAAc;AAAA,EAAC;AAAA,EACvB,OAAO,OAAO,OAAA,EAAiC;AAC7C,IAAA,OAAO,gBAAgB,OAAO,CAAA;AAAA,EAChC;AACF","file":"concurrency.js","sourcesContent":["/**\n * Public concurrency primitives (plan m0-foundation-expose-primitives, M0-2).\n *\n * Thin re-export of the in-house concurrency helpers (ADR D135 — no\n * `p-limit`/`p-map` dependency). Split into its own top-level module so\n * `tsup` builds a dedicated `@theokit/sdk/concurrency` sub-path entry,\n * mirroring the `path-safety` pattern.\n *\n *   - `createSemaphore(permits)` — N-permit async-aware counting semaphore.\n *   - `mapWithConcurrency(items, concurrency, fn, opts?)` — ordered bounded map.\n */\n\nimport { type AsyncSemaphore, createSemaphore } from \"./internal/concurrency/async-semaphore.js\";\n\nexport type { AsyncSemaphore };\n\n/** SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015). @public  *\n * `Semaphore.create` returns an **`AsyncSemaphore`** — the class is the namespace and\n * `AsyncSemaphore` is the type callers hold.\n */\nexport class Semaphore {\n  private constructor() {}\n  static create(permits: number): AsyncSemaphore {\n    return createSemaphore(permits);\n  }\n}\nexport { mapWithConcurrency } from \"./internal/concurrency/map-with-concurrency.js\";\n"]}

package/dist/context/index.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+var chunkIU5N5224_cjs = require('../chunk-IU5N5224.cjs');
+require('../chunk-KRD3GQAA.cjs');
+var chunkLOHMT36V_cjs = require('../chunk-LOHMT36V.cjs');
+require('../chunk-SA6K24NB.cjs');
+
+// src/context/index.ts
+function resolveContextImports(content, basePath, options) {
+  const internalOptions = {
+    visited: options.visited ?? /* @__PURE__ */ new Set(),
+    depth: options.depth ?? 0,
+    maxBytesPerFile: options.maxBytesPerFile,
+    projectRoot: options.projectRoot
+  };
+  return chunkIU5N5224_cjs.resolveImports(content, basePath, internalOptions);
+}
+
+Object.defineProperty(exports, "parseRules", {
+  enumerable: true,
+  get: function () { return chunkIU5N5224_cjs.parseRules; }
+});
+Object.defineProperty(exports, "runDiscovery", {
+  enumerable: true,
+  get: function () { return chunkIU5N5224_cjs.runDiscovery; }
+});
+Object.defineProperty(exports, "shouldActivateRule", {
+  enumerable: true,
+  get: function () { return chunkIU5N5224_cjs.shouldActivateRule; }
+});
+Object.defineProperty(exports, "DEFAULT_DISCOVERY_SPECS", {
+  enumerable: true,
+  get: function () { return chunkLOHMT36V_cjs.DEFAULT_DISCOVERY_SPECS; }
+});
+exports.resolveContextImports = resolveContextImports;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/context/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/context/index.ts"],"names":["resolveImports"],"mappings":";;;;;;;;AA+FO,SAAS,qBAAA,CACd,OAAA,EACA,QAAA,EACA,OAAA,EACiB;AACjB,EAAA,MAAM,eAAA,GAAyC;AAAA,IAC7C,OAAA,EAAS,OAAA,CAAQ,OAAA,oBAAW,IAAI,GAAA,EAAY;AAAA,IAC5C,KAAA,EAAO,QAAQ,KAAA,IAAS,CAAA;AAAA,IACxB,iBAAiB,OAAA,CAAQ,eAAA;AAAA,IACzB,aAAa,OAAA,CAAQ;AAAA,GACvB;AACA,EAAA,OAAOA,gCAAA,CAAuB,OAAA,EAAS,QAAA,EAAU,eAAe,CAAA;AAClE","file":"index.cjs","sourcesContent":["/**\n * `@theokit/sdk/context` — context assembly, as a SANCTIONED PUBLIC surface.\n *\n * Everything re-exported here is under semver. That is the whole difference from the\n * `internal/*` subpaths (`internal/persistence`, `internal/security`, `internal/memory-adapters`),\n * which the package documents as \"internal API — semver-exempt\" and is retiring:\n * `internal/persistence` is `@deprecated` in favour of the sanctioned `@theokit/sdk/persistence`,\n * and `internal/plugins` + `internal/observability` were deleted as dead public surface in July.\n *\n * **The list is explicit and there is no `export *`.** The tree behind it holds 13 files, including\n * YAML shims and parser internals a consumer never needs. Publishing the directory would commit\n * this package to every file in it; widening this list is a deliberate act.\n *\n * @public\n */\n\nimport {\n  type ResolveImportsOptions,\n  resolveImports as resolveImportsInternal,\n} from \"../internal/runtime/context/context-import-resolver.js\";\n\nexport type {\n  DiscoveryParser,\n  DiscoveryScope,\n  DiscoverySpec,\n} from \"../internal/runtime/context/context-discovery.js\";\n/**\n * The seven conventions {@link runDiscovery} looks for when `specs` is omitted — `AGENTS.md`,\n * `GEMINI.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `.theokit/rules/*.md`, `.theokit/context/*.md`\n * and `.theokit/THEO.md`.\n *\n * Exported because `specs` REPLACES this list rather than extending it. Without the constant, a\n * consumer registering one convention of its own silently loses every built-in one, and the loss is\n * invisible — discovery simply returns fewer sources. Spread it to extend:\n *\n * ```ts\n * await runDiscovery({ cwd, maxBytesPerFile, specs: [...DEFAULT_DISCOVERY_SPECS, mySpec] });\n * ```\n *\n * @public\n */\nexport { DEFAULT_DISCOVERY_SPECS } from \"../internal/runtime/context/context-discovery.js\";\nexport {\n  type DiscoveryRunnerOptions,\n  runDiscovery,\n} from \"../internal/runtime/context/context-discovery-runner.js\";\nexport {\n  parseRules,\n  shouldActivateRule,\n} from \"../internal/runtime/context/context-rules-frontmatter.js\";\n\n/**\n * Options for {@link resolveContextImports}.\n *\n * `projectRoot` is REQUIRED here and OPTIONAL on the internal `resolveImports`, and the asymmetry\n * is the point rather than an oversight.\n *\n * Internally the field has to be optional: it was added in 4.41.1 to close a defect where a\n * repository-supplied `CLAUDE.md` could name `@~/.ssh/id_rsa` and have that file inlined into the\n * agent's system prompt, and making it required would have broken every caller that predates it.\n *\n * As a PUBLIC contract the same optionality inverts into a trap. The obvious call omits the field,\n * compiles, and silently restores the un-contained behaviour — so the easiest way to use the API\n * would be the unsafe one, published under semver and therefore unfixable without a breaking\n * change. Requiring it makes the safe call the only call.\n *\n * @public\n */\nexport interface ResolveContextImportsOptions {\n  /**\n   * The directory an `@import` may not escape, compared after symlink resolution.\n   *\n   * A document carrying imports is repository-controlled — untrusted input whenever the repository\n   * came from somewhere else — so the boundary is not optional.\n   */\n  readonly projectRoot: string;\n  /** Per-import file cap, forwarded to the loader. */\n  readonly maxBytesPerFile: number;\n  /** Absolute paths already resolved, for cycle detection. Defaults to an empty set. */\n  readonly visited?: Set<string>;\n  /** Current recursion depth. Defaults to 0; the resolver caps at 5 hops. */\n  readonly depth?: number;\n}\n\n/**\n * Expand `@path` import directives in `content`, confined to `options.projectRoot`.\n *\n * A line that is exactly `@some/path` is replaced with that file's content, recursively, with cycle\n * detection and a 5-hop cap. A target resolving outside the root — by `..`, by an absolute path, by\n * `~/`, or through a symlink — is replaced with a refusal placeholder rather than its bytes, and the\n * placeholder echoes the path as the author wrote it rather than as resolved, so a refusal does not\n * leak the layout of the machine back into the same untrusted document.\n *\n * @public\n */\nexport function resolveContextImports(\n  content: string,\n  basePath: string,\n  options: ResolveContextImportsOptions,\n): Promise<string> {\n  const internalOptions: ResolveImportsOptions = {\n    visited: options.visited ?? new Set<string>(),\n    depth: options.depth ?? 0,\n    maxBytesPerFile: options.maxBytesPerFile,\n    projectRoot: options.projectRoot,\n  };\n  return resolveImportsInternal(content, basePath, internalOptions);\n}\n"]}

package/dist/context/index.d.cts

@@ -0,0 +1,78 @@
+/**
+ * `@theokit/sdk/context` — context assembly, as a SANCTIONED PUBLIC surface.
+ *
+ * Everything re-exported here is under semver. That is the whole difference from the
+ * `internal/*` subpaths (`internal/persistence`, `internal/security`, `internal/memory-adapters`),
+ * which the package documents as "internal API — semver-exempt" and is retiring:
+ * `internal/persistence` is `@deprecated` in favour of the sanctioned `@theokit/sdk/persistence`,
+ * and `internal/plugins` + `internal/observability` were deleted as dead public surface in July.
+ *
+ * **The list is explicit and there is no `export *`.** The tree behind it holds 13 files, including
+ * YAML shims and parser internals a consumer never needs. Publishing the directory would commit
+ * this package to every file in it; widening this list is a deliberate act.
+ *
+ * @public
+ */
+export type { DiscoveryParser, DiscoveryScope, DiscoverySpec, } from "../internal/runtime/context/context-discovery.js";
+/**
+ * The seven conventions {@link runDiscovery} looks for when `specs` is omitted — `AGENTS.md`,
+ * `GEMINI.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `.theokit/rules/*.md`, `.theokit/context/*.md`
+ * and `.theokit/THEO.md`.
+ *
+ * Exported because `specs` REPLACES this list rather than extending it. Without the constant, a
+ * consumer registering one convention of its own silently loses every built-in one, and the loss is
+ * invisible — discovery simply returns fewer sources. Spread it to extend:
+ *
+ * ```ts
+ * await runDiscovery({ cwd, maxBytesPerFile, specs: [...DEFAULT_DISCOVERY_SPECS, mySpec] });
+ * ```
+ *
+ * @public
+ */
+export { DEFAULT_DISCOVERY_SPECS } from "../internal/runtime/context/context-discovery.js";
+export { type DiscoveryRunnerOptions, runDiscovery, } from "../internal/runtime/context/context-discovery-runner.js";
+export { parseRules, shouldActivateRule, } from "../internal/runtime/context/context-rules-frontmatter.js";
+/**
+ * Options for {@link resolveContextImports}.
+ *
+ * `projectRoot` is REQUIRED here and OPTIONAL on the internal `resolveImports`, and the asymmetry
+ * is the point rather than an oversight.
+ *
+ * Internally the field has to be optional: it was added in 4.41.1 to close a defect where a
+ * repository-supplied `CLAUDE.md` could name `@~/.ssh/id_rsa` and have that file inlined into the
+ * agent's system prompt, and making it required would have broken every caller that predates it.
+ *
+ * As a PUBLIC contract the same optionality inverts into a trap. The obvious call omits the field,
+ * compiles, and silently restores the un-contained behaviour — so the easiest way to use the API
+ * would be the unsafe one, published under semver and therefore unfixable without a breaking
+ * change. Requiring it makes the safe call the only call.
+ *
+ * @public
+ */
+export interface ResolveContextImportsOptions {
+    /**
+     * The directory an `@import` may not escape, compared after symlink resolution.
+     *
+     * A document carrying imports is repository-controlled — untrusted input whenever the repository
+     * came from somewhere else — so the boundary is not optional.
+     */
+    readonly projectRoot: string;
+    /** Per-import file cap, forwarded to the loader. */
+    readonly maxBytesPerFile: number;
+    /** Absolute paths already resolved, for cycle detection. Defaults to an empty set. */
+    readonly visited?: Set<string>;
+    /** Current recursion depth. Defaults to 0; the resolver caps at 5 hops. */
+    readonly depth?: number;
+}
+/**
+ * Expand `@path` import directives in `content`, confined to `options.projectRoot`.
+ *
+ * A line that is exactly `@some/path` is replaced with that file's content, recursively, with cycle
+ * detection and a 5-hop cap. A target resolving outside the root — by `..`, by an absolute path, by
+ * `~/`, or through a symlink — is replaced with a refusal placeholder rather than its bytes, and the
+ * placeholder echoes the path as the author wrote it rather than as resolved, so a refusal does not
+ * leak the layout of the machine back into the same untrusted document.
+ *
+ * @public
+ */
+export declare function resolveContextImports(content: string, basePath: string, options: ResolveContextImportsOptions): Promise<string>;

package/dist/context/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `@theokit/sdk/context` — context assembly, as a SANCTIONED PUBLIC surface.
+ *
+ * Everything re-exported here is under semver. That is the whole difference from the
+ * `internal/*` subpaths (`internal/persistence`, `internal/security`, `internal/memory-adapters`),
+ * which the package documents as "internal API — semver-exempt" and is retiring:
+ * `internal/persistence` is `@deprecated` in favour of the sanctioned `@theokit/sdk/persistence`,
+ * and `internal/plugins` + `internal/observability` were deleted as dead public surface in July.
+ *
+ * **The list is explicit and there is no `export *`.** The tree behind it holds 13 files, including
+ * YAML shims and parser internals a consumer never needs. Publishing the directory would commit
+ * this package to every file in it; widening this list is a deliberate act.
+ *
+ * @public
+ */
+export type { DiscoveryParser, DiscoveryScope, DiscoverySpec, } from "../internal/runtime/context/context-discovery.js";
+/**
+ * The seven conventions {@link runDiscovery} looks for when `specs` is omitted — `AGENTS.md`,
+ * `GEMINI.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `.theokit/rules/*.md`, `.theokit/context/*.md`
+ * and `.theokit/THEO.md`.
+ *
+ * Exported because `specs` REPLACES this list rather than extending it. Without the constant, a
+ * consumer registering one convention of its own silently loses every built-in one, and the loss is
+ * invisible — discovery simply returns fewer sources. Spread it to extend:
+ *
+ * ```ts
+ * await runDiscovery({ cwd, maxBytesPerFile, specs: [...DEFAULT_DISCOVERY_SPECS, mySpec] });
+ * ```
+ *
+ * @public
+ */
+export { DEFAULT_DISCOVERY_SPECS } from "../internal/runtime/context/context-discovery.js";
+export { type DiscoveryRunnerOptions, runDiscovery, } from "../internal/runtime/context/context-discovery-runner.js";
+export { parseRules, shouldActivateRule, } from "../internal/runtime/context/context-rules-frontmatter.js";
+/**
+ * Options for {@link resolveContextImports}.
+ *
+ * `projectRoot` is REQUIRED here and OPTIONAL on the internal `resolveImports`, and the asymmetry
+ * is the point rather than an oversight.
+ *
+ * Internally the field has to be optional: it was added in 4.41.1 to close a defect where a
+ * repository-supplied `CLAUDE.md` could name `@~/.ssh/id_rsa` and have that file inlined into the
+ * agent's system prompt, and making it required would have broken every caller that predates it.
+ *
+ * As a PUBLIC contract the same optionality inverts into a trap. The obvious call omits the field,
+ * compiles, and silently restores the un-contained behaviour — so the easiest way to use the API
+ * would be the unsafe one, published under semver and therefore unfixable without a breaking
+ * change. Requiring it makes the safe call the only call.
+ *
+ * @public
+ */
+export interface ResolveContextImportsOptions {
+    /**
+     * The directory an `@import` may not escape, compared after symlink resolution.
+     *
+     * A document carrying imports is repository-controlled — untrusted input whenever the repository
+     * came from somewhere else — so the boundary is not optional.
+     */
+    readonly projectRoot: string;
+    /** Per-import file cap, forwarded to the loader. */
+    readonly maxBytesPerFile: number;
+    /** Absolute paths already resolved, for cycle detection. Defaults to an empty set. */
+    readonly visited?: Set<string>;
+    /** Current recursion depth. Defaults to 0; the resolver caps at 5 hops. */
+    readonly depth?: number;
+}
+/**
+ * Expand `@path` import directives in `content`, confined to `options.projectRoot`.
+ *
+ * A line that is exactly `@some/path` is replaced with that file's content, recursively, with cycle
+ * detection and a 5-hop cap. A target resolving outside the root — by `..`, by an absolute path, by
+ * `~/`, or through a symlink — is replaced with a refusal placeholder rather than its bytes, and the
+ * placeholder echoes the path as the author wrote it rather than as resolved, so a refusal does not
+ * leak the layout of the machine back into the same untrusted document.
+ *
+ * @public
+ */
+export declare function resolveContextImports(content: string, basePath: string, options: ResolveContextImportsOptions): Promise<string>;

package/dist/context/index.js

@@ -0,0 +1,20 @@
+import { resolveImports } from '../chunk-N6OOOYFZ.js';
+export { parseRules, runDiscovery, shouldActivateRule } from '../chunk-N6OOOYFZ.js';
+import '../chunk-KVNWIAO4.js';
+export { DEFAULT_DISCOVERY_SPECS } from '../chunk-2XRAWOZZ.js';
+import '../chunk-UKMBRMGT.js';
+
+// src/context/index.ts
+function resolveContextImports(content, basePath, options) {
+  const internalOptions = {
+    visited: options.visited ?? /* @__PURE__ */ new Set(),
+    depth: options.depth ?? 0,
+    maxBytesPerFile: options.maxBytesPerFile,
+    projectRoot: options.projectRoot
+  };
+  return resolveImports(content, basePath, internalOptions);
+}
+
+export { resolveContextImports };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/context/index.ts"],"names":[],"mappings":";;;;;;;AA+FO,SAAS,qBAAA,CACd,OAAA,EACA,QAAA,EACA,OAAA,EACiB;AACjB,EAAA,MAAM,eAAA,GAAyC;AAAA,IAC7C,OAAA,EAAS,OAAA,CAAQ,OAAA,oBAAW,IAAI,GAAA,EAAY;AAAA,IAC5C,KAAA,EAAO,QAAQ,KAAA,IAAS,CAAA;AAAA,IACxB,iBAAiB,OAAA,CAAQ,eAAA;AAAA,IACzB,aAAa,OAAA,CAAQ;AAAA,GACvB;AACA,EAAA,OAAO,cAAA,CAAuB,OAAA,EAAS,QAAA,EAAU,eAAe,CAAA;AAClE","file":"index.js","sourcesContent":["/**\n * `@theokit/sdk/context` — context assembly, as a SANCTIONED PUBLIC surface.\n *\n * Everything re-exported here is under semver. That is the whole difference from the\n * `internal/*` subpaths (`internal/persistence`, `internal/security`, `internal/memory-adapters`),\n * which the package documents as \"internal API — semver-exempt\" and is retiring:\n * `internal/persistence` is `@deprecated` in favour of the sanctioned `@theokit/sdk/persistence`,\n * and `internal/plugins` + `internal/observability` were deleted as dead public surface in July.\n *\n * **The list is explicit and there is no `export *`.** The tree behind it holds 13 files, including\n * YAML shims and parser internals a consumer never needs. Publishing the directory would commit\n * this package to every file in it; widening this list is a deliberate act.\n *\n * @public\n */\n\nimport {\n  type ResolveImportsOptions,\n  resolveImports as resolveImportsInternal,\n} from \"../internal/runtime/context/context-import-resolver.js\";\n\nexport type {\n  DiscoveryParser,\n  DiscoveryScope,\n  DiscoverySpec,\n} from \"../internal/runtime/context/context-discovery.js\";\n/**\n * The seven conventions {@link runDiscovery} looks for when `specs` is omitted — `AGENTS.md`,\n * `GEMINI.md`, `CLAUDE.md`, `.cursor/rules/*.mdc`, `.theokit/rules/*.md`, `.theokit/context/*.md`\n * and `.theokit/THEO.md`.\n *\n * Exported because `specs` REPLACES this list rather than extending it. Without the constant, a\n * consumer registering one convention of its own silently loses every built-in one, and the loss is\n * invisible — discovery simply returns fewer sources. Spread it to extend:\n *\n * ```ts\n * await runDiscovery({ cwd, maxBytesPerFile, specs: [...DEFAULT_DISCOVERY_SPECS, mySpec] });\n * ```\n *\n * @public\n */\nexport { DEFAULT_DISCOVERY_SPECS } from \"../internal/runtime/context/context-discovery.js\";\nexport {\n  type DiscoveryRunnerOptions,\n  runDiscovery,\n} from \"../internal/runtime/context/context-discovery-runner.js\";\nexport {\n  parseRules,\n  shouldActivateRule,\n} from \"../internal/runtime/context/context-rules-frontmatter.js\";\n\n/**\n * Options for {@link resolveContextImports}.\n *\n * `projectRoot` is REQUIRED here and OPTIONAL on the internal `resolveImports`, and the asymmetry\n * is the point rather than an oversight.\n *\n * Internally the field has to be optional: it was added in 4.41.1 to close a defect where a\n * repository-supplied `CLAUDE.md` could name `@~/.ssh/id_rsa` and have that file inlined into the\n * agent's system prompt, and making it required would have broken every caller that predates it.\n *\n * As a PUBLIC contract the same optionality inverts into a trap. The obvious call omits the field,\n * compiles, and silently restores the un-contained behaviour — so the easiest way to use the API\n * would be the unsafe one, published under semver and therefore unfixable without a breaking\n * change. Requiring it makes the safe call the only call.\n *\n * @public\n */\nexport interface ResolveContextImportsOptions {\n  /**\n   * The directory an `@import` may not escape, compared after symlink resolution.\n   *\n   * A document carrying imports is repository-controlled — untrusted input whenever the repository\n   * came from somewhere else — so the boundary is not optional.\n   */\n  readonly projectRoot: string;\n  /** Per-import file cap, forwarded to the loader. */\n  readonly maxBytesPerFile: number;\n  /** Absolute paths already resolved, for cycle detection. Defaults to an empty set. */\n  readonly visited?: Set<string>;\n  /** Current recursion depth. Defaults to 0; the resolver caps at 5 hops. */\n  readonly depth?: number;\n}\n\n/**\n * Expand `@path` import directives in `content`, confined to `options.projectRoot`.\n *\n * A line that is exactly `@some/path` is replaced with that file's content, recursively, with cycle\n * detection and a 5-hop cap. A target resolving outside the root — by `..`, by an absolute path, by\n * `~/`, or through a symlink — is replaced with a refusal placeholder rather than its bytes, and the\n * placeholder echoes the path as the author wrote it rather than as resolved, so a refusal does not\n * leak the layout of the machine back into the same untrusted document.\n *\n * @public\n */\nexport function resolveContextImports(\n  content: string,\n  basePath: string,\n  options: ResolveContextImportsOptions,\n): Promise<string> {\n  const internalOptions: ResolveImportsOptions = {\n    visited: options.visited ?? new Set<string>(),\n    depth: options.depth ?? 0,\n    maxBytesPerFile: options.maxBytesPerFile,\n    projectRoot: options.projectRoot,\n  };\n  return resolveImportsInternal(content, basePath, internalOptions);\n}\n"]}

package/dist/context-4QOEWRDF.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var chunkKGANQYP7_cjs = require('./chunk-KGANQYP7.cjs');
+require('./chunk-NYQ3IS7K.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "currentPersonalityContext", {
+  enumerable: true,
+  get: function () { return chunkKGANQYP7_cjs.currentPersonalityContext; }
+});
+Object.defineProperty(exports, "warnPersonalitySwitchInsideFork", {
+  enumerable: true,
+  get: function () { return chunkKGANQYP7_cjs.warnPersonalitySwitchInsideFork; }
+});
+Object.defineProperty(exports, "withPersonalityContext", {
+  enumerable: true,
+  get: function () { return chunkKGANQYP7_cjs.withPersonalityContext; }
+});
+//# sourceMappingURL=context-4QOEWRDF.cjs.map
+//# sourceMappingURL=context-4QOEWRDF.cjs.map

package/dist/context-4QOEWRDF.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"context-4QOEWRDF.cjs"}

package/dist/context-Z3CFTT3H.js

@@ -0,0 +1,6 @@
+export { currentPersonalityContext, warnPersonalitySwitchInsideFork, withPersonalityContext } from './chunk-AW6F6HZR.js';
+import './chunk-WMWEI3NS.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=context-Z3CFTT3H.js.map
+//# sourceMappingURL=context-Z3CFTT3H.js.map

package/dist/context-Z3CFTT3H.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"context-Z3CFTT3H.js"}