dna-sdk 0.8.0 → 0.10.0

package/dist/config.d.ts

@@ -11,6 +11,13 @@ export interface DnaConfig {
     search: SearchMode;
     /** Embedding provider selector (default `off`). */
     embedding: EmbeddingMode;
+    /**
+     * Opaque passthrough of the `auth:` section — the SDK only checks it is a
+     * mapping; its detailed schema (`providers[]` — the pluggable N-provider IdP
+     * layer of the MCP runtime face) is owned by the consumer (the CLI's
+     * `_mcp_auth.parse_auth_providers`). `null` when the file has no `auth:`.
+     */
+    auth: Record<string, unknown> | null;
     /** Where it was loaded from (`null` for a synthesized default). */
     path: string | null;
 }

package/dist/config.js

@@ -25,7 +25,7 @@ import yaml from "js-yaml";
 export const CONFIG_FILENAME = "dna.config.yaml";
 const VALID_SEARCH = ["off", "pgvector", "sqlite-vec"];
 const VALID_EMBEDDING = ["off", "fake", "onnx"];
-const KNOWN_KEYS = new Set(["source", "search", "embedding"]);
+const KNOWN_KEYS = new Set(["source", "search", "embedding", "auth"]);
 /**
  * Path to `dna.config.yaml` in `start` (default: cwd), or `null` if absent.
  * Deliberately NOT a walk-up — a config's meaning is tied to the boot dir.
@@ -93,10 +93,19 @@ function parse(raw, path) {
         throw new Error(`${path}: \`embedding: ${embedding}\` is not valid — choose one of ` +
             `${JSON.stringify(VALID_EMBEDDING)}.`);
     }
+    const rawAuth = obj.auth;
+    if (rawAuth !== undefined &&
+        rawAuth !== null &&
+        (typeof rawAuth !== "object" || Array.isArray(rawAuth))) {
+        throw new Error(`${path}: \`auth:\` must be a mapping (its \`providers:\` list configures ` +
+            `the MCP IdP layer).`);
+    }
+    const auth = (rawAuth ?? null);
     return {
         source,
         search: search,
         embedding: embedding,
+        auth,
         path,
     };
 }

package/dist/emit/agentFramework.d.ts

@@ -13,4 +13,6 @@ export declare class AgentFrameworkEmitter implements EmitterPort {
      *  order is intentional and preserved by js-yaml (insertion order). */
     toPromptAgent(ctx: EmitContext): Record<string, unknown>;
     emit(ctx: EmitContext): EmitResult;
+    /** Byte-equal invariant hook: read `instructions` back from the emitted YAML. */
+    extractInstructions(artifact: string): string | null;
 }

package/dist/emit/agentFramework.js

@@ -124,4 +124,10 @@ export class AgentFrameworkEmitter {
             mapping,
         };
     }
+    /** Byte-equal invariant hook: read `instructions` back from the emitted YAML. */
+    extractInstructions(artifact) {
+        const doc = yaml.load(artifact);
+        const value = doc?.instructions;
+        return typeof value === "string" ? value : null;
+    }
 }

package/dist/emit/agno.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DNA → **Agno** emitter (code-first, `agno.agent`; TS twin of python
+ * `dna.emit.agno`).
+ *
+ * Agno is code-first — you construct `Agent(name=..., model=..., instructions=...,
+ * tools=[...])`, there is no declarative agent file to map onto. So this target is a
+ * {@link ScaffoldEmitter}: it fills a curated `{agno × case}` template rather than
+ * generating code ad-hoc, and the emitted `INSTRUCTIONS` constant is byte-equal to
+ * the DNA-composed prompt.
+ *
+ * Model: the DNA coordinate is PRESERVED as a string (Agno accepts a `provider:model`
+ * string). Cases: `prompt-only` (no tools) and `with-tools` (one plain-function stub
+ * per DNA Tool — Agno auto-wraps callables as tools). `structured-output` (Agno's
+ * `output_schema`) is not shipped yet and falls back with a recorded loss.
+ */
+import { ScaffoldEmitter, type ScaffoldChoice } from "./scaffold.js";
+import type { EmitContext } from "./index.js";
+export declare class AgnoEmitter extends ScaffoldEmitter {
+    readonly framework = "agno";
+    readonly target = "agno";
+    readonly fileExtension = "py";
+    renderContext(ctx: EmitContext, _case: string): Record<string, unknown>;
+    losses(ctx: EmitContext, _choice: ScaffoldChoice): string[];
+    mapping(): Record<string, string>;
+}

package/dist/emit/agno.js

@@ -0,0 +1,65 @@
+/**
+ * DNA → **Agno** emitter (code-first, `agno.agent`; TS twin of python
+ * `dna.emit.agno`).
+ *
+ * Agno is code-first — you construct `Agent(name=..., model=..., instructions=...,
+ * tools=[...])`, there is no declarative agent file to map onto. So this target is a
+ * {@link ScaffoldEmitter}: it fills a curated `{agno × case}` template rather than
+ * generating code ad-hoc, and the emitted `INSTRUCTIONS` constant is byte-equal to
+ * the DNA-composed prompt.
+ *
+ * Model: the DNA coordinate is PRESERVED as a string (Agno accepts a `provider:model`
+ * string). Cases: `prompt-only` (no tools) and `with-tools` (one plain-function stub
+ * per DNA Tool — Agno auto-wraps callables as tools). `structured-output` (Agno's
+ * `output_schema`) is not shipped yet and falls back with a recorded loss.
+ */
+import { pyIdentifier, pyStrLiteral, ScaffoldEmitter } from "./scaffold.js";
+export class AgnoEmitter extends ScaffoldEmitter {
+    framework = "agno";
+    target = "agno";
+    fileExtension = "py";
+    renderContext(ctx, _case) {
+        const tools = ctx.tools.map((t) => ({
+            name: t.name,
+            func_name: pyIdentifier(t.name),
+            docstring_literal: pyStrLiteral(t.description || t.name),
+        }));
+        return {
+            has_model: ctx.model !== null,
+            model_literal: ctx.model ? pyStrLiteral(ctx.model) : "",
+            tools,
+            tool_list: tools.map((t) => t.func_name).join(", "),
+        };
+    }
+    losses(ctx, _choice) {
+        const out = [];
+        if (ctx.tools.length > 0) {
+            out.push("tool body — each tool is a scaffolded STUB (a bare callable + " +
+                "`raise NotImplementedError`); its real implementation and typed signature " +
+                "must be wired (Agno derives the tool schema from the function signature + " +
+                "docstring)");
+        }
+        if (ctx.model === null) {
+            out.push("model unbound in DNA and none supplied — emitted `Agent(...)` has no " +
+                "`model=`; supply one at wire-up (Agno requires a model)");
+        }
+        else {
+            out.push("model coordinate — the DNA coordinate is carried verbatim as a string; this " +
+                "assumes Agno's string-model resolution. A specific `Model` object (e.g. " +
+                "`OpenAIChat(id=...)`) is the alternative at wire-up");
+        }
+        if (ctx.outputSchema) {
+            out.push("output_schema — map DNA's `spec.output_schema` to `Agent(output_schema=...)` " +
+                "(a Pydantic model) by hand; the scaffold does not synthesize the class");
+        }
+        return out;
+    }
+    mapping() {
+        return {
+            "buildPrompt (Soul+guardrails+instruction)": "INSTRUCTIONS constant (byte-equal)",
+            "metadata.name": "Agent(name=...)",
+            "spec.model / Genome.default_llm": "Agent(model=...) (DNA coordinate preserved)",
+            "spec.tools[] (Tool Kind)": "plain-function stubs → Agent(tools=[...])",
+        };
+    }
+}

package/dist/emit/bedrock.d.ts

@@ -44,4 +44,7 @@ export declare class BedrockEmitter implements EmitterPort {
      *  order is intentional and preserved by JSON.stringify (insertion order). */
     toTemplate(ctx: EmitContext): Record<string, unknown>;
     emit(ctx: EmitContext): EmitResult;
+    /** Byte-equal invariant hook: read `Properties.Instruction` back from the
+     *  emitted CloudFormation template. */
+    extractInstructions(artifact: string): string | null;
 }

package/dist/emit/bedrock.js

@@ -166,4 +166,13 @@ export class BedrockEmitter {
             mapping,
         };
     }
+    /** Byte-equal invariant hook: read `Properties.Instruction` back from the
+     *  emitted CloudFormation template. */
+    extractInstructions(artifact) {
+        const template = JSON.parse(artifact);
+        const resources = template.Resources ?? {};
+        const first = Object.values(resources)[0];
+        const value = first?.Properties?.Instruction;
+        return typeof value === "string" ? value : null;
+    }
 }

package/dist/emit/deepagents.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DNA → **DeepAgents** emitter (code-first, `deepagents`; TS twin of python
+ * `dna.emit.deepagents`).
+ *
+ * DeepAgents (the LangChain "batteries-included agent harness") is code-first — you
+ * call `create_deep_agent(model=..., tools=[...], system_prompt="...")`, there is no
+ * declarative agent file to map onto. So this target is a {@link ScaffoldEmitter}: it
+ * fills a curated `{deepagents × case}` template rather than generating code ad-hoc,
+ * and the emitted `INSTRUCTIONS` constant is byte-equal to the DNA-composed prompt.
+ *
+ * `system_prompt` sits in FRONT of the deep-agent's built-in harness prompt (the
+ * planning / filesystem / sub-agent scaffolding the framework appends) — so the DNA
+ * prompt is a PREFIX of the effective system prompt. Model: the DNA coordinate is
+ * PRESERVED (resolved via `init_chat_model`). Cases: `prompt-only` and `with-tools`.
+ */
+import { ScaffoldEmitter, type ScaffoldChoice } from "./scaffold.js";
+import type { EmitContext } from "./index.js";
+export declare class DeepAgentsEmitter extends ScaffoldEmitter {
+    readonly framework = "deepagents";
+    readonly target = "deepagents";
+    readonly fileExtension = "py";
+    renderContext(ctx: EmitContext, _case: string): Record<string, unknown>;
+    losses(ctx: EmitContext, _choice: ScaffoldChoice): string[];
+    mapping(): Record<string, string>;
+}

package/dist/emit/deepagents.js

@@ -0,0 +1,71 @@
+/**
+ * DNA → **DeepAgents** emitter (code-first, `deepagents`; TS twin of python
+ * `dna.emit.deepagents`).
+ *
+ * DeepAgents (the LangChain "batteries-included agent harness") is code-first — you
+ * call `create_deep_agent(model=..., tools=[...], system_prompt="...")`, there is no
+ * declarative agent file to map onto. So this target is a {@link ScaffoldEmitter}: it
+ * fills a curated `{deepagents × case}` template rather than generating code ad-hoc,
+ * and the emitted `INSTRUCTIONS` constant is byte-equal to the DNA-composed prompt.
+ *
+ * `system_prompt` sits in FRONT of the deep-agent's built-in harness prompt (the
+ * planning / filesystem / sub-agent scaffolding the framework appends) — so the DNA
+ * prompt is a PREFIX of the effective system prompt. Model: the DNA coordinate is
+ * PRESERVED (resolved via `init_chat_model`). Cases: `prompt-only` and `with-tools`.
+ */
+import { pyIdentifier, pyStrLiteral, ScaffoldEmitter } from "./scaffold.js";
+export class DeepAgentsEmitter extends ScaffoldEmitter {
+    framework = "deepagents";
+    target = "deepagents";
+    fileExtension = "py";
+    renderContext(ctx, _case) {
+        const tools = ctx.tools.map((t) => ({
+            name: t.name,
+            func_name: pyIdentifier(t.name),
+            docstring_literal: pyStrLiteral(t.description || t.name),
+        }));
+        return {
+            has_model: ctx.model !== null,
+            model_literal: ctx.model ? pyStrLiteral(ctx.model) : "",
+            tools,
+            tool_list: tools.map((t) => t.func_name).join(", "),
+        };
+    }
+    losses(ctx, _choice) {
+        const out = [
+            "harness prompt — `system_prompt` sits in FRONT of the deep-agent's built-in " +
+                "harness prompt (planning / filesystem / sub-agent scaffolding), which the " +
+                "framework appends; the DNA prompt is a PREFIX of the effective system prompt, " +
+                "not the whole of it",
+            "metadata.name — `create_deep_agent` has no declarative name slot; the DNA agent " +
+                "name is not carried",
+        ];
+        if (ctx.tools.length > 0) {
+            out.push("tool body — each tool is a scaffolded STUB (a callable + " +
+                "`raise NotImplementedError`); its real implementation and typed signature " +
+                "must be wired");
+        }
+        if (ctx.model === null) {
+            out.push("model unbound in DNA and none supplied — emitted `create_deep_agent(...)` has " +
+                "no `model=`; the framework falls back to its default deep-agent model");
+        }
+        else {
+            out.push("model coordinate — the DNA coordinate is carried verbatim; " +
+                "`create_deep_agent` resolves it via `init_chat_model`, whose provider " +
+                "prefixes are `openai` / `anthropic` / `azure_openai` / `google_genai`; a " +
+                "DNA `azure/…` coordinate needs the `azure_openai:` prefix at wire-up");
+        }
+        if (ctx.outputSchema) {
+            out.push("output_schema — DNA's `spec.output_schema` has no direct `create_deep_agent` " +
+                "slot; enforce structured output via a middleware or a typed sub-agent by hand");
+        }
+        return out;
+    }
+    mapping() {
+        return {
+            "buildPrompt (Soul+guardrails+instruction)": "INSTRUCTIONS constant (byte-equal, PREFIX of system_prompt)",
+            "spec.model / Genome.default_llm": "create_deep_agent(model=...) (DNA coordinate preserved)",
+            "spec.tools[] (Tool Kind)": "callable stubs → create_deep_agent(tools=[...])",
+        };
+    }
+}

package/dist/emit/index.d.ts

@@ -7,9 +7,28 @@
  * consumes. The concrete first step of "DNA as the Terraform of agents": author
  * once, emit per runtime, swap runtimes without rewriting the agent.
  *
+ * The {@link EmitterPort} is a **first-class DNA port** — a documented contract
+ * on the same footing as the kernel's five ports, one layer OUT: the kernel
+ * *composes* the neutral agent; the EmitterPort *materializes* it for a runtime.
+ * See the `How to write an emitter` guide (`docs/guides/writing-an-emitter.md`).
+ *
+ * The contract has two surfaces: `buildEmitContext(mi, agent)` (the kernel-facing
+ * half — compose + project to the neutral {@link EmitContext}) and
+ * `EmitterPort.emit(ctx)` (the runtime-facing half a target implements — PURE,
+ * no kernel I/O). Its **central invariant**: the composed `instructions` in the
+ * emitted artifact is byte-equal to `mi.buildPrompt({agent})`. That invariant is
+ * checkable and *inheritable* via {@link EmitterPort.extractInstructions} — one
+ * generic test runs it over EVERY registered target.
+ *
+ * Two flavors satisfy the same port: **config-declarative** (a runtime with a
+ * published declarative schema — agent-framework / bedrock / vertex) and
+ * **scaffold-code** (a code-first runtime — see `scaffold.ts`; the `openai-agents`
+ * target is the reference).
+ *
  * Parity: the pure de-para (`toPromptAgent` in `agentFramework.ts`) mirrors the
  * Python emitter field-for-field; the serialization (js-yaml vs PyYAML) is a
- * rendering detail, so the parity contract is the emitted OBJECT, not the bytes.
+ * rendering detail, so the parity contract is the emitted OBJECT/behavior, not
+ * the bytes.
  *
  * Shape: {@link EmitContext} (runtime-agnostic view of a composed agent) →
  * {@link EmitterPort} (a target) → {@link EmitResult} (artifact + honest
@@ -57,11 +76,19 @@ export interface EmitResult {
     mapping: Record<string, string>;
 }
 /** A runtime emitter — pure: reads an {@link EmitContext}, returns an
- *  {@link EmitResult}. No kernel I/O, no network. */
+ *  {@link EmitResult}. No kernel I/O, no network.
+ *
+ *  A conforming emitter provides identity (`target` / `fileExtension`), the
+ *  materialization ({@link emit}), and the byte-equal invariant hook
+ *  ({@link extractInstructions}) that makes the central invariant inheritable. */
 export interface EmitterPort {
     readonly target: string;
     readonly fileExtension: string;
     emit(ctx: EmitContext): EmitResult;
+    /** Recover the composed instruction embedded in `artifact` (the inverse of the
+     *  instruction half of {@link emit}) — used by the generic byte-equal contract
+     *  test. Returns null only when the target has no instruction slot at all. */
+    extractInstructions(artifact: string): string | null;
 }
 export declare class EmitError extends Error {
 }
@@ -72,6 +99,10 @@ export declare class UnknownTarget extends EmitError {
 }
 /** Register an emitter under its `target` (last registration wins). */
 export declare function registerEmitter(emitter: EmitterPort): EmitterPort;
+/** Remove a registered emitter (a host override or a test double). Returns
+ *  whether a target was actually removed. Parity with the Python side popping
+ *  from `EMITTER_REGISTRY`. */
+export declare function unregisterEmitter(target: string): boolean;
 /** Look up a registered emitter or throw {@link UnknownTarget}. */
 export declare function getEmitter(target: string): Promise<EmitterPort>;
 /** Sorted list of registered target ids. */

package/dist/emit/index.js

@@ -21,7 +21,20 @@ async function ensureBuiltins() {
     builtinsWired = true;
     const { AgentFrameworkEmitter } = await import("./agentFramework.js");
     const { BedrockEmitter } = await import("./bedrock.js");
-    for (const e of [new AgentFrameworkEmitter(), new BedrockEmitter()]) {
+    const { VertexEmitter } = await import("./vertex.js");
+    const { OpenAIAgentsEmitter } = await import("./openaiAgents.js");
+    const { LanggraphEmitter } = await import("./langgraph.js");
+    const { AgnoEmitter } = await import("./agno.js");
+    const { DeepAgentsEmitter } = await import("./deepagents.js");
+    for (const e of [
+        new AgentFrameworkEmitter(),
+        new BedrockEmitter(),
+        new VertexEmitter(),
+        new OpenAIAgentsEmitter(),
+        new LanggraphEmitter(),
+        new AgnoEmitter(),
+        new DeepAgentsEmitter(),
+    ]) {
         if (!EMITTER_REGISTRY.has(e.target))
             EMITTER_REGISTRY.set(e.target, e);
     }
@@ -31,6 +44,12 @@ export function registerEmitter(emitter) {
     EMITTER_REGISTRY.set(emitter.target, emitter);
     return emitter;
 }
+/** Remove a registered emitter (a host override or a test double). Returns
+ *  whether a target was actually removed. Parity with the Python side popping
+ *  from `EMITTER_REGISTRY`. */
+export function unregisterEmitter(target) {
+    return EMITTER_REGISTRY.delete(target);
+}
 /** Look up a registered emitter or throw {@link UnknownTarget}. */
 export async function getEmitter(target) {
     await ensureBuiltins();

package/dist/emit/langgraph.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DNA → **LangGraph** emitter (code-first, `langgraph.prebuilt`; TS twin of
+ * python `dna.emit.langgraph`).
+ *
+ * LangGraph is code-first — you build an agent by calling
+ * `create_react_agent(model, tools=[...], prompt="...")`, there is no declarative
+ * agent file to map onto. So this target is a {@link ScaffoldEmitter}: it fills a
+ * curated `{langgraph × case}` template rather than generating code ad-hoc, and the
+ * emitted `INSTRUCTIONS` constant is byte-equal to the DNA-composed prompt.
+ *
+ * Model: the DNA coordinate is PRESERVED (unlike openai-agents, which strips the
+ * provider token) — `create_react_agent` resolves the string via `init_chat_model`,
+ * which takes a `provider:model` coordinate. Cases: `prompt-only` (no tools) and
+ * `with-tools` (the ReAct idiom — one `@tool` stub per DNA Tool). `structured-output`
+ * (LangGraph's `response_format`) is not shipped yet and falls back with a loss.
+ */
+import { ScaffoldEmitter, type ScaffoldChoice } from "./scaffold.js";
+import type { EmitContext } from "./index.js";
+export declare class LanggraphEmitter extends ScaffoldEmitter {
+    readonly framework = "langgraph";
+    readonly target = "langgraph";
+    readonly fileExtension = "py";
+    renderContext(ctx: EmitContext, _case: string): Record<string, unknown>;
+    losses(ctx: EmitContext, _choice: ScaffoldChoice): string[];
+    mapping(): Record<string, string>;
+}

package/dist/emit/langgraph.js

@@ -0,0 +1,70 @@
+/**
+ * DNA → **LangGraph** emitter (code-first, `langgraph.prebuilt`; TS twin of
+ * python `dna.emit.langgraph`).
+ *
+ * LangGraph is code-first — you build an agent by calling
+ * `create_react_agent(model, tools=[...], prompt="...")`, there is no declarative
+ * agent file to map onto. So this target is a {@link ScaffoldEmitter}: it fills a
+ * curated `{langgraph × case}` template rather than generating code ad-hoc, and the
+ * emitted `INSTRUCTIONS` constant is byte-equal to the DNA-composed prompt.
+ *
+ * Model: the DNA coordinate is PRESERVED (unlike openai-agents, which strips the
+ * provider token) — `create_react_agent` resolves the string via `init_chat_model`,
+ * which takes a `provider:model` coordinate. Cases: `prompt-only` (no tools) and
+ * `with-tools` (the ReAct idiom — one `@tool` stub per DNA Tool). `structured-output`
+ * (LangGraph's `response_format`) is not shipped yet and falls back with a loss.
+ */
+import { pyIdentifier, pyStrLiteral, ScaffoldEmitter } from "./scaffold.js";
+export class LanggraphEmitter extends ScaffoldEmitter {
+    framework = "langgraph";
+    target = "langgraph";
+    fileExtension = "py";
+    renderContext(ctx, _case) {
+        const tools = ctx.tools.map((t) => ({
+            name: t.name,
+            func_name: pyIdentifier(t.name),
+            docstring_literal: pyStrLiteral(t.description || t.name),
+        }));
+        return {
+            has_model: ctx.model !== null,
+            model_literal: ctx.model ? pyStrLiteral(ctx.model) : "",
+            has_name: Boolean(ctx.name),
+            tools,
+            tool_list: tools.map((t) => t.func_name).join(", "),
+        };
+    }
+    losses(ctx, _choice) {
+        const out = [];
+        if (ctx.tools.length > 0) {
+            out.push("tool body — each `@tool` is a scaffolded STUB (name + " +
+                "`raise NotImplementedError`); its real implementation and typed signature " +
+                "must be wired (LangChain derives the tool schema from the function " +
+                "signature + docstring)");
+        }
+        if (ctx.model === null) {
+            out.push("model unbound in DNA and none supplied — `create_react_agent` REQUIRES a " +
+                "model; the emitted call omits `model=`, so supply one at wire-up");
+        }
+        else {
+            out.push("model coordinate — the DNA coordinate is carried verbatim; " +
+                "`create_react_agent` resolves it via `init_chat_model`, whose provider " +
+                "prefixes are `openai` / `anthropic` / `azure_openai` / `google_genai`; a " +
+                "DNA `azure/…` coordinate needs the `azure_openai:` prefix (or a model " +
+                "instance) at wire-up");
+        }
+        if (ctx.outputSchema) {
+            out.push("output_schema — map DNA's `spec.output_schema` to " +
+                "`create_react_agent(response_format=...)` (a Pydantic model) by hand; the " +
+                "scaffold does not synthesize the class");
+        }
+        return out;
+    }
+    mapping() {
+        return {
+            "buildPrompt (Soul+guardrails+instruction)": "INSTRUCTIONS constant (byte-equal)",
+            "metadata.name": "create_react_agent(name=...) (graph name)",
+            "spec.model / Genome.default_llm": "create_react_agent(model=...) (DNA coordinate preserved)",
+            "spec.tools[] (Tool Kind)": "@tool stubs → create_react_agent(tools=[...])",
+        };
+    }
+}

package/dist/emit/openaiAgents.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DNA → **OpenAI Agents SDK** emitter (the first CODE-FIRST target; TS twin of
+ * python `dna.emit.openai_agents`).
+ *
+ * The OpenAI Agents SDK is code-first — you construct an agent in Python
+ * (`Agent(name=..., instructions=..., model=..., tools=[...])`) — so this target
+ * is a {@link ScaffoldEmitter}: it fills a curated `{openai-agents × case}`
+ * template rather than generating code ad-hoc, and the emitted `INSTRUCTIONS`
+ * constant is byte-equal to the DNA-composed prompt.
+ *
+ * Cases (selected from ctx signals): `prompt-only` (no tools) and `with-tools`
+ * (the ReAct idiom — one `@function_tool` stub per DNA Tool). `structured-output`
+ * is not shipped yet and falls back with a recorded loss.
+ */
+import { ScaffoldEmitter, type ScaffoldChoice } from "./scaffold.js";
+import type { EmitContext } from "./index.js";
+/** Strip a DNA `prov:model` / `prov/model` coordinate to the bare id. */
+export declare function bareModelId(model: string | null): string | null;
+export declare class OpenAIAgentsEmitter extends ScaffoldEmitter {
+    readonly framework = "openai-agents";
+    readonly target = "openai-agents";
+    readonly fileExtension = "py";
+    renderContext(ctx: EmitContext, _case: string): Record<string, unknown>;
+    losses(ctx: EmitContext, _choice: ScaffoldChoice): string[];
+    mapping(): Record<string, string>;
+}

package/dist/emit/openaiAgents.js

@@ -0,0 +1,91 @@
+/**
+ * DNA → **OpenAI Agents SDK** emitter (the first CODE-FIRST target; TS twin of
+ * python `dna.emit.openai_agents`).
+ *
+ * The OpenAI Agents SDK is code-first — you construct an agent in Python
+ * (`Agent(name=..., instructions=..., model=..., tools=[...])`) — so this target
+ * is a {@link ScaffoldEmitter}: it fills a curated `{openai-agents × case}`
+ * template rather than generating code ad-hoc, and the emitted `INSTRUCTIONS`
+ * constant is byte-equal to the DNA-composed prompt.
+ *
+ * Cases (selected from ctx signals): `prompt-only` (no tools) and `with-tools`
+ * (the ReAct idiom — one `@function_tool` stub per DNA Tool). `structured-output`
+ * is not shipped yet and falls back with a recorded loss.
+ */
+import { pyIdentifier, pyStrLiteral, ScaffoldEmitter } from "./scaffold.js";
+const DNA_PROVIDER_TOKENS = new Set([
+    "azure", "azureopenai", "azure_openai", "openai", "foundry", "azureaifoundry",
+    "vertex", "google", "gemini", "anthropic",
+]);
+/** Strip a DNA `prov:model` / `prov/model` coordinate to the bare id. */
+export function bareModelId(model) {
+    if (!model)
+        return null;
+    const ident = model.trim();
+    for (const sep of [":", "/"]) {
+        const i = ident.indexOf(sep);
+        if (i >= 0) {
+            const token = ident.slice(0, i).trim().toLowerCase();
+            if (DNA_PROVIDER_TOKENS.has(token))
+                return ident.slice(i + 1).trim();
+        }
+    }
+    return ident;
+}
+function isOpenAIModel(modelId) {
+    if (!modelId)
+        return false;
+    const m = modelId.trim().toLowerCase();
+    return m.startsWith("gpt-") || m.startsWith("o1") || m.startsWith("o3") || m.startsWith("o4");
+}
+export class OpenAIAgentsEmitter extends ScaffoldEmitter {
+    framework = "openai-agents";
+    target = "openai-agents";
+    fileExtension = "py";
+    renderContext(ctx, _case) {
+        const modelId = bareModelId(ctx.model);
+        const tools = ctx.tools.map((t) => ({
+            name: t.name,
+            func_name: pyIdentifier(t.name),
+            docstring_literal: pyStrLiteral(t.description || t.name),
+        }));
+        return {
+            has_model: modelId !== null,
+            model_literal: modelId ? pyStrLiteral(modelId) : "",
+            tools,
+            tool_list: tools.map((t) => t.func_name).join(", "),
+        };
+    }
+    losses(ctx, _choice) {
+        const out = [];
+        if (ctx.tools.length > 0) {
+            out.push("tool body — each `@function_tool` is a scaffolded STUB (name + " +
+                "`raise NotImplementedError`); its real implementation and typed " +
+                "signature must be wired (the OpenAI Agents SDK derives the tool schema " +
+                "from the Python function signature + docstring)");
+        }
+        const modelId = bareModelId(ctx.model);
+        if (modelId === null) {
+            out.push("model unbound in DNA and none supplied — emitted `Agent(...)` has no " +
+                "`model=`; the SDK falls back to its default");
+        }
+        else if (!isOpenAIModel(modelId)) {
+            out.push("model coordinate — the OpenAI Agents SDK `model=` takes an OpenAI model " +
+                "name or a `Model` object; a non-OpenAI coordinate needs a custom " +
+                "provider / `ModelSettings` at wire-up");
+        }
+        if (ctx.outputSchema) {
+            out.push("output_schema — map DNA's `spec.output_schema` to `Agent(output_type=...)` " +
+                "(a Pydantic/TypedDict class) by hand; the scaffold does not synthesize the class");
+        }
+        return out;
+    }
+    mapping() {
+        return {
+            "buildPrompt (Soul+guardrails+instruction)": "INSTRUCTIONS constant (byte-equal)",
+            "metadata.name": "Agent(name=...)",
+            "spec.model / Genome.default_llm": "Agent(model=...) (provider token stripped)",
+            "spec.tools[] (Tool Kind)": "@function_tool stubs → Agent(tools=[...])",
+        };
+    }
+}

package/dist/emit/scaffold.d.ts

@@ -0,0 +1,65 @@
+import { type EmitContext, type EmitResult, type EmitterPort } from "./index.js";
+/** Render `value` as a Python string literal that round-trips exactly. JSON
+ *  string syntax is a valid Python literal (`\n`, `\"`, `\\`, `\uXXXX`), single
+ *  line — so the emitted `INSTRUCTIONS` constant is byte-equal-recoverable. */
+export declare function pyStrLiteral(value: string): string;
+/** `kb-search` → `kb_search` — a valid Python identifier for a tool stub. */
+export declare function pyIdentifier(name: string): string;
+/** The default case classifier — read the DNA signals the ctx already carries. */
+export declare function classifyCase(ctx: EmitContext): string;
+/** Resolve a `{framework × case}` template to its Mustache source — the abstract
+ *  seam between an emitter and *where a template lives*. The MVP reads
+ *  package-data ({@link PackageDataScaffoldResolver}); a future kernel-backed
+ *  resolver returns a per-scope/per-tenant Scaffold Kind body, swappable with no
+ *  emitter change. Returns null when the source has no template for the pair. */
+export interface ScaffoldResolver {
+    resolve(framework: string, kase: string): string | null;
+}
+/** The MVP resolver: read `emit/scaffolds/<framework>/<case>.py.tmpl`. */
+export declare class PackageDataScaffoldResolver implements ScaffoldResolver {
+    resolve(framework: string, kase: string): string | null;
+}
+/** Swap the active template resolver — the seam the Scaffold-as-Kind promotion
+ *  (`s-scaffold-as-kind`) plugs into. */
+export declare function setScaffoldResolver(resolver: ScaffoldResolver): ScaffoldResolver;
+/** Resolve a `{framework × case}` template through the active resolver. */
+export declare function resolveScaffold(framework: string, kase: string): string | null;
+/** The outcome of {@link selectScaffold}: which case template to fill. */
+export interface ScaffoldChoice {
+    /** The case actually selected (a template exists for it). */
+    case: string;
+    /** The template source (Mustache). */
+    template: string;
+    /** The case the classifier requested — differs from `case` on a fallback. */
+    requested: string;
+}
+/** Pick the `{framework × case}` template for `ctx`: classify, then resolve to a
+ *  real template, falling back down the generality chain when needed. */
+export declare function selectScaffold(framework: string, ctx: EmitContext, classify?: (ctx: EmitContext) => string, resolver?: ScaffoldResolver | null): ScaffoldChoice;
+/** Base for a CODE-FIRST {@link EmitterPort}. A subclass is THIN — it declares the
+ *  framework + target ids and supplies the framework-specific template variables
+ *  ({@link renderContext}), losses, and field mapping; case selection, template
+ *  fill, and the byte-equal invariant hook are inherited. */
+export declare abstract class ScaffoldEmitter implements EmitterPort {
+    abstract readonly framework: string;
+    abstract readonly target: string;
+    readonly fileExtension: string;
+    /** Optional template-resolution override (defaults to the active resolver —
+     *  package-data today, a Scaffold Kind resolver tomorrow). */
+    readonly resolver: ScaffoldResolver | null;
+    /** Framework-specific template variables (merged over the common ones). */
+    renderContext(_ctx: EmitContext, _case: string): Record<string, unknown>;
+    /** Framework-specific de-para losses (in addition to the common ones). */
+    losses(_ctx: EmitContext, _choice: ScaffoldChoice): string[];
+    /** Field-level de-para (`dnaField -> targetField`) for reporting. */
+    mapping(): Record<string, string>;
+    /** The case classifier — override to add a framework-specific case. */
+    classify(ctx: EmitContext): string;
+    private commonContext;
+    private commonLosses;
+    emit(ctx: EmitContext): EmitResult;
+    /** Byte-equal invariant hook: read the top-level `INSTRUCTIONS = <literal>`
+     *  constant every scaffold template emits (a JSON/Python string literal on one
+     *  line), uniform across all code-first targets regardless of constructor shape. */
+    extractInstructions(artifact: string): string | null;
+}

package/dist/emit/scaffold.js

@@ -0,0 +1,179 @@
+/**
+ * `emit/scaffold` — the CODE-FIRST flavor of the {@link EmitterPort} (TS twin of
+ * python `dna.emit.scaffold`).
+ *
+ * Some runtimes have NO declarative agent format — you construct an agent object
+ * in code (OpenAI Agents SDK, LangGraph, Agno, DeepAgents all expose a simple
+ * constructor). For those the emitter must produce SOURCE CODE, and it does so by
+ * **filling a curated template**, never by generating code ad-hoc — the template
+ * captures the framework's best-practice idiom; the emitter only routes and fills.
+ *
+ * The mechanism is a template library indexed by `{framework × case}` plus a tiny
+ * case classifier:
+ *
+ *   scaffolds/<framework>/<case>.py.tmpl     // curated best-practice idiom per case
+ *   selectScaffold(framework, ctx)           // inspect ctx's DNA signals → pick a case
+ *
+ * There is deliberately NO single "one template per framework": a prompt-only, a
+ * tool-calling (ReAct), and a structured-output agent are DIFFERENT structures in
+ * the SAME framework. The classifier reads the neutral {@link EmitContext} signals
+ * (no tools → `prompt-only`; tools → `with-tools`; `outputSchema` →
+ * `structured-output`) and falls back down a generality chain when a framework
+ * does not ship a case, recording the fallback as a loss.
+ *
+ * Future direction — Scaffold as a Kind: templates are read through an abstract
+ * seam, {@link resolveScaffold} (a {@link ScaffoldResolver}), NOT a hardcoded file
+ * path. The MVP resolver reads package-data, but the seam lets a second source
+ * plug in with no change to any emitter — a first-class **Scaffold Kind** resolved
+ * by the kernel (scope-aware, tenant-overridable). Tracked as `s-scaffold-as-kind`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Mustache from "mustache";
+import { EmitError } from "./index.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The generality fallback chain (specific → general) per requested case. */
+const FALLBACK = {
+    "structured-output": ["structured-output", "with-tools", "prompt-only"],
+    "with-tools": ["with-tools", "prompt-only"],
+    "prompt-only": ["prompt-only"],
+};
+/** Render `value` as a Python string literal that round-trips exactly. JSON
+ *  string syntax is a valid Python literal (`\n`, `\"`, `\\`, `\uXXXX`), single
+ *  line — so the emitted `INSTRUCTIONS` constant is byte-equal-recoverable. */
+export function pyStrLiteral(value) {
+    return JSON.stringify(value);
+}
+/** `kb-search` → `kb_search` — a valid Python identifier for a tool stub. */
+export function pyIdentifier(name) {
+    let ident = String(name)
+        .trim()
+        .replace(/[^0-9a-zA-Z_]/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!ident)
+        ident = "tool";
+    if (/^[0-9]/.test(ident))
+        ident = `_${ident}`;
+    return ident;
+}
+/** The default case classifier — read the DNA signals the ctx already carries. */
+export function classifyCase(ctx) {
+    if (ctx.outputSchema)
+        return "structured-output";
+    if (ctx.tools.length > 0)
+        return "with-tools";
+    return "prompt-only";
+}
+/** The MVP resolver: read `emit/scaffolds/<framework>/<case>.py.tmpl`. */
+export class PackageDataScaffoldResolver {
+    resolve(framework, kase) {
+        const path = join(HERE, "scaffolds", framework, `${kase}.py.tmpl`);
+        return existsSync(path) ? readFileSync(path, "utf-8") : null;
+    }
+}
+let activeResolver = new PackageDataScaffoldResolver();
+/** Swap the active template resolver — the seam the Scaffold-as-Kind promotion
+ *  (`s-scaffold-as-kind`) plugs into. */
+export function setScaffoldResolver(resolver) {
+    activeResolver = resolver;
+    return resolver;
+}
+/** Resolve a `{framework × case}` template through the active resolver. */
+export function resolveScaffold(framework, kase) {
+    return activeResolver.resolve(framework, kase);
+}
+/** Pick the `{framework × case}` template for `ctx`: classify, then resolve to a
+ *  real template, falling back down the generality chain when needed. */
+export function selectScaffold(framework, ctx, classify = classifyCase, resolver = null) {
+    const resolve = resolver
+        ? (f, k) => resolver.resolve(f, k)
+        : resolveScaffold;
+    const requested = classify(ctx);
+    for (const kase of FALLBACK[requested] ?? [requested]) {
+        const template = resolve(framework, kase);
+        if (template !== null)
+            return { case: kase, template, requested };
+    }
+    throw new EmitError(`no scaffold template for framework '${framework}' ` +
+        `(looked for case '${requested}' and its fallbacks)`);
+}
+/** Base for a CODE-FIRST {@link EmitterPort}. A subclass is THIN — it declares the
+ *  framework + target ids and supplies the framework-specific template variables
+ *  ({@link renderContext}), losses, and field mapping; case selection, template
+ *  fill, and the byte-equal invariant hook are inherited. */
+export class ScaffoldEmitter {
+    fileExtension = "py";
+    /** Optional template-resolution override (defaults to the active resolver —
+     *  package-data today, a Scaffold Kind resolver tomorrow). */
+    resolver = null;
+    // ── the hooks a subclass overrides ────────────────────────────────────────
+    /** Framework-specific template variables (merged over the common ones). */
+    renderContext(_ctx, _case) {
+        return {};
+    }
+    /** Framework-specific de-para losses (in addition to the common ones). */
+    losses(_ctx, _choice) {
+        return [];
+    }
+    /** Field-level de-para (`dnaField -> targetField`) for reporting. */
+    mapping() {
+        return {};
+    }
+    /** The case classifier — override to add a framework-specific case. */
+    classify(ctx) {
+        return classifyCase(ctx);
+    }
+    // ── the inherited machinery ───────────────────────────────────────────────
+    commonContext(ctx) {
+        return {
+            name: ctx.name,
+            name_literal: pyStrLiteral(ctx.name),
+            description: ctx.description,
+            has_description: Boolean(ctx.description),
+            // INSTRUCTIONS constant — byte-equal, recoverable via extractInstructions.
+            instructions_literal: pyStrLiteral(ctx.instructions),
+        };
+    }
+    commonLosses(ctx, choice) {
+        const losses = [
+            "composition structure — Soul reuse + wired Guardrails flatten to one " +
+                "`INSTRUCTIONS` string (a code-first agent has no `soul:`/`guardrails:` slot)",
+            "tenant overlay — a per-tenant persona without a fork has no code-first field",
+            "eval-as-contract — prompt invariants (EvalCases) have no code-first slot",
+        ];
+        if (choice.case !== choice.requested) {
+            losses.push(`scaffold case — the '${choice.requested}' idiom is not shipped for ` +
+                `'${this.framework}'; fell back to the '${choice.case}' template ` +
+                "(structure closest to but not identical to the requested case)");
+        }
+        return losses;
+    }
+    emit(ctx) {
+        const choice = selectScaffold(this.framework, ctx, (c) => this.classify(c), this.resolver);
+        const variables = { ...this.commonContext(ctx), ...this.renderContext(ctx, choice.case) };
+        const artifact = Mustache.render(choice.template, variables);
+        const losses = [...this.commonLosses(ctx, choice), ...this.losses(ctx, choice)];
+        return {
+            artifact,
+            target: this.target,
+            filename: `${ctx.name}.${this.fileExtension}`,
+            losses,
+            mapping: this.mapping(),
+        };
+    }
+    /** Byte-equal invariant hook: read the top-level `INSTRUCTIONS = <literal>`
+     *  constant every scaffold template emits (a JSON/Python string literal on one
+     *  line), uniform across all code-first targets regardless of constructor shape. */
+    extractInstructions(artifact) {
+        const match = artifact.match(/^INSTRUCTIONS = (.+)$/m);
+        if (!match)
+            return null;
+        try {
+            return JSON.parse(match[1]);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/emit/scaffolds/agno/prompt-only.py.tmpl

@@ -0,0 +1,15 @@
+"""DNA-emitted Agno agent: {{name}}.
+
+Generated by `dna emit --target agno`. INSTRUCTIONS is the DNA-composed prompt
+(Soul + guardrails + instruction), carried byte-equal from the source of truth —
+edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+"""
+from agno.agent import Agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = Agent(
+    name={{{name_literal}}},
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    instructions=INSTRUCTIONS,
+)

package/dist/emit/scaffolds/agno/with-tools.py.tmpl

@@ -0,0 +1,23 @@
+"""DNA-emitted Agno agent (tool-calling): {{name}}.
+
+Generated by `dna emit --target agno`. INSTRUCTIONS is the DNA-composed prompt
+(Soul + guardrails + instruction), carried byte-equal. Each tool below is a STUB
+scaffolded from a DNA Tool's name + description — wire its real implementation and
+typed signature (Agno derives the tool schema from the function + docstring).
+"""
+from agno.agent import Agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = Agent(
+    name={{{name_literal}}},
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    instructions=INSTRUCTIONS,
+    tools=[{{tool_list}}],
+)

package/dist/emit/scaffolds/deepagents/prompt-only.py.tmpl

@@ -0,0 +1,16 @@
+"""DNA-emitted DeepAgents agent: {{name}}.
+
+Generated by `dna emit --target deepagents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal from the source of
+truth — edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+`system_prompt` sits in FRONT of the deep-agent's built-in harness prompt.
+"""
+from deepagents import create_deep_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = create_deep_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[],
+    system_prompt=INSTRUCTIONS,
+)

package/dist/emit/scaffolds/deepagents/with-tools.py.tmpl

@@ -0,0 +1,22 @@
+"""DNA-emitted DeepAgents agent (tool-calling): {{name}}.
+
+Generated by `dna emit --target deepagents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal. Each tool below is a
+STUB scaffolded from a DNA Tool's name + description — wire its real implementation
+and typed signature. `system_prompt` sits in FRONT of the deep-agent harness prompt.
+"""
+from deepagents import create_deep_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = create_deep_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[{{tool_list}}],
+    system_prompt=INSTRUCTIONS,
+)

package/dist/emit/scaffolds/langgraph/prompt-only.py.tmpl

@@ -0,0 +1,16 @@
+"""DNA-emitted LangGraph ReAct agent: {{name}}.
+
+Generated by `dna emit --target langgraph`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal from the source of
+truth — edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+"""
+from langgraph.prebuilt import create_react_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = create_react_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[],
+    prompt=INSTRUCTIONS,
+{{#has_name}}    name={{{name_literal}}},
+{{/has_name}})

package/dist/emit/scaffolds/langgraph/with-tools.py.tmpl

@@ -0,0 +1,25 @@
+"""DNA-emitted LangGraph ReAct agent (tool-calling): {{name}}.
+
+Generated by `dna emit --target langgraph`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal. Each @tool below is
+a STUB scaffolded from a DNA Tool's name + description — wire its real
+implementation and typed signature (LangChain derives the tool schema from them).
+"""
+from langchain_core.tools import tool
+from langgraph.prebuilt import create_react_agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+@tool
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = create_react_agent(
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[{{tool_list}}],
+    prompt=INSTRUCTIONS,
+{{#has_name}}    name={{{name_literal}}},
+{{/has_name}})

package/dist/emit/scaffolds/openai-agents/prompt-only.py.tmpl

@@ -0,0 +1,15 @@
+"""DNA-emitted OpenAI Agents SDK agent: {{name}}.
+
+Generated by `dna emit --target openai-agents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal from the source of
+truth — edit the agent in DNA and re-emit, do not hand-edit the prompt here.
+"""
+from agents import Agent
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+agent = Agent(
+    name={{{name_literal}}},
+    instructions=INSTRUCTIONS,
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}})

package/dist/emit/scaffolds/openai-agents/with-tools.py.tmpl

@@ -0,0 +1,24 @@
+"""DNA-emitted OpenAI Agents SDK agent (tool-calling / ReAct): {{name}}.
+
+Generated by `dna emit --target openai-agents`. INSTRUCTIONS is the DNA-composed
+prompt (Soul + guardrails + instruction), carried byte-equal. Each @function_tool
+below is a STUB scaffolded from a DNA Tool's name + description — wire its real
+implementation and typed signature (the SDK derives the tool schema from them).
+"""
+from agents import Agent, function_tool
+
+INSTRUCTIONS = {{{instructions_literal}}}
+
+{{#tools}}
+@function_tool
+def {{func_name}}() -> str:
+    {{{docstring_literal}}}
+    raise NotImplementedError("DNA scaffold: implement the {{name}} tool")
+
+{{/tools}}
+agent = Agent(
+    name={{{name_literal}}},
+    instructions=INSTRUCTIONS,
+{{#has_model}}    model={{{model_literal}}},
+{{/has_model}}    tools=[{{tool_list}}],
+)

package/dist/emit/vertex.d.ts

@@ -0,0 +1,22 @@
+import type { EmitContext, EmitResult, EmitterPort } from "./index.js";
+/** `concierge-grounded` → `concierge_grounded` (a valid ADK agent name — ADK
+ *  requires a Python identifier). Mirrors Bedrock's `camel` logical-id transform. */
+export declare function snake(name: string): string;
+/** Project a DNA model coordinate → an ADK `model` id. A known DNA provider token
+ *  (`vertex/gemini-2.0-flash` → `gemini-2.0-flash`, `openai:gpt-4o` → `gpt-4o`) is
+ *  stripped; a bare id passes through. */
+export declare function vertexModelId(model: string | null): string | null;
+/** Whether an emitted `model` id is a native Gemini id (else needs `model_code`). */
+export declare function isGemini(modelId: string | null): boolean;
+export declare class VertexEmitter implements EmitterPort {
+    readonly target = "vertex";
+    readonly fileExtension = "adk.yaml";
+    /** The PURE de-para: {@link EmitContext} → the ADK Agent Config object. Field
+     *  order is intentional; the schema-header comment is prepended at serialization
+     *  time, not part of this object. */
+    toAgentConfig(ctx: EmitContext): Record<string, unknown>;
+    emit(ctx: EmitContext): EmitResult;
+    /** Byte-equal invariant hook: read `instruction` back from the emitted ADK
+     *  Agent Config YAML (the `# yaml-language-server` header is a YAML comment). */
+    extractInstructions(artifact: string): string | null;
+}

package/dist/emit/vertex.js

@@ -0,0 +1,162 @@
+/**
+ * DNA → **Google ADK Agent Config** emitter (TS twin of python
+ * `dna.emit.vertex`). Materializes an {@link EmitContext} into a **Google Agent
+ * Development Kit (ADK) Agent Config** YAML — the declarative, code-free way to
+ * define an ADK `LlmAgent` (loaded with `config_agent_utils.from_config(...)`).
+ * The THIRD runtime the SAME DNA source emits to (after Microsoft agent-framework
+ * and Amazon Bedrock): the portability proof — author once, emit per runtime.
+ *
+ * Why the ADK **Agent Config** (not the code-first `LlmAgent` object or Vertex AI
+ * Agent Engine): only Agent Config has a published, field-for-field *declarative*
+ * schema (`agent_class`, `name`, `model`, `instruction`, `tools`, …), so it is the
+ * only honest de-para target. Emitting the YAML gives a lintable artifact that
+ * needs no GCP credential to produce or validate structurally (the
+ * `# yaml-language-server` header wires the real schema into any editor).
+ *
+ * The de-para (DNA field → ADK `LlmAgentConfig` field):
+ *   (fixed)                           -> agent_class: LlmAgent
+ *   metadata.name                     -> name          (snake_cased — valid identifier)
+ *   metadata.description              -> description    (when present)
+ *   Soul + guardrails + instruction   -> instruction   (flat, BYTE-EQUAL)
+ *   spec.model (or Genome default_llm)-> model          (Gemini id; provider stripped)
+ *   spec.tools[] (Tool Kind surfaces) -> tools[].name   (a CODE reference — see loss)
+ *
+ * `toAgentConfig` is the PURE de-para and is parity-critical: it must build the
+ * SAME object the Python `to_agent_config` builds from the same context.
+ */
+import yaml from "js-yaml";
+/** The published ADK Agent Config JSON Schema — emitted as a leading
+ *  `# yaml-language-server` header so any editor / validator binds the artifact to
+ *  the REAL schema (the credential-free structural-validation hook). */
+const ADK_SCHEMA_URL = "https://raw.githubusercontent.com/google/adk-python/refs/heads/main/" +
+    "src/google/adk/agents/config_schemas/AgentConfig.json";
+/** The ADK `agent_class` this emitter targets (the declarative LLM agent). */
+const AGENT_CLASS = "LlmAgent";
+/** DNA provider tokens (the `prov:model` / `prov/model` prefixes). Stripped to
+ *  expose the bare model id; a bare Gemini id passes through unchanged. */
+const DNA_PROVIDER_TOKENS = new Set([
+    "azure", "azureopenai", "azure_openai", "openai", "foundry", "azureaifoundry",
+    "vertex", "google", "gemini", "anthropic",
+]);
+/** `concierge-grounded` → `concierge_grounded` (a valid ADK agent name — ADK
+ *  requires a Python identifier). Mirrors Bedrock's `camel` logical-id transform. */
+export function snake(name) {
+    let ident = String(name)
+        .trim()
+        .split("")
+        .map((ch) => (/[a-zA-Z0-9_]/.test(ch) ? ch : "_"))
+        .join("")
+        .replace(/^_+|_+$/g, "")
+        .toLowerCase();
+    if (!ident)
+        ident = "agent";
+    if (/^[0-9]/.test(ident))
+        ident = `_${ident}`;
+    return ident;
+}
+/** Project a DNA model coordinate → an ADK `model` id. A known DNA provider token
+ *  (`vertex/gemini-2.0-flash` → `gemini-2.0-flash`, `openai:gpt-4o` → `gpt-4o`) is
+ *  stripped; a bare id passes through. */
+export function vertexModelId(model) {
+    if (!model)
+        return null;
+    const ident = model.trim();
+    const slash = ident.indexOf("/");
+    if (slash >= 0) {
+        const token = ident.slice(0, slash).trim().toLowerCase();
+        if (DNA_PROVIDER_TOKENS.has(token))
+            return ident.slice(slash + 1).trim();
+        return ident;
+    }
+    const colon = ident.indexOf(":");
+    if (colon >= 0) {
+        const token = ident.slice(0, colon).trim().toLowerCase();
+        if (DNA_PROVIDER_TOKENS.has(token))
+            return ident.slice(colon + 1).trim();
+    }
+    return ident;
+}
+/** Whether an emitted `model` id is a native Gemini id (else needs `model_code`). */
+export function isGemini(modelId) {
+    return !!modelId && modelId.trim().toLowerCase().startsWith("gemini");
+}
+/** Project neutral tool surfaces → ADK `tools` code references (`- name: <fqn>`).
+ *  ADK has no inline function-schema slot (unlike agent-framework / Bedrock): it
+ *  derives a tool's description + parameters from the referenced Python callable at
+ *  load, so the faithful de-para carries the tool NAME as a placeholder reference. */
+function emitTools(tools) {
+    return tools.map((t) => ({ name: t.name }));
+}
+export class VertexEmitter {
+    target = "vertex";
+    fileExtension = "adk.yaml";
+    /** The PURE de-para: {@link EmitContext} → the ADK Agent Config object. Field
+     *  order is intentional; the schema-header comment is prepended at serialization
+     *  time, not part of this object. */
+    toAgentConfig(ctx) {
+        const doc = { agent_class: AGENT_CLASS, name: snake(ctx.name) };
+        if (ctx.description)
+            doc.description = ctx.description;
+        const modelId = vertexModelId(ctx.model);
+        if (modelId)
+            doc.model = modelId;
+        doc.instruction = ctx.instructions; // verbatim — the byte-equal gate
+        if (ctx.tools.length > 0)
+            doc.tools = emitTools(ctx.tools);
+        return doc;
+    }
+    emit(ctx) {
+        const config = this.toAgentConfig(ctx);
+        const body = yaml.dump(config, { sortKeys: false, lineWidth: -1 });
+        const artifact = `# yaml-language-server: $schema=${ADK_SCHEMA_URL}\n${body}`;
+        const losses = [
+            "composition structure — Soul reuse + wired Guardrails flatten to one " +
+                "`instruction` string (Agent Config has no `soul:`/`guardrails:` slot)",
+            "tenant overlay — a per-tenant persona without a fork has no Agent Config field",
+            "eval-as-contract — prompt invariants (EvalCases) have no Agent Config slot",
+        ];
+        if (ctx.tools.length > 0) {
+            losses.push("tool binding — ADK binds a tool by a CODE reference (a fully qualified " +
+                "Python path or a built-in name), not a declarative schema; a Tool's " +
+                "`description` and `parameters` (JSON Schema) have no Agent Config slot " +
+                "(ADK derives them from the Python callable at load). Each emitted `- name` " +
+                "is a placeholder to repoint to the tool's real FQN");
+        }
+        if (ctx.outputSchema) {
+            losses.push("output_schema — ADK `output_schema` is a `CodeConfig` (a reference to a " +
+                "Pydantic class by FQN), not an inline JSON Schema; DNA's inline " +
+                "`spec.output_schema` has no inline Agent Config slot");
+        }
+        const modelId = vertexModelId(ctx.model);
+        if (modelId === null) {
+            losses.push("model unbound in DNA and none supplied — emitted config has no `model`; " +
+                "ADK inherits the ancestor / system default (gemini)");
+        }
+        else if (!isGemini(modelId)) {
+            losses.push("model coordinate — ADK `model` natively accepts a Gemini id; a DNA " +
+                "`azure/openai` coordinate is not a Gemini id and needs `model_code` (a " +
+                "`LiteLlm` CodeConfig) at deploy, plus a GCP project/region");
+        }
+        const mapping = {
+            "metadata.name": "name (snake_case identifier)",
+            "metadata.description": "description",
+            "buildPrompt (Soul+guardrails+instruction)": "instruction (byte-equal)",
+            "spec.model / Genome.default_llm": "model (Gemini id; provider token stripped)",
+            "spec.tools[] (Tool Kind)": "tools[].name (code reference)",
+        };
+        return {
+            artifact,
+            target: this.target,
+            filename: `${ctx.name}.${this.fileExtension}`,
+            losses,
+            mapping,
+        };
+    }
+    /** Byte-equal invariant hook: read `instruction` back from the emitted ADK
+     *  Agent Config YAML (the `# yaml-language-server` header is a YAML comment). */
+    extractInstructions(artifact) {
+        const config = yaml.load(artifact);
+        const value = config?.instruction;
+        return typeof value === "string" ? value : null;
+    }
+}

package/dist/extensions/sdlc.js

@@ -1357,6 +1357,9 @@ class HtmlArtifactKind extends KindBase {
             title: aj.title ?? null,
             source: aj.source ?? null,
             created_at: aj.created_at ?? null,
+            // published_url — canonical hosted location (e.g. claude.ai artifact
+            // URL) so the gallery renders a clickable link. Lives in artifact_json.
+            published_url: aj.published_url ?? null,
             html_bytes: (spec.html ?? "").length,
         };
     }

package/dist/index.d.ts

@@ -26,10 +26,14 @@ export { AgentNotFound, ToolNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
 export { ToolLibrary, loadTools } from "./tools.js";
 export type { ToolSurface } from "./tools.js";
-export { emitAgent, buildEmitContext, registerEmitter, getEmitter, availableTargets, EmitError, UnknownTarget, } from "./emit/index.js";
+export { emitAgent, buildEmitContext, registerEmitter, unregisterEmitter, getEmitter, availableTargets, EmitError, UnknownTarget, } from "./emit/index.js";
 export type { EmitContext, EmitResult, EmitTool, EmitterPort, BuildEmitContextOpts, } from "./emit/index.js";
 export { AgentFrameworkEmitter } from "./emit/agentFramework.js";
 export { BedrockEmitter } from "./emit/bedrock.js";
+export { VertexEmitter } from "./emit/vertex.js";
+export { OpenAIAgentsEmitter } from "./emit/openaiAgents.js";
+export { ScaffoldEmitter, selectScaffold, classifyCase, resolveScaffold, setScaffoldResolver, PackageDataScaffoldResolver, } from "./emit/scaffold.js";
+export type { ScaffoldChoice, ScaffoldResolver } from "./emit/scaffold.js";
 export type { LoadPromptsOptions } from "./prompts.js";
 export { anchorScopesRoot, PackageScopeNotFound, DEFAULT_SUBPATH } from "./package-scope.js";
 export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";

package/dist/index.js

@@ -30,9 +30,12 @@ export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, qui
 export { AgentNotFound, ToolNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
 export { ToolLibrary, loadTools } from "./tools.js";
-export { emitAgent, buildEmitContext, registerEmitter, getEmitter, availableTargets, EmitError, UnknownTarget, } from "./emit/index.js";
+export { emitAgent, buildEmitContext, registerEmitter, unregisterEmitter, getEmitter, availableTargets, EmitError, UnknownTarget, } from "./emit/index.js";
 export { AgentFrameworkEmitter } from "./emit/agentFramework.js";
 export { BedrockEmitter } from "./emit/bedrock.js";
+export { VertexEmitter } from "./emit/vertex.js";
+export { OpenAIAgentsEmitter } from "./emit/openaiAgents.js";
+export { ScaffoldEmitter, selectScaffold, classifyCase, resolveScaffold, setScaffoldResolver, PackageDataScaffoldResolver, } from "./emit/scaffold.js";
 export { anchorScopesRoot, PackageScopeNotFound, DEFAULT_SUBPATH } from "./package-scope.js";
 export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
 export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",