dna-sdk 0.1.0

package/dist/extensions/hooks.js

@@ -0,0 +1,247 @@
+/**
+ * HookExtension — Hook kind for declarative hook configuration.
+ *
+ * Hooks declared as YAML documents in the manifest. The kernel auto-registers
+ * them on the HookRegistry during instance creation.
+ */
+import yaml from "js-yaml";
+import { nodeFS } from "../kernel/fs.js";
+import { KindBase } from "../kernel/kind_base.js";
+import { HookSchema, HookSpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { SD } from "../kernel/protocols.js";
+// ---------------------------------------------------------------------------
+// HookKind
+// ---------------------------------------------------------------------------
+class HookKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "Hook";
+    alias = "helix-hook";
+    isSchemaAffecting = true;
+    origin = "github.com/ruinosus/dna";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.bundle("hooks", "HOOK.md", "text", "body");
+    graphStyle = { fill: "#F59E0B", stroke: "#D97706", textColor: "#fff" };
+    asciiIcon = "\u26A1";
+    displayLabel = "Hooks";
+    _sourceUrl = import.meta.url;
+    docs = "A Hook declares a middleware or event handler that the kernel auto-registers " +
+        "on the HookRegistry when the manifest is loaded. Hooks can inject fields into " +
+        "the prompt context (inject_fields), log events (log), or run custom scripts (script).";
+    uiSchema = {
+        target: {
+            widget: "select",
+            label: "Target Hook",
+            help: "Which kernel hook this attaches to",
+            options: ["pre_build_prompt", "post_build_prompt", "parse_error", "extension_error", "kinddef_conflict"],
+            order: 1,
+        },
+        type: {
+            widget: "select",
+            label: "Type",
+            help: "Middleware transforms context (returns modified ctx). Event is fire-and-forget.",
+            options: ["middleware", "event"],
+            order: 2,
+        },
+        action: {
+            widget: "select",
+            label: "Action",
+            help: "inject_fields: merge YAML key-value pairs into prompt context. log: log event to console. script: run custom code.",
+            options: ["inject_fields", "log", "script"],
+            order: 3,
+        },
+        fields: {
+            widget: "code",
+            language: "yaml",
+            label: "Injected Fields (YAML)",
+            help: "Key-value pairs merged into the prompt context when action is inject_fields",
+            height: 200,
+            order: 4,
+        },
+        body: {
+            widget: "code",
+            language: "javascript",
+            label: "Script",
+            help: "JavaScript function: (ctx) => { ... return ctx; } for middleware, or (ctx) => { ... } for events",
+            height: 300,
+            order: 5,
+        },
+    };
+    schema() { return zodSpecToJsonSchema(HookSpecSchema); }
+    parse(raw) {
+        return HookSchema.parse(raw);
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        return `Hook: ${doc.name} \u2192 ${spec.target} (${spec.action})`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            target: spec.target ?? "",
+            type: spec.type ?? "middleware",
+            action: spec.action ?? "inject_fields",
+        };
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        blocks.push({
+            kind: "fields",
+            title: "Hook Configuration",
+            fields: [
+                { label: "Target", value: String(spec.target ?? "") },
+                { label: "Type", value: String(spec.type ?? "middleware") },
+                { label: "Action", value: String(spec.action ?? "inject_fields") },
+            ],
+        });
+        const action = spec.action;
+        if (action === "inject_fields") {
+            const fields = spec.fields;
+            if (fields && Object.keys(fields).length > 0) {
+                blocks.push({
+                    kind: "code",
+                    title: "Injected Fields",
+                    body: JSON.stringify(fields, null, 2),
+                    language: "json",
+                });
+            }
+        }
+        else if (action === "script") {
+            const body = spec.body;
+            if (body) {
+                blocks.push({
+                    kind: "code",
+                    title: "Script",
+                    body,
+                    language: "javascript",
+                });
+            }
+        }
+        return blocks.length > 0 ? blocks : [{ kind: "empty", title: "Hook (empty)" }];
+    }
+}
+// ---------------------------------------------------------------------------
+// HookReader: detects HOOK.md and parses frontmatter + body
+// ---------------------------------------------------------------------------
+function parseFrontmatter(text) {
+    const match = text.match(/^---\n([\s\S]*?)---\n?/);
+    if (!match)
+        return [{}, text];
+    let fm = {};
+    try {
+        const parsed = yaml.load(match[1]);
+        if (typeof parsed === "object" && parsed !== null) {
+            fm = parsed;
+        }
+    }
+    catch { /* ignore */ }
+    const body = text.slice(match[0].length);
+    return [fm, body];
+}
+export class HookReader {
+    fs;
+    _marker = "HOOK.md";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/HOOK.md`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const text = this.fs.readFile(`${path}/HOOK.md`);
+        const [fm, body] = parseFrontmatter(text);
+        const name = String(fm.name || "") || path.split("/").pop() || "";
+        const description = String(fm.description || "");
+        const spec = {
+            target: fm.target ?? "pre_build_prompt",
+            type: fm.type ?? "middleware",
+            action: fm.action ?? "inject_fields",
+            body: body.trim(),
+        };
+        // Parse body based on action type
+        const action = spec.action;
+        if (action === "inject_fields" && body.trim()) {
+            try {
+                const parsed = yaml.load(body.trim());
+                if (typeof parsed === "object" && parsed !== null) {
+                    spec.fields = parsed;
+                }
+            }
+            catch {
+                // If YAML parse fails, treat as raw text
+                spec.fields = {};
+            }
+        }
+        return {
+            apiVersion: "github.com/ruinosus/dna/v1",
+            kind: "Hook",
+            metadata: { name, description },
+            spec,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// HookWriter: serializes Hook back to HOOK.md
+// ---------------------------------------------------------------------------
+export class HookWriter {
+    fs;
+    _kind = "Hook";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    canWrite(raw) {
+        return raw.kind === "Hook";
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        for (const f of this.serialize(raw)) {
+            this.fs.writeFile(`${path}/${f.relativePath}`, f.content ?? "");
+        }
+    }
+    serialize(raw) {
+        const meta = (raw.metadata ?? {});
+        const spec = (raw.spec ?? {});
+        const fmParts = [];
+        if (meta.name)
+            fmParts.push(`name: ${meta.name}`);
+        if (meta.description)
+            fmParts.push(`description: ${meta.description}`);
+        fmParts.push(`target: ${spec.target ?? "pre_build_prompt"}`);
+        fmParts.push(`type: ${spec.type ?? "middleware"}`);
+        fmParts.push(`action: ${spec.action ?? "inject_fields"}`);
+        const frontmatter = fmParts.join("\n");
+        let body = "";
+        const action = spec.action;
+        if (action === "inject_fields" && spec.fields) {
+            body = yaml.dump(spec.fields, { flowLevel: -1 }).trim();
+        }
+        else if (action === "script" && spec.body) {
+            body = String(spec.body);
+        }
+        const content = body
+            ? `---\n${frontmatter}\n---\n\n${body}\n`
+            : `---\n${frontmatter}\n---\n`;
+        return [{ relativePath: "HOOK.md", content }];
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class HookExtension {
+    fs;
+    name = "hooks";
+    version = "1.0.0";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    register(kernel) {
+        kernel.kind(new HookKind());
+        kernel.reader(new HookReader(this.fs));
+        kernel.writer(new HookWriter(this.fs));
+    }
+}

package/dist/extensions/kinddef/DOCS.md

@@ -0,0 +1,24 @@
+# KindDefinition
+
+`KindDefinition` is the Helix meta-kind: a declarative way to register
+brand-new kinds into a manifest without writing any extension code.
+
+A KindDefinition document lives at
+`.dna/<scope>/kinds/<name>/KIND.yaml` and carries:
+
+- `target_api_version` — the apiVersion new documents of this kind will claim
+- `target_kind` — the kind name (e.g. `Recipe`, `Meeting`)
+- `alias` — the `<owner>-<kind>` alias used in dep_filters and prompts
+- `origin` — provenance string
+- `schema` — a JSON Schema that validates each document's `spec`
+- `storage` — layout descriptor (`bundle`, `yaml`, `standalone`, `root`)
+- `docs` — prose description surfaced by `describeKind`
+- `is_root`, `prompt_target`, `flatten_in_context`, `dep_filters`,
+  `default_agent` — the same prompt + composition flags hand-written kinds
+  expose
+
+At load time the kernel performs a 2-phase parse: KindDefinitions are
+parsed first and each is wrapped in a synthesized `DeclarativeKindPort`
+that's registered on the kernel before any other document is parsed. If a
+KindDefinition claims the same `(apiVersion, kind)` as an extension-backed
+kind, the extension wins and the KindDefinition is skipped with a warning.

package/dist/extensions/kinddef.d.ts

@@ -0,0 +1,40 @@
+/**
+ * KindDefinitionExtension — the built-in meta-kind extension.
+ *
+ * Ships the `KindDefinition` kind itself. Documents live at
+ * `.dna/<scope>/kinds/<name>/KIND.yaml` (bundle layout). The kernel's
+ * 2-phase loader parses these first and synthesizes a DeclarativeKindPort
+ * for each before parsing the rest of the manifest.
+ *
+ * 1:1 parity with Python dna.extensions.kinddef.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { FSLike } from "../kernel/fs.js";
+import type { Extension, ReaderPort, SerializedFile, WriterPort } from "../kernel/protocols.js";
+import type { ExtensionHost } from "../kernel/protocols.js";
+/** Reader for `kinds/<name>/KIND.yaml` — plain YAML, not frontmatter+body. */
+export declare class KindDefinitionReader implements ReaderPort {
+    private fs;
+    /** Exposed for deferred-generic-registration detection. */
+    readonly _marker = "KIND.yaml";
+    constructor(fs?: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+/** Writer for KindDefinition bundles — plain YAML. */
+export declare class KindDefinitionWriter implements WriterPort {
+    private fs;
+    /** Exposed for deferred-generic-registration detection. */
+    readonly _kind = "KindDefinition";
+    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 KindDefinitionExtension implements Extension {
+    private fs;
+    readonly name = "kinddef";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/kinddef.js

@@ -0,0 +1,171 @@
+/**
+ * KindDefinitionExtension — the built-in meta-kind extension.
+ *
+ * Ships the `KindDefinition` kind itself. Documents live at
+ * `.dna/<scope>/kinds/<name>/KIND.yaml` (bundle layout). The kernel's
+ * 2-phase loader parses these first and synthesizes a DeclarativeKindPort
+ * for each before parsing the rest of the manifest.
+ *
+ * 1:1 parity with Python dna.extensions.kinddef.
+ */
+import yaml from "js-yaml";
+import { nodeFS } from "../kernel/fs.js";
+import { KindBase } from "../kernel/kind_base.js";
+import { KIND_DEFINITION_API_VERSION, KIND_DEFINITION_KIND, KindDefinitionSchema, KindDefinitionSpecSchema, zodSpecToJsonSchema, } from "../kernel/models.js";
+import { SD } from "../kernel/protocols.js";
+class KindDefinitionKind extends KindBase {
+    apiVersion = KIND_DEFINITION_API_VERSION;
+    kind = KIND_DEFINITION_KIND;
+    alias = "kinddef-kinddefinition";
+    isSchemaAffecting = true;
+    isOverlayable = false;
+    scopeInheritable = false;
+    origin = "github.com/ruinosus/dna/core";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.bundle("kinds", "KIND.yaml");
+    visibleInBackend = true; // user-authored via wizard, not system-generated
+    graphStyle = { fill: "#A855F7", stroke: "#9333EA", textColor: "#fff" };
+    asciiIcon = "🧬";
+    displayLabel = "KindDefinitions";
+    _sourceUrl = import.meta.url;
+    docs = "A KindDefinition declaratively defines a brand-new kind without " +
+        "writing TypeScript code. Its spec carries the target apiVersion, kind " +
+        "name, alias, JSON Schema for the document spec, storage layout, and " +
+        "prompt flags. The kernel's 2-phase loader parses KindDefinitions first, " +
+        "synthesizes a DeclarativeKindPort for each, then parses the rest of " +
+        "the manifest so regular documents can reference the newly registered kind.";
+    depFilters() {
+        return null;
+    }
+    dependencies() {
+        return this.depFilters();
+    }
+    schema() {
+        return zodSpecToJsonSchema(KindDefinitionSpecSchema);
+    }
+    getDefaultAgentName(_doc) {
+        return null;
+    }
+    getLayerPolicies(_doc) {
+        return null;
+    }
+    parse(raw) {
+        return KindDefinitionSchema.parse(raw);
+    }
+    describe() {
+        return null;
+    }
+    summary() {
+        return null;
+    }
+    promptTemplate() {
+        return null;
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const fields = [];
+        if (typeof spec.target_kind === "string")
+            fields.push({ label: "target_kind", value: spec.target_kind });
+        if (typeof spec.target_api_version === "string")
+            fields.push({ label: "target_api_version", value: spec.target_api_version });
+        if (typeof spec.alias === "string")
+            fields.push({ label: "alias", value: spec.alias });
+        if (typeof spec.origin === "string")
+            fields.push({ label: "origin", value: spec.origin });
+        for (const flag of ["is_root", "prompt_target", "flatten_in_context"]) {
+            if (spec[flag] != null) {
+                fields.push({ label: flag, value: String(spec[flag]) });
+            }
+        }
+        if (spec.storage) {
+            fields.push({
+                label: "storage",
+                value: JSON.stringify(spec.storage, null, 2),
+            });
+        }
+        if (spec.schema) {
+            fields.push({
+                label: "schema",
+                value: JSON.stringify(spec.schema, null, 2),
+            });
+        }
+        if (typeof spec.docs === "string" && spec.docs) {
+            fields.push({ label: "docs", value: spec.docs });
+        }
+        if (fields.length === 0) {
+            return [{ kind: "empty", title: `KindDefinition ${doc.name}` }];
+        }
+        return [{ kind: "fields", title: `KindDefinition ${doc.name}`, fields }];
+    }
+}
+/** Reader for `kinds/<name>/KIND.yaml` — plain YAML, not frontmatter+body. */
+export class KindDefinitionReader {
+    fs;
+    /** Exposed for deferred-generic-registration detection. */
+    _marker = "KIND.yaml";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/KIND.yaml`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const text = this.fs.readFile(`${path}/KIND.yaml`);
+        const doc = yaml.load(text);
+        if (doc == null || typeof doc !== "object") {
+            throw new Error(`${path}/KIND.yaml did not parse into a mapping`);
+        }
+        const raw = doc;
+        if (!raw.apiVersion)
+            raw.apiVersion = KIND_DEFINITION_API_VERSION;
+        if (!raw.kind)
+            raw.kind = KIND_DEFINITION_KIND;
+        const meta = raw.metadata ?? {};
+        if (!meta.name)
+            meta.name = path.split("/").pop() ?? "";
+        raw.metadata = meta;
+        return raw;
+    }
+}
+/** Writer for KindDefinition bundles — plain YAML. */
+export class KindDefinitionWriter {
+    fs;
+    /** Exposed for deferred-generic-registration detection. */
+    _kind = KIND_DEFINITION_KIND;
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    canWrite(raw) {
+        return raw.kind === KIND_DEFINITION_KIND;
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        this.fs.writeFile(`${path}/KIND.yaml`, yaml.dump(raw, { sortKeys: false, flowLevel: -1 }));
+    }
+    serialize(raw) {
+        return [
+            {
+                relativePath: "KIND.yaml",
+                content: yaml.dump(raw, { sortKeys: false, flowLevel: -1 }),
+            },
+        ];
+    }
+}
+export class KindDefinitionExtension {
+    fs;
+    name = "kinddef";
+    version = "1.0.0";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    register(kernel) {
+        kernel.kind(new KindDefinitionKind());
+        kernel.reader(new KindDefinitionReader(this.fs));
+        kernel.writer(new KindDefinitionWriter(this.fs));
+    }
+}

package/dist/extensions/lesson.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare class LessonExtension implements Extension {
+    name: string;
+    version: string;
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/lesson.js

@@ -0,0 +1,194 @@
+/**
+ * LessonExtension — declarative educational activity Kind (TS twin).
+ *
+ * 1:1 parity with python/dna/extensions/lesson/__init__.py.
+ * A Lesson is a short structured activity a child-companion agent runs. Bundle
+ * storage: LESSON.md (frontmatter = spec). GLOBAL — the catalog is per-scope.
+ */
+import yaml from "js-yaml";
+import { KindBase } from "../kernel/kind_base.js";
+import { SD, TenantScope } from "../kernel/protocols.js";
+import { writeEntriesToHandle } from "../kernel/writer-helpers.js";
+const API_VERSION = "github.com/ruinosus/dna/lesson/v1";
+function parseFrontmatter(text) {
+    const m = text.match(/^---\n([\s\S]*?)---\n?([\s\S]*)$/);
+    if (!m)
+        return { fm: {}, body: text };
+    try {
+        const parsed = yaml.load(m[1]);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { fm: parsed, body: (m[2] ?? "").replace(/^\n+/, "") };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { fm: {}, body: text };
+}
+class LessonKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "Lesson";
+    alias = "lesson-lesson";
+    origin = "github.com/ruinosus/dna/lesson";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    // GLOBAL — the catalog is per-scope, not per-tenant.
+    scope = TenantScope.GLOBAL;
+    storage = SD.bundle("lessons", "LESSON.md");
+    graphStyle = { fill: "#F59E0B", stroke: "#D97706", textColor: "#fff" };
+    asciiIcon = "📚";
+    displayLabel = "Lessons";
+    docs = "A Lesson is a short, structured educational activity the agent can run with " +
+        "a pre-reader child. Declarative — content is in YAML, edited by caregivers " +
+        "in Studio, no code review. Tools: start_lesson(subject) picks one; " +
+        "record_attempt(concept, correct) tracks performance into LessonLearned docs.";
+    dependencies() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["subject", "target_concepts", "prompts"],
+            additionalProperties: true,
+            properties: {
+                subject: { type: "string", description: "Short concept group ('cores-basicas', 'animais-conhecidos', 'rotina-comer')." },
+                title: { type: "string", description: "Display title in PT-BR ('Cores básicas', 'Animais que você conhece')." },
+                skill: {
+                    type: "string",
+                    enum: ["reconhecer", "identificar", "parear", "repetir", "associar", "contar", "ordenar"],
+                    default: "reconhecer",
+                },
+                modality: {
+                    type: "array",
+                    items: { type: "string", enum: ["visual", "audio", "interativo"] },
+                    default: ["visual", "audio", "interativo"],
+                },
+                difficulty: { type: "integer", minimum: 1, maximum: 5, default: 1 },
+                duration_seconds_max: { type: "integer", default: 120, description: "Cap to respect TDAH attention budget. 60-180 typical for ages 8-12." },
+                target_concepts: { type: "array", items: { type: "string" }, description: "Concept slugs that match Pictogram.spec.concept (azul, vermelho, etc)." },
+                prompts: { type: "array", items: { type: "string" }, description: "DEPRECATED v2: legacy flat list of Lumi-spoken prompts. Use `steps` instead. Kept for back-compat with v1 seeds — if `steps` is missing, runtime synthesizes a 1-step-per-prompt timeline." },
+                steps: {
+                    type: "array",
+                    description: "Ordered list of LessonStep objects. Agent walks them in order, listening to Mateus between each, calling show_pictogram for visual anchor and record_attempt on test steps.",
+                    items: {
+                        type: "object",
+                        required: ["kind", "prompt"],
+                        additionalProperties: true,
+                        properties: {
+                            kind: {
+                                type: "string",
+                                enum: ["present", "repeat", "test", "celebrate", "review"],
+                                description: "present = introduce concept; repeat = ask Mateus to repeat/imitate; test = ask Mateus to identify (calls record_attempt); celebrate = positive reinforcement; review = recap before next step.",
+                            },
+                            prompt: { type: "string", description: "Short PT-BR phrase Lumi speaks at this step. ≤6 words ideal." },
+                            expected_concept: { type: "string", description: "Optional Pictogram concept slug to show via show_pictogram(). Required on `test` steps so record_attempt knows the target." },
+                            on_correct: { type: "string", description: "Lumi's reaction on success. Default: 'Isso!' for test, advance otherwise." },
+                            on_incorrect: { type: "string", description: "Lumi's reaction on failure. Default: gentle re-prompt + show pictogram again." },
+                            hint_ladder: { type: "array", items: { type: "string" }, description: "Optional 1-3 progressively stronger hints if Mateus errs (silhouette → color → sound)." },
+                        },
+                    },
+                },
+                reinforcement: { type: "string", enum: ["celebrate", "gentle", "neutral"], default: "celebrate", description: "How Lumi reacts to correct answers. 'celebrate' = set_pose celebrating + warm phrase." },
+                on_no_response: { type: "string", default: "Vamos tentar outra coisa?", description: "Phrase Lumi says after ~30s of no input. Always gentle, never pressuring." },
+                success_criteria: { type: "object", additionalProperties: true, description: "How to mark this lesson 'done well'. Example: {matches: 3, duration_min: 30}." },
+                approved_by: { type: "array", items: { type: "string" }, default: [] },
+                labels: { type: "array", items: { type: "string" }, default: [] },
+            },
+        };
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        const title = spec.title || spec.subject || "?";
+        const diff = spec.difficulty ?? 1;
+        return `${title} (lv ${diff})`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        const concepts = spec.target_concepts ?? [];
+        const steps = spec.steps ?? [];
+        return {
+            subject: spec.subject ?? "",
+            skill: spec.skill ?? "",
+            difficulty: spec.difficulty ?? 1,
+            concept_count: concepts.length,
+            step_count: steps.length,
+            format: steps.length ? "multi-step" : "legacy-prompts",
+        };
+    }
+}
+class LessonReader {
+    async detect(bundle) {
+        return bundle.exists("LESSON.md");
+    }
+    async read(bundle) {
+        const text = await bundle.readText("LESSON.md");
+        const { fm } = parseFrontmatter(text);
+        if (fm && typeof fm === "object" && "spec" in fm && fm["spec"] && typeof fm["spec"] === "object") {
+            const metadata = fm["metadata"] ?? {};
+            if (!("name" in metadata))
+                metadata["name"] = bundle.name;
+            return {
+                apiVersion: fm["apiVersion"] ?? API_VERSION,
+                kind: fm["kind"] ?? "Lesson",
+                metadata,
+                spec: fm["spec"],
+            };
+        }
+        return {
+            apiVersion: API_VERSION,
+            kind: "Lesson",
+            metadata: { name: bundle.name },
+            spec: fm,
+        };
+    }
+}
+class LessonWriter {
+    canWrite(raw) {
+        return raw["kind"] === "Lesson";
+    }
+    serialize(raw) {
+        const spec = (raw["spec"] ?? {});
+        const meta = { ...(raw["metadata"] ?? {}) };
+        const cleanSpec = {};
+        for (const [k, v] of Object.entries(spec)) {
+            if (v === null || v === undefined || v === "")
+                continue;
+            if (Array.isArray(v) && v.length === 0)
+                continue;
+            if (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0)
+                continue;
+            cleanSpec[k] = v;
+        }
+        const cleanMeta = {};
+        for (const [k, v] of Object.entries(meta)) {
+            if (v !== null && v !== undefined)
+                cleanMeta[k] = v;
+        }
+        const envelope = {
+            apiVersion: raw["apiVersion"] ?? API_VERSION,
+            kind: raw["kind"] ?? "Lesson",
+            metadata: cleanMeta,
+            spec: cleanSpec,
+        };
+        const fmYaml = yaml.dump(envelope, { lineWidth: 100, noRefs: true, sortKeys: false }).trimEnd();
+        const title = cleanSpec["title"] || cleanSpec["subject"] || "?";
+        const skill = cleanSpec["skill"] ?? "reconhecer";
+        const diff = cleanSpec["difficulty"] ?? 1;
+        const subject = cleanSpec["subject"] ?? "?";
+        const body = `# Lesson — ${title} (skill: ${skill}, lv ${diff})\n\n` +
+            `Curated educational activity for child-companion agents. Run via ` +
+            `\`start_lesson(${subject})\`.\n`;
+        return [{ relativePath: "LESSON.md", content: `---\n${fmYaml}\n---\n\n${body}` }];
+    }
+    async write(bundle, raw) {
+        await writeEntriesToHandle(bundle, this.serialize(raw));
+    }
+}
+export class LessonExtension {
+    name = "lesson";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new LessonKind());
+        kernel.reader(new LessonReader());
+        kernel.writer(new LessonWriter());
+    }
+}