import { type NativeTaskTools } from "./native-task-policy.js";
/**
 * Derive a deterministic UUID from a system agent ID slug.
 * All workers and clients produce the same UUID for the same slug.
 */
export declare function systemAgentUUID(slug: string): string;
/**
 * Derive a deterministic UUID for a system child agent from its parent session
 * and child slug. This keeps system children like sweeper/resource manager
 * stable across restarts while avoiding collisions between different parents.
 */
export declare function systemChildAgentUUID(parentSessionId: string, slug: string): string;
export interface AgentConfig {
    name: string;
    description?: string;
    prompt: string;
    tools?: string[] | null;
    /** Skill names to preload from the session's configured skill directories. */
    skills?: string[];
    /**
     * Named references to deployment-catalog MCP servers (entries in the
     * merged `.mcp.json` map) this agent's sessions should receive. Inline
     * server definitions are not accepted in frontmatter — define the server
     * in the plugin's `.mcp.json` (which puts it in the catalog) and
     * reference it here by name. Declared refs that miss the catalog are
     * dropped with a warning at load time. Agents using this field should
     * declare `schemaVersion: 2` so older loaders skip the file instead of
     * silently dropping its MCP servers.
     */
    mcpServers?: string[];
    /**
     * When true, the agent also receives the deployment's default MCP set
     * (catalog servers tagged `"default": true` in `.mcp.json`). Defaults to
     * false — an agent gets no MCP servers unless it declares or inherits
     * them.
     */
    inheritDefaultMcpServers?: boolean;
    /** Explicit per-native-task external tool allowlists (schemaVersion 4). */
    nativeTaskTools?: NativeTaskTools;
    /** If true, this is a system agent started automatically by workers. */
    system?: boolean;
    /** Deterministic ID slug for system agents (e.g. "sweeper"). Used to derive a fixed session UUID. */
    id?: string;
    /** Display title for the session list (e.g. "Resource Manager Agent"). Falls back to capitalized name + " Agent". */
    title?: string;
    /** Parent system agent ID slug (e.g. "pilotswarm"). Makes this a sub-agent of the parent. */
    parent?: string;
    /** Splash banner (terminal markup) shown in the TUI when the session is selected. */
    splash?: string;
    /** Narrow-viewport splash variant, swapped in when the main splash art is wider than the pane (mobile portal, narrow terminals). */
    splashMobile?: string;
    /** Initial prompt to send when the system agent is first created. */
    initialPrompt?: string;
    /** Declared tool with a registered handler that must run during the named agent's initial prompt turn. */
    initialRequiredTool?: string;
    /** Source plugin namespace (e.g. "pilotswarm", "smelter"). Set by the worker during plugin loading. */
    namespace?: string;
    /** Internal: identifies which prompt layering path this agent should use. */
    promptLayerKind?: "app-agent" | "app-system-agent" | "pilotswarm-system-agent";
    /**
     * App-assigned CRAWLER role. When `true`, a session bound to this agent
     * receives the privileged crawl queue when a graph store is configured.
     * Graph extraction/fill is app-specific, so the app sets `crawler: true` in
     * its own crawler agent's frontmatter. The role is derived from this
     * definition on the worker every turn — never inherited from a parent
     * session.
     */
    crawler?: boolean;
    /** @deprecated Use `crawler: true`; accepted as a compatibility alias. */
    harvester?: boolean;
    /**
     * Frontmatter schema version. Defaults to 1 when the file omits it. Higher integers
     * indicate forward-incompatible frontmatter shapes the loader may reject in the future.
     */
    schemaVersion?: number;
    /**
     * Author-supplied version label for this agent definition. PilotSwarm-authored system
     * agents use SemVer; app authors may use any meaningful non-empty string.
     */
    version?: string;
    /**
     * Names of the agents that spawn this one. Purely descriptive — it does
     * not gate anything at runtime; the picker uses it to nest an agent under
     * whichever entry point creates it, so a package's composition is visible
     * before you start a session with it.
     *
     * An agent with no `startedBy` is an ENTRY POINT of its package. A package
     * may have one, several, or none, which is why there is no `main` field to
     * keep honest — the shape falls out of the graph.
     */
    startedBy?: string[];
    /**
     * Whether a person may start this agent as a top-level session directly.
     * Defaults to `true` when `startedBy` is absent and `false` when it is
     * present: something written to be called by another agent usually reads
     * as broken when started cold. Set it explicitly to publish a sub-agent
     * that is also useful on its own.
     */
    supportsDirectStart?: boolean;
    /** Absolute path the agent was loaded from, when known. Used for diagnostics. */
    sourcePath?: string;
}
export interface AgentDefinitionIssue {
    code: "initial_required_tool_schema" | "initial_required_tool_not_declared" | "native_task_policy";
    message: string;
}
export declare function validateAgentDefinition(agent: Pick<AgentConfig, "schemaVersion" | "tools" | "initialRequiredTool" | "nativeTaskTools">): AgentDefinitionIssue[];
export interface LoadAgentFilesOptions {
    /** Package validation keeps invalid definitions long enough to report structured issue codes. */
    includeInvalid?: boolean;
}
/**
 * `supportsDirectStart` with its default applied. The default is the inverse
 * of "is a sub-agent", so a package that declares neither field behaves
 * exactly as it did before the fields existed.
 */
export declare function agentSupportsDirectStart(agent: {
    startedBy?: string[] | null;
    supportsDirectStart?: boolean | null;
} | null | undefined): boolean;
/**
 * Load all .agent.md files from a directory and convert to CustomAgentConfig[].
 *
 * @param agentsDir - Path to the agents directory.
 * @returns Array of agent configs. Files that fail to parse are skipped with a warning.
 */
export declare function loadAgentFiles(agentsDir: string, options?: LoadAgentFilesOptions): AgentConfig[];
/**
 * Names of every agent bundled with the SDK itself (system, mgmt, and
 * optional default-agents tiers), INCLUDING system agents. This is the
 * reserved-name set agent packages validate against — a package must not
 * shadow sweeper/resourcemgr/etc. even though those never appear in
 * creatable catalogs.
 */
export declare function listBundledAgentNames(): string[];
//# sourceMappingURL=agent-loader.d.ts.map