dna-sdk 0.1.0

package/dist/adapters/search/sqlite-vec.d.ts

@@ -0,0 +1,66 @@
+/** The slice of the kernel this provider needs (embedding surface). */
+export interface EmbeddingKernel {
+    embed(texts: string[]): Promise<number[][]>;
+    readonly embeddingDims: number;
+    readonly embeddingModelId: string;
+}
+/** A record to index. `text` is used verbatim if present; otherwise derived
+ *  from `raw` via {@link documentText}. */
+export interface SearchRecord {
+    scope: string;
+    kind: string;
+    name: string;
+    tenant?: string;
+    text?: string;
+    raw?: Record<string, unknown>;
+    title?: string;
+    snippet?: string;
+}
+export interface SearchHit extends Record<string, unknown> {
+    scope: string;
+    kind: string;
+    name: string;
+    score: number;
+}
+/** An id to delete: `{ scope, kind, name, tenant? }`. */
+export interface RecordId {
+    scope: string;
+    kind: string;
+    name: string;
+    tenant?: string;
+}
+/** Derive the searchable text blob for a raw document — every string value in
+ *  `spec` plus `metadata.name`, in document order (parity with the Python
+ *  `document_text`). */
+export declare function documentText(raw: Record<string, unknown>): string;
+export declare class SqliteVecRecordSearchProvider {
+    private readonly kernel;
+    private readonly dbDir;
+    private readonly singlePath;
+    private readonly rrfK;
+    private readonly conns;
+    constructor(kernel: EmbeddingKernel, opts?: {
+        dbDir?: string;
+        dbPath?: string;
+        rrfK?: number;
+    });
+    private pathFor;
+    private connFor;
+    private pinIdentity;
+    /** Index (upsert) records into their scope's store. Idempotent by text hash
+     *  (re-indexing unchanged text is skipped). Returns the count actually
+     *  (re)embedded. */
+    index(records: SearchRecord[]): Promise<number>;
+    private upsert;
+    /** Delete indexed records. Returns the number of rows removed. */
+    delete(ids: RecordId[]): Promise<number>;
+    search(opts: {
+        scope: string;
+        queryText: string;
+        kind?: string | null;
+        k?: number;
+        tenant?: string;
+    }): Promise<SearchHit[]>;
+    private resolveMeta;
+    close(): void;
+}

package/dist/adapters/search/sqlite-vec.js

@@ -0,0 +1,294 @@
+/**
+ * SqliteVecRecordSearchProvider — the embeddable default RecordSearchProvider
+ * (TS twin of `dna/adapters/search/sqlite_vec.py`).
+ *
+ * The FIRST real implementation of the `RecordSearchProvider` port on the TS
+ * side. Hybrid search inside one SQLite file per scope, offline, no server:
+ *
+ *   - dense   — sqlite-vec `vec0` KNN over `kernel.embed()` vectors (the
+ *               deterministic `FakeEmbeddingProvider` floor by default).
+ *   - lexical — FTS5 BM25 over the same text.
+ *   - fusion  — Reciprocal Rank Fusion (`reciprocalRankFusion`, the pure
+ *               function shared with the Python twin).
+ *
+ * The store schema is OWNED by a numbered migration (`migrations.ts`), closing
+ * f-embeddings-ddl-debt. Overlay/tenant-aware: `tenant` is a column ('' = base);
+ * a tenant search reads base ∪ overlay and the overlay row shadows the base row
+ * for the same `(kind, name)`.
+ *
+ * SQLite access goes through {@link openSearchDb} (bun:sqlite or node:sqlite);
+ * sqlite-vec is an OPTIONAL peer dep (`sqlite-vec`), never in the default graph.
+ * Both are exercised by the shared record-search conformance kit with the fake
+ * embedder, offline.
+ */
+import { sha256 } from "js-sha256";
+import { DEFAULT_RRF_K, reciprocalRankFusion } from "./rrf.js";
+import { buildMigrations, runSearchMigrations } from "./migrations.js";
+import { openSearchDb, serializeF32 } from "./driver.js";
+const OVERFETCH = 4;
+const MIN_CANDIDATES = 40;
+/** Derive the searchable text blob for a raw document — every string value in
+ *  `spec` plus `metadata.name`, in document order (parity with the Python
+ *  `document_text`). */
+export function documentText(raw) {
+    const parts = [];
+    const meta = raw.metadata ?? {};
+    const name = meta.name ?? raw.name;
+    if (typeof name === "string")
+        parts.push(name);
+    const walk = (node) => {
+        if (typeof node === "string")
+            parts.push(node);
+        else if (Array.isArray(node))
+            node.forEach(walk);
+        else if (node && typeof node === "object")
+            Object.values(node).forEach(walk);
+    };
+    walk(raw.spec ?? {});
+    return parts.filter((p) => p).join("\n");
+}
+export class SqliteVecRecordSearchProvider {
+    kernel;
+    dbDir;
+    singlePath;
+    rrfK;
+    conns = new Map();
+    constructor(kernel, opts = {}) {
+        this.kernel = kernel;
+        let dbDir = opts.dbDir ?? null;
+        if (dbDir === null && !opts.dbPath) {
+            const env = globalThis
+                .process?.env;
+            dbDir = env?.DNA_SEARCH_DIR ?? ".dna-search";
+        }
+        this.dbDir = opts.dbPath ? null : dbDir;
+        this.singlePath = opts.dbPath ?? null;
+        this.rrfK = opts.rrfK ?? DEFAULT_RRF_K;
+    }
+    // ------------------------------------------------------------------
+    // store / schema (migration-owned)
+    // ------------------------------------------------------------------
+    pathFor(scope) {
+        if (this.singlePath)
+            return this.singlePath;
+        const safe = scope.replace(/[/\\]/g, "_");
+        return `${this.dbDir}/${safe}.db`;
+    }
+    async connFor(scope) {
+        const path = this.pathFor(scope);
+        const existing = this.conns.get(path);
+        if (existing)
+            return existing;
+        if (this.dbDir && !this.singlePath)
+            await ensureDir(this.dbDir);
+        const db = await openSearchDb(path);
+        runSearchMigrations(db, buildMigrations(this.kernel.embeddingDims));
+        this.pinIdentity(db);
+        this.conns.set(path, db);
+        return db;
+    }
+    pinIdentity(db) {
+        const dims = String(this.kernel.embeddingDims);
+        const modelId = this.kernel.embeddingModelId;
+        const rows = db.all("SELECT key, value FROM search_meta");
+        if (rows.length === 0) {
+            db.run("INSERT INTO search_meta (key, value) VALUES (?, ?)", ["embedding_dims", dims]);
+            db.run("INSERT INTO search_meta (key, value) VALUES (?, ?)", ["embedding_model_id", modelId]);
+            return;
+        }
+        const meta = Object.fromEntries(rows.map((r) => [r.key, r.value]));
+        if (meta.embedding_dims !== dims || meta.embedding_model_id !== modelId) {
+            throw new Error(`search store was built for embedding space (${meta.embedding_model_id}, `
+                + `dims=${meta.embedding_dims}) but the active provider is (${modelId}, `
+                + `dims=${dims}) — the vectors are incomparable. Use a fresh store dir `
+                + "or re-index.");
+        }
+    }
+    // ------------------------------------------------------------------
+    // index / delete
+    // ------------------------------------------------------------------
+    /** Index (upsert) records into their scope's store. Idempotent by text hash
+     *  (re-indexing unchanged text is skipped). Returns the count actually
+     *  (re)embedded. */
+    async index(records) {
+        if (records.length === 0)
+            return 0;
+        const pending = records.map((rec) => {
+            const text = rec.text ?? documentText(rec.raw ?? {});
+            return { rec, text, hash: sha256(text) };
+        });
+        const toEmbed = [];
+        for (const item of pending) {
+            const db = await this.connFor(item.rec.scope);
+            const existing = db.get("SELECT text_hash FROM search_docs WHERE scope=? AND kind=? AND name=? AND tenant=?", [item.rec.scope, item.rec.kind, item.rec.name, item.rec.tenant ?? ""]);
+            if (existing && existing.text_hash === item.hash)
+                continue;
+            toEmbed.push(item);
+        }
+        if (toEmbed.length === 0)
+            return 0;
+        const vectors = await this.kernel.embed(toEmbed.map((i) => i.text));
+        toEmbed.forEach((item, i) => this.upsert(item.rec, item.text, item.hash, vectors[i]));
+        return toEmbed.length;
+    }
+    upsert(rec, text, textHash, vector) {
+        const db = this.conns.get(this.pathFor(rec.scope));
+        const tenant = rec.tenant ?? "";
+        const title = rec.title ?? null;
+        const snippet = rec.snippet ?? snippetOf(text);
+        const row = db.get("SELECT rowid FROM search_docs WHERE scope=? AND kind=? AND name=? AND tenant=?", [rec.scope, rec.kind, rec.name, tenant]);
+        let rowid;
+        if (!row) {
+            const info = db.run("INSERT INTO search_docs (scope, kind, name, tenant, text_hash, title, snippet, text) "
+                + "VALUES (?,?,?,?,?,?,?,?)", [rec.scope, rec.kind, rec.name, tenant, textHash, title, snippet, text]);
+            rowid = info.lastInsertRowid;
+        }
+        else {
+            rowid = row.rowid;
+            db.run("UPDATE search_docs SET text_hash=?, title=?, snippet=?, text=? WHERE rowid=?", [
+                textHash, title, snippet, text, rowid,
+            ]);
+            db.run("DELETE FROM search_vec WHERE doc_rowid=?", [BigInt(rowid)]);
+            db.run("DELETE FROM search_fts WHERE rowid=?", [BigInt(rowid)]);
+        }
+        // vec0 (and fts5) require an INTEGER rowid binding — node:sqlite binds a JS
+        // number as a double and vec0 rejects it, so pass BigInt (both drivers OK).
+        db.run("INSERT INTO search_vec (doc_rowid, embedding) VALUES (?, ?)", [
+            BigInt(rowid), serializeF32(vector),
+        ]);
+        db.run("INSERT INTO search_fts (rowid, text) VALUES (?, ?)", [BigInt(rowid), text]);
+    }
+    /** Delete indexed records. Returns the number of rows removed. */
+    async delete(ids) {
+        let removed = 0;
+        for (const id of ids) {
+            const db = await this.connFor(id.scope);
+            const row = db.get("SELECT rowid FROM search_docs WHERE scope=? AND kind=? AND name=? AND tenant=?", [id.scope, id.kind, id.name, id.tenant ?? ""]);
+            if (!row)
+                continue;
+            const rowid = BigInt(row.rowid);
+            db.run("DELETE FROM search_vec WHERE doc_rowid=?", [rowid]);
+            db.run("DELETE FROM search_fts WHERE rowid=?", [rowid]);
+            db.run("DELETE FROM search_docs WHERE rowid=?", [rowid]);
+            removed += 1;
+        }
+        return removed;
+    }
+    // ------------------------------------------------------------------
+    // search (RecordSearchProvider)
+    // ------------------------------------------------------------------
+    async search(opts) {
+        const { scope, queryText } = opts;
+        const kind = opts.kind ?? null;
+        const k = opts.k ?? 10;
+        const tenant = opts.tenant ?? "";
+        if (!queryText.trim() || k <= 0)
+            return [];
+        const db = await this.connFor(scope);
+        const overfetch = Math.max(MIN_CANDIDATES, k * OVERFETCH);
+        const queryVec = (await this.kernel.embed([queryText]))[0];
+        let denseRanked = [];
+        if (queryVec.some((x) => x !== 0)) {
+            denseRanked = db
+                .all("SELECT doc_rowid FROM search_vec WHERE embedding MATCH ? ORDER BY distance LIMIT ?", [serializeF32(queryVec), overfetch])
+                .map((r) => r.doc_rowid);
+        }
+        let lexicalRanked = [];
+        const ftsQuery = ftsQueryOf(queryText);
+        if (ftsQuery) {
+            try {
+                lexicalRanked = db
+                    .all("SELECT rowid FROM search_fts WHERE search_fts MATCH ? ORDER BY bm25(search_fts) LIMIT ?", [ftsQuery, overfetch])
+                    .map((r) => r.rowid);
+            }
+            catch {
+                lexicalRanked = [];
+            }
+        }
+        if (denseRanked.length === 0 && lexicalRanked.length === 0)
+            return [];
+        const fused = reciprocalRankFusion([denseRanked.map(String), lexicalRanked.map(String)], this.rrfK);
+        const densePos = new Map(denseRanked.map((r, i) => [r, i + 1]));
+        const lexicalPos = new Map(lexicalRanked.map((r, i) => [r, i + 1]));
+        const rowids = fused.map(([rid]) => Number(rid));
+        const meta = this.resolveMeta(db, rowids);
+        const best = new Map();
+        for (const [rid, score] of fused) {
+            const rowid = Number(rid);
+            const m = meta.get(rowid);
+            if (!m)
+                continue;
+            if (kind !== null && m.kind !== kind)
+                continue;
+            const rowTenant = m.tenant ?? "";
+            if (rowTenant !== "" && rowTenant !== (tenant || ""))
+                continue; // other tenant — never leaks
+            const key = `${m.kind}${m.name}`;
+            const prev = best.get(key);
+            const hit = makeHit(scope, m, score, densePos.get(rowid), lexicalPos.get(rowid));
+            if (!prev) {
+                best.set(key, hit);
+            }
+            else {
+                const thisIsOverlay = rowTenant !== "" && rowTenant === (tenant || "");
+                if (thisIsOverlay && prev._tenant === "")
+                    best.set(key, hit);
+            }
+        }
+        const hits = [...best.values()].sort((a, b) => b.score - a.score);
+        for (const h of hits)
+            delete h._tenant;
+        return hits.slice(0, k);
+    }
+    resolveMeta(db, rowids) {
+        if (rowids.length === 0)
+            return new Map();
+        const placeholders = rowids.map(() => "?").join(",");
+        const rows = db.all(`SELECT rowid, scope, kind, name, tenant, title, snippet FROM search_docs `
+            + `WHERE rowid IN (${placeholders})`, rowids);
+        return new Map(rows.map((r) => [r.rowid, r]));
+    }
+    close() {
+        for (const db of this.conns.values()) {
+            try {
+                db.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.conns.clear();
+    }
+}
+function makeHit(scope, m, score, rankDense, rankLexical) {
+    const hit = {
+        scope, kind: m.kind, name: m.name, score, _tenant: m.tenant ?? "",
+    };
+    if (m.title)
+        hit.title = m.title;
+    if (m.snippet)
+        hit.snippet = m.snippet;
+    if (rankDense !== undefined)
+        hit.rank_dense = rankDense;
+    if (rankLexical !== undefined)
+        hit.rank_lexical = rankLexical;
+    return hit;
+}
+function snippetOf(text, maxLen = 200) {
+    const flat = text.split(/\s+/).filter(Boolean).join(" ");
+    return flat.length > maxLen ? flat.slice(0, maxLen) + "…" : flat;
+}
+/** OR of quoted alphanumeric tokens — parity with the Python `_fts_query`. */
+function ftsQueryOf(queryText) {
+    const tokens = queryText.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+    return tokens.map((t) => `"${t}"`).join(" OR ");
+}
+async function ensureDir(dir) {
+    try {
+        const fs = (await import("node:fs"));
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        /* best effort — open will surface a real failure */
+    }
+}

package/dist/bootstrap.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Opinionated SDK bootstrap.
+ *
+ * The kernel itself (src/kernel/*) is extension-agnostic by design — it
+ * knows about the 5-port architecture and nothing else. This module is
+ * where the SDK ships its default wiring: the six built-in extensions,
+ * the default resolvers, and the quick-start helpers used by examples
+ * and tests.
+ *
+ * Callers that want a minimal kernel can `import { Kernel }` directly
+ * and register exactly the extensions they need. Callers that want the
+ * batteries-included experience use `createKernelWithBuiltins()` or
+ * `quickInstance()`.
+ */
+import { Kernel } from "./kernel/index.js";
+import { Runtime } from "./kernel/runtime.js";
+import type { ManifestInstance } from "./kernel/instance.js";
+/**
+ * Return a fresh Kernel with all six built-in extensions registered.
+ * No source, cache, or resolvers wired — callers are responsible for
+ * that. Use `quickInstance()` if you want the full batteries-included
+ * shortcut.
+ */
+export declare function createKernelWithBuiltins(): Kernel;
+/**
+ * Batteries-included shortcut: kernel + all built-in extensions +
+ * default filesystem source / cache / resolvers, then returns a
+ * `ManifestInstance` for the given scope. Equivalent to the old
+ * `Kernel.quick(scope, baseDir)` static method that used to live on
+ * the kernel class itself.
+ */
+export declare function quickInstance(scope: string, baseDir?: string): Promise<ManifestInstance>;
+/**
+ * Return a fresh Runtime with all six built-in extensions registered.
+ * No source, cache, or resolvers wired — callers are responsible for
+ * that. Use `quickManifest()` if you want the full batteries-included
+ * shortcut.
+ */
+export declare function createRuntimeWithBuiltins(): Runtime;
+/**
+ * Batteries-included shortcut using Runtime: all built-in extensions +
+ * default filesystem source / cache / resolvers, then returns a
+ * `ManifestInstance` for the given scope.
+ */
+export declare function quickManifest(scope: string, baseDir?: string): Promise<ManifestInstance>;

package/dist/bootstrap.js

@@ -0,0 +1,134 @@
+/**
+ * Opinionated SDK bootstrap.
+ *
+ * The kernel itself (src/kernel/*) is extension-agnostic by design — it
+ * knows about the 5-port architecture and nothing else. This module is
+ * where the SDK ships its default wiring: the six built-in extensions,
+ * the default resolvers, and the quick-start helpers used by examples
+ * and tests.
+ *
+ * Callers that want a minimal kernel can `import { Kernel }` directly
+ * and register exactly the extensions they need. Callers that want the
+ * batteries-included experience use `createKernelWithBuiltins()` or
+ * `quickInstance()`.
+ */
+import { Kernel } from "./kernel/index.js";
+import { Runtime } from "./kernel/runtime.js";
+import { FilesystemSource } from "./adapters/filesystem/source.js";
+import { FilesystemCache } from "./adapters/filesystem/cache.js";
+import { LocalResolver } from "./adapters/resolvers/local.js";
+import { HttpResolver } from "./adapters/resolvers/http.js";
+import { GitHubResolver } from "./adapters/resolvers/github.js";
+import { HelixExtension } from "./extensions/helix.js";
+import { AgentSkillsExtension } from "./extensions/agentskills.js";
+import { SoulSpecExtension } from "./extensions/soulspec.js";
+import { AgentsMdExtension } from "./extensions/agentsmd.js";
+import { GuardrailExtension } from "./extensions/guardrails.js";
+import { HookExtension } from "./extensions/hooks.js";
+import { KindDefinitionExtension } from "./extensions/kinddef.js";
+import { SafetyPolicyExtension } from "./extensions/safety.js";
+import { RecognizerExtension } from "./extensions/recognizer.js";
+import { FederationExtension } from "./extensions/federation.js";
+import { SdlcExtension } from "./extensions/sdlc.js";
+import { AuditExtension } from "./extensions/audit.js";
+import { LessonExtension } from "./extensions/lesson.js";
+import { TenantExtension } from "./extensions/tenant.js";
+import { EvidenceExtension } from "./extensions/evidence.js";
+import { DocExtension } from "./extensions/doc.js";
+import { ResearchExtension } from "./extensions/research.js";
+import { TestkitExtension } from "./extensions/testkit.js";
+import { ModelRegExtension } from "./extensions/modelreg.js";
+import { AutomationExtension } from "./extensions/automation.js";
+import { EvalExtension } from "./extensions/eval.js";
+/**
+ * The canonical built-in extension set. Loaded into BOTH a Kernel and a
+ * Runtime through this SINGLE list so the two bootstraps can never drift
+ * (s-export-unwired-ts-extensions — they had, and Community/Research/Sdlc were
+ * loaded by neither). Add a built-in here once and both paths get it.
+ */
+function loadBuiltins(target) {
+    for (const ext of [
+        new HelixExtension(),
+        new AgentSkillsExtension(),
+        new SoulSpecExtension(),
+        new AgentsMdExtension(),
+        new GuardrailExtension(),
+        new HookExtension(),
+        new KindDefinitionExtension(),
+        new SafetyPolicyExtension(),
+        new RecognizerExtension(),
+        new FederationExtension(),
+        new SdlcExtension(),
+        new AuditExtension(),
+        new LessonExtension(),
+        new TenantExtension(),
+        new EvidenceExtension(),
+        new DocExtension(),
+        new ResearchExtension(),
+        new TestkitExtension(),
+        new ModelRegExtension(),
+        new AutomationExtension(),
+        new EvalExtension(),
+    ]) {
+        target.load(ext);
+    }
+    // s-alias-generated-not-typed — com TODAS as extensions carregadas, todo
+    // dep_filter builtin deve resolver pra um alias registrado. Antes: alias
+    // com typo degradava o prompt silenciosamente (warning enterrado); agora
+    // o boot falha apontando o Kind + campo + alias. Runtime herda de Kernel,
+    // então AMBOS os caminhos (createKernelWithBuiltins/createRuntimeWithBuiltins)
+    // passam por aqui — o twin TS do gate no fim de Kernel.auto() (Python).
+    target
+        .validateDepFilters?.();
+    return target;
+}
+/**
+ * Return a fresh Kernel with all six built-in extensions registered.
+ * No source, cache, or resolvers wired — callers are responsible for
+ * that. Use `quickInstance()` if you want the full batteries-included
+ * shortcut.
+ */
+export function createKernelWithBuiltins() {
+    return loadBuiltins(new Kernel());
+}
+/**
+ * Batteries-included shortcut: kernel + all built-in extensions +
+ * default filesystem source / cache / resolvers, then returns a
+ * `ManifestInstance` for the given scope. Equivalent to the old
+ * `Kernel.quick(scope, baseDir)` static method that used to live on
+ * the kernel class itself.
+ */
+export async function quickInstance(scope, baseDir = ".dna") {
+    const k = createKernelWithBuiltins();
+    k.source(new FilesystemSource(baseDir));
+    k.cache(new FilesystemCache(baseDir));
+    k.resolver("local", new LocalResolver(baseDir));
+    k.resolver("http", new HttpResolver());
+    k.resolver("https", new HttpResolver());
+    k.resolver("github", new GitHubResolver());
+    return k.instance(scope);
+}
+/**
+ * Return a fresh Runtime with all six built-in extensions registered.
+ * No source, cache, or resolvers wired — callers are responsible for
+ * that. Use `quickManifest()` if you want the full batteries-included
+ * shortcut.
+ */
+export function createRuntimeWithBuiltins() {
+    return loadBuiltins(new Runtime());
+}
+/**
+ * Batteries-included shortcut using Runtime: all built-in extensions +
+ * default filesystem source / cache / resolvers, then returns a
+ * `ManifestInstance` for the given scope.
+ */
+export async function quickManifest(scope, baseDir = ".dna") {
+    const rt = createRuntimeWithBuiltins();
+    rt.storage(new FilesystemSource(baseDir));
+    rt.cache(new FilesystemCache(baseDir));
+    rt.resolver("local", new LocalResolver(baseDir));
+    rt.resolver("http", new HttpResolver());
+    rt.resolver("https", new HttpResolver());
+    rt.resolver("github", new GitHubResolver());
+    return rt.manifest(scope);
+}

package/dist/extensions/agentskills/DOCS.md

@@ -0,0 +1,18 @@
+# Skill
+
+A Skill is a modular, progressively-disclosed unit of know-how. It is stored
+as a bundle rooted on a `SKILL.md` marker file plus optional `scripts/`,
+`references/`, and `assets/` directories. The shape is compatible with
+Anthropic's Agent Skills format
+(https://docs.anthropic.com/en/docs/agents/skills).
+
+Skills are NOT flattened into the agent's system prompt. Instead, the harness
+(e.g. DeepAgents' `SkillsMiddleware`) exposes a short catalogue of
+`{name, description}` entries in the system prompt; the agent decides when to
+read the full `SKILL.md` on demand via the `read` tool. This keeps the context
+window lean while still giving the agent access to deep procedural knowledge.
+
+**Composition:** Agents reference Skills via their `dep_filters.skills`
+(alias `agentskills-skill`). A single Skill can be shared across many agents
+or modules, resolved either locally or from remote dependencies via the
+resolver ports.

package/dist/extensions/agentskills.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AgentSkillsExtension — Skill kind + SkillReader.
+ *
+ * 1:1 parity with Python dna.v3.extensions.agentskills.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { ExtensionHost, Extension, ReaderPort, SerializedFile, WriterPort } from "../kernel/protocols.js";
+import type { FSLike } from "../kernel/fs.js";
+export declare class SkillReader implements ReaderPort {
+    private fs;
+    constructor(fs: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+export declare class SkillWriter implements WriterPort {
+    private fs;
+    constructor(fs: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}
+export declare class AgentSkillsExtension implements Extension {
+    private fs;
+    readonly name = "agentskills";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}