@phamvuhoang/otto-core 0.22.0 → 0.24.0

package/dist/external-skills.js

@@ -0,0 +1,417 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { skillDir, skillExists, toSkillName, writeSkill, } from "./skills.js";
+const SOURCES_REL = join(".otto", "skills", "sources.json");
+const LOCK_REL = join(".otto", "skills.lock.json");
+const SKILL_MD = "SKILL.md";
+const MAX_DEPTH = 8;
+/** Absolute path to the sources config (`.otto/skills/sources.json`). */
+export function sourcesPath(workspaceDir) {
+    return join(workspaceDir, SOURCES_REL);
+}
+/** Absolute path to the import lockfile (`.otto/skills.lock.json`). */
+export function lockPath(workspaceDir) {
+    return join(workspaceDir, LOCK_REL);
+}
+const SOURCE_TYPES = new Set([
+    "git",
+    "local",
+    "archive",
+    "registry",
+]);
+function stringArray(raw) {
+    return Array.isArray(raw)
+        ? raw.filter((s) => typeof s === "string")
+        : [];
+}
+/** Normalize one untrusted source entry; null when it lacks the required shape. */
+export function parseSource(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    if (typeof o.name !== "string" || o.name.length === 0)
+        return null;
+    if (typeof o.location !== "string" || o.location.length === 0)
+        return null;
+    const type = typeof o.type === "string" && SOURCE_TYPES.has(o.type)
+        ? o.type
+        : "local";
+    const src = { name: o.name, type, location: o.location };
+    if (typeof o.ref === "string" && o.ref.length > 0)
+        src.ref = o.ref;
+    return src;
+}
+/** Read configured sources; absent/malformed → `[]` (never throws). */
+export function readSources(workspaceDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(sourcesPath(workspaceDir), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const list = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed.sources
+        : parsed;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const r of list) {
+        const s = parseSource(r);
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+/** Write the sources config, sorted by name for deterministic diffs. */
+export function writeSources(workspaceDir, sources) {
+    const sorted = [...sources].sort((a, b) => a.name.localeCompare(b.name));
+    writeFileSync(sourcesPath(workspaceDir), JSON.stringify({ sources: sorted }, null, 2) + "\n");
+}
+function parseLockEntry(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    if (typeof o.skill !== "string" || typeof o.source !== "string")
+        return null;
+    if (typeof o.checksum !== "string" || typeof o.importedAt !== "string") {
+        return null;
+    }
+    const type = typeof o.type === "string" && SOURCE_TYPES.has(o.type)
+        ? o.type
+        : "local";
+    const e = {
+        skill: o.skill,
+        source: o.source,
+        type,
+        upstreamPath: typeof o.upstreamPath === "string" ? o.upstreamPath : "",
+        checksum: o.checksum,
+        importedAt: o.importedAt,
+        capabilities: stringArray(o.capabilities),
+    };
+    if (typeof o.ref === "string")
+        e.ref = o.ref;
+    if (typeof o.license === "string")
+        e.license = o.license;
+    return e;
+}
+/** Read the import lock; absent/malformed → `{ entries: [] }` (never throws). */
+export function readLock(workspaceDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(lockPath(workspaceDir), "utf8"));
+    }
+    catch {
+        return { entries: [] };
+    }
+    const list = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed.entries
+        : parsed;
+    if (!Array.isArray(list))
+        return { entries: [] };
+    const entries = [];
+    for (const r of list) {
+        const e = parseLockEntry(r);
+        if (e)
+            entries.push(e);
+    }
+    return { entries };
+}
+/** Write the lock, entries sorted by skill name for deterministic diffs. */
+export function writeLock(workspaceDir, lock) {
+    const entries = [...lock.entries].sort((a, b) => a.skill.localeCompare(b.skill));
+    writeFileSync(lockPath(workspaceDir), JSON.stringify({ entries }, null, 2) + "\n");
+}
+/** Add (or replace by name) a source. Pure — returns a new array. */
+export function addSource(sources, source) {
+    return [...sources.filter((s) => s.name !== source.name), source];
+}
+/** Remove a source by name. Pure — returns a new array. */
+export function removeSource(sources, name) {
+    return sources.filter((s) => s.name !== name);
+}
+/** sha256 of a buffer/string, hex (stable content checksum). */
+function checksum(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * Parse a leading `--- … ---` frontmatter block into flat string fields plus the
+ * remaining body. Minimal `key: value` parsing (no nested YAML) — enough for the
+ * `name`/`description`/`license`/`capabilities` fields skill packs declare.
+ */
+export function parseFrontmatter(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!m)
+        return { fields: {}, body: text };
+    const fields = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (kv)
+            fields[kv[1].toLowerCase()] = kv[2].trim();
+    }
+    return { fields, body: text.slice(m[0].length) };
+}
+function splitList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .replace(/^\[|\]$/g, "")
+        .split(",")
+        .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+        .filter((s) => s.length > 0);
+}
+function listDirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find every `SKILL.md` package under a local source directory (recursively,
+ * depth-bounded). Covers the `skills/<name>/SKILL.md` Superpowers/PM-Skills shape
+ * and `.codex-plugin`/`.claude-plugin` bundles that nest the same file. Each
+ * package's skill name comes from its SKILL.md `name:` frontmatter, else its
+ * containing directory name, slugified. Returns packages sorted by name. Absent/
+ * unreadable dir → `[]` (never throws).
+ */
+export function discoverPackages(sourceDir) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > MAX_DEPTH)
+            return;
+        const mdPath = join(dir, SKILL_MD);
+        if (existsSync(mdPath)) {
+            let raw;
+            try {
+                raw = readFileSync(mdPath, "utf8");
+            }
+            catch {
+                raw = "";
+            }
+            const { fields } = parseFrontmatter(raw);
+            const rel = relative(sourceDir, dir);
+            const name = toSkillName(fields.name ?? "") ||
+                toSkillName(rel.split(sep).pop() ?? "") ||
+                toSkillName(rel);
+            if (name) {
+                found.push({
+                    name,
+                    upstreamPath: rel === "" ? "." : rel.split(sep).join("/"),
+                    raw,
+                });
+            }
+            return; // a package directory is a leaf; don't descend into it
+        }
+        for (const child of listDirs(dir))
+            walk(join(dir, child), depth + 1);
+    };
+    walk(sourceDir, 0);
+    return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Normalize a discovered package + its source into an unverified, inert
+ * {@link Skill} plus the resolved {@link ExternalSkillLockEntry}. The skill body
+ * is the SKILL.md content minus frontmatter; capabilities come from a
+ * `capabilities:` frontmatter field when present (else empty); trust is always
+ * `unverified` and validation empty so the loop cannot apply it. `now` is the
+ * import timestamp (injected for deterministic tests).
+ */
+export function normalizePackage(source, pkg, now) {
+    const { fields, body } = parseFrontmatter(pkg.raw);
+    const capabilities = splitList(fields.capabilities);
+    const license = fields.license;
+    // Checksum the persisted body (what lands in instructions.md) so a later audit
+    // can recompute it from disk and detect hand-edits after import.
+    const instructions = body.trim() + "\n";
+    const sum = checksum(instructions);
+    const provenance = {
+        source: source.name,
+        upstreamPath: pkg.upstreamPath,
+        checksum: sum,
+    };
+    if (source.ref)
+        provenance.upstreamRef = source.ref;
+    if (license)
+        provenance.license = license;
+    const skill = {
+        name: pkg.name,
+        version: typeof fields.version === "string" ? fields.version : "0.0.0",
+        capabilities,
+        constraints: [],
+        scope: [],
+        instructions,
+        scripts: {},
+        tests: [],
+        validation: {},
+        trust: "unverified",
+        createdAt: now.toISOString(),
+        useCount: 0,
+        provenance,
+    };
+    const entry = {
+        skill: pkg.name,
+        source: source.name,
+        type: source.type,
+        upstreamPath: pkg.upstreamPath,
+        checksum: sum,
+        importedAt: now.toISOString(),
+        capabilities,
+    };
+    if (source.ref)
+        entry.ref = source.ref;
+    if (license)
+        entry.license = license;
+    return { skill, entry };
+}
+/**
+ * Compute a deterministic sync plan over the given local sources without writing
+ * anything — the engine behind both `sync --dry-run` and `sync`. For each source
+ * (in name order) every discovered package is classified:
+ *
+ * - `conflict`  — a different source earlier in the plan already claims the name;
+ * - `add`       — the skill is not present on disk;
+ * - `update`    — present, but the lock's recorded checksum differs (drift);
+ * - `unchanged` — present and the checksum matches the lock.
+ *
+ * Only `local` sources resolve in this slice; other types are skipped (a later
+ * slice adds git/archive fetch ahead of this same planner).
+ */
+export function planSync(workspaceDir, sources, now) {
+    const lock = readLock(workspaceDir);
+    const lockBySkill = new Map(lock.entries.map((e) => [e.skill, e]));
+    const claimedBy = new Map();
+    const items = [];
+    for (const source of [...sources].sort((a, b) => a.name.localeCompare(b.name))) {
+        if (source.type !== "local")
+            continue;
+        for (const pkg of discoverPackages(source.location)) {
+            const resolved = normalizePackage(source, pkg, now);
+            const claimer = claimedBy.get(pkg.name);
+            if (claimer && claimer !== source.name) {
+                items.push({
+                    skill: pkg.name,
+                    source: source.name,
+                    action: "conflict",
+                    conflictWith: claimer,
+                    resolved,
+                });
+                continue;
+            }
+            claimedBy.set(pkg.name, source.name);
+            let action;
+            const locked = lockBySkill.get(pkg.name);
+            if (!skillExists(workspaceDir, pkg.name) || !locked) {
+                action = "add";
+            }
+            else if (locked.checksum !== resolved.entry.checksum) {
+                action = "update";
+            }
+            else {
+                action = "unchanged";
+            }
+            items.push({ skill: pkg.name, source: source.name, action, resolved });
+        }
+    }
+    return { items };
+}
+/**
+ * Apply a sync plan: write each `add`/`update` skill package and refresh the lock
+ * to exactly the set of resolved (non-conflict) packages. `conflict` items are
+ * skipped (logged by the caller). Returns the persisted lock. Side-effecting
+ * counterpart to {@link planSync}; the dry-run path calls `planSync` only.
+ */
+export function applySync(workspaceDir, plan) {
+    const entries = [];
+    for (const item of plan.items) {
+        if (item.action === "conflict")
+            continue;
+        if (item.action === "add" || item.action === "update") {
+            writeSkill(workspaceDir, item.resolved.skill);
+        }
+        entries.push(item.resolved.entry);
+    }
+    const lock = { entries };
+    writeLock(workspaceDir, lock);
+    return lock;
+}
+/**
+ * Audit the external registry (`otto-skills audit --external`). Surfaces:
+ * unpinned source refs, lock entries with no license, duplicate skill names
+ * across sources, sources whose type this slice cannot resolve, and stale
+ * imported copies (on-disk skill checksum drifted from the lock). Pure over the
+ * given sources/lock + a checksum probe; deterministic, sorted by kind+subject.
+ */
+export function auditExternal(sources, lock, onDiskChecksum) {
+    const findings = [];
+    for (const s of sources) {
+        if ((s.type === "git" || s.type === "archive") && !s.ref) {
+            findings.push({
+                kind: "unpinned-ref",
+                subject: s.name,
+                detail: `source "${s.name}" (${s.type}) has no pinned ref`,
+            });
+        }
+        if (s.type === "registry") {
+            findings.push({
+                kind: "unsupported-format",
+                subject: s.name,
+                detail: `source type "registry" is not resolvable yet`,
+            });
+        }
+    }
+    const bySkill = new Map();
+    for (const e of lock.entries) {
+        (bySkill.get(e.skill) ?? bySkill.set(e.skill, []).get(e.skill)).push(e);
+    }
+    for (const [skill, es] of bySkill) {
+        if (es.length > 1) {
+            const srcs = [...new Set(es.map((e) => e.source))].sort();
+            if (srcs.length > 1) {
+                findings.push({
+                    kind: "duplicate-name",
+                    subject: skill,
+                    detail: `skill "${skill}" imported from multiple sources: ${srcs.join(", ")}`,
+                });
+            }
+        }
+    }
+    for (const e of lock.entries) {
+        if (!e.license) {
+            findings.push({
+                kind: "missing-license",
+                subject: e.skill,
+                detail: `imported skill "${e.skill}" (from ${e.source}) has no license`,
+            });
+        }
+        const disk = onDiskChecksum(e.skill);
+        if (disk !== null && disk !== e.checksum) {
+            findings.push({
+                kind: "stale-copy",
+                subject: e.skill,
+                detail: `on-disk "${e.skill}" drifted from lock (re-run sync)`,
+            });
+        }
+    }
+    return findings.sort((a, b) => a.kind.localeCompare(b.kind) || a.subject.localeCompare(b.subject));
+}
+/**
+ * Recompute the checksum of an imported skill's on-disk body (`instructions.md`)
+ * so {@link auditExternal} can compare it to the lock and flag a `stale-copy`
+ * when the package was hand-edited after import. Returns null when the skill or
+ * its body is absent. The hash domain matches {@link normalizePackage}.
+ */
+export function importedChecksum(workspaceDir, skill) {
+    try {
+        const body = readFileSync(join(skillDir(workspaceDir, skill), "instructions.md"), "utf8");
+        return checksum(body);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=external-skills.js.map

package/dist/external-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-skills.js","sourceRoot":"","sources":["../src/external-skills.ts"],"names":[],"mappings":"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"}

package/dist/headroom-adapter.d.ts

@@ -0,0 +1,58 @@
+import type { CompressInput, ContextCompressor } from "./context-compressor.js";
+import type { ToolDefinition } from "./tools.js";
+/**
+ * Headroom adapter (issue #112 P20) behind P19's external-tool contract.
+ * [Headroom](https://github.com/headroomlabs-ai/headroom) compresses token-heavy
+ * content (tool outputs, logs, RAG chunks, files, history). Otto talks to it as a
+ * governed {@link ToolDefinition}, so the same registry/policy authority that
+ * gates any tool gates the compressor — it can only run in allowed stages, with
+ * the declared scope.
+ *
+ * This slice implements **local-first command mode** (the roadmap's preferred,
+ * service-free path): Otto shells out to a local `headroom` binary, piping the
+ * content on stdin and reading the compressed result on stdout. MCP mode and the
+ * TypeScript library path slot in behind the same {@link ContextCompressor}
+ * interface without changing callers; proxy/wrapper mode stays an explicit
+ * advanced option because it alters provider transport.
+ *
+ * Everything is injectable ({@link HeadroomRunner}) so tests never spawn a real
+ * process, and a missing binary degrades cleanly (the compressor reports
+ * unavailable and the orchestrator keeps the original content).
+ */
+/** The default binary, overridable via `OTTO_HEADROOM_BIN`. */
+export declare const HEADROOM_VERSION = "headroom-cmd-1";
+/**
+ * The low-level transport the adapter drives. The default shells out to the
+ * `headroom` CLI; tests inject a double. `available` is the health probe;
+ * `run` performs one compression.
+ */
+export type HeadroomRunner = {
+    available: () => boolean;
+    run: (input: CompressInput) => {
+        ok: boolean;
+        text: string;
+        note?: string;
+    };
+};
+/**
+ * Default command-mode runner: `headroom --version` for availability, and
+ * `headroom compress --category <c>` (content on stdin → compressed stdout) for
+ * one compression. A non-zero exit / spawn error is a recoverable failure
+ * (`ok: false`), which the orchestrator turns into a degraded passthrough.
+ */
+export declare function defaultHeadroomRunner(env?: NodeJS.ProcessEnv, timeoutMs?: number): HeadroomRunner;
+/**
+ * Build a {@link ContextCompressor} over a {@link HeadroomRunner}. Availability
+ * is cached per instance after the first probe so a run does not re-spawn
+ * `headroom --version` for every compression.
+ */
+export declare function createHeadroomCompressor(runner?: HeadroomRunner): ContextCompressor;
+/**
+ * The {@link ToolDefinition} a repo drops into `.otto/tools/headroom.json` to put
+ * the compressor under registry/policy authority. `stages: []` keeps it opt-in
+ * (a repo enables it per stage); no network/write scope by default — local
+ * command mode touches neither. Returned as a value so `otto-extensions`
+ * (P21 `context-saver`) can generate it.
+ */
+export declare function headroomToolDefinition(): ToolDefinition;
+//# sourceMappingURL=headroom-adapter.d.ts.map

package/dist/headroom-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headroom-adapter.d.ts","sourceRoot":"","sources":["../src/headroom-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,GAAG,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E,CAAC;AAQF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,SAAS,GACjB,cAAc,CA2BhB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,GAAE,cAAwC,GAC/C,iBAAiB,CAWnB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CAiBvD"}

package/dist/headroom-adapter.js

@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Headroom adapter (issue #112 P20) behind P19's external-tool contract.
+ * [Headroom](https://github.com/headroomlabs-ai/headroom) compresses token-heavy
+ * content (tool outputs, logs, RAG chunks, files, history). Otto talks to it as a
+ * governed {@link ToolDefinition}, so the same registry/policy authority that
+ * gates any tool gates the compressor — it can only run in allowed stages, with
+ * the declared scope.
+ *
+ * This slice implements **local-first command mode** (the roadmap's preferred,
+ * service-free path): Otto shells out to a local `headroom` binary, piping the
+ * content on stdin and reading the compressed result on stdout. MCP mode and the
+ * TypeScript library path slot in behind the same {@link ContextCompressor}
+ * interface without changing callers; proxy/wrapper mode stays an explicit
+ * advanced option because it alters provider transport.
+ *
+ * Everything is injectable ({@link HeadroomRunner}) so tests never spawn a real
+ * process, and a missing binary degrades cleanly (the compressor reports
+ * unavailable and the orchestrator keeps the original content).
+ */
+/** The default binary, overridable via `OTTO_HEADROOM_BIN`. */
+export const HEADROOM_VERSION = "headroom-cmd-1";
+/** Resolve the headroom binary name (env override, else `headroom`). */
+function headroomBin(env) {
+    const b = env.OTTO_HEADROOM_BIN;
+    return typeof b === "string" && b.length > 0 ? b : "headroom";
+}
+/**
+ * Default command-mode runner: `headroom --version` for availability, and
+ * `headroom compress --category <c>` (content on stdin → compressed stdout) for
+ * one compression. A non-zero exit / spawn error is a recoverable failure
+ * (`ok: false`), which the orchestrator turns into a degraded passthrough.
+ */
+export function defaultHeadroomRunner(env = process.env, timeoutMs = 30_000) {
+    const bin = headroomBin(env);
+    return {
+        available: () => {
+            try {
+                return spawnSync(bin, ["--version"], { timeout: 5_000 }).status === 0;
+            }
+            catch {
+                return false;
+            }
+        },
+        run: (input) => {
+            const r = spawnSync(bin, ["compress", "--category", input.category], {
+                input: input.text,
+                encoding: "utf8",
+                timeout: timeoutMs,
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            if (r.status !== 0 || typeof r.stdout !== "string") {
+                return {
+                    ok: false,
+                    text: input.text,
+                    note: r.error?.message ?? `headroom exit ${r.status}`,
+                };
+            }
+            return { ok: true, text: r.stdout };
+        },
+    };
+}
+/**
+ * Build a {@link ContextCompressor} over a {@link HeadroomRunner}. Availability
+ * is cached per instance after the first probe so a run does not re-spawn
+ * `headroom --version` for every compression.
+ */
+export function createHeadroomCompressor(runner = defaultHeadroomRunner()) {
+    let probed;
+    return {
+        name: "headroom",
+        version: HEADROOM_VERSION,
+        isAvailable: () => {
+            if (probed === undefined)
+                probed = runner.available();
+            return probed;
+        },
+        compress: (input) => Promise.resolve(runner.run(input)),
+    };
+}
+/**
+ * The {@link ToolDefinition} a repo drops into `.otto/tools/headroom.json` to put
+ * the compressor under registry/policy authority. `stages: []` keeps it opt-in
+ * (a repo enables it per stage); no network/write scope by default — local
+ * command mode touches neither. Returned as a value so `otto-extensions`
+ * (P21 `context-saver`) can generate it.
+ */
+export function headroomToolDefinition() {
+    return {
+        name: "headroom",
+        kind: "command",
+        description: "Local-first context compressor (Headroom command mode).",
+        capabilities: ["compression", "context-engineering"],
+        stages: [],
+        command: "headroom compress",
+        env: ["OTTO_HEADROOM_BIN"],
+        networkDomains: [],
+        writeRoots: [],
+        secretRefs: [],
+        approvalActions: [],
+        timeoutMs: 30_000,
+        healthCheck: "headroom --version",
+        enabled: true,
+    };
+}
+//# sourceMappingURL=headroom-adapter.js.map

package/dist/headroom-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headroom-adapter.js","sourceRoot":"","sources":["../src/headroom-adapter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -13,11 +13,13 @@ export { analyzeContext, estimateTokens, formatContextReport, type ContextBreakd
 export { DEFAULT_COMMITS_BUDGET_CHARS, compactCommits, formatCompactedCommits, parseCommitLog, type CommitEntry, type CompactedCommits, } from "./iteration-compaction.js";
 export { DEFAULT_CONTEXT_BUDGET_FRACTION, DEFAULT_CONTEXT_WINDOW_TOKENS, assessContextBudget, formatContextBudget, modelContextBudget, modelContextWindow, type BudgetRecommendation, type ContextBudgetAssessment, type ContextBudgetContext, } from "./context-budget.js";
 export { emptyReadLedger, fingerprintContent, formatReadReference, recordRead, summarizeReads, type DedupResult, type DedupSummary, type ReadFingerprint, type ReadLedger, type ReadStatus, } from "./read-dedup.js";
-export { allocateRunId, hasRunReport, listRunIds, readManifest, readRunReport, readStageRecords, runReportDir, runsDir, writeManifest, writeRunReport, writeStageRecord, type RunArtifact, type RunManifest, type SafetyEvent, type SkillUsage, type StageRecord, } from "./run-report.js";
+export { allocateRunId, hasRunReport, listRunIds, readManifest, readRunReport, readStageRecords, runReportDir, runsDir, writeManifest, writeRunReport, writeStageRecord, type RunArtifact, type RunManifest, type SafetyEvent, type SkillUsage, type StageRecord, type ToolUsage, } from "./run-report.js";
 export { formatRunReport, runInspect, type InspectDeps } from "./inspect.js";
 export { formatPlainReport, runExplain, type ExplainDeps, } from "./report-explain.js";
 export { formatRunsList, runRuns, summarizeManifest, type RunsDeps, type RunSummary, } from "./runs-cli.js";
 export { formatContextReportRun, runContextReport, type ContextReportDeps, } from "./context-report-cli.js";
+export { compressContent, compressionToolUsage, formatCompressionSummary, readCompressorMode, resolveCompressorMode, runRetrievalStore, summarizeCompression, summarizeToolCompression, type CompressInput, type CompressOutput, type CompressionCategory, type CompressionSummary, type CompressorMode, type ContextCompressor, type RetrievalStore, } from "./context-compressor.js";
+export { HEADROOM_VERSION, createHeadroomCompressor, defaultHeadroomRunner, headroomToolDefinition, type HeadroomRunner, } from "./headroom-adapter.js";
 export { formatPlanReport, readTaskPlans, runPlanReport, type PlanReportDeps, type TaskPlanScore, } from "./plan-report-cli.js";
 export { formatAuditReport, runMemory, type MemoryDeps } from "./memory-cli.js";
 export { allocateMemoryId, auditMemory, boundLearnings, detectConflicts, DEFAULT_FREQUENT_USE, DEFAULT_LEARNINGS_BUDGET_CHARS, formatBoundedLearnings, listMemoryIds, memoryDir, memoryRecordPath, memoryStatus, parseMemoryRecord, projectLearnings, readMemoryRecord, readMemoryRecords, selectRelevantMemory, supersede, touchMemory, writeMemoryRecord, type AuditReport, type BoundedMemory, type MemoryRecord, type MemorySelectionContext, type MemoryStatus, type MemoryTrust, type Supersession, } from "./memory.js";
@@ -27,8 +29,11 @@ export { deriveProgress, type IterationObservation, type ProgressSignals, } from
 export { decide, type PolicyAction, type PolicyContext, type PolicyDecision, } from "./policy.js";
 export { checkApprovalRequired, checkCommand, checkNetworkDomain, checkWritePath, DEFAULT_POLICY, parseSafetyPolicy, readSafetyPolicy, type PolicyViolation, type PolicyViolationKind, type SafetyPolicy, } from "./safety-policy.js";
 export { TAINT_SOURCES, UNTRUSTED_WARNING, wrapUntrusted, type TaintSource, } from "./taint.js";
-export { findSkillCandidates, globMatch, listSkillIds, parseSkill, readSkill, readSkills, recordValidation, selectSkills, skillDir, skillExists, skillInstructionsPath, skillManifestPath, skillsDir, skillStatus, toSkillName, writeSkill, type CandidateRun, type Skill, type SkillCandidate, type SkillMatch, type SkillMatchContext, type SkillStatus, type SkillTrust, type SkillValidation, } from "./skills.js";
-export { formatCandidates, formatSkillsAudit, formatSkillsReport, formatWhy, runSkills, type SkillsDeps, } from "./skills-cli.js";
+export { authorizeToolInvocation, parseTool, readToolConfig, readTools, selectToolsForStage, toolEnabledForStage, toolPath, toolsDir, type ToolAuthorization, type ToolConfig, type ToolDefinition, type ToolInvocation, type ToolKind, type ToolOverride, type ToolResult, type ToolSelection, } from "./tools.js";
+export { auditTools, auditToolPolicyConflicts, formatToolsAudit, formatToolsList, formatToolsWhy, runTools, type ToolAuditFinding, type ToolsDeps, } from "./tools-cli.js";
+export { findSkillCandidates, globMatch, listSkillIds, parseSkill, readSkill, readSkills, recordValidation, selectSkills, skillDir, skillExists, skillInstructionsPath, skillManifestPath, skillsDir, skillStatus, toSkillName, writeSkill, type CandidateRun, type Skill, type SkillCandidate, type SkillMatch, type SkillMatchContext, type ImportedSkillProvenance, type SkillStatus, type SkillTrust, type SkillValidation, } from "./skills.js";
+export { addSource, applySync, auditExternal, discoverPackages, importedChecksum, lockPath, normalizePackage, parseFrontmatter, parseSource, planSync, readLock, readSources, removeSource, sourcesPath, writeLock, writeSources, type DiscoveredPackage, type ExternalAuditFinding, type ExternalSkillLock, type ExternalSkillLockEntry, type ExternalSkillSource, type ExternalSourceType, type SyncAction, type SyncPlan, type SyncPlanItem, } from "./external-skills.js";
+export { formatCandidates, formatExternalAudit, formatSkillsAudit, formatSkillsReport, formatSources, formatSyncPlan, formatWhy, runSkills, type SkillsDeps, } from "./skills-cli.js";
 export { compareTrajectories, scoreTrajectory, type EvalSignals, type LabelledSignals, } from "./eval.js";
 export { PLAN_CRITERIA, detectScopeDrift, extractPlanFileMap, formatPlanDepthRubric, formatPlanRubric, scorePlanDepth, scorePlanQuality, type PlanDepthCriterion, type PlanDepthCriterionResult, type PlanDepthScore, type PlanCriterion, type PlanCriterionResult, type PlanRubricScore, type ScopeDriftResult, } from "./plan-rubric.js";
 export { buildFallbackRunReport, extractRunReport, finalizeReportText, summarizeReviewSeverity, type FinalizeReportContext, type ReviewSeveritySummary, type ScopeDriftSummary, } from "./report-finalize.js";