@arnilo/prism 0.0.1 → 0.0.3

package/dist/instruction-injection.js

@@ -0,0 +1,55 @@
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new Error("Instruction injector aborted");
+}
+function shouldApply(contribution, ctx) {
+    if (contribution.when === "first_turn")
+        return ctx.turn === 1;
+    if (contribution.when === "every_turn")
+        return true;
+    // on_input: predicate optional, absent = apply every turn (default).
+    return contribution.predicate ? contribution.predicate(ctx) : true;
+}
+/** Run each selected injector against `ctx`, returning the matching contributions as
+ *  `package`-source `SystemPromptContribution[]` (for `composeSystemPrompt`) and
+ *  `ContextBlock[]` (for the context merge). Aborts on `ctx.signal`. Non-matching
+ *  injectors contribute nothing; only `instructions`/`contextBlocks` are honored —
+ *  injectors cannot register tools, skills, or permissions. */
+export function runInstructionInjectors(injectors, ctx) {
+    const instructions = [];
+    const contextBlocks = [];
+    for (const injector of injectors) {
+        throwIfAborted(ctx.signal);
+        const contribution = injector.apply(ctx);
+        if (!shouldApply(contribution, ctx))
+            continue;
+        // ponytail: only instructions/contextBlocks honored; other fields grant nothing.
+        if (contribution.instructions) {
+            instructions.push({ id: `injector:${injector.name}`, source: "package", mode: "append", text: contribution.instructions });
+        }
+        if (contribution.contextBlocks)
+            contextBlocks.push(...contribution.contextBlocks);
+    }
+    return { instructions, contextBlocks };
+}
+/**
+ * Resolve the effective injector list for a run. Mirrors {@link resolveActiveSkills}
+ * fail-closed name resolution. When `configured` is provided it wins (RunOptions
+ * supplies an explicit list); otherwise names are resolved against `registry`.
+ * An unknown name throws `Unknown instruction injector: <name>`.
+ *
+ * ponytail: no toolNames enforcement — injectors grant no tools (unlike skills).
+ */
+export function resolveInstructionInjectors(options) {
+    if (options.configured)
+        return options.configured;
+    if (!options.names || !options.registry)
+        return [];
+    return options.names.map((name) => {
+        const injector = options.registry.get(name);
+        if (!injector)
+            throw new Error(`Unknown instruction injector: ${name}`);
+        return injector;
+    });
+}
+//# sourceMappingURL=instruction-injection.js.map

package/dist/manifests.d.ts

@@ -1,5 +1,5 @@
 import type { JsonObject } from "./contracts.js";
-export type ManifestContributionKind = "provider" | "model" | "tool" | "contextProvider" | "skill" | "command" | "agent" | "inputBuilder" | "promptBuilder" | "compactionStrategy" | "retryPolicy" | "storeFactory" | "resourceLoader" | "settingsProvider" | "credentialResolver" | "providerPackage" | "authMethod" | "providerRequestPolicy" | "systemPromptContribution";
+export type ManifestContributionKind = "provider" | "model" | "tool" | "contextProvider" | "skill" | "command" | "agent" | "inputBuilder" | "promptBuilder" | "compactionStrategy" | "retryPolicy" | "storeFactory" | "resourceLoader" | "settingsProvider" | "credentialResolver" | "providerPackage" | "authMethod" | "providerRequestPolicy" | "systemPromptContribution" | "instructionInjector";
 export interface ManifestContributionDeclaration {
     readonly kind: ManifestContributionKind;
     readonly name: string;

package/dist/manifests.js

@@ -1,4 +1,4 @@
-import { assertJsonObject, isJsonObject } from "./config.js";
+import { assertJsonObject } from "./config.js";
 export function definePrismManifest(manifest) {
     return parsePrismManifest(manifest);
 }
@@ -77,6 +77,7 @@ function readKind(value, index) {
         "authMethod",
         "providerRequestPolicy",
         "systemPromptContribution",
+        "instructionInjector",
     ]);
     if (typeof value !== "string" || !kinds.has(value)) {
         throw new Error(`manifest.contributions[${index}].kind must be a known contribution kind`);
@@ -101,8 +102,7 @@ function readOptionalJsonObject(record, key, label = `manifest.${key}`) {
     const value = record[key];
     if (value === undefined)
         return {};
-    if (!isJsonObject(value))
-        throw new Error(`${label} must be a JSON object`);
+    assertJsonObject(value, label);
     return { [key]: value };
 }
 //# sourceMappingURL=manifests.js.map

package/dist/models.d.ts

@@ -1,8 +1,11 @@
 import type { ModelConfig } from "./contracts.js";
+import { type DuplicateRegistrationOptions } from "./registry-options.js";
 export interface ModelRegistry {
     register(model: ModelConfig): void;
     get(provider: string, model: string): ModelConfig | undefined;
     resolve(provider: string, model: string): ModelConfig;
     list(): readonly ModelConfig[];
 }
-export declare function createModelRegistry(models?: readonly ModelConfig[]): ModelRegistry;
+export interface ModelRegistryOptions extends DuplicateRegistrationOptions {
+}
+export declare function createModelRegistry(models?: readonly ModelConfig[], options?: ModelRegistryOptions): ModelRegistry;

package/dist/models.js

@@ -1,9 +1,12 @@
-export function createModelRegistry(models = []) {
+import { assertCanRegister } from "./registry-options.js";
+export function createModelRegistry(models = [], options = {}) {
     const byId = new Map();
     const key = (provider, model) => `${provider}\0${model}`;
     const registry = {
         register(model) {
-            byId.set(key(model.provider, model.model), model);
+            const id = key(model.provider, model.model);
+            assertCanRegister(byId, id, "model", `${model.provider}/${model.model}`, options.duplicate);
+            byId.set(id, model);
         },
         get(provider, model) {
             return byId.get(key(provider, model));

package/dist/node/agent-definitions.d.ts

@@ -0,0 +1,98 @@
+import type { Agent, AgentDefinitionResolutionContext, ContextProvider, DiscoveredContribution, ProviderResolver, ToolDefinition } from "../contracts.js";
+import type { PermissionPolicy, TrustPolicy } from "../security.js";
+/** Options for {@link resolveAgentBundle}. */
+export interface ResolveAgentBundleOptions {
+    /** File reader. Defaults to `node:fs/promises.readFile`. */
+    readonly readFile?: (path: string) => Promise<string>;
+    /** Workspace root for the repo-level project prompt (`AGENTS.md`) and repo contributions. */
+    readonly workspaceRoot?: string;
+    /** Repo-level contributions from {@link discoverContributions}. */
+    readonly repoContributions?: readonly DiscoveredContribution[];
+    /** Host registries (models, providers, context providers). */
+    readonly registries?: AgentDefinitionResolutionContext["registries"];
+    /** Provider resolver override. */
+    readonly providerSource?: ProviderResolver;
+    /** Tool scope override. */
+    readonly tools?: AgentDefinitionResolutionContext["tools"];
+    /** Skill registry override. */
+    readonly skillsRegistry?: AgentDefinitionResolutionContext["skillsRegistry"];
+    /** Migration-only: omitted `tools`/`skills` activate every in-scope tool/skill. Defaults to fail-closed. */
+    readonly activateAllCapabilities?: AgentDefinitionResolutionContext["activateAllCapabilities"];
+    /** Final config overrides applied after the bundle is resolved. */
+    readonly overrides?: AgentDefinitionResolutionContext["overrides"];
+    /** Trust policy gating the app-config root (`SYSTEM.md`) and workspace root (`AGENTS.md`) independently. */
+    readonly trust?: TrustPolicy;
+    /** Permission policy asserting each prompt-file read. */
+    readonly permission?: PermissionPolicy;
+    /** Scope inclusion flags. All sources default to `true`. */
+    readonly include?: AgentBundleScopeFlags;
+}
+/** Which scopes contribute to a {@link resolveAgentBundle} call. */
+export interface AgentBundleScopeFlags {
+    readonly systemPrompt?: boolean;
+    readonly agentPrompt?: boolean;
+    readonly repoPrompt?: boolean;
+    readonly globalSkills?: boolean;
+    readonly agentSkills?: boolean;
+    readonly repoSkills?: boolean;
+    readonly globalTools?: boolean;
+    readonly agentTools?: boolean;
+    readonly repoTools?: boolean;
+}
+/** Lightweight envelope describing an app-config agent bundle discovered on disk. */
+export interface AgentBundle {
+    /** Agent name (from the containing directory or AGENT.md frontmatter, validated later). */
+    readonly name: string;
+    /** Absolute path to the per-agent `AGENT.md` file. */
+    readonly path: string;
+    /** Root directory that was scanned. */
+    readonly configRoot: string;
+    /** Path to the app-global `SYSTEM.md` prompt, if present. */
+    readonly systemPromptPath?: string;
+    /** Paths to global skills under `<configRoot>/agents/skills/`. */
+    readonly globalSkills: readonly string[];
+    /** Paths to global tools under `<configRoot>/agents/tools/`. */
+    readonly globalTools: readonly string[];
+    /** Paths to agent-specific skills under `<agentDir>/skills/`. */
+    readonly agentSkills: readonly string[];
+    /** Paths to agent-specific tools under `<agentDir>/tools/`. */
+    readonly agentTools: readonly string[];
+}
+/** Options for {@link discoverAgentBundles}. */
+export interface DiscoverAgentBundlesOptions {
+    /** App configuration root. Scans `<configRoot>/agents/`. */
+    readonly configRoot: string;
+    readonly trust?: TrustPolicy;
+    readonly permission?: PermissionPolicy;
+    readonly signal?: AbortSignal;
+}
+/** Discover app-config agent bundles under `<configRoot>/agents/`.
+ *
+ *  Returns one {@link AgentBundle} per subdirectory containing an `AGENT.md` file.
+ *  Also collects paths to the app-global `SYSTEM.md`, global skills/tools, and
+ *  per-agent skills/tools. No file content is parsed here; resolution happens in
+ *  {@link resolveAgentBundle}. Trust/permission policies apply to `configRoot`
+ *  and its subdirectories; symlinks escaping `configRoot/agents` are excluded.
+ */
+export declare function discoverAgentBundles(options: DiscoverAgentBundlesOptions): Promise<readonly AgentBundle[]>;
+/** Resolve a discovered {@link AgentBundle} into a runnable {@link Agent}.
+ *
+ *  Builds union tool/skill registries across the included scopes (global,
+ *  agent-specific, and repo-level). Duplicate names across included scopes throw
+ *  rather than override. System prompts append in fixed order
+ *  `SYSTEM.md` → `AGENT.md` → `AGENTS.md` when enabled, before delegating to
+ *  {@link resolveAgentDefinition}. No `import()` is performed; descriptor-only
+ *  repo tools throw if executed.
+ *
+ *  The caller controls scope by which registries and flags it passes. Missing
+ *  dependencies fail closed at resolution time. Each prompt file is read at
+ *  most once per call; resolution is one-shot, so no cross-call cache is kept
+ *  (ponytail: add memoization only if a host resolves the same bundle repeatedly). */
+export declare function resolveAgentBundle(bundle: AgentBundle, options: ResolveAgentBundleOptions): Promise<Agent>;
+/** Parse a `CONTEXT.md` into a static {@link ContextProvider}. The markdown
+ *  body becomes the context block content; frontmatter `name` overrides the
+ *  directory name. */
+export declare function parseContextFile(text: string, path: string): ContextProvider;
+/** Parse a `TOOL.md` into a descriptor-only {@link ToolDefinition}. The
+ *  executable behavior is host-owned; calling `execute` throws. */
+export declare function parseToolFile(text: string, path: string): ToolDefinition;

package/dist/node/agent-definitions.js

@@ -0,0 +1,389 @@
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { readdir, stat } from "node:fs/promises";
+import { parseSkillFile, splitFrontmatter } from "../contribution-parsing.js";
+import { resolveAgentDefinition } from "../agent-definitions.js";
+import { assertPermission, isTrusted } from "../security.js";
+import { isPathInsideReal } from "./trust.js";
+import { readOptionalFile } from "./contribution-discovery.js";
+import { createSkillRegistry } from "../skills.js";
+const defaultInclude = {
+    systemPrompt: true,
+    agentPrompt: true,
+    repoPrompt: true,
+    globalSkills: true,
+    agentSkills: true,
+    repoSkills: true,
+    globalTools: true,
+    agentTools: true,
+    repoTools: true,
+};
+/** Discover app-config agent bundles under `<configRoot>/agents/`.
+ *
+ *  Returns one {@link AgentBundle} per subdirectory containing an `AGENT.md` file.
+ *  Also collects paths to the app-global `SYSTEM.md`, global skills/tools, and
+ *  per-agent skills/tools. No file content is parsed here; resolution happens in
+ *  {@link resolveAgentBundle}. Trust/permission policies apply to `configRoot`
+ *  and its subdirectories; symlinks escaping `configRoot/agents` are excluded.
+ */
+export async function discoverAgentBundles(options) {
+    const { configRoot, trust, permission, signal } = options;
+    if (signal?.aborted)
+        throw signal.reason;
+    if (trust) {
+        const decision = await trust.check({ kind: "project", target: configRoot });
+        if (!decision.trusted)
+            return [];
+    }
+    const agentsDir = join(configRoot, "agents");
+    const systemPromptPath = await findSystemPromptPath(agentsDir);
+    const globalSkills = await scanSkillPaths(join(agentsDir, "skills"), agentsDir, permission);
+    const globalTools = await scanToolPaths(join(agentsDir, "tools"), agentsDir, permission);
+    const bundles = [];
+    for (const name of await listSubdirs(agentsDir)) {
+        if (name === "skills" || name === "tools")
+            continue;
+        const agentDir = join(agentsDir, name);
+        const agentPath = join(agentDir, "AGENT.md");
+        if ((await readOptionalFile(agentPath)) === undefined)
+            continue;
+        await assertPermission(permission, { kind: "resource", action: "load", target: agentDir });
+        if (!(await isPathInsideReal(agentsDir, agentDir)))
+            continue;
+        const agentSkills = await scanSkillPaths(join(agentDir, "skills"), agentsDir, permission);
+        const agentTools = await scanToolPaths(join(agentDir, "tools"), agentsDir, permission);
+        bundles.push({
+            name,
+            path: agentPath,
+            configRoot,
+            systemPromptPath,
+            globalSkills,
+            globalTools,
+            agentSkills,
+            agentTools,
+        });
+    }
+    return bundles;
+}
+async function findSystemPromptPath(agentsDir) {
+    const path = join(agentsDir, "SYSTEM.md");
+    return (await readOptionalFile(path)) !== undefined ? path : undefined;
+}
+async function scanSkillPaths(dir, agentsDir, permission) {
+    const out = [];
+    for (const name of await listSubdirs(dir)) {
+        const path = join(dir, name, "SKILL.md");
+        if ((await readOptionalFile(path)) === undefined)
+            continue;
+        await assertPermission(permission, { kind: "resource", action: "load", target: join(dir, name) });
+        if (!(await isPathInsideReal(agentsDir, path)))
+            continue;
+        out.push(path);
+    }
+    return out;
+}
+async function scanToolPaths(dir, agentsDir, permission) {
+    const out = [];
+    for (const name of await listSubdirs(dir)) {
+        const path = join(dir, name, "manifest.json");
+        if ((await readOptionalFile(path)) === undefined)
+            continue;
+        await assertPermission(permission, { kind: "resource", action: "load", target: join(dir, name) });
+        if (!(await isPathInsideReal(agentsDir, path)))
+            continue;
+        out.push(path);
+    }
+    return out;
+}
+/** Resolve a discovered {@link AgentBundle} into a runnable {@link Agent}.
+ *
+ *  Builds union tool/skill registries across the included scopes (global,
+ *  agent-specific, and repo-level). Duplicate names across included scopes throw
+ *  rather than override. System prompts append in fixed order
+ *  `SYSTEM.md` → `AGENT.md` → `AGENTS.md` when enabled, before delegating to
+ *  {@link resolveAgentDefinition}. No `import()` is performed; descriptor-only
+ *  repo tools throw if executed.
+ *
+ *  The caller controls scope by which registries and flags it passes. Missing
+ *  dependencies fail closed at resolution time. Each prompt file is read at
+ *  most once per call; resolution is one-shot, so no cross-call cache is kept
+ *  (ponytail: add memoization only if a host resolves the same bundle repeatedly). */
+export async function resolveAgentBundle(bundle, options) {
+    const read = options.readFile ?? ((path) => readFile(path, "utf8"));
+    const text = await read(bundle.path);
+    const { front } = splitFrontmatter(text, bundle.path);
+    const include = { ...defaultInclude, ...(options.include ?? {}) };
+    const skillSources = await buildSkillSources(bundle, options, read, include);
+    const skills = unionSkills(skillSources);
+    const toolSources = buildToolSources(bundle, options, include);
+    const tools = unionTools(toolSources);
+    const systemPrompts = await buildSystemPrompts(bundle, options, read, text, include);
+    const rawName = String(front.get("name") ?? "").trim() || parentDirName(bundle.path);
+    if (!NAME_RE.test(rawName)) {
+        throw new Error(`Invalid agent name in ${bundle.path}: ${JSON.stringify(rawName)}`);
+    }
+    const def = {
+        name: rawName.replace(/\s+/g, "-"),
+        description: getString(front, "description"),
+        model: getString(front, "model"),
+        tools: getStringList(front, "tools"),
+        skills: getStringList(front, "skills"),
+        context: getStringList(front, "context"),
+        instructions: getString(front, "instructions"),
+        ...(systemPrompts.length > 0 ? { systemPrompt: systemPrompts } : {}),
+        metadata: collectMetadata(front),
+    };
+    // ponytail: SKILL.md context names are resolved against the host context-provider registry.
+    resolveSkillContexts(skills, options.registries?.contextProviders);
+    return resolveAgentDefinition(def, {
+        registries: options.registries,
+        providerSource: options.providerSource,
+        tools: tools.length > 0 ? tools : options.tools,
+        skillsRegistry: skills.length > 0 ? createSkillRegistry(skills) : options.skillsRegistry,
+        activateAllCapabilities: options.activateAllCapabilities,
+        overrides: options.overrides,
+    });
+}
+async function buildSkillSources(bundle, options, read, include) {
+    const out = [];
+    if (include.globalSkills) {
+        out.push({ scope: "global", skills: await parseSkillPaths(bundle.globalSkills, read) });
+    }
+    if (include.agentSkills) {
+        out.push({ scope: "agent", skills: await parseSkillPaths(bundle.agentSkills, read) });
+    }
+    if (include.repoSkills && options.repoContributions) {
+        const skills = options.repoContributions
+            .filter((c) => c.kind === "skill" && c.skill !== undefined)
+            .map((c) => c.skill);
+        out.push({ scope: "repo", skills });
+    }
+    return out;
+}
+function buildToolSources(bundle, options, include) {
+    const out = [];
+    if (include.globalTools) {
+        out.push({ scope: "global", tools: bundle.globalTools.map((path) => toolDescriptorFromPath(path)) });
+    }
+    if (include.agentTools) {
+        out.push({ scope: "agent", tools: bundle.agentTools.map((path) => toolDescriptorFromPath(path)) });
+    }
+    if (include.repoTools && options.repoContributions) {
+        const tools = options.repoContributions
+            .filter((c) => c.kind === "tool" && c.declaration !== undefined)
+            .map((c) => toolDescriptorFromDeclaration(c.declaration));
+        out.push({ scope: "repo", tools });
+    }
+    return out;
+}
+async function buildSystemPrompts(bundle, options, read, agentText, include) {
+    const out = [];
+    if (include.systemPrompt && bundle.systemPromptPath) {
+        // ponytail: trust-gate the app-config root independently from the workspace root. SYSTEM.md is
+        // app-supplied, so an untrusted configRoot contributes nothing (fail-closed, no throw).
+        if (await isTrusted(options.trust, { kind: "project", target: bundle.systemPromptPath })) {
+            await assertPermission(options.permission, { kind: "resource", action: "load", target: bundle.systemPromptPath });
+            const text = await readOptional(read, bundle.systemPromptPath);
+            if (text !== undefined) {
+                out.push({
+                    id: "agent-system",
+                    source: "user",
+                    mode: "append",
+                    text,
+                });
+            }
+        }
+    }
+    if (include.agentPrompt) {
+        const text = bodyAsInstructions(agentText, bundle.path);
+        if (text) {
+            out.push({
+                id: "agent-prompt",
+                source: "package",
+                mode: "append",
+                text,
+            });
+        }
+    }
+    if (include.repoPrompt && options.workspaceRoot) {
+        const repoPath = join(options.workspaceRoot, "AGENTS.md");
+        // ponytail: trust-gate the workspace root independently; untrusted AGENTS.md is skipped silently.
+        if (await isTrusted(options.trust, { kind: "project", target: repoPath })) {
+            await assertPermission(options.permission, { kind: "resource", action: "load", target: repoPath });
+            const text = await readOptional(read, repoPath);
+            if (text !== undefined) {
+                out.push({
+                    id: "repo-project-prompt",
+                    source: "app",
+                    mode: "append",
+                    text,
+                });
+            }
+        }
+    }
+    return out;
+}
+async function parseSkillPaths(paths, read) {
+    const out = [];
+    for (const path of paths) {
+        const text = await read(path);
+        out.push(parseSkillFile(text, path));
+    }
+    return out;
+}
+function unionSkills(sources) {
+    const seen = new Map();
+    const out = [];
+    for (const { scope, skills } of sources) {
+        for (const skill of skills) {
+            if (seen.has(skill.name)) {
+                throw new Error(`Duplicate skill name across scopes: ${skill.name} (found in ${scope} and ${seen.get(skill.name)})`);
+            }
+            seen.set(skill.name, scope);
+            out.push(skill);
+        }
+    }
+    return out;
+}
+function unionTools(sources) {
+    const seen = new Map();
+    const out = [];
+    for (const { scope, tools } of sources) {
+        for (const tool of tools) {
+            if (seen.has(tool.name)) {
+                throw new Error(`Duplicate tool name across scopes: ${tool.name} (found in ${scope} and ${seen.get(tool.name)})`);
+            }
+            seen.set(tool.name, scope);
+            out.push(tool);
+        }
+    }
+    return out;
+}
+function toolDescriptorFromPath(path) {
+    const name = parentDirName(path);
+    return toolDescriptor(name);
+}
+function toolDescriptorFromDeclaration(declaration) {
+    return toolDescriptor(declaration.name);
+}
+function toolDescriptor(name) {
+    return {
+        name,
+        execute: () => {
+            throw new Error(`Discovered tool ${name} requires host execution`);
+        },
+    };
+}
+function resolveSkillContexts(skills, contextProviders) {
+    if (!contextProviders)
+        return;
+    for (const skill of skills) {
+        const names = skill.metadata?.context;
+        if (!Array.isArray(names))
+            continue;
+        skill.context = names.map((name) => contextProviders.resolve(String(name)));
+    }
+}
+function collectMetadata(front) {
+    const metadata = {};
+    for (const [key, value] of front) {
+        if (key !== "name" && key !== "description" && key !== "model" && key !== "tools" && key !== "skills" && key !== "context" && key !== "instructions") {
+            metadata[key] = value;
+        }
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+function getString(front, key) {
+    const value = front.get(key);
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+function getStringList(front, key) {
+    const value = front.get(key);
+    if (Array.isArray(value))
+        return value.map(String);
+    if (typeof value === "string")
+        return value.split(",").map((s) => s.trim()).filter(Boolean);
+    return undefined;
+}
+function bodyAsInstructions(text, path) {
+    const { body } = splitFrontmatter(text, path);
+    const trimmed = body.replace(/^\n+/, "").trimEnd();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+async function listSubdirs(dir) {
+    try {
+        const entries = await readdir(dir);
+        const out = [];
+        for (const entry of entries) {
+            const path = join(dir, entry);
+            try {
+                if ((await stat(path)).isDirectory())
+                    out.push(entry);
+            }
+            catch {
+                // ignore stat errors for individual entries
+            }
+        }
+        return out;
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return [];
+        throw error;
+    }
+}
+async function readOptional(read, path) {
+    try {
+        return await read(path);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+const NAME_RE = /^[A-Za-z0-9 _-]+$/;
+function parentDirName(path) {
+    const parts = path.split(/[/\\]+/).filter(Boolean);
+    return parts.length >= 2 ? parts[parts.length - 2] : parts[parts.length - 1] ?? "";
+}
+/** Parse a `CONTEXT.md` into a static {@link ContextProvider}. The markdown
+ *  body becomes the context block content; frontmatter `name` overrides the
+ *  directory name. */
+export function parseContextFile(text, path) {
+    const { front, body } = splitFrontmatter(text, path);
+    const rawName = String(front.get("name") ?? "").trim() || parentDirName(path);
+    if (!NAME_RE.test(rawName)) {
+        throw new Error(`Invalid context provider name in ${path}: ${JSON.stringify(rawName)}`);
+    }
+    const name = rawName.replace(/\s+/g, "-");
+    const title = String(front.get("title") ?? name);
+    return {
+        name,
+        resolve: () => [{ title, content: body.replace(/^\n+/, "").trimEnd() }],
+    };
+}
+/** Parse a `TOOL.md` into a descriptor-only {@link ToolDefinition}. The
+ *  executable behavior is host-owned; calling `execute` throws. */
+export function parseToolFile(text, path) {
+    const { front, body } = splitFrontmatter(text, path);
+    const rawName = String(front.get("name") ?? "").trim() || parentDirName(path);
+    if (!NAME_RE.test(rawName)) {
+        throw new Error(`Invalid tool name in ${path}: ${JSON.stringify(rawName)}`);
+    }
+    const name = rawName.replace(/\s+/g, "-");
+    const description = String(front.get("description") ?? "").trim() || body.replace(/^\n+/, "").slice(0, 80).trim();
+    return {
+        name,
+        ...(description ? { description } : {}),
+        execute: () => {
+            throw new Error(`Discovered tool ${name} requires host execution`);
+        },
+    };
+}
+//# sourceMappingURL=agent-definitions.js.map

package/dist/node/contribution-discovery.d.ts

@@ -0,0 +1,17 @@
+import type { ContributionFileKind, DiscoveredContribution } from "../contracts.js";
+import type { PermissionPolicy } from "../security.js";
+import type { TrustPolicy } from "../security.js";
+export interface DiscoveryOptions {
+    readonly kinds: readonly ContributionFileKind[];
+    /** Workspace root. Scans `<root>/.agents/<kind>s/<name>/`. Gated by `trust`. */
+    readonly workspaceRoot?: string;
+    readonly permission?: PermissionPolicy;
+    readonly trust?: TrustPolicy;
+}
+/**
+ * Discover contributions on disk. Scans the workspace `.agents/` tree only;
+ * no global root. One `readdir` per kind-root; no `import()`. Inert output —
+ * executable behavior is host-owned.
+ */
+export declare function discoverContributions(options: DiscoveryOptions): Promise<readonly DiscoveredContribution[]>;
+export declare function readOptionalFile(path: string): Promise<string | undefined>;