dna-sdk 0.5.0 → 0.7.0

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,15 @@ 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 { 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 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,12 @@ 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 { emitAgent, buildEmitContext, registerEmitter, getEmitter, availableTargets, EmitError, UnknownTarget, } from "./emit/index.js";
+export { AgentFrameworkEmitter } from "./emit/agentFramework.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>;