@phamvuhoang/otto-core 0.22.0 → 0.24.0

package/dist/context-compressor.d.ts

@@ -0,0 +1,147 @@
+import type { ToolUsage } from "./run-report.js";
+/**
+ * Context compression at a governed harness boundary (issue #112 P20). Long
+ * unattended runs are constrained by token spend (P7); a compressor such as
+ * [Headroom](https://github.com/headroomlabs-ai/headroom) can shrink token-heavy
+ * content before it reaches the model. P20 routes selected content through a
+ * compressor and **measures** the result, with two hard rules from the roadmap:
+ *
+ * 1. **Off by default, degrades cleanly.** No compressor unless explicitly
+ *    enabled (`--context-compressor headroom` / `OTTO_CONTEXT_COMPRESSOR` /
+ *    `.otto/config.json` `contextCompressor`). A missing/failed compressor falls
+ *    back to the original content with a warning — never a broken run.
+ * 2. **Reversible, never hides evidence.** Every compression stores the original
+ *    under a durable retrieval handle and records tokens before/after, latency,
+ *    and the compressor version, so reports/evals/reviewers can still reach the
+ *    original.
+ *
+ * The compressor is invoked behind P19's external-tool contract (see
+ * `headroom-adapter.ts`); this module is the transport-agnostic core: setting
+ * resolution, the `ContextCompressor` interface, the reversible-compress
+ * orchestrator, and the savings summary. Pure except for the fs retrieval store,
+ * which is injected.
+ *
+ * **Scope of this slice (P20a spike):** the setting, contract, adapter,
+ * reversible mechanism, and inspectability are wired and tested. Applying
+ * compression at every live spill/log/memory call site is the P20 production
+ * follow-up — until then a run with the compressor off behaves exactly as today.
+ */
+/** Off, or route through the Headroom adapter. */
+export type CompressorMode = "off" | "headroom";
+/**
+ * The token-heavy content categories P7 already flags — the targets the roadmap
+ * names. Carried on each compression so a report can attribute savings by source.
+ */
+export type CompressionCategory = "issue-body" | "command-log" | "prior-iteration" | "read-artifact" | "memory-projection";
+/** Content handed to the compressor, tagged by source category + a stable key. */
+export type CompressInput = {
+    /** A run-unique key (used to name the retrieval artifact). */
+    key: string;
+    category: CompressionCategory;
+    text: string;
+};
+/**
+ * A compressor adapter (Headroom, or a test double). `compress` is async because
+ * a real adapter shells out / calls a local MCP server. `ok: false` signals a
+ * recoverable failure (the orchestrator then degrades to the original).
+ */
+export type ContextCompressor = {
+    name: string;
+    version: string;
+    /** Whether the underlying tool is installed/reachable right now. */
+    isAvailable: () => boolean | Promise<boolean>;
+    compress: (input: CompressInput) => Promise<{
+        text: string;
+        ok: boolean;
+        note?: string;
+    }>;
+};
+/** The measured outcome of one compression (or a degraded passthrough). */
+export type CompressOutput = {
+    /** The text to actually use downstream (compressed, or original if degraded). */
+    text: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    /** Durable handle to the original; absent when nothing was stored (passthrough). */
+    retrievalHandle?: string;
+    latencyMs: number;
+    compressorVersion: string;
+    /** True when the compressor was unavailable/failed and the original was kept. */
+    degraded: boolean;
+    note?: string;
+};
+/**
+ * Persist the original content and return a durable retrieval handle. Injected so
+ * the orchestrator stays testable; {@link runRetrievalStore} is the fs default.
+ */
+export type RetrievalStore = (key: string, original: string) => string;
+/**
+ * Resolve the compressor mode from the flag/env/config precedence chain (flag >
+ * env > config > off). An unrecognized value resolves to `off`, so a typo never
+ * silently enables compression. Pure.
+ */
+export declare function resolveCompressorMode(opts: {
+    flag?: string;
+    env?: string;
+    config?: string;
+}): CompressorMode;
+/**
+ * Read the effective compressor mode for a workspace: `--context-compressor`
+ * flag, else `OTTO_CONTEXT_COMPRESSOR`, else `.otto/config.json`
+ * `contextCompressor`, else `off`. Missing/malformed config → off (never throws).
+ */
+export declare function readCompressorMode(workspaceDir: string, env?: NodeJS.ProcessEnv, flag?: string): CompressorMode;
+/**
+ * Default fs retrieval store: write each original under
+ * `.otto/runs/<run-id>/compressed/<key>.orig` and return that **workspace-relative**
+ * path as the durable handle, so the run bundle stays portable.
+ */
+export declare function runRetrievalStore(workspaceDir: string, runId: string): RetrievalStore;
+/**
+ * Compress one piece of content reversibly and measure it. The single entry
+ * point both the live loop and the benchmark use:
+ *
+ * - off (`compressor` null) → returns the original verbatim, zero savings, no
+ *   handle, not degraded;
+ * - compressor unavailable or `ok: false` → degraded passthrough (original kept,
+ *   `degraded: true`, a `note`), never throws;
+ * - success → stores the original via `store`, returns the compressed text plus
+ *   the measured tokens-before/after, savings, retrieval handle, and latency.
+ *
+ * A "compression" that did not actually shrink the token estimate is discarded
+ * in favor of the original (no point paying a retrieval indirection for nothing).
+ * `now` is injected for deterministic latency in tests.
+ */
+export declare function compressContent(compressor: ContextCompressor | null, input: CompressInput, store: RetrievalStore | null, deps?: {
+    now?: () => number;
+}): Promise<CompressOutput>;
+/**
+ * Build the {@link ToolUsage} evidence record for a compression, so the loop can
+ * attach it to a stage's `toolsUsed[]` (P19). Pure.
+ */
+export declare function compressionToolUsage(output: CompressOutput, category: CompressionCategory, stage?: string): ToolUsage;
+/** Aggregate savings across a run's compressions (for the context report). */
+export type CompressionSummary = {
+    invocations: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    retrievals: number;
+    degraded: number;
+};
+/** Sum a set of compression outcomes into a {@link CompressionSummary}. Pure. */
+export declare function summarizeCompression(outputs: CompressOutput[]): CompressionSummary;
+/**
+ * Summarize the compression {@link ToolUsage} records on a run's stage records
+ * (name `headroom`) — what `--context-report` reads, since the loop attaches
+ * compression evidence as `toolsUsed[]`. Pure.
+ */
+export declare function summarizeToolCompression(usages: ToolUsage[]): {
+    invocations: number;
+    tokensSaved: number;
+    retrievals: number;
+};
+/** One-line human summary of compression savings for the context report. Pure. */
+export declare function formatCompressionSummary(s: CompressionSummary): string;
+//# sourceMappingURL=context-compressor.d.ts.map

package/dist/context-compressor.d.ts.map

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

package/dist/context-compressor.js

@@ -0,0 +1,199 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { estimateTokens } from "./context-report.js";
+import { runReportDir } from "./run-report.js";
+const MODES = new Set(["off", "headroom"]);
+/**
+ * Resolve the compressor mode from the flag/env/config precedence chain (flag >
+ * env > config > off). An unrecognized value resolves to `off`, so a typo never
+ * silently enables compression. Pure.
+ */
+export function resolveCompressorMode(opts) {
+    for (const raw of [opts.flag, opts.env, opts.config]) {
+        if (typeof raw === "string" && raw.length > 0) {
+            const v = raw.trim().toLowerCase();
+            return MODES.has(v) ? v : "off";
+        }
+    }
+    return "off";
+}
+/**
+ * Read the effective compressor mode for a workspace: `--context-compressor`
+ * flag, else `OTTO_CONTEXT_COMPRESSOR`, else `.otto/config.json`
+ * `contextCompressor`, else `off`. Missing/malformed config → off (never throws).
+ */
+export function readCompressorMode(workspaceDir, env = process.env, flag) {
+    let config;
+    try {
+        const raw = JSON.parse(readFileSync(join(workspaceDir, ".otto", "config.json"), "utf8"));
+        if (typeof raw.contextCompressor === "string")
+            config = raw.contextCompressor;
+    }
+    catch {
+        // no/invalid config → leave undefined (resolves to off)
+    }
+    return resolveCompressorMode({
+        flag,
+        env: env.OTTO_CONTEXT_COMPRESSOR,
+        config,
+    });
+}
+/**
+ * Default fs retrieval store: write each original under
+ * `.otto/runs/<run-id>/compressed/<key>.orig` and return that **workspace-relative**
+ * path as the durable handle, so the run bundle stays portable.
+ */
+export function runRetrievalStore(workspaceDir, runId) {
+    const absDir = join(runReportDir(workspaceDir, runId), "compressed");
+    return (key, original) => {
+        mkdirSync(absDir, { recursive: true });
+        const safe = key.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80);
+        writeFileSync(join(absDir, `${safe}.orig`), original);
+        return join(".otto", "runs", runId, "compressed", `${safe}.orig`);
+    };
+}
+/**
+ * Compress one piece of content reversibly and measure it. The single entry
+ * point both the live loop and the benchmark use:
+ *
+ * - off (`compressor` null) → returns the original verbatim, zero savings, no
+ *   handle, not degraded;
+ * - compressor unavailable or `ok: false` → degraded passthrough (original kept,
+ *   `degraded: true`, a `note`), never throws;
+ * - success → stores the original via `store`, returns the compressed text plus
+ *   the measured tokens-before/after, savings, retrieval handle, and latency.
+ *
+ * A "compression" that did not actually shrink the token estimate is discarded
+ * in favor of the original (no point paying a retrieval indirection for nothing).
+ * `now` is injected for deterministic latency in tests.
+ */
+export async function compressContent(compressor, input, store, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const tokensBefore = estimateTokens(input.text.length);
+    const passthrough = (degraded, note) => ({
+        text: input.text,
+        tokensBefore,
+        tokensAfter: tokensBefore,
+        tokensSaved: 0,
+        latencyMs: 0,
+        compressorVersion: compressor?.version ?? "off",
+        degraded,
+        ...(note ? { note } : {}),
+    });
+    if (!compressor)
+        return passthrough(false);
+    const start = now();
+    let available;
+    try {
+        available = await compressor.isAvailable();
+    }
+    catch {
+        available = false;
+    }
+    if (!available) {
+        return passthrough(true, `compressor "${compressor.name}" unavailable — kept original`);
+    }
+    let result;
+    try {
+        result = await compressor.compress(input);
+    }
+    catch (e) {
+        return passthrough(true, `compressor error: ${e.message ?? e}`);
+    }
+    const latencyMs = Math.max(0, now() - start);
+    const tokensAfter = estimateTokens(result.text.length);
+    if (!result.ok || tokensAfter >= tokensBefore) {
+        return {
+            ...passthrough(!result.ok, result.note ??
+                (result.ok ? "no token reduction — kept original" : undefined)),
+            latencyMs,
+        };
+    }
+    const retrievalHandle = store ? store(input.key, input.text) : undefined;
+    return {
+        text: result.text,
+        tokensBefore,
+        tokensAfter,
+        tokensSaved: tokensBefore - tokensAfter,
+        ...(retrievalHandle ? { retrievalHandle } : {}),
+        latencyMs,
+        compressorVersion: compressor.version,
+        degraded: false,
+        ...(result.note ? { note: result.note } : {}),
+    };
+}
+/**
+ * Build the {@link ToolUsage} evidence record for a compression, so the loop can
+ * attach it to a stage's `toolsUsed[]` (P19). Pure.
+ */
+export function compressionToolUsage(output, category, stage) {
+    return {
+        name: "headroom",
+        kind: "command",
+        ...(stage ? { stage } : {}),
+        tokensSaved: output.tokensSaved,
+        ...(output.retrievalHandle
+            ? { retrievalHandle: output.retrievalHandle }
+            : {}),
+        reasons: [
+            `compressed ${category}`,
+            output.degraded
+                ? "degraded: kept original"
+                : `saved ${output.tokensSaved} tokens`,
+        ],
+    };
+}
+/** Sum a set of compression outcomes into a {@link CompressionSummary}. Pure. */
+export function summarizeCompression(outputs) {
+    const s = {
+        invocations: outputs.length,
+        tokensBefore: 0,
+        tokensAfter: 0,
+        tokensSaved: 0,
+        retrievals: 0,
+        degraded: 0,
+    };
+    for (const o of outputs) {
+        s.tokensBefore += o.tokensBefore;
+        s.tokensAfter += o.tokensAfter;
+        s.tokensSaved += o.tokensSaved;
+        if (o.retrievalHandle)
+            s.retrievals += 1;
+        if (o.degraded)
+            s.degraded += 1;
+    }
+    return s;
+}
+/**
+ * Summarize the compression {@link ToolUsage} records on a run's stage records
+ * (name `headroom`) — what `--context-report` reads, since the loop attaches
+ * compression evidence as `toolsUsed[]`. Pure.
+ */
+export function summarizeToolCompression(usages) {
+    let tokensSaved = 0;
+    let retrievals = 0;
+    let invocations = 0;
+    for (const u of usages) {
+        if (u.name !== "headroom")
+            continue;
+        invocations += 1;
+        tokensSaved += u.tokensSaved ?? 0;
+        if (u.retrievalHandle)
+            retrievals += 1;
+    }
+    return { invocations, tokensSaved, retrievals };
+}
+/** One-line human summary of compression savings for the context report. Pure. */
+export function formatCompressionSummary(s) {
+    if (s.invocations === 0)
+        return "Context compression: not used.";
+    const pct = s.tokensBefore > 0 ? Math.round((s.tokensSaved / s.tokensBefore) * 100) : 0;
+    const parts = [
+        `Context compression: ${s.tokensSaved} tokens saved (${pct}%) across ${s.invocations} call(s)`,
+        `${s.retrievals} original(s) retained`,
+    ];
+    if (s.degraded > 0)
+        parts.push(`${s.degraded} degraded (kept original)`);
+    return parts.join("; ") + ".";
+}
+//# sourceMappingURL=context-compressor.js.map

package/dist/context-compressor.js.map

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

package/dist/context-report-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-report-cli.d.ts","sourceRoot":"","sources":["../src/context-report-cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGjF;;;;;;;;;GASG;AAEH,mFAAmF;AACnF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAgBF;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EAAE,GACpB,MAAM,CAyDR;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,iBAA+B,GACpC,OAAO,CAAC,MAAM,CAAC,CAajB"}
+{"version":3,"file":"context-report-cli.d.ts","sourceRoot":"","sources":["../src/context-report-cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;;;GASG;AAEH,mFAAmF;AACnF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAgBF;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EAAE,GACpB,MAAM,CAuER;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,iBAA+B,GACpC,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/context-report-cli.js

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
-import { listRunIds, readStageRecords } from "./run-report.js";
+import { summarizeToolCompression } from "./context-compressor.js";
+import { listRunIds, readStageRecords, } from "./run-report.js";
 import { formatCacheEfficiency, summarizeCacheEfficiency } from "./tokens.js";
 const defaultDeps = {
     env: process.env,
@@ -59,6 +60,13 @@ export function formatContextReportRun(runId, stages) {
     if (cache.totalInputTokens > 0) {
         lines.push("", `  ${formatCacheEfficiency(cache)}`);
     }
+    // Context compression savings (P20) — drawn from compression tool-usage records
+    // on the stage bundle; omitted entirely when no compressor ran.
+    const comp = summarizeToolCompression(stages.flatMap((s) => s.toolsUsed ?? []));
+    if (comp.invocations > 0) {
+        lines.push("", `  Context compression: ~${num.format(comp.tokensSaved)} tokens saved across ` +
+            `${comp.invocations} call(s); ${comp.retrievals} original(s) retained.`);
+    }
     return lines.join("\n");
 }
 /**

package/dist/context-report-cli.js.map

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

package/dist/external-skills.d.ts

@@ -0,0 +1,170 @@
+import { type Skill } from "./skills.js";
+/**
+ * External skill source registry (issue #110 P16). Otto can import outside skill
+ * packs (Superpowers, PM-Skills, …) into the existing `.otto/skills/<name>/`
+ * package shape, but **import is separated from trust and runtime use**: every
+ * imported skill lands as `trust: "unverified"` with empty validation, so it
+ * stays inert on the loop until a later validation/activation slice (P17/P18).
+ *
+ * Two files back the registry, both pure fs + JSON with safe defaults (never
+ * throw on the read path, mirroring `skills.ts`/`memory.ts`):
+ *
+ * - `.otto/skills/sources.json` — the configured sources (`{ sources: [...] }`).
+ * - `.otto/skills.lock.json`    — what was actually resolved and imported:
+ *   resolved ref, checksum, import timestamp, source type, license, normalized
+ *   skill name and capabilities, for deterministic diffing and drift audits.
+ *
+ * This slice supports `local` source directories (the roadmap's "local fixture
+ * directories before networked git fetch"). `git`/`archive` resolution layers on
+ * top later without changing the lock/normalization shape.
+ */
+/** A source's transport kind. `registry` is reserved for a later slice. */
+export type ExternalSourceType = "git" | "local" | "archive" | "registry";
+/** One configured external skill source (`.otto/skills/sources.json`). */
+export type ExternalSkillSource = {
+    /** Registry key, unique within sources.json. */
+    name: string;
+    type: ExternalSourceType;
+    /** URL (git/archive) or filesystem path (local). */
+    location: string;
+    /** Pinned ref (sha/tag). Absent = unpinned (an audit finding). */
+    ref?: string;
+};
+/** One resolved import in `.otto/skills.lock.json`. */
+export type ExternalSkillLockEntry = {
+    /** Normalized skill name = `.otto/skills/<skill>` directory. */
+    skill: string;
+    /** Source name it came from. */
+    source: string;
+    type: ExternalSourceType;
+    /** Package path within the source tree. */
+    upstreamPath: string;
+    /** Resolved ref the source was pinned to, if any. */
+    ref?: string;
+    /** Content checksum of the imported package. */
+    checksum: string;
+    /** Import timestamp (ISO). */
+    importedAt: string;
+    license?: string;
+    capabilities: string[];
+};
+export type ExternalSkillLock = {
+    entries: ExternalSkillLockEntry[];
+};
+/** Absolute path to the sources config (`.otto/skills/sources.json`). */
+export declare function sourcesPath(workspaceDir: string): string;
+/** Absolute path to the import lockfile (`.otto/skills.lock.json`). */
+export declare function lockPath(workspaceDir: string): string;
+/** Normalize one untrusted source entry; null when it lacks the required shape. */
+export declare function parseSource(raw: unknown): ExternalSkillSource | null;
+/** Read configured sources; absent/malformed → `[]` (never throws). */
+export declare function readSources(workspaceDir: string): ExternalSkillSource[];
+/** Write the sources config, sorted by name for deterministic diffs. */
+export declare function writeSources(workspaceDir: string, sources: ExternalSkillSource[]): void;
+/** Read the import lock; absent/malformed → `{ entries: [] }` (never throws). */
+export declare function readLock(workspaceDir: string): ExternalSkillLock;
+/** Write the lock, entries sorted by skill name for deterministic diffs. */
+export declare function writeLock(workspaceDir: string, lock: ExternalSkillLock): void;
+/** Add (or replace by name) a source. Pure — returns a new array. */
+export declare function addSource(sources: ExternalSkillSource[], source: ExternalSkillSource): ExternalSkillSource[];
+/** Remove a source by name. Pure — returns a new array. */
+export declare function removeSource(sources: ExternalSkillSource[], name: string): ExternalSkillSource[];
+/**
+ * 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 declare function parseFrontmatter(text: string): {
+    fields: Record<string, string>;
+    body: string;
+};
+/** A SKILL.md package located inside a source tree, before normalization. */
+export type DiscoveredPackage = {
+    /** Normalized skill name (also the `.otto/skills/<name>` dir). */
+    name: string;
+    /** Package path within the source tree (POSIX-style, for the lock). */
+    upstreamPath: string;
+    /** Raw SKILL.md content. */
+    raw: string;
+};
+/**
+ * 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 declare function discoverPackages(sourceDir: string): DiscoveredPackage[];
+/**
+ * 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 declare function normalizePackage(source: ExternalSkillSource, pkg: DiscoveredPackage, now: Date): {
+    skill: Skill;
+    entry: ExternalSkillLockEntry;
+};
+/** What a `sync` would do to one skill package. */
+export type SyncAction = "add" | "update" | "unchanged" | "conflict";
+export type SyncPlanItem = {
+    skill: string;
+    source: string;
+    action: SyncAction;
+    /** Set for `conflict`: the other source already claiming this name. */
+    conflictWith?: string;
+    /** Resolved skill + lock entry (carried so apply needn't re-normalize). */
+    resolved: {
+        skill: Skill;
+        entry: ExternalSkillLockEntry;
+    };
+};
+export type SyncPlan = {
+    items: SyncPlanItem[];
+};
+/**
+ * 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 declare function planSync(workspaceDir: string, sources: ExternalSkillSource[], now: Date): SyncPlan;
+/**
+ * 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 declare function applySync(workspaceDir: string, plan: SyncPlan): ExternalSkillLock;
+/** One governance problem with the external registry. */
+export type ExternalAuditFinding = {
+    kind: "unpinned-ref" | "missing-license" | "duplicate-name" | "unsupported-format" | "stale-copy";
+    subject: string;
+    detail: string;
+};
+/**
+ * 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 declare function auditExternal(sources: ExternalSkillSource[], lock: ExternalSkillLock, onDiskChecksum: (skill: string) => string | null): ExternalAuditFinding[];
+/**
+ * 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 declare function importedChecksum(workspaceDir: string, skill: string): string | null;
+//# sourceMappingURL=external-skills.d.ts.map

package/dist/external-skills.d.ts.map

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