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

Filesystem-first framework for durable backend AI agents that run anywhere.

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;
}
/**
 * Hook source reference preserved by the discovery manifest.
 */
export type HookSourceRef = ModuleSourceRef;
/**
 * 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);
/**
 * Tool source reference preserved by the discovery manifest.
 */
export type ToolSourceRef = ModuleSourceRef;
/**
 * 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;
/**
 * Extension mount source reference preserved by the discovery manifest. Each
 * `agent/extensions/*.ts` file re-exports (and configures) an extension
 * package; the file basename is the mount namespace.
 */
export type ExtensionSourceRef = ModuleSourceRef;
/**
 * A mounted extension resolved to its package and discovered agent-shaped
 * source tree. The compiler composes each mount's {@link manifest} into the
 * consuming agent, prefixing contributions with {@link namespace}.
 */
export interface ResolvedExtensionMount {
    /** Mount namespace derived from the mount filename (e.g. `crm`). */
    readonly namespace: string;
    /** Package specifier the mount imports (e.g. `@acme/crm`). */
    readonly specifier: string;
    /** Package name from the resolved package.json, used to scope state. */
    readonly packageName: string;
    /** Absolute path to the resolved package root. */
    readonly packageRoot: string;
    /** Absolute path to the extension's agent-shaped source root. */
    readonly sourceRoot: string;
    /** Discovered agent-shaped source manifest for the extension. */
    readonly manifest: AgentSourceManifest;
    /**
     * Consumer-authored overrides discovered in the mount directory form
     * (`extensions/<ns>/{tools,connections,…}/`). Composed under the same
     * `<ns>__` namespace as the extension's own contributions but winning on
     * name collision. Absent for the flat file mount form.
     */
    readonly overrides?: AgentSourceManifest;
}
/**
 * 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;
    /**
     * Mounted extension source references discovered under `agent/extensions/`.
     * Each entry's logical-path basename is the mount namespace the compiler
     * prefixes onto the extension's composed contributions.
     */
    extensions: ExtensionSourceRef[];
    /**
     * Mounted extensions resolved to their packages and discovered source trees.
     * Populated only for the agent root; extension trees do not mount further
     * extensions (transitive mounting is a non-goal).
     */
    resolvedExtensions: ResolvedExtensionMount[];
    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[];
    extensions?: readonly ExtensionSourceRef[];
    resolvedExtensions?: readonly ResolvedExtensionMount[];
    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;