dna-sdk 0.9.0 → 0.11.0

package/dist/bootstrap.js

@@ -38,8 +38,10 @@ 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 { CloudExtension } from "./extensions/cloud.js";
 import { AutomationExtension } from "./extensions/automation.js";
 import { EvalExtension } from "./extensions/eval.js";
+import { IntelExtension } from "./extensions/intel.js";
 import { loadConfig } from "./config.js";
 import { resolveDefaultFsUrl, sourceFromUrl } from "./adapters/source-url.js";
 /**
@@ -69,8 +71,10 @@ function loadBuiltins(target) {
         new ResearchExtension(),
         new TestkitExtension(),
         new ModelRegExtension(),
+        new CloudExtension(),
         new AutomationExtension(),
         new EvalExtension(),
+        new IntelExtension(),
     ]) {
         target.load(ext);
     }

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

@@ -22,7 +22,19 @@ async function ensureBuiltins() {
     const { AgentFrameworkEmitter } = await import("./agentFramework.js");
     const { BedrockEmitter } = await import("./bedrock.js");
     const { VertexEmitter } = await import("./vertex.js");
-    for (const e of [new AgentFrameworkEmitter(), new BedrockEmitter(), new VertexEmitter()]) {
+    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);
     }
@@ -32,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=[...])",
+        };
+    }
+}