dna-sdk 0.7.0 → 0.9.0

package/dist/emit/bedrock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * DNA → **Amazon Bedrock Agent** emitter (TS twin of python
+ * `dna.emit.bedrock`). Materializes an {@link EmitContext} into an AWS
+ * **CloudFormation** template that declares an `AWS::Bedrock::Agent` resource —
+ * the managed, declarative Bedrock Agents service. The SECOND runtime the SAME
+ * DNA source emits to (the first is Microsoft agent-framework): the portability
+ * proof — author once, emit per runtime.
+ *
+ * Why Bedrock **Agents** (not Strands / AgentCore): only Bedrock Agents has a
+ * published *declarative* schema (`Instruction`, `FoundationModel`,
+ * `ActionGroups` with a `FunctionSchema`) that maps field-for-field from a DNA
+ * agent. Emitting a CloudFormation template gives a lintable, deployable artifact
+ * that needs no AWS credential to produce or validate structurally.
+ *
+ * The de-para (DNA field → CloudFormation `AWS::Bedrock::Agent` field):
+ *   metadata.name                     -> Resources.<Camel>Agent.Properties.AgentName
+ *   metadata.description              -> Properties.Description        (when present)
+ *   Soul + guardrails + instruction   -> Properties.Instruction        (flat, BYTE-EQUAL)
+ *   spec.model (or Genome default_llm)-> Properties.FoundationModel     (provider token stripped)
+ *   spec.tools[] (Tool Kind surfaces) -> Properties.ActionGroups[0].FunctionSchema.Functions[]
+ *
+ * `toTemplate` is the PURE de-para and is parity-critical: it must build the SAME
+ * object the Python `to_template` builds from the same context.
+ */
+import type { EmitContext, EmitResult, EmitterPort } from "./index.js";
+/** `concierge-grounded` → `ConciergeGrounded` (a valid CFN logical id). */
+export declare function camel(name: string): string;
+/** Project a DNA model coordinate → a Bedrock `FoundationModel` id. Bedrock
+ *  encodes the provider inside the id (`anthropic.claude-v2`), so a DNA
+ *  `prov:model` / `prov/model` provider token is dropped; a bare coordinate
+ *  passes through unchanged. */
+export declare function bedrockModelId(model: string | null): string | null;
+/** Project a Tool's input JSON Schema → Bedrock `Function.Parameters`
+ *  (`{name: {Type, Description, Required}}`). Returns the map + whether any type
+ *  was coerced (for the loss report). */
+export declare function emitParameters(inputSchema: Record<string, unknown>): {
+    params: Record<string, unknown>;
+    coerced: boolean;
+};
+export declare class BedrockEmitter implements EmitterPort {
+    readonly target = "bedrock";
+    readonly fileExtension = "bedrock.json";
+    /** The PURE de-para: {@link EmitContext} → the CloudFormation object. Field
+     *  order is intentional and preserved by JSON.stringify (insertion order). */
+    toTemplate(ctx: EmitContext): Record<string, unknown>;
+    emit(ctx: EmitContext): EmitResult;
+}

package/dist/emit/bedrock.js

@@ -0,0 +1,169 @@
+/** Bedrock `ParameterDetail.Type` allowed values. A JSON-Schema type outside
+ *  this set (notably `object`) is coerced to `string` (the depth loss). */
+const BEDROCK_PARAM_TYPES = new Set(["string", "number", "integer", "boolean", "array"]);
+/** CloudFormation template format version — the stable, only value. */
+const CFN_VERSION = "2010-09-09";
+/** DNA provider tokens (the `prov:model` / `prov/model` prefixes DNA authors
+ *  use). Stripped to expose the bare model id. Bedrock-native provider prefixes
+ *  (anthropic./amazon./…) use a DOT and are NOT here, so a real Bedrock id (incl.
+ *  a `:0` version suffix) passes through. */
+const DNA_PROVIDER_TOKENS = new Set([
+    "azure", "azureopenai", "azure_openai", "openai", "foundry", "azureaifoundry",
+    "vertex", "google", "gemini",
+]);
+/** `concierge-grounded` → `ConciergeGrounded` (a valid CFN logical id). */
+export function camel(name) {
+    return String(name)
+        .replace(/_/g, "-")
+        .split("-")
+        .filter(Boolean)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+}
+/** Project a DNA model coordinate → a Bedrock `FoundationModel` id. Bedrock
+ *  encodes the provider inside the id (`anthropic.claude-v2`), so a DNA
+ *  `prov:model` / `prov/model` provider token is dropped; a bare coordinate
+ *  passes through unchanged. */
+export function bedrockModelId(model) {
+    if (!model)
+        return null;
+    const ident = model.trim();
+    if (ident.toLowerCase().startsWith("arn:"))
+        return ident; // ARN — never split.
+    const slash = ident.indexOf("/");
+    if (slash >= 0)
+        return ident.slice(slash + 1).trim(); // DNA slash coordinate.
+    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; // bare / Bedrock-native id (keeps any `:version`).
+}
+/** Project a Tool's input JSON Schema → Bedrock `Function.Parameters`
+ *  (`{name: {Type, Description, Required}}`). Returns the map + whether any type
+ *  was coerced (for the loss report). */
+export function emitParameters(inputSchema) {
+    const props = inputSchema?.properties;
+    if (!props || typeof props !== "object" || Object.keys(props).length === 0) {
+        return { params: {}, coerced: false };
+    }
+    const required = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+    const requiredSet = new Set(required);
+    const out = {};
+    let coerced = false;
+    for (const [pname, raw] of Object.entries(props)) {
+        const pschema = (raw && typeof raw === "object" ? raw : {});
+        const jtype = pschema.type ?? "string";
+        let btype;
+        if (BEDROCK_PARAM_TYPES.has(jtype)) {
+            btype = jtype;
+        }
+        else {
+            btype = "string"; // object / unknown → flatten to string (recorded loss)
+            coerced = true;
+        }
+        const detail = { Type: btype };
+        if (pschema.description)
+            detail.Description = pschema.description;
+        detail.Required = requiredSet.has(pname);
+        out[pname] = detail;
+    }
+    return { params: out, coerced };
+}
+/** Project the agent's tools → a single Bedrock action group. The executor is
+ *  `CustomControl: RETURN_CONTROL` — Bedrock returns the tool call to the CALLER
+ *  (the faithful mapping for DNA's client-side tools; no Lambda ARN needed). */
+function emitActionGroups(ctx) {
+    const functions = [];
+    let anyCoerced = false;
+    for (const t of ctx.tools) {
+        const fn = { Name: t.name };
+        if (t.description)
+            fn.Description = t.description;
+        const { params, coerced } = emitParameters((t.parameters ?? {}));
+        anyCoerced = anyCoerced || coerced;
+        if (Object.keys(params).length > 0)
+            fn.Parameters = params;
+        functions.push(fn);
+    }
+    const group = {
+        ActionGroupName: `${ctx.name}-actions`,
+        Description: `DNA-emitted tools for agent ${ctx.name}`,
+        ActionGroupExecutor: { CustomControl: "RETURN_CONTROL" },
+        FunctionSchema: { Functions: functions },
+    };
+    return { groups: [group], coerced: anyCoerced };
+}
+export class BedrockEmitter {
+    target = "bedrock";
+    fileExtension = "bedrock.json";
+    /** The PURE de-para: {@link EmitContext} → the CloudFormation object. Field
+     *  order is intentional and preserved by JSON.stringify (insertion order). */
+    toTemplate(ctx) {
+        const logicalId = `${camel(ctx.name)}Agent`;
+        const props = { AgentName: ctx.name };
+        if (ctx.description)
+            props.Description = ctx.description;
+        const modelId = bedrockModelId(ctx.model);
+        if (modelId)
+            props.FoundationModel = modelId;
+        props.Instruction = ctx.instructions; // verbatim — the byte-equal gate
+        if (ctx.tools.length > 0)
+            props.ActionGroups = emitActionGroups(ctx).groups;
+        props.AutoPrepare = true;
+        return {
+            AWSTemplateFormatVersion: CFN_VERSION,
+            Description: `DNA-emitted Amazon Bedrock Agent: ${ctx.name}`,
+            Resources: {
+                [logicalId]: { Type: "AWS::Bedrock::Agent", Properties: props },
+            },
+        };
+    }
+    emit(ctx) {
+        const template = this.toTemplate(ctx);
+        const artifact = JSON.stringify(template, null, 2) + "\n";
+        const losses = [
+            "composition structure — Soul reuse + wired Guardrails flatten to one " +
+                "`Instruction` string (Bedrock `GuardrailConfiguration` is an " +
+                "ID-referenced Bedrock Guardrail, not DNA's composed guardrails)",
+            "tenant overlay — a per-tenant persona without a fork has no Bedrock Agent field",
+            "eval-as-contract — prompt invariants (EvalCases) have no Bedrock slot",
+        ];
+        if (ctx.tools.length > 0) {
+            losses.push("tool parameter depth — Bedrock `ParameterDetail` is a flat " +
+                "{Type, Description, Required} map (Type ∈ string|number|integer|" +
+                "boolean|array); JSON-Schema `default`, `enum`, nested object " +
+                "`properties`, and array `items` typing are dropped");
+        }
+        if (ctx.outputSchema) {
+            losses.push("output_schema — Bedrock Agent has no structured-response / " +
+                "output-schema field; the agent's typed output contract is dropped");
+        }
+        if (ctx.model === null) {
+            losses.push("model unbound in DNA and none supplied — emitted template has no " +
+                "`FoundationModel`; pass provider/model or set spec.model / Genome default_llm");
+        }
+        else {
+            losses.push("model coordinate — a DNA `azure/openai` coordinate is not a Bedrock " +
+                "foundation-model id; `FoundationModel` needs a Bedrock model id or " +
+                "inference-profile ARN, plus an `AgentResourceRoleArn` at deploy");
+        }
+        const mapping = {
+            "metadata.name": "Resources.<id>Agent.Properties.AgentName",
+            "metadata.description": "Properties.Description",
+            "buildPrompt (Soul+guardrails+instruction)": "Properties.Instruction (byte-equal)",
+            "spec.model / Genome.default_llm": "Properties.FoundationModel",
+            "spec.tools[] (Tool Kind)": "Properties.ActionGroups[].FunctionSchema.Functions[]",
+            "Tool.input_schema.properties": "Function.Parameters{Type,Description,Required}",
+        };
+        return {
+            artifact,
+            target: this.target,
+            filename: `${ctx.name}.${this.fileExtension}`,
+            losses,
+            mapping,
+        };
+    }
+}

package/dist/emit/index.js

@@ -20,9 +20,12 @@ async function ensureBuiltins() {
         return;
     builtinsWired = true;
     const { AgentFrameworkEmitter } = await import("./agentFramework.js");
-    const e = new AgentFrameworkEmitter();
-    if (!EMITTER_REGISTRY.has(e.target))
-        EMITTER_REGISTRY.set(e.target, e);
+    const { BedrockEmitter } = await import("./bedrock.js");
+    const { VertexEmitter } = await import("./vertex.js");
+    for (const e of [new AgentFrameworkEmitter(), new BedrockEmitter(), new VertexEmitter()]) {
+        if (!EMITTER_REGISTRY.has(e.target))
+            EMITTER_REGISTRY.set(e.target, e);
+    }
 }
 /** Register an emitter under its `target` (last registration wins). */
 export function registerEmitter(emitter) {

package/dist/emit/vertex.d.ts

@@ -0,0 +1,19 @@
+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;
+}

package/dist/emit/vertex.js

@@ -0,0 +1,155 @@
+/**
+ * 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,
+        };
+    }
+}

package/dist/extensions/research.js

@@ -101,6 +101,14 @@ class ResearchKind extends KindBase {
                     items: { type: "string" },
                     default: [],
                 },
+                cited_by: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                    description: "Kind/name of docs that cite this Research as a grounding source. " +
+                        "Auto-maintained by `dna sdlc cite Research/<name> --from <Kind>/<name>` " +
+                        "— don't author by hand.",
+                },
                 findings: {
                     type: "array",
                     items: {

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

@@ -29,6 +29,7 @@ export type { ToolSurface } from "./tools.js";
 export { emitAgent, buildEmitContext, registerEmitter, 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 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

@@ -32,6 +32,7 @@ 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 { AgentFrameworkEmitter } from "./emit/agentFramework.js";
+export { BedrockEmitter } from "./emit/bedrock.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.7.0",
+  "version": "0.9.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",