dna-sdk 0.5.0 → 0.6.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/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.

package/dist/extensions/helix.js

@@ -7,7 +7,8 @@ import yaml from "js-yaml";
 import { join as pathJoin } from "node:path";
 import { nodeFS, readTextSafe, collectDir } from "../kernel/fs.js";
 import { KindBase } from "../kernel/kind_base.js";
-import { AgentSchema, ActorSchema, UseCaseSchema, ToolSchema, AgentSpecSchema, ActorSpecSchema, UseCaseSpecSchema, ToolSpecSchema, GenomeSchema, GenomeSpecSchema, LayerPolicySchema, LayerPolicySpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { AgentSchema, ActorSchema, UseCaseSchema, AgentSpecSchema, ActorSpecSchema, UseCaseSpecSchema, GenomeSchema, GenomeSpecSchema, LayerPolicySchema, LayerPolicySpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
 import { SD } from "../kernel/protocols.js";
 import { readSpecString, readSpecStringArray } from "../kernel/spec-access.js";
 import { SettingKind, ThemeKind, UserProfileKind, CanvasKind } from "./helix_extras.js";
@@ -529,102 +530,6 @@ class UseCaseKind extends KindBase {
     }
 }
 // ---------------------------------------------------------------------------
-// ToolKind
-// ---------------------------------------------------------------------------
-class ToolKind extends KindBase {
-    apiVersion = "github.com/ruinosus/dna/v1";
-    kind = "Tool";
-    alias = "helix-tool";
-    isSchemaAffecting = true;
-    origin = "github.com/ruinosus/dna/tool";
-    isPromptTarget = false;
-    promptTargetPriority = 0;
-    flattenInContext = false;
-    storage = SD.yaml("tools");
-    graphStyle = { fill: "#14B8A6", stroke: "#0D9488", textColor: "#fff" };
-    asciiIcon = "🔧";
-    displayLabel = "Tools";
-    _sourceUrl = MOD_URL;
-    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. Bridges helix with OpenAI/Anthropic tool-calling " +
-        "conventions. Each Tool declares an input/output JSON Schema, an auth " +
-        "strategy, and read_only / requires_confirmation flags that the harness " +
-        "honors at runtime. Agents reference Tools via dep_filters.tools. " +
-        "Stored as tools/<name>.yaml — marketplace-shareable as standalone bundles.";
-    uiSchema = {
-        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.", 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. Edit via YAML for now.", order: 110 },
-    };
-    schema() { return zodSpecToJsonSchema(ToolSpecSchema); }
-    parse(raw) {
-        return ToolSchema.parse(raw);
-    }
-    summary() { return null; }
-    preview(doc) {
-        const spec = (doc.spec ?? {});
-        const fields = [];
-        if (typeof spec.type === "string")
-            fields.push({ label: "type", value: spec.type });
-        if (typeof spec.endpoint === "string")
-            fields.push({ label: "endpoint", value: spec.endpoint });
-        if (typeof spec.method === "string")
-            fields.push({ label: "method", value: spec.method });
-        if (typeof spec.mcp_server === "string")
-            fields.push({ label: "mcp_server", value: spec.mcp_server });
-        if (typeof spec.mcp_tool === "string")
-            fields.push({ label: "mcp_tool", value: spec.mcp_tool });
-        if (typeof spec.python_module === "string")
-            fields.push({ label: "python_module", value: spec.python_module });
-        if (typeof spec.python_callable === "string")
-            fields.push({ label: "python_callable", value: spec.python_callable });
-        if (typeof spec.shell_command === "string")
-            fields.push({ label: "shell_command", value: spec.shell_command });
-        if (spec.input_schema)
-            fields.push({ label: "input_schema", value: JSON.stringify(spec.input_schema, null, 2) });
-        if (spec.output_schema)
-            fields.push({ label: "output_schema", value: JSON.stringify(spec.output_schema, null, 2) });
-        if (typeof spec.auth_type === "string")
-            fields.push({ label: "auth", value: spec.auth_type });
-        if (spec.read_only != null)
-            fields.push({ label: "read_only", value: String(spec.read_only) });
-        if (spec.requires_confirmation != null)
-            fields.push({ label: "requires_confirmation", value: String(spec.requires_confirmation) });
-        if (fields.length === 0) {
-            return [{ kind: "empty", title: `Tool ${doc.name}` }];
-        }
-        return [{ kind: "fields", title: `Tool ${doc.name}`, fields }];
-    }
-}
-// ---------------------------------------------------------------------------
 // AgentReader / AgentWriter
 // ---------------------------------------------------------------------------
 const KNOWN_DIRS = new Set(["scripts", "references", "assets"]);
@@ -985,9 +890,15 @@ export class HelixExtension {
         kernel.kind(new GenomeKind());
         kernel.kind(new LayerPolicyKind());
         kernel.kind(new AgentKind());
-        kernel.kind(new ToolKind());
         kernel.kind(new ActorKind());
         kernel.kind(new UseCaseKind());
+        // Tool (helix-tool) ships as a descriptor — helix/kinds/tool.kind.yaml
+        // (f-dna-tools-as-data / s-tool-kind-descriptor). It WAS a hand-written
+        // ToolKind class; migrated to a record-plane descriptor per the repo's
+        // own ratchet (record Kinds are data, not classes).
+        for (const raw of loadDescriptors(import.meta.url, "helix/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
         // 2026-05-26 — absorbed from claude-code-templates catalog (MIT).
         // Setting rounds out the Claude-Code-customization primitives that
         // live alongside Skill / UA / Soul / Tool.

package/dist/index.d.ts

@@ -22,8 +22,12 @@ export { ReportBuilder } from "./kernel/reports.js";
 export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 export * from "./viz/index.js";
 export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
-export { AgentNotFound, UnknownLayout } from "./kernel/errors.js";
+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 type { LoadPromptsOptions } from "./prompts.js";
+export { anchorScopesRoot, PackageScopeNotFound, DEFAULT_SUBPATH } from "./package-scope.js";
 export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
 export type { DnaConfig, SearchMode, EmbeddingMode } from "./config.js";
 export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";

package/dist/index.js

@@ -27,8 +27,10 @@ export * from "./viz/index.js";
 export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
 // DX consumer surface (s-dx-*): fail-loud prompt building + the collapse-the-
 // shim helper + declarative port wiring.
-export { AgentNotFound, UnknownLayout } from "./kernel/errors.js";
+export { AgentNotFound, ToolNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { ToolLibrary, loadTools } from "./tools.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";
 export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";

package/dist/kernel/errors.d.ts

@@ -31,6 +31,24 @@ export declare class AgentNotFound extends Error {
     readonly agent: string | null;
     constructor(agent: string | null);
 }
+/**
+ * `loadTools(scope).get(name)` was asked for a Tool that no `Tool` document in
+ * the scope declares (missing, renamed, or in another scope).
+ *
+ * Fail-loud contract (s-load-tools-helper), the twin of `AgentNotFound`: the
+ * agent-facing tool surface is data, so a miss must throw a typed error —
+ * never return an empty surface that would silently reach a model as a tool
+ * with no description.
+ *
+ * 1:1 parity with python `dna.ToolNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export declare class ToolNotFound extends Error {
+    readonly toolName: string | null;
+    readonly scope: string | null;
+    readonly available: string[];
+    constructor(name: string | null, scope?: string | null, available?: string[]);
+}
 /**
  * `buildPrompt` hit an Agent whose `layout:` names a preset the Kind does not
  * offer (s-dx-named-layouts).

package/dist/kernel/errors.js

@@ -36,6 +36,33 @@ export class AgentNotFound extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * `loadTools(scope).get(name)` was asked for a Tool that no `Tool` document in
+ * the scope declares (missing, renamed, or in another scope).
+ *
+ * Fail-loud contract (s-load-tools-helper), the twin of `AgentNotFound`: the
+ * agent-facing tool surface is data, so a miss must throw a typed error —
+ * never return an empty surface that would silently reach a model as a tool
+ * with no description.
+ *
+ * 1:1 parity with python `dna.ToolNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export class ToolNotFound extends Error {
+    toolName;
+    scope;
+    available;
+    constructor(name, scope = null, available = []) {
+        const where = scope ? ` in scope '${scope}'` : "";
+        const hint = available.length ? ` — available: ${available.join(", ")}` : "";
+        super(`Tool '${name}' not found${where}${hint}`);
+        this.name = "ToolNotFound";
+        this.toolName = name;
+        this.scope = scope;
+        this.available = available;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /**
  * `buildPrompt` hit an Agent whose `layout:` names a preset the Kind does not
  * offer (s-dx-named-layouts).

package/dist/kernel/kind-registry.js

@@ -115,7 +115,9 @@ export function generateAlias(owner, kind) {
 export const EXPLICIT_ALIAS_ALLOWLIST = new Set([
     // helix
     "helix-genome", "helix-agent", "helix-actor",
-    "helix-usecase", "helix-tool", "policy-layer-policy",
+    // helix-tool migrated to a descriptor (s-tool-kind-descriptor): its alias
+    // lives in helix/kinds/tool.kind.yaml (parity-critical) — shrink-only.
+    "helix-usecase", "policy-layer-policy",
     "helix-canvas",
     "helix-setting", "helix-theme", "helix-user-profile",
     // sdlc (classes; descriptors are outside the ratchet)

package/dist/kernel/models.d.ts

@@ -1166,197 +1166,6 @@ export declare const UseCaseSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type TypedUseCase = z.output<typeof UseCaseSchema>;
-export declare const ToolTypeEnum: z.ZodEnum<["http", "mcp", "python", "shell", "builtin"]>;
-export declare const ToolAuthTypeEnum: z.ZodEnum<["none", "api_key", "bearer", "oauth2"]>;
-export declare const ToolSpecSchema: z.ZodObject<{
-    type: z.ZodDefault<z.ZodEnum<["http", "mcp", "python", "shell", "builtin"]>>;
-    endpoint: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    mcp_server: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    mcp_tool: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    python_module: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    python_callable: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    shell_command: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    input_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    output_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    auth_type: z.ZodDefault<z.ZodEnum<["none", "api_key", "bearer", "oauth2"]>>;
-    auth_env_var: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    read_only: z.ZodDefault<z.ZodBoolean>;
-    requires_confirmation: z.ZodDefault<z.ZodBoolean>;
-    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    examples: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
-}, "strip", z.ZodTypeAny, {
-    type: "http" | "mcp" | "python" | "shell" | "builtin";
-    tags: string[];
-    input_schema: Record<string, unknown>;
-    endpoint: string;
-    method: string;
-    mcp_server: string;
-    mcp_tool: string;
-    python_module: string;
-    python_callable: string;
-    shell_command: string;
-    output_schema: Record<string, unknown>;
-    auth_type: "none" | "api_key" | "bearer" | "oauth2";
-    auth_env_var: string;
-    read_only: boolean;
-    requires_confirmation: boolean;
-    examples: Record<string, unknown>[];
-}, {
-    type?: "http" | "mcp" | "python" | "shell" | "builtin" | undefined;
-    tags?: string[] | undefined;
-    input_schema?: Record<string, unknown> | undefined;
-    endpoint?: string | undefined;
-    method?: string | undefined;
-    mcp_server?: string | undefined;
-    mcp_tool?: string | undefined;
-    python_module?: string | undefined;
-    python_callable?: string | undefined;
-    shell_command?: string | undefined;
-    output_schema?: Record<string, unknown> | undefined;
-    auth_type?: "none" | "api_key" | "bearer" | "oauth2" | undefined;
-    auth_env_var?: string | undefined;
-    read_only?: boolean | undefined;
-    requires_confirmation?: boolean | undefined;
-    examples?: Record<string, unknown>[] | undefined;
-}>;
-export declare const ToolSchema: z.ZodObject<{
-    apiVersion: z.ZodLiteral<"github.com/ruinosus/dna/v1">;
-    kind: z.ZodLiteral<"Tool">;
-    metadata: z.ZodObject<{
-        name: z.ZodString;
-        description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        icon: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        group: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        labels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        description: string;
-        version: string;
-        icon: string;
-        group: string;
-        labels: Record<string, string>;
-    }, {
-        name: string;
-        description?: string | undefined;
-        version?: string | undefined;
-        icon?: string | undefined;
-        group?: string | undefined;
-        labels?: Record<string, string> | undefined;
-    }>;
-    spec: z.ZodDefault<z.ZodObject<{
-        type: z.ZodDefault<z.ZodEnum<["http", "mcp", "python", "shell", "builtin"]>>;
-        endpoint: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        mcp_server: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        mcp_tool: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        python_module: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        python_callable: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        shell_command: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        input_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        output_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        auth_type: z.ZodDefault<z.ZodEnum<["none", "api_key", "bearer", "oauth2"]>>;
-        auth_env_var: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        read_only: z.ZodDefault<z.ZodBoolean>;
-        requires_confirmation: z.ZodDefault<z.ZodBoolean>;
-        tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        examples: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        type: "http" | "mcp" | "python" | "shell" | "builtin";
-        tags: string[];
-        input_schema: Record<string, unknown>;
-        endpoint: string;
-        method: string;
-        mcp_server: string;
-        mcp_tool: string;
-        python_module: string;
-        python_callable: string;
-        shell_command: string;
-        output_schema: Record<string, unknown>;
-        auth_type: "none" | "api_key" | "bearer" | "oauth2";
-        auth_env_var: string;
-        read_only: boolean;
-        requires_confirmation: boolean;
-        examples: Record<string, unknown>[];
-    }, {
-        type?: "http" | "mcp" | "python" | "shell" | "builtin" | undefined;
-        tags?: string[] | undefined;
-        input_schema?: Record<string, unknown> | undefined;
-        endpoint?: string | undefined;
-        method?: string | undefined;
-        mcp_server?: string | undefined;
-        mcp_tool?: string | undefined;
-        python_module?: string | undefined;
-        python_callable?: string | undefined;
-        shell_command?: string | undefined;
-        output_schema?: Record<string, unknown> | undefined;
-        auth_type?: "none" | "api_key" | "bearer" | "oauth2" | undefined;
-        auth_env_var?: string | undefined;
-        read_only?: boolean | undefined;
-        requires_confirmation?: boolean | undefined;
-        examples?: Record<string, unknown>[] | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    metadata: {
-        name: string;
-        description: string;
-        version: string;
-        icon: string;
-        group: string;
-        labels: Record<string, string>;
-    };
-    spec: {
-        type: "http" | "mcp" | "python" | "shell" | "builtin";
-        tags: string[];
-        input_schema: Record<string, unknown>;
-        endpoint: string;
-        method: string;
-        mcp_server: string;
-        mcp_tool: string;
-        python_module: string;
-        python_callable: string;
-        shell_command: string;
-        output_schema: Record<string, unknown>;
-        auth_type: "none" | "api_key" | "bearer" | "oauth2";
-        auth_env_var: string;
-        read_only: boolean;
-        requires_confirmation: boolean;
-        examples: Record<string, unknown>[];
-    };
-    apiVersion: "github.com/ruinosus/dna/v1";
-    kind: "Tool";
-}, {
-    metadata: {
-        name: string;
-        description?: string | undefined;
-        version?: string | undefined;
-        icon?: string | undefined;
-        group?: string | undefined;
-        labels?: Record<string, string> | undefined;
-    };
-    apiVersion: "github.com/ruinosus/dna/v1";
-    kind: "Tool";
-    spec?: {
-        type?: "http" | "mcp" | "python" | "shell" | "builtin" | undefined;
-        tags?: string[] | undefined;
-        input_schema?: Record<string, unknown> | undefined;
-        endpoint?: string | undefined;
-        method?: string | undefined;
-        mcp_server?: string | undefined;
-        mcp_tool?: string | undefined;
-        python_module?: string | undefined;
-        python_callable?: string | undefined;
-        shell_command?: string | undefined;
-        output_schema?: Record<string, unknown> | undefined;
-        auth_type?: "none" | "api_key" | "bearer" | "oauth2" | undefined;
-        auth_env_var?: string | undefined;
-        read_only?: boolean | undefined;
-        requires_confirmation?: boolean | undefined;
-        examples?: Record<string, unknown>[] | undefined;
-    } | undefined;
-}>;
-export type TypedTool = z.output<typeof ToolSchema>;
 export declare const SkillSpecSchema: z.ZodObject<{
     instruction: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     scripts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;

package/dist/kernel/models.js

@@ -335,38 +335,6 @@ export const UseCaseSchema = z.object({
     spec: UseCaseSpecSchema.default({}),
 });
 // ---------------------------------------------------------------------------
-// Tool (github.com/ruinosus/dna/v1)
-//
-// Declarative, invocable capability an agent can call. Bridges helix with
-// OpenAI/Anthropic tool-calling conventions.
-// ---------------------------------------------------------------------------
-export const ToolTypeEnum = z.enum(["http", "mcp", "python", "shell", "builtin"]);
-export const ToolAuthTypeEnum = z.enum(["none", "api_key", "bearer", "oauth2"]);
-export const ToolSpecSchema = z.object({
-    type: ToolTypeEnum.default("builtin"),
-    endpoint: z.string().optional().default(""),
-    method: z.string().optional().default("POST"),
-    mcp_server: z.string().optional().default(""),
-    mcp_tool: z.string().optional().default(""),
-    python_module: z.string().optional().default(""),
-    python_callable: z.string().optional().default(""),
-    shell_command: z.string().optional().default(""),
-    input_schema: z.record(z.unknown()).default({}),
-    output_schema: z.record(z.unknown()).default({}),
-    auth_type: ToolAuthTypeEnum.default("none"),
-    auth_env_var: z.string().optional().default(""),
-    read_only: z.boolean().default(true),
-    requires_confirmation: z.boolean().default(false),
-    tags: z.array(z.string()).default([]),
-    examples: z.array(z.record(z.unknown())).default([]),
-});
-export const ToolSchema = z.object({
-    apiVersion: z.literal("github.com/ruinosus/dna/v1"),
-    kind: z.literal("Tool"),
-    metadata: MetadataSchema,
-    spec: ToolSpecSchema.default({}),
-});
-// ---------------------------------------------------------------------------
 // Skill (agentskills.io/v1)
 // ---------------------------------------------------------------------------
 export const SkillSpecSchema = z.object({

package/dist/package-scope.d.ts

@@ -0,0 +1,18 @@
+/** The conventional scopes-root sub-directory inside a package (matches the
+ * repo's own `.dna/<scope>/` layout). */
+export declare const DEFAULT_SUBPATH = ".dna";
+/** Raised when an `anchor` package / subpath can't be resolved to a real
+ * on-disk scopes-root directory. */
+export declare class PackageScopeNotFound extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the `.dna` scopes-root embedded in package `anchor`.
+ *
+ * `anchor` is a resolvable package specifier (e.g. `"app"`); `subpath` is the
+ * scopes-root dir inside it (default `.dna`). Returns the concrete filesystem
+ * path of `<anchor-package>/<subpath>` — the `baseDir` a FilesystemSource
+ * consumes. Fails loud (`PackageScopeNotFound`) when the package cannot be
+ * resolved or the subpath does not exist in the installed package.
+ */
+export declare function anchorScopesRoot(anchor: string, subpath?: string): string;

package/dist/package-scope.js

@@ -0,0 +1,87 @@
+/**
+ * Resolve a DNA scope embedded as PACKAGE DATA (`s-scope-as-package-data`).
+ *
+ * 1:1 parity with python `dna/package_scope.py`. A consumer that deploys an
+ * app used to make the scope travel by hand — a brittle
+ * `path.resolve(__dirname, "../../.dna")` plus a manual `COPY .dna` in the
+ * Dockerfile. The image is the *app*, not the repo; forget the COPY and the
+ * app boots with no scope. This module owns the deploy-safe alternative:
+ * resolve the scope from INSIDE the installed package.
+ *
+ * The TS mechanism mirrors how the SDK finds its OWN bundled `*.kind.yaml`
+ * (see `kernel/descriptor-loader.ts`): resolve relative to a module. Here the
+ * anchor is a package NAME, so we resolve its `package.json` via
+ * `createRequire(import.meta.url)` — the package root is that file's dir —
+ * then join the scopes-root subpath (`.dna` by default). `npm`/`bun`/`pnpm`
+ * install the package UNPACKED into `node_modules`, and the package's `files`
+ * field carries the scope into the published tarball and into a Docker image,
+ * so resolution works from a source checkout, an installed dependency, and a
+ * container whose CWD is not the repo — zero path navigation, zero manual copy.
+ *
+ * Read-only by nature: package data is composition input, never a write
+ * target. To WRITE a scope, use a filesystem or postgres source.
+ */
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+/** The conventional scopes-root sub-directory inside a package (matches the
+ * repo's own `.dna/<scope>/` layout). */
+export const DEFAULT_SUBPATH = ".dna";
+/** Raised when an `anchor` package / subpath can't be resolved to a real
+ * on-disk scopes-root directory. */
+export class PackageScopeNotFound extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PackageScopeNotFound";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+const require = createRequire(import.meta.url);
+/**
+ * Resolve the `.dna` scopes-root embedded in package `anchor`.
+ *
+ * `anchor` is a resolvable package specifier (e.g. `"app"`); `subpath` is the
+ * scopes-root dir inside it (default `.dna`). Returns the concrete filesystem
+ * path of `<anchor-package>/<subpath>` — the `baseDir` a FilesystemSource
+ * consumes. Fails loud (`PackageScopeNotFound`) when the package cannot be
+ * resolved or the subpath does not exist in the installed package.
+ */
+export function anchorScopesRoot(anchor, subpath = DEFAULT_SUBPATH) {
+    const pkgRoot = resolvePackageRoot(anchor);
+    const base = subpath ? join(pkgRoot, subpath) : pkgRoot;
+    if (!existsSync(base)) {
+        throw new PackageScopeNotFound(`anchor '${anchor}' is installed, but its scopes-root '${subpath}' was ` +
+            `not found at ${base}. Declare the scope files as package data so ` +
+            `they ship in the tarball/image: add the scopes dir to the package's ` +
+            `"files" array in package.json (e.g. "files": ["dist", "${subpath}"]). ` +
+            `See the guide "Shipping a scope with your app".`);
+    }
+    return base;
+}
+/** Locate a package's root dir from its name, via its `package.json`. */
+function resolvePackageRoot(anchor) {
+    // Primary: resolve the package's package.json — its dir IS the package root.
+    // (A package can gate this behind "exports"; the example adds the standard
+    // `"./package.json": "./package.json"` so it always resolves.)
+    try {
+        return dirname(require.resolve(join(anchor, "package.json")));
+    }
+    catch {
+        // Fallback: an absolute/relative path anchor (a directory, not a package
+        // name) — treat it as the package root directly.
+        if (isAbsolute(anchor) && existsSync(anchor))
+            return anchor;
+        try {
+            // Last resort: resolve the package entry point and use its dir. Only
+            // reliable for a flat single-file package, but better than nothing.
+            return dirname(require.resolve(anchor));
+        }
+        catch (err) {
+            throw new PackageScopeNotFound(`anchor '${anchor}' is not resolvable — it must be an INSTALLED ` +
+                `package that embeds the scope as package data (npm/bun install it, ` +
+                `and list the scopes dir in the package's "files" so it ships). ` +
+                `If it uses "exports", add "./package.json": "./package.json". ` +
+                `Original resolve error: ${err.message}`);
+        }
+    }
+}

package/dist/prompts.d.ts

@@ -17,11 +17,34 @@ export declare class PromptLibrary {
     /** Names of every prompt-target document in the scope, sorted. */
     names(): string[];
 }
+/** Options for {@link loadPrompts}. */
+export interface LoadPromptsOptions {
+    /**
+     * The directory that holds `<scope>/` (the `.dna` scopes root), following
+     * the {@link quickInstance} convention.
+     */
+    baseDir?: string;
+    /**
+     * A package specifier whose package data embeds the scope. When given, the
+     * scope is resolved from INSIDE the installed package (via its
+     * `package.json`), so it TRAVELS with the app — an `npm`/`bun install`
+     * carries the package data into the published tarball and into a Docker
+     * image, and resolution works identically from a source checkout, an
+     * installed dependency, or a container whose CWD is not the repo (no
+     * `path.resolve(__dirname, "../..")` navigation, no manual `COPY .dna`).
+     * A scope embedded via `anchor` is READ-ONLY. See the guide "Shipping a
+     * scope with your app".
+     */
+    anchor?: string;
+}
 /**
  * Compose the prompts of `scope` behind a {@link PromptLibrary}.
  *
- * `baseDir` follows the {@link quickInstance} convention — the directory that
- * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
- * var, then `.dna` in the cwd.
+ * Precedence for the scopes-root (first one set wins):
+ *
+ *   `opts.baseDir`  >  `$DNA_BASE_DIR`  >  `opts.anchor` (package data)  >  `.dna`
+ *
+ * The legacy positional-string form (`loadPrompts(scope, "/path/.dna")`) is
+ * still accepted for back-compat and is treated as `baseDir`.
  */
-export declare function loadPrompts(scope: string, baseDir?: string): Promise<PromptLibrary>;
+export declare function loadPrompts(scope: string, opts?: string | LoadPromptsOptions): Promise<PromptLibrary>;

package/dist/prompts.js

@@ -24,6 +24,7 @@
  * is `await`ed in TS but not in Python).
  */
 import { quickInstance } from "./bootstrap.js";
+import { anchorScopesRoot } from "./package-scope.js";
 /** Lazy, cached view `agent name -> composed prompt` over one scope. */
 export class PromptLibrary {
     mi;
@@ -65,12 +66,26 @@ export class PromptLibrary {
 /**
  * Compose the prompts of `scope` behind a {@link PromptLibrary}.
  *
- * `baseDir` follows the {@link quickInstance} convention — the directory that
- * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
- * var, then `.dna` in the cwd.
+ * Precedence for the scopes-root (first one set wins):
+ *
+ *   `opts.baseDir`  >  `$DNA_BASE_DIR`  >  `opts.anchor` (package data)  >  `.dna`
+ *
+ * The legacy positional-string form (`loadPrompts(scope, "/path/.dna")`) is
+ * still accepted for back-compat and is treated as `baseDir`.
  */
-export async function loadPrompts(scope, baseDir) {
-    const resolved = baseDir ?? process.env.DNA_BASE_DIR ?? ".dna";
-    const mi = await quickInstance(scope, resolved);
+export async function loadPrompts(scope, opts) {
+    const o = typeof opts === "string" ? { baseDir: opts } : opts ?? {};
+    const mi = await quickInstance(scope, resolveScopeBaseDir(o));
     return new PromptLibrary(mi);
 }
+/** Pick the `.dna` scopes-root by the documented precedence. */
+function resolveScopeBaseDir(o) {
+    if (o.baseDir !== undefined)
+        return o.baseDir;
+    const env = process.env.DNA_BASE_DIR;
+    if (env)
+        return env;
+    if (o.anchor !== undefined)
+        return anchorScopesRoot(o.anchor);
+    return ".dna";
+}

package/dist/tools.d.ts

@@ -0,0 +1,41 @@
+import { ToolNotFound } from "./kernel/errors.js";
+import type { ManifestInstance } from "./kernel/instance.js";
+export { ToolNotFound };
+/**
+ * The agent-facing surface of a Tool — exactly what a tool-calling model is
+ * shown to decide whether, and how, to call it.
+ */
+export interface ToolSurface {
+    /** Natural-language description (`metadata.description`) — the text the
+     *  model reads. */
+    readonly description: string;
+    /** JSON Schema of the arguments (`spec.input_schema`) — what the model
+     *  fills in. Empty `{}` when the tool takes no args. */
+    readonly parameters: Record<string, unknown>;
+}
+/** Lazy, cached view `tool name -> ToolSurface` over one scope. */
+export declare class ToolLibrary {
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    readonly mi: ManifestInstance;
+    private readonly cache;
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi: ManifestInstance);
+    /**
+     * Project `name`'s agent-facing surface (cached). Throws {@link ToolNotFound}
+     * on a miss.
+     */
+    get(name: string): ToolSurface;
+    /** True when `name` is a Tool document in the scope (no projection). */
+    has(name: string): boolean;
+    /** Names of every Tool document in the scope, sorted. */
+    names(): string[];
+}
+/**
+ * Load the Tool surfaces of `scope` behind a {@link ToolLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export declare function loadTools(scope: string, baseDir?: string): Promise<ToolLibrary>;

package/dist/tools.js

@@ -0,0 +1,88 @@
+/**
+ * `loadTools` — the agent-facing tool surface, as data (TS twin of python
+ * `dna.load_tools`).
+ *
+ * The DNA already governs persona, instruction and guardrails declaratively.
+ * A **Tool** (record-plane Kind, `helix/kinds/tool.kind.yaml`) moves the last
+ * hard-coded piece into the same plane: the `description` the model reads to
+ * decide whether to call a tool, and the JSON Schema of its `parameters`.
+ * `loadTools` is the consumer one-liner — the twin of `loadPrompts`:
+ *
+ * ```ts
+ * import { loadTools } from "@ruinosus/dna";
+ *
+ * const tools = await loadTools("open-swe");
+ * const surface = tools.get("github-search"); // or throws ToolNotFound
+ * surface.description;                          // the text the model reads
+ * surface.parameters;                           // the args JSON Schema
+ * ```
+ *
+ * Because a Tool is ONE declarative document, the SAME surface is served to a
+ * Python backend (a `@tool` function's `description=`) and this TypeScript
+ * frontend (CopilotKit `useCopilotAction`) from one source of truth — the
+ * first place the Py↔TS descriptor parity pays off in a real consumer (see
+ * `examples/tools_as_data`).
+ *
+ * TS/Py asymmetry: `loadTools` is async (booting the kernel is async, exactly
+ * like `loadPrompts`), but `get(name)` is SYNC — reading a record document
+ * needs no async work (unlike `loadPrompts.get`, which awaits composition).
+ * A missing tool throws {@link ToolNotFound} (never an empty surface).
+ * Overlay-aware: a tenant overlay that overrides a tool's
+ * `metadata.description` / `spec.input_schema` is reflected here.
+ */
+import { quickInstance } from "./bootstrap.js";
+import { ToolNotFound } from "./kernel/errors.js";
+export { ToolNotFound };
+/** Lazy, cached view `tool name -> ToolSurface` over one scope. */
+export class ToolLibrary {
+    mi;
+    cache = new Map();
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi) {
+        this.mi = mi;
+    }
+    /**
+     * Project `name`'s agent-facing surface (cached). Throws {@link ToolNotFound}
+     * on a miss.
+     */
+    get(name) {
+        const cached = this.cache.get(name);
+        if (cached !== undefined)
+            return cached;
+        const doc = this.mi._one("Tool", name);
+        if (doc === null) {
+            throw new ToolNotFound(name, this.mi.scope ?? null, this.names());
+        }
+        const meta = doc.metadata;
+        const spec = doc.spec;
+        const description = typeof meta.description === "string" ? meta.description : "";
+        const rawParams = spec.input_schema;
+        const parameters = rawParams && typeof rawParams === "object" && !Array.isArray(rawParams)
+            ? { ...rawParams }
+            : {};
+        const surface = { description, parameters };
+        this.cache.set(name, surface);
+        return surface;
+    }
+    /** True when `name` is a Tool document in the scope (no projection). */
+    has(name) {
+        return this.names().includes(name);
+    }
+    /** Names of every Tool document in the scope, sorted. */
+    names() {
+        return this.mi._all("Tool").map((d) => d.name).sort();
+    }
+}
+/**
+ * Load the Tool surfaces of `scope` behind a {@link ToolLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export async function loadTools(scope, baseDir) {
+    const resolved = baseDir ?? process.env.DNA_BASE_DIR ?? ".dna";
+    const mi = await quickInstance(scope, resolved);
+    return new ToolLibrary(mi);
+}

package/package.json

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