veryfront 0.1.758 → 0.1.761

package/esm/src/discovery/agent-scoped-capabilities.js

@@ -0,0 +1,228 @@
+/**
+ * Per-agent colocated capability registration.
+ *
+ * Directory-layout agents (`agents/{id}/`) may ship their own tools and
+ * skills:
+ * - Tools: `agents/{id}/tools/*.ts` → registered into the global tool
+ *   registry under `{agentId}--{shortName}` with `ownerAgentId` metadata.
+ * - Skills: `agents/{id}/SKILL.md` (the agent's own skill, registered under
+ *   the agent id) and `agents/{id}/skills/<sub>/SKILL.md` (registered under
+ *   `{agentId}--{sub}`), both with `ownerAgentId` metadata.
+ *
+ * Discovery here is PURE REGISTRATION: no binding decisions. Visibility and
+ * selector resolution (`skills:` / `tools:`, `true` or lists, own short names
+ * first) happen at invocation time through the owner-aware resolvers, so flat
+ * and directory agents share identical binding semantics.
+ *
+ * The namespace separator is `--` (decided platform-wide): provider-safe and
+ * never confusable with `<provider>__<tool>` integration tool naming.
+ */
+import { toolRegistry } from "../tool/index.js";
+import { parseSkillFrontmatter, validateSkillMetadata } from "../skill/parser.js";
+import { getSkill, registerSkill } from "../skill/registry.js";
+import { SKILL_MD_FILENAME } from "../skill/types.js";
+import { registerTool } from "../mcp/index.js";
+import { ensureError } from "../errors/veryfront-error.js";
+import { filenameToId } from "./discovery-utils.js";
+import { discoveryFileExists, findTypeScriptFiles, listDiscoveryDirectoryEntries, readDiscoveryTextFile, } from "./file-discovery.js";
+import { importModule } from "./transpiler.js";
+const AGENT_TOOLS_SUBDIR = "tools";
+const AGENT_SKILLS_SUBDIR = "skills";
+/** Separator between the agent namespace and the capability short name. */
+export const AGENT_CAPABILITY_NAMESPACE_SEPARATOR = "--";
+/** Provider tool-call names allow only this charset, max 64 chars. */
+const PROVIDER_TOOL_NAME_REGEX = /^[A-Za-z0-9_-]{1,64}$/;
+/** Whether a namespaced tool name is valid for provider tool calls. */
+export function isProviderSafeToolName(name) {
+    return PROVIDER_TOOL_NAME_REGEX.test(name);
+}
+const SAFE_PATH_SEGMENT_REGEX = /^[A-Za-z0-9._-]+$/;
+/**
+ * Whether a directory/file entry name is a safe single path segment — used
+ * before joining it into a filesystem path. Rejects `.` and `..` (which match
+ * the permissive name regex) as defense-in-depth against path traversal.
+ */
+export function isSafePathSegment(name) {
+    return name !== "." && name !== ".." && SAFE_PATH_SEGMENT_REGEX.test(name);
+}
+/** Sanitizes an agent id into a provider-safe namespace segment. */
+export function sanitizeCapabilityNamespace(agentId) {
+    return agentId.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/** Namespaces a capability short name under its owning agent. */
+export function namespaceAgentCapability(agentId, shortName) {
+    return `${sanitizeCapabilityNamespace(agentId)}${AGENT_CAPABILITY_NAMESPACE_SEPARATOR}${shortName}`;
+}
+function isTool(value) {
+    return value !== null && typeof value === "object" &&
+        typeof value.execute === "function";
+}
+function hasExplicitToolId(tool) {
+    const generated = tool.__veryfrontGeneratedId;
+    if (typeof tool.id !== "string" || tool.id.trim().length === 0) {
+        return false;
+    }
+    return generated === undefined || tool.id !== generated;
+}
+function toolShortName(tool, file) {
+    return hasExplicitToolId(tool) ? tool.id : filenameToId(file);
+}
+function collectModuleTools(module, file) {
+    const tools = new Map();
+    const record = module;
+    for (const value of Object.values(record ?? {})) {
+        if (isTool(value)) {
+            tools.set(toolShortName(value, file), value);
+        }
+    }
+    return tools;
+}
+function reportShadowedGlobalCapability(input) {
+    const global = input.kind === "tool"
+        ? toolRegistry.get(input.shortName)
+        : getSkill(input.shortName);
+    if (global && global.ownerAgentId === undefined) {
+        input.result?.errors.push({
+            file: input.file,
+            error: ensureError(`Colocated ${input.kind} "${input.shortName}" of agent "${input.agentId}" shadows the ` +
+                `global ${input.kind} id "${input.shortName}": the agent's selector resolves its own ` +
+                `${input.kind} first. Rename one to make the reference unambiguous.`),
+        });
+    }
+}
+/**
+ * Registers an agent's colocated `tools/*.ts` into the global tool registry
+ * under `{agentId}--{shortName}` with owner metadata. Returns registered ids.
+ */
+export async function registerAgentColocatedTools(input) {
+    const toolsDir = `${input.rootPath}/${AGENT_TOOLS_SUBDIR}`;
+    if (!(await discoveryFileExists(toolsDir, input.context))) {
+        return [];
+    }
+    const files = (await findTypeScriptFiles(toolsDir, input.context)).sort((left, right) => left.localeCompare(right));
+    const registeredIds = [];
+    const seenThisPass = new Set();
+    for (const file of files) {
+        try {
+            const module = await importModule(file, input.context);
+            for (const [shortName, moduleTool] of collectModuleTools(module, file)) {
+                const namespaced = namespaceAgentCapability(input.agentId, shortName);
+                if (!isProviderSafeToolName(namespaced)) {
+                    input.result?.errors.push({
+                        file,
+                        error: ensureError(`Colocated tool "${shortName}" for agent "${input.agentId}" produces an ` +
+                            `invalid tool name "${namespaced}" (must match [A-Za-z0-9_-], max 64 chars).`),
+                    });
+                    continue;
+                }
+                // Two colocated tools resolving to the same short name within one
+                // discovery pass is a user error — report it instead of silently
+                // keeping the first (a later "unknown tool" with no breadcrumb).
+                // A pre-existing registry entry from a previous pass is a normal
+                // re-discovery refresh and is overwritten.
+                if (seenThisPass.has(namespaced)) {
+                    input.result?.errors.push({
+                        file,
+                        error: ensureError(`Duplicate colocated tool "${shortName}" for agent "${input.agentId}": ` +
+                            `another tools/ module already registered "${namespaced}"; keeping the first.`),
+                    });
+                    continue;
+                }
+                seenThisPass.add(namespaced);
+                reportShadowedGlobalCapability({
+                    kind: "tool",
+                    agentId: input.agentId,
+                    shortName,
+                    file,
+                    result: input.result,
+                });
+                registerTool(namespaced, {
+                    ...moduleTool,
+                    id: namespaced,
+                    ownerAgentId: input.agentId,
+                    shortName,
+                });
+                registeredIds.push(namespaced);
+            }
+        }
+        catch (error) {
+            input.result?.errors.push({ file, error: ensureError(error) });
+        }
+    }
+    return registeredIds;
+}
+async function buildSkillFromDir(input) {
+    const skillMdPath = `${input.skillDir}/${SKILL_MD_FILENAME}`;
+    if (!(await discoveryFileExists(skillMdPath, input.context))) {
+        return null;
+    }
+    const content = await readDiscoveryTextFile(skillMdPath, input.context);
+    const parsed = await parseSkillFrontmatter(content);
+    const metadata = validateSkillMetadata(parsed.frontmatter, input.id);
+    return {
+        id: input.id,
+        metadata,
+        rootPath: input.skillDir.replace(/^file:\/\//, ""),
+        ownerAgentId: input.ownerAgentId,
+        shortName: input.shortName,
+        ...(input.context.fsAdapter ? { fsAdapter: input.context.fsAdapter } : {}),
+    };
+}
+/**
+ * Registers an agent's colocated skills into the skill registry with owner
+ * metadata. The agent's own `SKILL.md` registers under the agent id; nested
+ * `skills/<sub>/SKILL.md` skills register under `{agentId}--{sub}`. Returns
+ * registered ids.
+ */
+export async function registerAgentColocatedSkills(input) {
+    const candidates = [];
+    if (await discoveryFileExists(`${input.rootPath}/${SKILL_MD_FILENAME}`, input.context)) {
+        candidates.push({ id: input.agentId, shortName: input.agentId, skillDir: input.rootPath });
+    }
+    const skillsDir = `${input.rootPath}/${AGENT_SKILLS_SUBDIR}`;
+    const entries = (await listDiscoveryDirectoryEntries(skillsDir, input.context)).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (!entry.isDirectory || !isSafePathSegment(entry.name)) {
+            continue;
+        }
+        candidates.push({
+            id: namespaceAgentCapability(input.agentId, entry.name),
+            shortName: entry.name,
+            skillDir: `${skillsDir}/${entry.name}`,
+        });
+    }
+    const registeredIds = [];
+    for (const candidate of candidates) {
+        try {
+            const skill = await buildSkillFromDir({
+                id: candidate.id,
+                skillDir: candidate.skillDir,
+                ownerAgentId: input.agentId,
+                shortName: candidate.shortName,
+                context: input.context,
+            });
+            if (!skill) {
+                continue;
+            }
+            if (candidate.shortName !== input.agentId) {
+                reportShadowedGlobalCapability({
+                    kind: "skill",
+                    agentId: input.agentId,
+                    shortName: candidate.shortName,
+                    file: `${candidate.skillDir}/${SKILL_MD_FILENAME}`,
+                    result: input.result,
+                });
+            }
+            registerSkill(skill.id, skill);
+            input.result?.skills.set(skill.id, skill);
+            registeredIds.push(skill.id);
+        }
+        catch (error) {
+            input.result?.errors.push({
+                file: `${candidate.skillDir}/${SKILL_MD_FILENAME}`,
+                error: ensureError(error),
+            });
+        }
+    }
+    return registeredIds;
+}

package/esm/src/discovery/discovery-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-engine.d.ts","sourceRoot":"","sources":["../../../src/src/discovery/discovery-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAEhB,MAAM,YAAY,CAAC;AAsIpB;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA2EnF"}
+{"version":3,"file":"discovery-engine.d.ts","sourceRoot":"","sources":["../../../src/src/discovery/discovery-engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAEhB,MAAM,YAAY,CAAC;AAsIpB;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA+EnF"}

package/esm/src/discovery/discovery-engine.js

@@ -120,6 +120,25 @@ export async function discoverAll(config) {
     for (const dir of config.toolDirs ?? ["tools"]) {
         await discoverItems(`${baseDir}/${dir}`, result, context, toolHandler, config.verbose);
     }
+    // Clear stale skills before any skill registration so deleted/renamed
+    // skills are removed. Global skills are discovered BEFORE agents so that
+    // directory-agent colocated skills (registered during agent discovery)
+    // survive the clear and owned-short-name shadow diagnostics can see the
+    // global ids they shadow.
+    skillRegistry.clear();
+    // Discover skills (parallel path — markdown-based, not TypeScript import)
+    for (const dir of config.skillDirs ?? ["skills"]) {
+        const skillResult = await discoverSkills(join(baseDir, dir), context, config.verbose);
+        for (const [id, skill] of skillResult.skills) {
+            if (result.skills.has(id)) {
+                logger.warn(`Duplicate skill "${id}" across discovery roots; keeping first registration`);
+                continue;
+            }
+            registerSkill(id, skill);
+            result.skills.set(id, skill);
+        }
+        result.errors.push(...skillResult.errors.map((e) => ({ file: e.file, error: e.error })));
+    }
     // Discover agents
     for (const dir of config.agentDirs ?? ["agents"]) {
         await discoverItems(`${baseDir}/${dir}`, result, context, agentHandler, config.verbose);
@@ -141,20 +160,5 @@ export async function discoverAll(config) {
     for (const dir of config.taskDirs ?? ["tasks"]) {
         await discoverItems(`${baseDir}/${dir}`, result, context, taskHandler, config.verbose);
     }
-    // Clear stale skills before rediscovery so deleted/renamed skills are removed.
-    skillRegistry.clear();
-    // Discover skills (parallel path — markdown-based, not TypeScript import)
-    for (const dir of config.skillDirs ?? ["skills"]) {
-        const skillResult = await discoverSkills(join(baseDir, dir), context, config.verbose);
-        for (const [id, skill] of skillResult.skills) {
-            if (result.skills.has(id)) {
-                logger.warn(`Duplicate skill "${id}" across discovery roots; keeping first registration`);
-                continue;
-            }
-            registerSkill(id, skill);
-            result.skills.set(id, skill);
-        }
-        result.errors.push(...skillResult.errors.map((e) => ({ file: e.file, error: e.error })));
-    }
     return result;
 }

package/esm/src/discovery/file-discovery.d.ts

@@ -13,4 +13,14 @@ export declare function findTypeScriptFiles(dir: string, context: FileDiscoveryC
  */
 export declare function findMarkdownFiles(dir: string, context: FileDiscoveryContext): Promise<string[]>;
 export declare function readDiscoveryTextFile(fileUrl: string, context: FileDiscoveryContext): Promise<string>;
+/** A single top-level entry inside a discovery directory. */
+export type DiscoveryDirectoryEntry = {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+};
+/** Lists the immediate (non-recursive) entries of a discovery directory. */
+export declare function listDiscoveryDirectoryEntries(dir: string, context: FileDiscoveryContext): Promise<DiscoveryDirectoryEntry[]>;
+/** Returns true when a discovery file exists (fsAdapter-aware). */
+export declare function discoveryFileExists(path: string, context: FileDiscoveryContext): Promise<boolean>;
 //# sourceMappingURL=file-discovery.d.ts.map

package/esm/src/discovery/file-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-discovery.d.ts","sourceRoot":"","sources":["../../../src/src/discovery/file-discovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAsEvD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CASjB"}
+{"version":3,"file":"file-discovery.d.ts","sourceRoot":"","sources":["../../../src/src/discovery/file-discovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAsEvD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,6DAA6D;AAC7D,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,4EAA4E;AAC5E,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAkCpC;AAED,mEAAmE;AACnE,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/esm/src/discovery/file-discovery.js

@@ -76,3 +76,49 @@ export async function readDiscoveryTextFile(fileUrl, context) {
     const { fs } = await getNodeDeps(context);
     return fs.readFileSync(path, "utf-8");
 }
+/** Lists the immediate (non-recursive) entries of a discovery directory. */
+export async function listDiscoveryDirectoryEntries(dir, context) {
+    const entries = [];
+    try {
+        if (context.fsAdapter) {
+            if (!(await context.fsAdapter.exists(dir)))
+                return entries;
+            for await (const entry of context.fsAdapter.readDir(dir)) {
+                entries.push({
+                    name: entry.name,
+                    isFile: entry.isFile,
+                    isDirectory: entry.isDirectory,
+                });
+            }
+            return entries;
+        }
+        const { fs } = await getNodeDeps(context);
+        if (!fs.existsSync(dir))
+            return entries;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            entries.push({
+                name: entry.name,
+                isFile: entry.isFile(),
+                isDirectory: entry.isDirectory(),
+            });
+        }
+    }
+    catch (_) {
+        /* expected: directory may not exist or be unreadable */
+        return entries;
+    }
+    return entries;
+}
+/** Returns true when a discovery file exists (fsAdapter-aware). */
+export async function discoveryFileExists(path, context) {
+    try {
+        if (context.fsAdapter) {
+            return await context.fsAdapter.exists(path);
+        }
+        const { fs } = await getNodeDeps(context);
+        return fs.existsSync(path);
+    }
+    catch (_) {
+        return false;
+    }
+}

package/esm/src/discovery/handlers/runtime-agent-markdown-handler.d.ts

@@ -1,3 +1,15 @@
 import type { DiscoveryResult, FileDiscoveryContext } from "../types.js";
+/**
+ * Discovers markdown agents from a directory.
+ *
+ * Supports two layouts side by side:
+ * - Flat: `agents/{id}.md`
+ * - Directory: `agents/{id}/AGENT.md` (+ colocated `SKILL.md` / `skills/` /
+ *   `tools/`, registered with owner metadata)
+ *
+ * Binding is NOT decided here: both layouts pass their parsed definition to
+ * the same adapter, and the owner-aware resolvers apply one rule for every
+ * agent kind at invocation time.
+ */
 export declare function discoverRuntimeAgentMarkdownDefinitions(dir: string, result: DiscoveryResult, context: FileDiscoveryContext): Promise<void>;
 //# sourceMappingURL=runtime-agent-markdown-handler.d.ts.map

package/esm/src/discovery/handlers/runtime-agent-markdown-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-agent-markdown-handler.d.ts","sourceRoot":"","sources":["../../../../src/src/discovery/handlers/runtime-agent-markdown-handler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AA6CzE,wBAAsB,uCAAuC,CAC3D,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAqBf"}
+{"version":3,"file":"runtime-agent-markdown-handler.d.ts","sourceRoot":"","sources":["../../../../src/src/discovery/handlers/runtime-agent-markdown-handler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAkKzE;;;;;;;;;;;GAWG;AACH,wBAAsB,uCAAuC,CAC3D,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/esm/src/discovery/handlers/runtime-agent-markdown-handler.js

@@ -3,25 +3,82 @@ import { parseRuntimeAgentMarkdownDefinition, } from "../../agent/runtime/agent-
 import { agentRegistry, registerAgent } from "../../agent/composition/index.js";
 import { ensureError } from "../../errors/veryfront-error.js";
 import { trackAgentPath } from "../discovery-utils.js";
-import { findMarkdownFiles, readDiscoveryTextFile } from "../file-discovery.js";
+import { discoveryFileExists, listDiscoveryDirectoryEntries, readDiscoveryTextFile, } from "../file-discovery.js";
+import { isSafePathSegment, registerAgentColocatedSkills, registerAgentColocatedTools, sanitizeCapabilityNamespace, } from "../agent-scoped-capabilities.js";
 const MARKDOWN_AGENT_FILE_PATTERN = /^[A-Za-z0-9._-]+\.md$/;
-function getFileName(file) {
-    return file.split("/").pop() ?? "";
-}
-function getMarkdownAgentCandidate(file) {
-    const fileName = getFileName(file);
+const DIRECTORY_AGENT_FILENAME = "AGENT.md";
+const RESERVED_TOP_LEVEL_FILENAMES = new Set(["AGENT.md", "SKILL.md"]);
+function getFlatAgentCandidate(dir, fileName) {
+    if (RESERVED_TOP_LEVEL_FILENAMES.has(fileName)) {
+        return null;
+    }
     if (!MARKDOWN_AGENT_FILE_PATTERN.test(fileName)) {
         return null;
     }
+    const id = fileName.slice(0, -".md".length);
+    // Reject `.`/`..` ids as defense-in-depth against path traversal.
+    if (!isSafePathSegment(id)) {
+        return null;
+    }
     return {
-        id: fileName.slice(0, -".md".length),
-        file,
+        id,
+        file: `${dir}/${fileName}`,
     };
 }
-function registerMarkdownAgent(definition, file, result) {
+async function getDirectoryAgentCandidate(dir, entryName, context) {
+    // Reject `.`/`..` and other non-segment names before joining into a path.
+    if (!isSafePathSegment(entryName)) {
+        return null;
+    }
+    const rootPath = `${dir}/${entryName}`;
+    const agentFile = `${rootPath}/${DIRECTORY_AGENT_FILENAME}`;
+    if (!(await discoveryFileExists(agentFile, context))) {
+        return null;
+    }
+    return { id: entryName, file: agentFile, rootPath };
+}
+/**
+ * Registers a directory agent's colocated capabilities. This is PURE
+ * REGISTRATION — binding (`skills:` / `tools:` selectors) happens at
+ * invocation time via the owner-aware resolvers, identically for flat and
+ * directory agents.
+ *
+ * Two distinct agent ids can sanitize to the same provider-safe namespace
+ * (e.g. "a.b" and "a_b" -> "a_b"), which would collide owned capability ids;
+ * detected and reported instead of silently overwriting.
+ */
+async function registerColocatedCapabilities(definition, rootPath, result, context, namespaceOwners) {
+    const namespace = sanitizeCapabilityNamespace(definition.id);
+    const existingOwner = namespaceOwners.get(namespace);
+    if (existingOwner !== undefined && existingOwner !== definition.id) {
+        result.errors.push({
+            file: rootPath,
+            error: ensureError(`Agent "${definition.id}" shares the sanitized capability namespace ` +
+                `"${namespace}" with agent "${existingOwner}". Rename one to avoid ` +
+                `colliding colocated tool/skill ids.`),
+        });
+        return;
+    }
+    namespaceOwners.set(namespace, definition.id);
+    // Skills and tools live in disjoint subtrees; register them concurrently.
+    await Promise.all([
+        registerAgentColocatedSkills({ agentId: definition.id, rootPath, context, result }),
+        registerAgentColocatedTools({ agentId: definition.id, rootPath, context, result }),
+    ]);
+}
+async function registerMarkdownAgent(definition, file, rootPath, result, context, namespaceOwners) {
     if (result.agents.has(definition.id)) {
+        result.errors.push({
+            file,
+            error: ensureError(`Duplicate agent id "${definition.id}". An agent with this id was already ` +
+                `discovered (e.g. both a flat "${definition.id}.md" and a "${definition.id}/" ` +
+                `directory exist); keeping the first.`),
+        });
         return;
     }
+    if (rootPath) {
+        await registerColocatedCapabilities(definition, rootPath, result, context, namespaceOwners);
+    }
     const runtimeAgent = createRuntimeAgentFromMarkdownDefinition(definition);
     if (runtimeAgent.id !== definition.id) {
         agentRegistry.delete(runtimeAgent.id);
@@ -30,22 +87,42 @@ function registerMarkdownAgent(definition, file, result) {
     trackAgentPath(definition.id, file);
     result.agents.set(definition.id, runtimeAgent);
 }
+async function discoverMarkdownAgentCandidate(candidate, result, context, namespaceOwners) {
+    try {
+        const definition = parseRuntimeAgentMarkdownDefinition({
+            id: candidate.id,
+            content: await readDiscoveryTextFile(candidate.file, context),
+        });
+        await registerMarkdownAgent(definition, candidate.file, candidate.rootPath, result, context, namespaceOwners);
+    }
+    catch (error) {
+        result.errors.push({ file: candidate.file, error: ensureError(error) });
+    }
+}
+/**
+ * Discovers markdown agents from a directory.
+ *
+ * Supports two layouts side by side:
+ * - Flat: `agents/{id}.md`
+ * - Directory: `agents/{id}/AGENT.md` (+ colocated `SKILL.md` / `skills/` /
+ *   `tools/`, registered with owner metadata)
+ *
+ * Binding is NOT decided here: both layouts pass their parsed definition to
+ * the same adapter, and the owner-aware resolvers apply one rule for every
+ * agent kind at invocation time.
+ */
 export async function discoverRuntimeAgentMarkdownDefinitions(dir, result, context) {
-    const files = (await findMarkdownFiles(dir, context)).sort((left, right) => left.localeCompare(right));
-    for (const file of files) {
-        const candidate = getMarkdownAgentCandidate(file);
+    const entries = (await listDiscoveryDirectoryEntries(dir, context)).sort((left, right) => left.name.localeCompare(right.name));
+    const namespaceOwners = new Map();
+    for (const entry of entries) {
+        const candidate = entry.isDirectory
+            ? await getDirectoryAgentCandidate(dir, entry.name, context)
+            : entry.isFile
+                ? getFlatAgentCandidate(dir, entry.name)
+                : null;
         if (!candidate) {
             continue;
         }
-        try {
-            const definition = parseRuntimeAgentMarkdownDefinition({
-                id: candidate.id,
-                content: await readDiscoveryTextFile(candidate.file, context),
-            });
-            registerMarkdownAgent(definition, candidate.file, result);
-        }
-        catch (error) {
-            result.errors.push({ file: candidate.file, error: ensureError(error) });
-        }
+        await discoverMarkdownAgentCandidate(candidate, result, context, namespaceOwners);
     }
 }

package/esm/src/errors/error-registry/agent.d.ts

@@ -4,6 +4,7 @@ export declare const AGENT_TIMEOUT: import("../types.js").RegisteredError;
 export declare const AGENT_INTENT_ERROR: import("../types.js").RegisteredError;
 export declare const ORCHESTRATION_ERROR: import("../types.js").RegisteredError;
 export declare const COST_LIMIT_EXCEEDED: import("../types.js").RegisteredError;
+export declare const TOOL_ID_CONFLICT: import("../types.js").RegisteredError;
 /** Registry fragment for AGENT errors (slug → definition). */
 export declare const AGENT_REGISTRY: {
     readonly "agent-error": import("../types.js").RegisteredError;
@@ -12,5 +13,6 @@ export declare const AGENT_REGISTRY: {
     readonly "agent-intent-error": import("../types.js").RegisteredError;
     readonly "orchestration-error": import("../types.js").RegisteredError;
     readonly "cost-limit-exceeded": import("../types.js").RegisteredError;
+    readonly "tool-id-conflict": import("../types.js").RegisteredError;
 };
 //# sourceMappingURL=agent.d.ts.map

package/esm/src/errors/error-registry/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../src/src/errors/error-registry/agent.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,uCAMtB,CAAC;AAEH,eAAO,MAAM,eAAe,uCAM1B,CAAC;AAEH,eAAO,MAAM,aAAa,uCAMxB,CAAC;AAEH,eAAO,MAAM,kBAAkB,uCAM7B,CAAC;AAEH,eAAO,MAAM,mBAAmB,uCAM9B,CAAC;AAEH,eAAO,MAAM,mBAAmB,uCAM9B,CAAC;AAEH,8DAA8D;AAC9D,eAAO,MAAM,cAAc;;;;;;;CAOjB,CAAC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../src/src/errors/error-registry/agent.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,uCAMtB,CAAC;AAEH,eAAO,MAAM,eAAe,uCAM1B,CAAC;AAEH,eAAO,MAAM,aAAa,uCAMxB,CAAC;AAEH,eAAO,MAAM,kBAAkB,uCAM7B,CAAC;AAEH,eAAO,MAAM,mBAAmB,uCAM9B,CAAC;AAEH,eAAO,MAAM,mBAAmB,uCAM9B,CAAC;AAEH,eAAO,MAAM,gBAAgB,uCAM3B,CAAC;AAEH,8DAA8D;AAC9D,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC"}

package/esm/src/errors/error-registry/agent.js

@@ -41,6 +41,13 @@ export const COST_LIMIT_EXCEEDED = defineError({
     title: "Cost limit exceeded",
     suggestion: "Wait for the budget period to reset or increase the limit",
 });
+export const TOOL_ID_CONFLICT = defineError({
+    slug: "tool-id-conflict",
+    category: "AGENT",
+    status: 409,
+    title: "Tool ID conflict",
+    suggestion: "Use a unique tool ID or rename one of the conflicting tools",
+});
 /** Registry fragment for AGENT errors (slug → definition). */
 export const AGENT_REGISTRY = {
     "agent-error": AGENT_ERROR,
@@ -49,4 +56,5 @@ export const AGENT_REGISTRY = {
     "agent-intent-error": AGENT_INTENT_ERROR,
     "orchestration-error": ORCHESTRATION_ERROR,
     "cost-limit-exceeded": COST_LIMIT_EXCEEDED,
+    "tool-id-conflict": TOOL_ID_CONFLICT,
 };

package/esm/src/errors/error-registry.d.ts

@@ -31,6 +31,7 @@ export declare const ERROR_REGISTRY: {
     readonly "agent-intent-error": import("./types.js").RegisteredError;
     readonly "orchestration-error": import("./types.js").RegisteredError;
     readonly "cost-limit-exceeded": import("./types.js").RegisteredError;
+    readonly "tool-id-conflict": import("./types.js").RegisteredError;
     readonly "deployment-error": import("./types.js").RegisteredError;
     readonly "platform-error": import("./types.js").RegisteredError;
     readonly "env-var-missing": import("./types.js").RegisteredError;

package/esm/src/errors/error-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../../../src/src/errors/error-registry.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAgBhD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYjB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,cAAc,CAAC;AAEpD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,wCAE7C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,0CAE1D;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,SAAS,EAAE,CAEzC"}
+{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../../../src/src/errors/error-registry.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAgBhD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYjB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,cAAc,CAAC;AAEpD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,wCAE7C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,0CAE1D;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,SAAS,EAAE,CAEzC"}

package/esm/src/extensions/errors.d.ts

@@ -11,4 +11,6 @@ export declare const EXTENSION_VALIDATION_ERROR: import("../errors/types.js").Re
 export declare const CIRCULAR_DEPENDENCY_ERROR: import("../errors/types.js").RegisteredError;
 /** Shared extension conflict error value. */
 export declare const EXTENSION_CONFLICT_ERROR: import("../errors/types.js").RegisteredError;
+/** Shared extension setup timeout error value. */
+export declare const EXTENSION_SETUP_TIMEOUT_ERROR: import("../errors/types.js").RegisteredError;
 //# sourceMappingURL=errors.d.ts.map

package/esm/src/extensions/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,8CAMlC,CAAC;AAEH,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,8CAMrC,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,8CAMpC,CAAC;AAEH,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,8CAMnC,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,8CAMlC,CAAC;AAEH,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,8CAMrC,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,8CAMpC,CAAC;AAEH,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,8CAMnC,CAAC;AAEH,kDAAkD;AAClD,eAAO,MAAM,6BAA6B,8CAOxC,CAAC"}

package/esm/src/extensions/errors.js

@@ -36,3 +36,11 @@ export const EXTENSION_CONFLICT_ERROR = defineError({
     title: "Conflicting extensions detected",
     suggestion: "Remove or disable one of the conflicting extensions in your configuration",
 });
+/** Shared extension setup timeout error value. */
+export const EXTENSION_SETUP_TIMEOUT_ERROR = defineError({
+    slug: "extension-setup-timeout",
+    category: "RUNTIME",
+    status: 500,
+    title: "Extension setup timed out",
+    suggestion: "Check the extension's setup() for blocking operations, or increase VF_EXTENSION_SETUP_TIMEOUT_MS",
+});

package/esm/src/extensions/loader.d.ts

@@ -1,9 +1,12 @@
-/**
- * Extension loader — topological sort, lifecycle management, preset flattening.
- *
- * @module extensions/loader
- */
 import type { ExtensionLogger, ResolvedExtension } from "./types.js";
+/** Options for {@link ExtensionLoader.setupAll}. */
+export interface SetupAllOptions {
+    /**
+     * Per-extension setup() timeout in milliseconds.
+     * Defaults to 30 000 ms. Pass `0` to disable.
+     */
+    setupTimeoutMs?: number;
+}
 /** Implement extension loader. */
 export declare class ExtensionLoader {
     private logger;
@@ -32,7 +35,7 @@ export declare class ExtensionLoader {
      * Run the full setup lifecycle for all extensions.
      * If called while extensions are already loaded, tears them down first.
      */
-    setupAll(extensions: ResolvedExtension[], projectConfig: Record<string, unknown>): Promise<void>;
+    setupAll(extensions: ResolvedExtension[], projectConfig: Record<string, unknown>, options?: SetupAllOptions): Promise<void>;
     /**
      * Teardown all loaded extensions in reverse order.
      */

package/esm/src/extensions/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAA+B,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAElG,kCAAkC;AAClC,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,MAAM,CAA+B;IAE7C;;;;OAIG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;gBAI5C,MAAM,EAAE,eAAe;IAInC;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE;IAIpE,OAAO,CAAC,mBAAmB;IA8B3B;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE;IAyErE;;;OAGG;IACG,QAAQ,CACZ,UAAU,EAAE,iBAAiB,EAAE,EAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC;IAuFhB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAmBnC"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/src/extensions/loader.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAA+B,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKlG,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,kCAAkC;AAClC,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,MAAM,CAA+B;IAE7C;;;;OAIG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;gBAI5C,MAAM,EAAE,eAAe;IAInC;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE;IAIpE,OAAO,CAAC,mBAAmB;IA8B3B;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE;IAyErE;;;OAGG;IACG,QAAQ,CACZ,UAAU,EAAE,iBAAiB,EAAE,EAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC;IAuHhB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAmBnC"}