dna-sdk 0.5.0 → 0.7.0

package/dist/adapters/source-url.d.ts

@@ -10,6 +10,9 @@
  *   file:// <path>      → FilesystemSource (read/write on disk)
  *   fs:// <path>        → alias of file://
  *   <plain path>        → treated as file://<path>
+ *   pkg://<pkg>[/sub]   → FilesystemSource (READ-ONLY) over a scope embedded
+ *                         as PACKAGE DATA of <pkg> (sub defaults to .dna);
+ *                         travels with the app (tarball / Docker)
  *   postgresql:// …     → PostgresSource (node-postgres)
  *   postgres:// …       → alias of postgresql://
  *   sqlite:// <path>    → NOT SUPPORTED in the TS runtime (Python-only; the

package/dist/adapters/source-url.js

@@ -16,6 +16,22 @@ function schemeOf(url) {
     const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url);
     return (m ? m[1] : "file").toLowerCase();
 }
+/**
+ * Split `pkg://<package>[/<subpath>]` into `{ pkg, subpath }`. Parity with the
+ * python `_parse_pkg_url`: `pkg://app` → `{pkg:"app", subpath:""}`;
+ * `pkg://app/.dna` → `{pkg:"app", subpath:".dna"}`. The package is the netloc
+ * (a dotted `pkg://my.app` stays `my.app`).
+ */
+function parsePkgUrl(url) {
+    const m = /^pkg:\/\/([^/]*)(?:\/(.*))?$/.exec(url);
+    const pkg = m?.[1] ?? "";
+    if (!pkg) {
+        throw new UnsupportedSourceScheme(`pkg:// source URL is missing a package name — use ` +
+            `pkg://<package>[/<subpath>] (e.g. pkg://app or pkg://app/.dna). ` +
+            `Got: ${url}`);
+    }
+    return { pkg, subpath: m?.[2] ?? "" };
+}
 /**
  * Build a source from a scheme URL (see module docstring).
  *
@@ -29,6 +45,16 @@ export async function sourceFromUrl(url, opts = {}) {
         const { FilesystemSource } = await import("./filesystem/source.js");
         return new FilesystemSource(urlToFsPath(url) || url);
     }
+    if (scheme === "pkg") {
+        // A scope embedded as PACKAGE DATA — resolve it from inside the installed
+        // package so it travels with the app (tarball / Docker), no path
+        // navigation and no manual copy. READ-ONLY: FilesystemSource has no write
+        // surface here (to write, use file:// or postgresql://).
+        const { FilesystemSource } = await import("./filesystem/source.js");
+        const { anchorScopesRoot, DEFAULT_SUBPATH } = await import("../package-scope.js");
+        const { pkg, subpath } = parsePkgUrl(url);
+        return new FilesystemSource(anchorScopesRoot(pkg, subpath || DEFAULT_SUBPATH));
+    }
     if (base === "postgresql" || base === "postgres") {
         const { PostgresSource } = await import("./postgres/source.js");
         const src = new PostgresSource({ connectionString: url, schema: opts.schema });
@@ -41,7 +67,8 @@ export async function sourceFromUrl(url, opts = {}) {
             `(filesystem) or postgresql:// here. Got: ${url}`);
     }
     throw new UnsupportedSourceScheme(`unsupported source URL scheme '${scheme}://' — the TS runtime ships ` +
-        `file:// (filesystem) and postgresql:// adapters. Got: ${url}`);
+        `file:// (filesystem), pkg:// (read-only package-data scope) and ` +
+        `postgresql:// adapters. Got: ${url}`);
 }
 /**
  * The `file://` URL the SDK falls back to with no explicit config.

package/dist/emit/agentFramework.d.ts

@@ -0,0 +1,16 @@
+import type { EmitContext, EmitResult, EmitterPort } from "./index.js";
+/** `concierge-grounded` → `ConciergeGrounded`. */
+export declare function camel(name: string): string;
+/** Split a DNA model coordinate into agent-framework `{id, provider}`. */
+export declare function splitModel(model: string | null, providerHint?: string | null): {
+    id: string;
+    provider: string;
+} | null;
+export declare class AgentFrameworkEmitter implements EmitterPort {
+    readonly target = "agent-framework";
+    readonly fileExtension = "agent.yaml";
+    /** The PURE de-para: {@link EmitContext} → the PromptAgent object. Field
+     *  order is intentional and preserved by js-yaml (insertion order). */
+    toPromptAgent(ctx: EmitContext): Record<string, unknown>;
+    emit(ctx: EmitContext): EmitResult;
+}

package/dist/emit/agentFramework.js

@@ -0,0 +1,127 @@
+/**
+ * DNA → Microsoft **agent-framework** emitter (TS twin of python
+ * `dna.emit.agent_framework`). Materializes an {@link EmitContext} into the
+ * declarative `PromptAgent` YAML that `agent-framework-declarative`'s
+ * `AgentFactory` loads.
+ *
+ * The de-para (DNA field → PromptAgent field):
+ *   metadata.name                     -> name         (CamelCased id)
+ *   metadata.description              -> description
+ *   Soul + guardrails + instruction   -> instructions (flat — kernel-composed)
+ *   spec.model (or Genome default_llm)-> model.{id, provider}
+ *   spec.tools[] (Tool Kind surfaces) -> tools[] (kind: function)
+ *   spec.output_schema                -> outputSchema (only when present)
+ *
+ * `toPromptAgent` is the PURE de-para and is parity-critical: it must build the
+ * SAME object the Python `to_prompt_agent` builds from the same context.
+ */
+import yaml from "js-yaml";
+/** DNA provider token → agent-framework `model.provider` value. Unknown tokens
+ *  pass through unchanged so a future provider needs no code change. */
+const PROVIDER_MAP = {
+    azure: "AzureOpenAI",
+    azureopenai: "AzureOpenAI",
+    azure_openai: "AzureOpenAI",
+    openai: "OpenAI",
+    anthropic: "Anthropic",
+    foundry: "AzureAIFoundry",
+    azureaifoundry: "AzureAIFoundry",
+};
+/** Bare model with no provider token and no `--provider` → AzureOpenAI (the
+ *  provider the spike proved). Documented default, never silently wrong. */
+const DEFAULT_PROVIDER = "AzureOpenAI";
+/** `concierge-grounded` → `ConciergeGrounded`. */
+export function camel(name) {
+    return String(name)
+        .replace(/_/g, "-")
+        .split("-")
+        .filter(Boolean)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+}
+/** Split a DNA model coordinate into agent-framework `{id, provider}`. */
+export function splitModel(model, providerHint) {
+    if (!model)
+        return null;
+    let token = null;
+    let ident = model;
+    for (const sep of [":", "/"]) {
+        const i = model.indexOf(sep);
+        if (i >= 0) {
+            token = model.slice(0, i);
+            ident = model.slice(i + 1);
+            break;
+        }
+    }
+    let provider;
+    if (providerHint)
+        provider = providerHint;
+    else if (token)
+        provider = PROVIDER_MAP[token.trim().toLowerCase()] ?? token;
+    else
+        provider = DEFAULT_PROVIDER;
+    return { id: ident.trim(), provider };
+}
+function emitTools(tools) {
+    return tools.map((t) => {
+        const entry = {
+            name: t.name,
+            kind: "function", // AgentSchema function-tool kind (NOT `type`)
+            description: t.description ?? "",
+        };
+        if (t.parameters && Object.keys(t.parameters).length > 0) {
+            entry.parameters = t.parameters;
+        }
+        return entry;
+    });
+}
+export class AgentFrameworkEmitter {
+    target = "agent-framework";
+    fileExtension = "agent.yaml";
+    /** The PURE de-para: {@link EmitContext} → the PromptAgent object. Field
+     *  order is intentional and preserved by js-yaml (insertion order). */
+    toPromptAgent(ctx) {
+        const providerHint = ctx.options?.provider ?? null;
+        const doc = { kind: "Prompt", name: camel(ctx.name) };
+        if (ctx.description)
+            doc.description = ctx.description;
+        const model = splitModel(ctx.model, providerHint);
+        if (model)
+            doc.model = model;
+        if (ctx.tools.length > 0)
+            doc.tools = emitTools(ctx.tools);
+        doc.instructions = ctx.instructions; // verbatim — the byte-equal gate
+        if (ctx.outputSchema)
+            doc.outputSchema = ctx.outputSchema;
+        return doc;
+    }
+    emit(ctx) {
+        const promptAgent = this.toPromptAgent(ctx);
+        const artifact = yaml.dump(promptAgent, { sortKeys: false, lineWidth: -1 });
+        const losses = [
+            "composition structure — Soul reuse + wired Guardrails flatten to one " +
+                "`instructions` string (no `soul:`/`guardrails:` slot in a PromptAgent)",
+            "tenant overlay — a per-tenant persona without a fork has no PromptAgent field",
+            "eval-as-contract — prompt invariants (EvalCases) have no PromptAgent slot",
+        ];
+        if (ctx.model === null) {
+            losses.push("model unbound in DNA and none supplied — emitted PromptAgent has no " +
+                "`model:` block; pass provider/model or set spec.model / Genome default_llm");
+        }
+        const mapping = {
+            "metadata.name": "name (CamelCase)",
+            "metadata.description": "description",
+            "buildPrompt (Soul+guardrails+instruction)": "instructions",
+            "spec.model / Genome.default_llm": "model.{id,provider}",
+            "spec.tools[] (Tool Kind)": "tools[] (kind: function)",
+            "spec.output_schema": "outputSchema",
+        };
+        return {
+            artifact,
+            target: this.target,
+            filename: `${ctx.name}.${this.fileExtension}`,
+            losses,
+            mapping,
+        };
+    }
+}

package/dist/emit/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `emit` — the vendor-neutral EMITTER layer (TS twin of python `dna.emit`).
+ *
+ * DNA authors an agent ONCE — a persona (Soul), an instruction (Agent), wired
+ * Guardrails, and Tools — as declarative Kinds. This module materializes that
+ * one neutral definition into the NATIVE artifact each runtime framework
+ * consumes. The concrete first step of "DNA as the Terraform of agents": author
+ * once, emit per runtime, swap runtimes without rewriting the agent.
+ *
+ * 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.
+ *
+ * Shape: {@link EmitContext} (runtime-agnostic view of a composed agent) →
+ * {@link EmitterPort} (a target) → {@link EmitResult} (artifact + honest
+ * `losses`). {@link registerEmitter}/{@link getEmitter}/{@link availableTargets}
+ * are the pluggable registry — a new target is a class + one register call.
+ */
+import type { ManifestInstance } from "../kernel/instance.js";
+/** Runtime-agnostic view of ONE composed DNA agent. */
+export interface EmitContext {
+    /** The DNA agent slug (`metadata.name`). */
+    name: string;
+    /** `metadata.description`, or "". */
+    description: string;
+    /** DNA-composed system prompt (Soul + guardrails + instruction, flat). The
+     *  byte-equal gate: an emitter MUST carry it verbatim. */
+    instructions: string;
+    /** Raw DNA model coordinate (`openai:gpt-4o-mini` / `azure/gpt-4o` / bare), or
+     *  null when the DNA leaves the model unbound. */
+    model: string | null;
+    /** Resolved tool surfaces (`spec.tools` → Tool Kind). */
+    tools: EmitTool[];
+    /** Optional response JSON Schema (`spec.output_schema`), or null. */
+    outputSchema: Record<string, unknown> | null;
+    /** Scope the agent was composed from (provenance). */
+    scope: string | null;
+    /** Per-emitter hints (e.g. a `--provider` override). */
+    options: Record<string, unknown>;
+}
+export interface EmitTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** The emitted native artifact + an honest account of the de-para. */
+export interface EmitResult {
+    /** The serialized native artifact. */
+    artifact: string;
+    /** The target runtime id. */
+    target: string;
+    /** Suggested filename. */
+    filename: string;
+    /** DNA axes with NO slot in this target — what did NOT survive the emit. */
+    losses: string[];
+    /** Field-level de-para (`dnaField -> targetField`). */
+    mapping: Record<string, string>;
+}
+/** A runtime emitter — pure: reads an {@link EmitContext}, returns an
+ *  {@link EmitResult}. No kernel I/O, no network. */
+export interface EmitterPort {
+    readonly target: string;
+    readonly fileExtension: string;
+    emit(ctx: EmitContext): EmitResult;
+}
+export declare class EmitError extends Error {
+}
+export declare class UnknownTarget extends EmitError {
+    readonly target: string;
+    readonly available: string[];
+    constructor(target: string, available: string[]);
+}
+/** Register an emitter under its `target` (last registration wins). */
+export declare function registerEmitter(emitter: EmitterPort): EmitterPort;
+/** Look up a registered emitter or throw {@link UnknownTarget}. */
+export declare function getEmitter(target: string): Promise<EmitterPort>;
+/** Sorted list of registered target ids. */
+export declare function availableTargets(): Promise<string[]>;
+export interface BuildEmitContextOpts {
+    model?: string | null;
+    provider?: string | null;
+}
+/** Compose a DNA agent through the kernel and project it to an
+ *  {@link EmitContext}. `mi` is a live ManifestInstance. */
+export declare function buildEmitContext(mi: ManifestInstance, agent: string, opts?: BuildEmitContextOpts): Promise<EmitContext>;
+/** Compose `agent` from `mi` and emit it for `target`. */
+export declare function emitAgent(mi: ManifestInstance, agent: string, target: string, opts?: BuildEmitContextOpts): Promise<EmitResult>;

package/dist/emit/index.js

@@ -0,0 +1,95 @@
+import { ToolLibrary } from "../tools.js";
+export class EmitError extends Error {
+}
+export class UnknownTarget extends EmitError {
+    target;
+    available;
+    constructor(target, available) {
+        super(`no emitter registered for target '${target}'; available: ` +
+            (available.join(", ") || "(none)"));
+        this.target = target;
+        this.available = available;
+        this.name = "UnknownTarget";
+    }
+}
+// ── registry ──────────────────────────────────────────────────────────────
+const EMITTER_REGISTRY = new Map();
+let builtinsWired = false;
+async function ensureBuiltins() {
+    if (builtinsWired)
+        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);
+}
+/** Register an emitter under its `target` (last registration wins). */
+export function registerEmitter(emitter) {
+    EMITTER_REGISTRY.set(emitter.target, emitter);
+    return emitter;
+}
+/** Look up a registered emitter or throw {@link UnknownTarget}. */
+export async function getEmitter(target) {
+    await ensureBuiltins();
+    const e = EMITTER_REGISTRY.get(target);
+    if (!e)
+        throw new UnknownTarget(target, await availableTargets());
+    return e;
+}
+/** Sorted list of registered target ids. */
+export async function availableTargets() {
+    await ensureBuiltins();
+    return [...EMITTER_REGISTRY.keys()].sort();
+}
+/** Compose a DNA agent through the kernel and project it to an
+ *  {@link EmitContext}. `mi` is a live ManifestInstance. */
+export async function buildEmitContext(mi, agent, opts = {}) {
+    const doc = mi.findAgent(agent);
+    if (!doc) {
+        throw new EmitError(`agent '${agent}' not found in scope '${mi.scope ?? "?"}'`);
+    }
+    const spec = (doc.spec ?? {});
+    const meta = (doc.metadata ?? {});
+    const description = meta.description ?? "";
+    const instructions = await mi.buildPrompt({ agent });
+    let resolvedModel = opts.model ?? spec.model ?? null;
+    if (!resolvedModel) {
+        const root = mi.root;
+        const rootSpec = (root?.spec ?? {});
+        resolvedModel = rootSpec.default_llm ?? null;
+    }
+    const tools = resolveTools(mi, spec);
+    const outputSchema = spec.output_schema ?? null;
+    return {
+        name: doc.name ?? agent,
+        description,
+        instructions,
+        model: resolvedModel,
+        tools,
+        outputSchema,
+        scope: mi.scope ?? null,
+        options: opts.provider ? { provider: opts.provider } : {},
+    };
+}
+function resolveTools(mi, spec) {
+    const names = spec.tools;
+    if (!names || names.length === 0)
+        return [];
+    const lib = new ToolLibrary(mi);
+    return names.map((name) => {
+        const surface = lib.get(name); // throws ToolNotFound (fail-loud)
+        return {
+            name,
+            description: surface.description,
+            parameters: { ...surface.parameters },
+        };
+    });
+}
+// ── high-level surface ──────────────────────────────────────────────────────
+/** Compose `agent` from `mi` and emit it for `target`. */
+export async function emitAgent(mi, agent, target, opts = {}) {
+    const emitter = await getEmitter(target);
+    const ctx = await buildEmitContext(mi, agent, opts);
+    return emitter.emit(ctx);
+}

package/dist/extensions/helix/kinds/tool.kind.yaml

@@ -0,0 +1,240 @@
+# Tool — a declarative, invocable capability an agent can call (record plane).
+#
+# "Tools as data" (f-dna-tools-as-data). The DNA already governs persona,
+# instruction and guardrails declaratively; a Tool moves the AGENT-FACING
+# surface of a tool into the same declarative plane — the ``description`` the
+# model reads to decide whether to call it (``metadata.description``) and the
+# ``parameters`` JSON Schema of its arguments (``spec.input_schema``). One
+# source of truth, versioned, testable, and overridable per tenant, served
+# identically to a Python backend (`@tool`) and a TypeScript frontend
+# (CopilotKit `useCopilotAction`) via ``dna.load_tools`` / ``loadTools``.
+#
+# F3 migration (s-tool-kind-descriptor): this WAS a hand-written ``ToolKind``
+# class (helix/__init__.py + helix.ts) with a ``TypedTool``/``ToolSpec``
+# model. It is now a ``kinds/tool.kind.yaml`` descriptor — a record Kind
+# expressed as data, per the repo's own ratchet (record Kinds are
+# descriptors, never classes). The invocation surface (type/endpoint/mcp/
+# python/shell + input/output schema + auth + read_only/requires_confirmation)
+# is preserved verbatim; only the IMPLEMENTATION moved class → descriptor and
+# the plane moved composition → record (a Tool is not a prompt target and
+# never composes into an agent prompt, so it carries no composition signal —
+# writing a Tool no longer invalidates the composition schema cache).
+#
+# Agents reference Tools by name via ``dep_filters.tools`` (unchanged — the
+# alias ``helix-tool`` is stable). Stored as ``tools/<name>.yaml`` —
+# marketplace-shareable as standalone bundles.
+#
+# tenant_scope intentionally NOT declared — permissive (base Tool + optional
+# per-tenant overlay). A tenant may legitimately override a tool's
+# description/parameters (the SaaS value hook); the base stays intact and the
+# máxima "inheritable ⇒ never tenanted" holds.
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# helix/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: tool
+spec:
+  target_api_version: github.com/ruinosus/dna/v1
+  target_kind: Tool
+  alias: helix-tool
+  origin: github.com/ruinosus/dna/tool
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: tools
+  schema:
+    type: object
+    properties:
+      type:
+        type: string
+        enum:
+        - http
+        - mcp
+        - python
+        - shell
+        - builtin
+        description: How the tool is executed. builtin | http | mcp | python
+          | shell.
+      endpoint:
+        type: string
+        description: URL called when type=http. Supports {placeholder}
+          templating.
+      method:
+        type: string
+        description: HTTP method when type=http (default POST).
+      mcp_server:
+        type: string
+        description: MCP server name when type=mcp.
+      mcp_tool:
+        type: string
+        description: Tool name on the MCP server when type=mcp.
+      python_module:
+        type: string
+        description: Dotted import path when type=python.
+      python_callable:
+        type: string
+        description: Attribute on the module (function or class) when
+          type=python.
+      shell_command:
+        type: string
+        description: Command template when type=shell. Never executed without
+          confirmation.
+      input_schema:
+        type: object
+        description: JSON Schema of the arguments the agent passes when
+          invoking the tool — the "parameters" the model fills in. Surfaced
+          as ``parameters`` by ``dna.load_tools`` / ``loadTools``.
+      output_schema:
+        type: object
+        description: JSON Schema describing the shape of the tool's response.
+      auth_type:
+        type: string
+        enum:
+        - none
+        - api_key
+        - bearer
+        - oauth2
+        description: Credential strategy for the invocation.
+      auth_env_var:
+        type: string
+        description: Environment variable holding the credential (e.g.
+          GITHUB_TOKEN).
+      read_only:
+        type: boolean
+        description: False = the tool may mutate state (DB writes, file
+          changes, external side effects).
+      requires_confirmation:
+        type: boolean
+        description: Force user approval before each invocation.
+      tags:
+        type: array
+        items:
+          type: string
+        description: Free-form labels for filtering and search.
+      examples:
+        type: array
+        items:
+          type: object
+        description: Usage examples ([{input, output}]).
+  ui:
+    mode: build
+    label:
+      en: Tools
+      pt-BR: Ferramentas
+    description:
+      en: '@tool functions available to agents.'
+      pt-BR: Ferramentas (@tool) disponíveis aos agentes.
+    routes:
+      list: docs/Tool
+      detail: docs/Tool/:name
+    permissions:
+      list: any
+      detail: any
+    in_sidebar: true
+    display_order: 53
+  ui_schema:
+    type:
+      widget: select
+      label: Invocation type
+      help: 'How the tool is executed: http | mcp | python | shell | builtin.'
+      order: 10
+    endpoint:
+      widget: text
+      label: HTTP endpoint
+      help: URL called when type=http. Supports {placeholder} templating.
+      order: 20
+    method:
+      widget: select
+      label: HTTP method
+      order: 25
+    mcp_server:
+      widget: text
+      label: MCP server
+      help: Server name when type=mcp.
+      order: 30
+    mcp_tool:
+      widget: text
+      label: MCP tool name
+      order: 35
+    python_module:
+      widget: text
+      label: Python module
+      help: Dotted import path when type=python.
+      order: 40
+    python_callable:
+      widget: text
+      label: Python callable
+      help: Attribute on the module (function or class).
+      order: 45
+    shell_command:
+      widget: textarea
+      label: Shell command
+      help: Command template when type=shell. Never executed without
+        confirmation.
+      order: 50
+    input_schema:
+      widget: code
+      language: yaml
+      label: Input schema (JSON Schema)
+      help: Validates the arguments the agent passes when invoking the tool.
+      height: 260
+      order: 60
+    output_schema:
+      widget: code
+      language: yaml
+      label: Output schema (JSON Schema)
+      help: Describes the shape of the tool's response.
+      height: 220
+      order: 70
+    auth_type:
+      widget: select
+      label: Auth type
+      help: none | api_key | bearer | oauth2.
+      order: 80
+    auth_env_var:
+      widget: text
+      label: Auth env var
+      help: Environment variable holding the credential.
+      order: 85
+    read_only:
+      widget: checkbox
+      label: Read-only
+      help: Uncheck if the tool mutates state (database writes, file changes,
+        external side effects).
+      order: 90
+    requires_confirmation:
+      widget: checkbox
+      label: Requires confirmation
+      help: Force user approval before each invocation.
+      order: 95
+    tags:
+      widget: tags
+      label: Tags
+      order: 100
+    examples:
+      widget: readonly
+      label: Examples
+      help: Usage examples. Nested list — edit via YAML for now.
+      order: 110
+  graph_style:
+    fill: '#14B8A6'
+    stroke: '#0D9488'
+    text_color: '#fff'
+  ascii_icon: 🔧
+  display_label: Tools
+  docs: A Tool is a declarative, invocable capability an agent can call — an
+    HTTP endpoint, an MCP server tool, a Python callable, a shell command, or
+    a builtin. It bridges DNA with OpenAI/Anthropic tool-calling conventions.
+    The agent-facing surface is its ``metadata.description`` (the text the
+    model reads to decide to call it) and its ``spec.input_schema`` (the
+    "parameters" JSON Schema of the arguments); ``dna.load_tools`` /
+    ``loadTools`` serve exactly that surface, identically to Python and
+    TypeScript consumers from this one source. It also declares an auth
+    strategy and read_only / requires_confirmation flags the host honors at
+    runtime. Agents reference Tools via ``dep_filters.tools``. Stored as
+    ``tools/<name>.yaml`` — marketplace-shareable as standalone bundles.