eve 0.5.4 → 0.6.0-beta.3

package/dist/src/discover/filesystem.d.ts

@@ -0,0 +1,71 @@
+import type { Dirent } from "node:fs";
+/**
+ * Supported authored JavaScript and TypeScript module file extensions.
+ */
+export declare const SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS: readonly [".cts", ".mts", ".cjs", ".mjs", ".ts", ".js"];
+/**
+ * Files that mark a surrounding directory as an application root when paired
+ * with a top-level `agent/` directory.
+ */
+export declare const PROJECT_MARKER_FILE_NAMES: readonly ["package.json", "vercel.json"];
+/**
+ * Filesystem entry type used by discovery classifiers.
+ */
+export type DirectoryEntryType = "directory" | "file" | "other";
+/**
+ * Classified root-level agent entry.
+ */
+export type AgentRootEntryKind = "agent-config-module" | "channels-directory" | "connections-directory" | "hooks-directory" | "instructions-directory" | "instructions-markdown" | "instructions-module" | "lib-directory" | "sandbox-directory" | "schedules-directory" | "skills-directory" | "system-markdown" | "system-module" | "tools-directory" | "unknown" | "subagents-directory";
+/**
+ * Classified local-subagent root entry.
+ */
+export type LocalSubagentEntryKind = "agent-config-module" | "connections-directory" | "hooks-directory" | "instructions-directory" | "instructions-markdown" | "instructions-module" | "invalid-schedules-directory" | "lib-directory" | "sandbox-directory" | "skills-directory" | "system-markdown" | "system-module" | "tools-directory" | "unknown" | "subagents-directory";
+/**
+ * Classified Agent Skills package entry.
+ */
+export type SkillPackageEntryKind = "skill-assets-directory" | "skill-markdown" | "skill-references-directory" | "skill-resource" | "skill-scripts-directory";
+/**
+ * Classified top-level entry inside `skills/`.
+ */
+export type SkillsDirectoryEntryKind = "flat-skill-markdown" | "flat-skill-module" | "skill-package-directory" | "unknown";
+/**
+ * Returns the normalized entry type for a Node filesystem dirent.
+ */
+export declare function getDirectoryEntryType(entry: Pick<Dirent, "isDirectory" | "isFile">): DirectoryEntryType;
+/**
+ * Returns whether an entry marks a directory as an app root for nested agents.
+ */
+export declare function isProjectMarkerEntry(name: string, entryType: DirectoryEntryType): boolean;
+/**
+ * Classifies a top-level agent-root entry according to the spec-legal grammar.
+ */
+export declare function classifyAgentRootEntry(name: string, entryType: DirectoryEntryType): AgentRootEntryKind;
+/**
+ * Classifies a local-subagent package root entry according to the spec-legal grammar.
+ */
+export declare function classifyLocalSubagentEntry(name: string, entryType: DirectoryEntryType): LocalSubagentEntryKind;
+/**
+ * Classifies a file or directory inside an Agent Skills package.
+ */
+export declare function classifySkillPackageEntry(name: string, entryType: DirectoryEntryType): SkillPackageEntryKind;
+/**
+ * Classifies one top-level entry inside the authored `skills/` directory.
+ */
+export declare function classifySkillsDirectoryEntry(name: string, entryType: DirectoryEntryType): SkillsDirectoryEntryKind;
+/**
+ * Normalizes an agent-root-relative logical path to forward slashes.
+ */
+export declare function normalizeLogicalPath(input: string): string;
+/**
+ * Returns the authored module basename when the file uses a supported module
+ * extension.
+ */
+export declare function getSupportedModuleBaseName(name: string): string | null;
+/**
+ * Returns whether the file name matches one supported authored module basename.
+ */
+export declare function matchesSupportedModuleBaseName(name: string, baseName: string): boolean;
+/**
+ * Removes a final file extension from a logical path when present.
+ */
+export declare function stripLogicalPathExtension(input: string): string;

package/dist/src/discover/filesystem.js

@@ -0,0 +1 @@
+import{sep}from"node:path";const SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS=[`.cts`,`.mts`,`.cjs`,`.mjs`,`.ts`,`.js`],PROJECT_MARKER_FILE_NAMES=[`package.json`,`vercel.json`],PROJECT_MARKER_FILE_NAME_SET=new Set(PROJECT_MARKER_FILE_NAMES);function getDirectoryEntryType(e){return e.isDirectory()?`directory`:e.isFile()?`file`:`other`}function isProjectMarkerEntry(e,t){return t===`file`&&PROJECT_MARKER_FILE_NAME_SET.has(e)}function classifyAgentRootEntry(e,t){if(t===`file`)return matchesSupportedModuleBaseName(e,`agent`)?`agent-config-module`:e===`instructions.md`?`instructions-markdown`:matchesSupportedModuleBaseName(e,`instructions`)?`instructions-module`:e===`system.md`?`system-markdown`:matchesSupportedModuleBaseName(e,`system`)?`system-module`:`unknown`;if(t===`directory`){if(e===`channels`)return`channels-directory`;if(e===`connections`)return`connections-directory`;if(e===`hooks`)return`hooks-directory`;if(e===`instructions`)return`instructions-directory`;if(e===`lib`)return`lib-directory`;if(e===`skills`)return`skills-directory`;if(e===`sandbox`)return`sandbox-directory`;if(e===`tools`)return`tools-directory`;if(e===`schedules`)return`schedules-directory`;if(e===`subagents`)return`subagents-directory`}return`unknown`}function classifyLocalSubagentEntry(e,t){if(t===`file`)return matchesSupportedModuleBaseName(e,`agent`)?`agent-config-module`:e===`instructions.md`?`instructions-markdown`:matchesSupportedModuleBaseName(e,`instructions`)?`instructions-module`:e===`system.md`?`system-markdown`:matchesSupportedModuleBaseName(e,`system`)?`system-module`:`unknown`;if(t===`directory`){if(e===`connections`)return`connections-directory`;if(e===`hooks`)return`hooks-directory`;if(e===`instructions`)return`instructions-directory`;if(e===`lib`)return`lib-directory`;if(e===`sandbox`)return`sandbox-directory`;if(e===`skills`)return`skills-directory`;if(e===`tools`)return`tools-directory`;if(e===`subagents`)return`subagents-directory`;if(e===`schedules`)return`invalid-schedules-directory`}return`unknown`}function classifySkillPackageEntry(e,t){if(t===`file`)return e===`SKILL.md`?`skill-markdown`:`skill-resource`;if(t===`directory`){if(e===`scripts`)return`skill-scripts-directory`;if(e===`references`)return`skill-references-directory`;if(e===`assets`)return`skill-assets-directory`}return`skill-resource`}function classifySkillsDirectoryEntry(e,t){if(t===`directory`)return`skill-package-directory`;if(t===`file`){if(e.endsWith(`.md`))return`flat-skill-markdown`;if(getSupportedModuleBaseName(e)!==null)return`flat-skill-module`}return`unknown`}function normalizeLogicalPath(t){return t.replaceAll(sep,`/`).replace(/^\.\//,``).replace(/^\/+/,``)}function getSupportedModuleBaseName(e){for(let n of SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS)if(e.endsWith(n)&&e.length>n.length)return e.slice(0,-n.length);return null}function matchesSupportedModuleBaseName(e,t){return getSupportedModuleBaseName(e)===t}function stripLogicalPathExtension(e){let t=normalizeLogicalPath(e),n=t.lastIndexOf(`/`),r=t.lastIndexOf(`.`);return r===-1||r<n?t:t.slice(0,r)}export{PROJECT_MARKER_FILE_NAMES,SUPPORTED_AUTHORED_MODULE_FILE_EXTENSIONS,classifyAgentRootEntry,classifyLocalSubagentEntry,classifySkillPackageEntry,classifySkillsDirectoryEntry,getDirectoryEntryType,getSupportedModuleBaseName,isProjectMarkerEntry,matchesSupportedModuleBaseName,normalizeLogicalPath,stripLogicalPathExtension};

package/dist/src/discover/grammar.d.ts

@@ -0,0 +1,202 @@
+import type { Dirent } from "node:fs";
+import type { ModuleSourceRef } from "#shared/source-ref.js";
+import { type DiscoverDiagnostic } from "#discover/diagnostics.js";
+import { type DirectoryEntryType } from "#discover/filesystem.js";
+import { type InstructionsSourceRef } from "#discover/manifest.js";
+import type { ProjectSource, ProjectSourceEntry } from "#discover/project-source.js";
+/**
+ * Shared diagnostic emitted when a slot has multiple authored module sources.
+ */
+export declare const DISCOVER_MODULE_SLOT_COLLISION = "discover/module-slot-collision";
+/**
+ * Shared diagnostic emitted when the required instructions prompt source
+ * is missing.
+ */
+export declare const DISCOVER_REQUIRED_INSTRUCTIONS_MISSING = "discover/required-instructions-missing";
+/**
+ * Shared diagnostic emitted when discovery falls back to the deprecated
+ * `system.{md,ts,...}` slot because no `instructions.{md,ts,...}` source
+ * was found. The fallback resolves successfully; the warning prompts the
+ * author to rename the file.
+ */
+export declare const DISCOVER_DEPRECATED_SYSTEM_SLOT = "discover/deprecated-system-slot";
+/**
+ * Shared diagnostic emitted when a slot has both markdown and module sources.
+ */
+export declare const DISCOVER_SLOT_COLLISION = "discover/slot-collision";
+/**
+ * Shared diagnostic emitted when the authored `tools/` root is not a
+ * directory.
+ */
+export declare const DISCOVER_TOOLS_DIRECTORY_INVALID = "discover/tools-directory-invalid";
+/**
+ * Shared diagnostic emitted when the authored `hooks/` root is not a
+ * directory.
+ */
+export declare const DISCOVER_HOOKS_DIRECTORY_INVALID = "discover/hooks-directory-invalid";
+/**
+ * Shared diagnostic emitted when the authored `channels/` root is not a
+ * directory.
+ */
+export declare const DISCOVER_CHANNELS_DIRECTORY_INVALID = "discover/channels-directory-invalid";
+/**
+ * Shared diagnostic emitted when an authored `tools/*.{ts,…}` filename does
+ * not satisfy the model tool-name charset rule.
+ */
+export declare const DISCOVER_TOOL_NAME_INVALID = "discover/tool-name-invalid";
+/**
+ * Shared diagnostic emitted when an authored `connections/*.{ts,…}` filename
+ * does not satisfy the connection slug charset rule.
+ */
+export declare const DISCOVER_CONNECTION_NAME_INVALID = "discover/connection-name-invalid";
+/**
+ * Shared diagnostic emitted when the authored `sandbox/` root is not a
+ * directory. The diagnostic code string retains its plural suffix for
+ * stability across manifest versions.
+ */
+export declare const DISCOVER_SANDBOX_DIRECTORY_INVALID = "discover/sandbox-directory-invalid";
+/**
+ * Shared diagnostic emitted when the authored `instructions/` root is not a
+ * directory.
+ */
+export declare const DISCOVER_INSTRUCTIONS_DIRECTORY_INVALID = "discover/instructions-directory-invalid";
+/**
+ * Shared diagnostic emitted when an authored `channels/**` filename or
+ * directory segment does not satisfy the channel slug charset rule.
+ */
+export declare const DISCOVER_CHANNEL_NAME_INVALID = "discover/channel-name-invalid";
+/**
+ * Shared diagnostic emitted when an authored `hooks/**` filename or
+ * directory segment does not satisfy the hook slug charset rule.
+ */
+export declare const DISCOVER_HOOK_NAME_INVALID = "discover/hook-name-invalid";
+/**
+ * Tool filename charset. The slug must start with an ASCII letter and may
+ * contain ASCII letters, digits, underscores, and dashes. The 64-character
+ * cap matches the most restrictive provider tool-name limit.
+ *
+ * The model-facing tool name is the filename slug verbatim — there is no
+ * authored `name` override and no compile-time normalization. Authors who
+ * want a snake_case identifier should name the file in snake_case.
+ */
+export declare const TOOL_SLUG_PATTERN: RegExp;
+/**
+ * Connection filename charset. Connections use the same lowercase
+ * kebab-case rule as sandbox since they are not directly exposed to
+ * model APIs as identifiers.
+ */
+export declare const CONNECTION_SLUG_PATTERN: RegExp;
+/**
+ * Channel filename / directory segment charset.
+ */
+export declare const CHANNEL_SLUG_PATTERN: RegExp;
+/**
+ * Hook filename / directory segment charset. Each segment of the
+ * path-relative slug uses the same restrictive charset as tool slugs:
+ * ASCII letters, digits, underscores, and dashes, starting with a
+ * letter, up to 64 characters per segment. Bracketed parameter forms
+ * are not allowed — hooks have no URL semantics.
+ */
+export declare const HOOK_SLUG_PATTERN: RegExp;
+/**
+ * Shared diagnostic emitted when discovery ignores one unsupported directory.
+ */
+export declare const DISCOVER_UNSUPPORTED_DIRECTORY = "discover/unsupported-directory";
+/**
+ * Structural `Dirent`-like entry used throughout discovery.
+ *
+ * Legacy alias preserved for backwards compatibility inside `src/discover/`.
+ * Every discover function now consumes {@link ProjectSourceEntry}, which
+ * has the same three properties (`name`, `isDirectory()`, `isFile()`). Real
+ * `Dirent<string>` values from `node:fs` satisfy this shape, so
+ * {@link createDiskProjectSource} returns them directly.
+ */
+export type StringDirent = Dirent<string>;
+/**
+ * Reads one directory through `source` and returns its entries sorted by name.
+ */
+export declare function readSortedDirectoryEntries(source: ProjectSource, directoryPath: string): Promise<ProjectSourceEntry[]>;
+/**
+ * Discovers instructions sources from a root directory.
+ *
+ * Supports three forms:
+ * 1. **Directory**: `agent/instructions/` with multiple `.md` and `.ts` files.
+ * 2. **Flat file**: `agent/instructions.md` or `agent/instructions.{ts,...}`.
+ * 3. **Legacy**: `agent/system.{md,ts,...}` with a deprecation warning.
+ *
+ * A flat file and a directory can coexist — the flat file appears first
+ * in the returned array.
+ */
+export declare function discoverInstructionsSource(input: {
+    required?: boolean;
+    rootEntries: readonly ProjectSourceEntry[];
+    rootPath: string;
+    source: ProjectSource;
+}): Promise<{
+    diagnostics: DiscoverDiagnostic[];
+    instructions: InstructionsSourceRef[];
+}>;
+/**
+ * Discovers one flat module slot such as `agent.ts` or `subagent.cjs`.
+ */
+export declare function discoverFlatModuleSource(input: {
+    missingDiagnostic?: {
+        code: string;
+        message: string;
+    };
+    rootEntries: readonly ProjectSourceEntry[];
+    rootPath: string;
+    slotName: string;
+}): {
+    diagnostics: DiscoverDiagnostic[];
+    module?: ModuleSourceRef;
+};
+/**
+ * Returns a discovery diagnostic when a tool slot name violates
+ * {@link TOOL_SLUG_PATTERN}, or `null` when it satisfies the rule.
+ *
+ * Wired in by {@link discoverNamedSourceDirectory} callers via
+ * `validateSegment` so the discover layer rejects illegal filenames before
+ * the compiler ever loads the module.
+ */
+export declare function createToolNameDiagnostic(slotName: string, sourcePath: string): DiscoverDiagnostic | null;
+/**
+ * Returns a discovery diagnostic when a connection slot name violates
+ * {@link CONNECTION_SLUG_PATTERN}, or `null` when it satisfies the rule.
+ */
+export declare function createConnectionNameDiagnostic(slotName: string, sourcePath: string): DiscoverDiagnostic | null;
+/**
+ * Returns a discovery diagnostic when a channel filesystem segment violates
+ * {@link CHANNEL_SLUG_PATTERN}, or `null` when it satisfies the rule.
+ *
+ * Each path segment under `agent/channels/` is validated independently —
+ * file leaves and directory ancestors both go through this check so the
+ * runtime never sees a malformed URL segment.
+ */
+export declare function createChannelNameDiagnostic(segment: string, sourcePath: string): DiscoverDiagnostic | null;
+/**
+ * Returns a discovery diagnostic when a hook filesystem segment violates
+ * {@link HOOK_SLUG_PATTERN}, or `null` when it satisfies the rule.
+ *
+ * Each path segment under `agent/hooks/` is validated independently so
+ * the runtime never sees a malformed slug.
+ */
+export declare function createHookNameDiagnostic(segment: string, sourcePath: string): DiscoverDiagnostic | null;
+export { discoverNamedSourceDirectory, type DiscoverNamedSourceDirectoryModuleInput, type DiscoverNamedSourceDirectoryWithMarkdownInput, } from "#discover/named-source-directory.js";
+/**
+ * Emits shared diagnostics for unsupported root-level directories.
+ */
+export declare function createUnsupportedRootDirectoryDiagnostics(input: {
+    classifyEntry: (name: string, entryType: DirectoryEntryType) => string;
+    createUnsupportedDirectoryMessage: (directoryName: string) => string;
+    rootEntries: readonly ProjectSourceEntry[];
+    rootPath: string;
+}): DiscoverDiagnostic[];
+/**
+ * Creates one slot-collision diagnostic with shared wording.
+ */
+export declare function createSlotCollisionDiagnostic(directoryPath: string, slotLogicalPath: string, fileNames: readonly string[]): DiscoverDiagnostic;
+/**
+ * Creates one module-slot collision diagnostic with shared wording.
+ */
+export declare function createModuleSlotCollisionDiagnostic(directoryPath: string, slotLogicalPath: string, fileNames: readonly string[]): DiscoverDiagnostic;

package/dist/src/discover/grammar.js

@@ -0,0 +1 @@
+import{join}from"node:path";import{createDiscoverErrorDiagnostic,createDiscoverWarningDiagnostic}from"#discover/diagnostics.js";import{getDirectoryEntryType}from"#discover/filesystem.js";import{createModuleSourceRef}from"#discover/manifest.js";import{collectFlatSlotCandidates}from"#discover/slots.js";import{lowerInstructionsMarkdown}from"#internal/helpers/markdown.js";import{discoverMarkdownSource}from"#discover/markdown.js";import{discoverNamedSourceDirectory,discoverNamedSourceDirectory as discoverNamedSourceDirectory$1}from"#discover/named-source-directory.js";const DISCOVER_MODULE_SLOT_COLLISION=`discover/module-slot-collision`,DISCOVER_REQUIRED_INSTRUCTIONS_MISSING=`discover/required-instructions-missing`,DISCOVER_DEPRECATED_SYSTEM_SLOT=`discover/deprecated-system-slot`,DISCOVER_SLOT_COLLISION=`discover/slot-collision`,DISCOVER_TOOLS_DIRECTORY_INVALID=`discover/tools-directory-invalid`,DISCOVER_HOOKS_DIRECTORY_INVALID=`discover/hooks-directory-invalid`,DISCOVER_CHANNELS_DIRECTORY_INVALID=`discover/channels-directory-invalid`,DISCOVER_TOOL_NAME_INVALID=`discover/tool-name-invalid`,DISCOVER_CONNECTION_NAME_INVALID=`discover/connection-name-invalid`,DISCOVER_SANDBOX_DIRECTORY_INVALID=`discover/sandbox-directory-invalid`,DISCOVER_INSTRUCTIONS_DIRECTORY_INVALID=`discover/instructions-directory-invalid`,DISCOVER_CHANNEL_NAME_INVALID=`discover/channel-name-invalid`,DISCOVER_HOOK_NAME_INVALID=`discover/hook-name-invalid`,TOOL_SLUG_PATTERN=/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/,CONNECTION_SLUG_PATTERN=/^[a-z][a-z0-9-]{0,63}$/,CHANNEL_SLUG_PATTERN=/^(\.?[a-z][a-z0-9-]{0,63}|\[[a-zA-Z][a-zA-Z0-9_]{0,63}\])$/,HOOK_SLUG_PATTERN=/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/,DISCOVER_UNSUPPORTED_DIRECTORY=`discover/unsupported-directory`;async function readSortedDirectoryEntries(e,t){let n=[...await e.readDirectory(t)];return n.sort((e,t)=>e.name.localeCompare(t.name)),n}async function discoverInstructionsSource(r){let i=r.rootEntries.some(e=>e.name===`instructions`&&e.isDirectory()),a=await discoverSlotSource({markdownFileName:`instructions.md`,moduleBaseName:`instructions`,rootEntries:r.rootEntries,rootPath:r.rootPath,slotLabel:`instructions`,source:r.source});if(i){let t=await discoverNamedSourceDirectory$1({allowMarkdown:!0,directoryName:`instructions`,invalidDirectoryCode:DISCOVER_INSTRUCTIONS_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${join(r.rootPath,`instructions`)}" to be a directory of authored instructions.`,markdownLowerer:e=>lowerInstructionsMarkdown(e),recursive:!1,rootEntries:r.rootEntries,rootPath:r.rootPath,source:r.source}),n=[...t.sources];return a.source!==void 0&&n.unshift(a.source),{diagnostics:[...a.diagnostics,...t.diagnostics],instructions:n}}if(a.diagnostics.length>0||a.source!==void 0)return{diagnostics:a.diagnostics,instructions:a.source===void 0?[]:[a.source]};let o=await discoverSlotSource({markdownFileName:`system.md`,moduleBaseName:`system`,rootEntries:r.rootEntries,rootPath:r.rootPath,slotLabel:`system`,source:r.source});if(o.source!==void 0){let t=o.source.sourceKind===`markdown`?`system.md`:o.source.logicalPath;return{diagnostics:[createDiscoverWarningDiagnostic({code:DISCOVER_DEPRECATED_SYSTEM_SLOT,message:`The "${t}" slot is deprecated. Rename it to "${t.replace(/^system/,`instructions`)}" — the runtime still loads the legacy slot for now, but support will be removed in a future release.`,sourcePath:join(r.rootPath,t)}),...o.diagnostics],instructions:[o.source]}}return o.diagnostics.length>0?{diagnostics:o.diagnostics,instructions:[]}:r.required===!1?{diagnostics:[],instructions:[]}:{diagnostics:[createDiscoverErrorDiagnostic({code:DISCOVER_REQUIRED_INSTRUCTIONS_MISSING,message:`Expected authored instructions at "instructions.md", "instructions.ts", "instructions.cts", "instructions.mts", "instructions.js", "instructions.cjs", "instructions.mjs", or "instructions/" directory.`,sourcePath:r.rootPath})],instructions:[]}}async function discoverSlotSource(t){let n=collectFlatSlotCandidates(t.rootEntries,{markdownFileName:t.markdownFileName,moduleBaseName:t.moduleBaseName});if(n.markdownFileName!==void 0&&n.moduleFileNames.length>0)return{diagnostics:[createSlotCollisionDiagnostic(t.rootPath,t.slotLabel,[n.markdownFileName,...n.moduleFileNames])]};if(n.moduleFileNames.length>1)return{diagnostics:[createModuleSlotCollisionDiagnostic(t.rootPath,t.slotLabel,n.moduleFileNames)]};if(n.markdownFileName!==void 0)return{diagnostics:[],source:await discoverMarkdownSource({logicalPath:t.markdownFileName,lower:lowerInstructionsMarkdown,source:t.source,sourcePath:join(t.rootPath,n.markdownFileName)})};let[r]=n.moduleFileNames;return r===void 0?{diagnostics:[]}:{diagnostics:[],source:createModuleSourceRef({logicalPath:r})}}function discoverFlatModuleSource(e){let n=collectFlatSlotCandidates(e.rootEntries,{moduleBaseName:e.slotName});if(n.moduleFileNames.length>1)return{diagnostics:[createModuleSlotCollisionDiagnostic(e.rootPath,e.slotName,n.moduleFileNames)]};let[r]=n.moduleFileNames;return r===void 0?e.missingDiagnostic===void 0?{diagnostics:[]}:{diagnostics:[createDiscoverErrorDiagnostic({code:e.missingDiagnostic.code,message:e.missingDiagnostic.message,sourcePath:e.rootPath})]}:{diagnostics:[],module:createModuleSourceRef({logicalPath:r})}}function createToolNameDiagnostic(e,n){return TOOL_SLUG_PATTERN.test(e)?null:createDiscoverErrorDiagnostic({code:DISCOVER_TOOL_NAME_INVALID,message:`Tool filename "${e}" is not a legal tool name. Expected ASCII letters, digits, underscores, and dashes only, starting with a letter, up to 64 characters.`,sourcePath:n})}function createConnectionNameDiagnostic(e,n){return CONNECTION_SLUG_PATTERN.test(e)?null:createDiscoverErrorDiagnostic({code:DISCOVER_CONNECTION_NAME_INVALID,message:`Connection filename "${e}" is not a legal connection name. Expected lowercase ASCII letters, digits, and dashes only, starting with a letter, up to 64 characters.`,sourcePath:n})}function createChannelNameDiagnostic(e,n){return CHANNEL_SLUG_PATTERN.test(e)?null:createDiscoverErrorDiagnostic({code:DISCOVER_CHANNEL_NAME_INVALID,message:`Channel path segment "${e}" is not a legal channel name. Expected lowercase kebab-case (\`my-channel\`), optionally with a leading dot (\`.well-known\`), or a path parameter form (\`[sessionId]\`).`,sourcePath:n})}function createHookNameDiagnostic(e,n){return HOOK_SLUG_PATTERN.test(e)?null:createDiscoverErrorDiagnostic({code:DISCOVER_HOOK_NAME_INVALID,message:`Hook path segment "${e}" is not a legal hook name. Expected ASCII letters, digits, underscores, and dashes only, starting with a letter, up to 64 characters.`,sourcePath:n})}function createUnsupportedRootDirectoryDiagnostics(t){return t.rootEntries.flatMap(i=>!i.isDirectory()||t.classifyEntry(i.name,getDirectoryEntryType(i))!==`unknown`?[]:[createDiscoverWarningDiagnostic({code:DISCOVER_UNSUPPORTED_DIRECTORY,message:t.createUnsupportedDirectoryMessage(i.name),sourcePath:join(t.rootPath,i.name)})])}function createSlotCollisionDiagnostic(e,n,r){return createDiscoverErrorDiagnostic({code:DISCOVER_SLOT_COLLISION,message:`Found conflicting authored sources for "${n}": ${formatQuotedFileList(r)}.`,sourcePath:e})}function createModuleSlotCollisionDiagnostic(e,n,r){return createDiscoverErrorDiagnostic({code:DISCOVER_MODULE_SLOT_COLLISION,message:`Found multiple authored module sources for "${n}": ${formatQuotedFileList(r)}.`,sourcePath:e})}function formatQuotedFileList(e){return e.map(e=>`"${e}"`).join(`, `)}export{CHANNEL_SLUG_PATTERN,CONNECTION_SLUG_PATTERN,DISCOVER_CHANNELS_DIRECTORY_INVALID,DISCOVER_CHANNEL_NAME_INVALID,DISCOVER_CONNECTION_NAME_INVALID,DISCOVER_DEPRECATED_SYSTEM_SLOT,DISCOVER_HOOKS_DIRECTORY_INVALID,DISCOVER_HOOK_NAME_INVALID,DISCOVER_INSTRUCTIONS_DIRECTORY_INVALID,DISCOVER_MODULE_SLOT_COLLISION,DISCOVER_REQUIRED_INSTRUCTIONS_MISSING,DISCOVER_SANDBOX_DIRECTORY_INVALID,DISCOVER_SLOT_COLLISION,DISCOVER_TOOLS_DIRECTORY_INVALID,DISCOVER_TOOL_NAME_INVALID,DISCOVER_UNSUPPORTED_DIRECTORY,HOOK_SLUG_PATTERN,TOOL_SLUG_PATTERN,createChannelNameDiagnostic,createConnectionNameDiagnostic,createHookNameDiagnostic,createModuleSlotCollisionDiagnostic,createSlotCollisionDiagnostic,createToolNameDiagnostic,createUnsupportedRootDirectoryDiagnostics,discoverFlatModuleSource,discoverInstructionsSource,discoverNamedSourceDirectory,readSortedDirectoryEntries};

package/dist/src/discover/lib.d.ts

@@ -0,0 +1,34 @@
+import type { ModuleSourceRef } from "#shared/source-ref.js";
+import type { DiscoverDiagnostic } from "#discover/diagnostics.js";
+import type { ProjectSource, ProjectSourceEntry } from "#discover/project-source.js";
+/**
+ * Diagnostic emitted when the authored `lib/` root exists but is not a
+ * directory.
+ */
+export declare const DISCOVER_LIB_DIRECTORY_INVALID = "discover/lib-directory-invalid";
+/**
+ * Diagnostic emitted when discovery finds an unsupported entry under the
+ * authored `lib/` tree.
+ */
+export declare const DISCOVER_LIB_ENTRY_UNSUPPORTED = "discover/lib-entry-unsupported";
+/**
+ * Input for discovering authored helper modules under `lib/`.
+ */
+interface DiscoverLibSourcesInput {
+    agentRoot: string;
+    rootEntries: readonly ProjectSourceEntry[];
+    source: ProjectSource;
+}
+/**
+ * Result of recursively discovering authored helper modules under `lib/`.
+ */
+interface DiscoverLibSourcesResult {
+    diagnostics: DiscoverDiagnostic[];
+    lib: ModuleSourceRef[];
+}
+/**
+ * Discovers module-only helper sources under `lib/` without executing
+ * authored modules.
+ */
+export declare function discoverLibSources(input: DiscoverLibSourcesInput): Promise<DiscoverLibSourcesResult>;
+export {};

package/dist/src/discover/lib.js

@@ -0,0 +1 @@
+import{discoverNamedSourceDirectory}from"#discover/grammar.js";const DISCOVER_LIB_DIRECTORY_INVALID=`discover/lib-directory-invalid`,DISCOVER_LIB_ENTRY_UNSUPPORTED=`discover/lib-entry-unsupported`;async function discoverLibSources(t){let n=await discoverNamedSourceDirectory({directoryName:`lib`,invalidDirectoryCode:DISCOVER_LIB_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${t.agentRoot}/lib" to be a directory of authored helper modules.`,recursive:!0,rootEntries:t.rootEntries,rootPath:t.agentRoot,source:t.source,unsupportedEntryCode:DISCOVER_LIB_ENTRY_UNSUPPORTED,unsupportedEntryMessage:e=>`Expected "${e}" to be a supported authored module within "lib/".`,unsupportedFileCode:DISCOVER_LIB_ENTRY_UNSUPPORTED,unsupportedFileMessage:e=>`Expected "${e}" to be a supported authored module within "lib/".`});return{diagnostics:n.diagnostics,lib:n.sources}}export{DISCOVER_LIB_DIRECTORY_INVALID,DISCOVER_LIB_ENTRY_UNSUPPORTED,discoverLibSources};

package/dist/src/discover/manifest.d.ts

@@ -0,0 +1,250 @@
+import type { MarkdownSourceRef, ModuleSourceRef, SkillPackageSourceRef } from "#shared/source-ref.js";
+import type { NamedSkillDefinition } from "#shared/skill-definition.js";
+import type { ScheduleDefinition } from "#public/definitions/schedule.js";
+import type { SkillDefinition } from "#public/definitions/skill.js";
+import type { InstructionsDefinition } from "#public/definitions/instructions.js";
+import type { DiscoverDiagnostic, DiscoverDiagnosticsSummary } from "#discover/diagnostics.js";
+/**
+ * Stable manifest kind emitted by discovery.
+ */
+export declare const AGENT_SOURCE_MANIFEST_KIND = "eve-agent-discovery-manifest";
+/**
+ * Current manifest schema version.
+ */
+export declare const AGENT_SOURCE_MANIFEST_VERSION = 12;
+/**
+ * Channel source reference preserved by the discovery manifest.
+ */
+export type ChannelSourceRef = ModuleSourceRef;
+/**
+ * Connection source reference preserved by the discovery manifest.
+ *
+ * Carries the explicit `connectionName` so the compiler does not have to
+ * re-derive it from the module's logical path.
+ */
+export interface ConnectionSourceRef extends ModuleSourceRef {
+    /**
+     * Authored connection name. Equals the basename of the file form
+     * (`connections/linear.ts` -> `"linear"`) or the directory name of the
+     * folder form (`connections/linear/connection.ts` -> `"linear"`).
+     */
+    readonly connectionName: string;
+}
+/**
+ * Instructions source reference preserved by discovery for compiler
+ * normalization.
+ */
+export type InstructionsSourceRef = MarkdownSourceRef<InstructionsDefinition> | ModuleSourceRef;
+/**
+ * Skill source reference preserved by the discovery manifest.
+ */
+export type SkillSourceRef = MarkdownSourceRef<SkillDefinition> | ModuleSourceRef | (NamedSkillDefinition & SkillPackageSourceRef);
+/**
+ * Recursive manifest entry for a local subagent package.
+ */
+export interface LocalSubagentSourceRef {
+    entryPath: string;
+    logicalPath: string;
+    manifest: AgentSourceManifest;
+    rootPath: string;
+    sourceId: string;
+    subagentId: string;
+}
+/**
+ * Schedule source reference preserved by the discovery manifest. A
+ * schedule may be authored either as a TypeScript module
+ * (`schedules/<name>.ts`) or as a markdown file with frontmatter
+ * (`schedules/<name>.md`).
+ */
+export type ScheduleSourceRef = MarkdownSourceRef<ScheduleDefinition> | ModuleSourceRef;
+/**
+ * Sandbox source reference preserved by the discovery manifest.
+ *
+ * Every agent owns exactly one sandbox; the source ref is just a
+ * module reference identifying the authored `sandbox.<ext>` (or
+ * `sandbox/sandbox.<ext>`) override.
+ */
+export type SandboxSourceRef = ModuleSourceRef;
+/**
+ * Sandbox workspace folder reference preserved by the discovery
+ * manifest.
+ *
+ * Emitted when `agent/sandbox/workspace/` is found on disk. The
+ * compiler and runtime mount the contents of `sourcePath` into the
+ * sandbox's live cwd at session bootstrap.
+ */
+export interface SandboxWorkspaceFolderSourceRef {
+    /**
+     * Logical path of the workspace folder relative to the agent root,
+     * e.g. `"sandbox/workspace"`.
+     */
+    readonly logicalPath: string;
+    /**
+     * Top-level directory entries discovered inside the workspace folder.
+     * Directories are listed with a trailing `/`. Used by the workspace
+     * prompt section so the model can see the file tree at a glance.
+     */
+    readonly rootEntries: readonly string[];
+    /**
+     * Stable id derived from the logical path.
+     */
+    readonly sourceId: string;
+    /**
+     * Absolute on-disk path to the workspace folder.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * Package-local helper module preserved by the discovery manifest.
+ */
+export type LibSourceRef = ModuleSourceRef;
+/**
+ * Subagent source reference preserved by the discovery manifest.
+ */
+export type SubagentSourceRef = LocalSubagentSourceRef;
+/**
+ * Input used to build a manifest-ready connection source ref.
+ */
+export interface CreateConnectionSourceRefInput extends CreateModuleSourceRefInput {
+    connectionName: string;
+}
+/**
+ * Versioned source manifest emitted by discovery.
+ */
+export interface AgentSourceManifest {
+    agentId: string;
+    agentRoot: string;
+    appRoot: string;
+    channels: ChannelSourceRef[];
+    connections: ConnectionSourceRef[];
+    configModule?: ModuleSourceRef;
+    diagnosticsSummary: DiscoverDiagnosticsSummary;
+    hooks: ModuleSourceRef[];
+    lib: LibSourceRef[];
+    kind: typeof AGENT_SOURCE_MANIFEST_KIND;
+    /**
+     * Authored instructions prompt sources discovered at the agent root.
+     *
+     * Supports three forms:
+     * 1. Flat file: `instructions.md` or `instructions.{ts,...}` → single element.
+     * 2. Directory: `instructions/` with `.md` and `.ts` files → multiple elements.
+     * 3. Legacy: `system.{md,ts,...}` → single element with deprecation warning.
+     *
+     * Empty when no instructions are authored.
+     */
+    instructions: InstructionsSourceRef[];
+    /**
+     * Authored sandbox module discovered for this agent, or `null` when
+     * the agent does not declare one. Every agent owns at most one
+     * sandbox.
+     */
+    sandbox: SandboxSourceRef | null;
+    /**
+     * Authored sandbox workspace folder discovered under
+     * `agent/sandbox/workspace/`. At most one entry per agent; mounted
+     * into the live sandbox cwd at session bootstrap.
+     */
+    sandboxWorkspaces: SandboxWorkspaceFolderSourceRef[];
+    schedules: ScheduleSourceRef[];
+    skills: SkillSourceRef[];
+    tools: ModuleSourceRef[];
+    version: typeof AGENT_SOURCE_MANIFEST_VERSION;
+    subagents: SubagentSourceRef[];
+}
+/**
+ * Input used to build a discovery manifest with stable defaults.
+ */
+export interface CreateAgentSourceManifestInput {
+    agentId?: string;
+    agentRoot: string;
+    appRoot: string;
+    channels?: readonly ChannelSourceRef[];
+    connections?: readonly ConnectionSourceRef[];
+    configModule?: ModuleSourceRef;
+    diagnostics?: readonly DiscoverDiagnostic[];
+    hooks?: readonly ModuleSourceRef[];
+    lib?: readonly LibSourceRef[];
+    /**
+     * Optional package name read from the app root's package.json.
+     * When provided this is preferred over `basename(appRoot)` for agent id
+     * derivation so that builds running in synthetic CI paths (e.g.
+     * `/vercel/path0`) produce a meaningful agent id.
+     */
+    packageName?: string;
+    instructions?: readonly InstructionsSourceRef[];
+    sandbox?: SandboxSourceRef | null;
+    sandboxWorkspaces?: readonly SandboxWorkspaceFolderSourceRef[];
+    schedules?: readonly ScheduleSourceRef[];
+    skills?: readonly SkillSourceRef[];
+    tools?: readonly ModuleSourceRef[];
+    subagents?: readonly SubagentSourceRef[];
+}
+/**
+ * Input used to build a manifest-ready skill package source ref.
+ */
+export interface CreateSkillPackageSourceRefInput {
+    assetsPath?: string;
+    description: string;
+    license?: string;
+    logicalPath: string;
+    markdown: string;
+    metadata?: Readonly<Record<string, string>>;
+    name: string;
+    referencesPath?: string;
+    rootPath: string;
+    scriptsPath?: string;
+    skillFilePath: string;
+    skillId: string;
+    sourceId: string;
+}
+/**
+ * Input used to build a manifest-ready module source ref.
+ */
+export interface CreateModuleSourceRefInput {
+    exportName?: string;
+    logicalPath: string;
+    sourceId?: string;
+}
+/**
+ * Input used to build a manifest-ready local subagent source ref.
+ */
+export interface CreateLocalSubagentSourceRefInput {
+    entryPath: string;
+    logicalPath: string;
+    manifest: AgentSourceManifest;
+    rootPath: string;
+    sourceId?: string;
+    subagentId: string;
+}
+/**
+ * Creates a versioned discovery manifest with stable empty-array defaults.
+ */
+export declare function createAgentSourceManifest(input: CreateAgentSourceManifestInput): AgentSourceManifest;
+/**
+ * Derives a stable agent id from the resolved app and agent roots.
+ *
+ * When `packageName` is provided it is preferred over `basename(appRoot)` so
+ * that builds running inside synthetic CI working directories (e.g.
+ * `/vercel/path0`) produce a meaningful agent id instead of `"path0"`.
+ */
+export declare function deriveAgentIdFromRoots(appRoot: string, agentRoot: string, packageName?: string): string;
+/**
+ * Creates a stable path-derived source id for manifest entries.
+ */
+export declare function createPathDerivedSourceId(logicalPath: string): string;
+/**
+ * Creates a module source ref while omitting optional undefined fields.
+ */
+export declare function createModuleSourceRef(input: CreateModuleSourceRefInput): ModuleSourceRef;
+/**
+ * Creates a connection source ref tagged with its authored name.
+ */
+export declare function createConnectionSourceRef(input: CreateConnectionSourceRefInput): ConnectionSourceRef;
+/**
+ * Creates a local subagent source ref while omitting optional undefined fields.
+ */
+export declare function createLocalSubagentSourceRef(input: CreateLocalSubagentSourceRefInput): LocalSubagentSourceRef;
+/**
+ * Creates a skill package source ref while omitting optional undefined fields.
+ */
+export declare function createSkillPackageSourceRef(input: CreateSkillPackageSourceRefInput): NamedSkillDefinition & SkillPackageSourceRef;

package/dist/src/discover/manifest.js

@@ -0,0 +1 @@
+import{basename,relative,resolve}from"node:path";import{summarizeDiscoverDiagnostics}from"#discover/diagnostics.js";import{normalizeLogicalPath}from"#discover/filesystem.js";const AGENT_SOURCE_MANIFEST_KIND=`eve-agent-discovery-manifest`,AGENT_SOURCE_MANIFEST_VERSION=12;function createAgentSourceManifest(e){let t=resolve(e.appRoot),i=resolve(e.agentRoot),o={agentId:e.agentId??deriveAgentIdFromRoots(t,i,e.packageName),agentRoot:i,appRoot:t,channels:[...e.channels??[]],connections:[...e.connections??[]],diagnosticsSummary:summarizeDiscoverDiagnostics(e.diagnostics??[]),hooks:[...e.hooks??[]],instructions:[...e.instructions??[]],lib:[...e.lib??[]],kind:AGENT_SOURCE_MANIFEST_KIND,sandbox:e.sandbox??null,sandboxWorkspaces:[...e.sandboxWorkspaces??[]],schedules:[...e.schedules??[]],skills:[...e.skills??[]],tools:[...e.tools??[]],version:12,subagents:[...e.subagents??[]]};return e.configModule!==void 0&&(o.configModule=e.configModule),o}function deriveAgentIdFromRoots(n,r,a){let o=normalizeLogicalPath(relative(n,r));return o===``||o===`.`||o===`agent`?a??basename(n):basename(r)}function createPathDerivedSourceId(e){return normalizeLogicalPath(e)}function createModuleSourceRef(e){let t=normalizeLogicalPath(e.logicalPath),n={sourceKind:`module`,logicalPath:t,sourceId:e.sourceId??createPathDerivedSourceId(t)};return e.exportName!==void 0&&(n.exportName=e.exportName),n}function createConnectionSourceRef(e){return{...createModuleSourceRef(e),connectionName:e.connectionName}}function createLocalSubagentSourceRef(e){let t=normalizeLogicalPath(e.logicalPath);return{entryPath:e.entryPath,logicalPath:t,manifest:e.manifest,rootPath:e.rootPath,sourceId:e.sourceId??createPathDerivedSourceId(t),subagentId:e.subagentId}}function createSkillPackageSourceRef(e){return{assetsPath:e.assetsPath,description:e.description,license:e.license,logicalPath:normalizeLogicalPath(e.logicalPath),markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name,referencesPath:e.referencesPath,rootPath:e.rootPath,scriptsPath:e.scriptsPath,skillFilePath:e.skillFilePath,skillId:e.skillId,sourceId:e.sourceId,sourceKind:`skill-package`}}export{AGENT_SOURCE_MANIFEST_KIND,AGENT_SOURCE_MANIFEST_VERSION,createAgentSourceManifest,createConnectionSourceRef,createLocalSubagentSourceRef,createModuleSourceRef,createPathDerivedSourceId,createSkillPackageSourceRef,deriveAgentIdFromRoots};

package/dist/src/discover/markdown.d.ts

@@ -0,0 +1,19 @@
+import type { MarkdownSourceRef } from "#shared/source-ref.js";
+import type { ProjectSource } from "#discover/project-source.js";
+/**
+ * Input for lowering one discovered markdown file into a typed source ref.
+ */
+interface DiscoverMarkdownSourceInput<TDefinition> {
+    logicalPath: string;
+    lower: (source: string, input: {
+        name: string;
+    }) => TDefinition;
+    source: ProjectSource;
+    sourcePath: string;
+}
+/**
+ * Reads one markdown-authored source from a {@link ProjectSource} and lowers
+ * it into the shared manifest shape.
+ */
+export declare function discoverMarkdownSource<TDefinition>(input: DiscoverMarkdownSourceInput<TDefinition>): Promise<MarkdownSourceRef<TDefinition>>;
+export {};

package/dist/src/discover/markdown.js

@@ -0,0 +1 @@
+import{normalizeLogicalPath,stripLogicalPathExtension}from"#discover/filesystem.js";import{createPathDerivedSourceId}from"#discover/manifest.js";async function discoverMarkdownSource(e){let t=normalizeLogicalPath(e.logicalPath);return{definition:e.lower(await e.source.readTextFile(e.sourcePath),{name:stripLogicalPathExtension(t)}),sourceKind:`markdown`,logicalPath:t,sourceId:createPathDerivedSourceId(t)}}export{discoverMarkdownSource};