export type AgentMode = "primary" | "subagent";
export interface AgentConfig {
    /** Backend row id (cloud agents only — system agents have none). */
    id?: string;
    /** Parent PRIMARY agent id (cloud subagents only; null/undefined = root). */
    parentId?: string | null;
    name: string;
    description: string;
    mode: AgentMode;
    model?: string;
    systemPrompt: string;
    source: "cloud" | "system";
    filePath: string;
}
export declare const SYSTEM_AGENTS: AgentConfig[];
export declare function setCloudAgents(agents: AgentConfig[], teamId?: string): void;
/**
 * Outcome of a cloud-agent refresh. Lets callers react to auth rejection
 * (e.g. trigger a forced machine re-registration) instead of silently
 * treating an auth failure as "no agents".
 */
export type CloudAgentRefreshResult = {
    /** Auth rejected by the backend (HTTP 401/403 or GraphQL auth error). */
    authRejected: true;
    /** Human-readable reason for diagnostics. */
    reason: string;
} | {
    authRejected: false;
    /** Number of cloud agents loaded into the cache (may be 0 legitimately). */
    count: number;
};
export declare function refreshCloudAgents(opts: {
    backendUrl: string;
    machineJwt: string;
    teamId?: string;
}): Promise<CloudAgentRefreshResult>;
/**
 * Discover all agents available to a session: built-in system agents
 * (SYSTEM_AGENTS, read-only) plus cloud agents from the backend cache
 * (refreshCloudAgents, managed in Aexol Studio).
 *
 * Discovery is name-agnostic: ALL agents are returned, including cloud
 * agents that share a name with a system agent (subagent names are no
 * longer globally unique per team). Name-collision precedence is applied
 * at resolution time in `resolveAgentByName` (system agents win in
 * team-wide mode; a primary's own subtree wins in scoped mode).
 * Primaries remain unique per team by construction (the backend blocks
 * reserved system names for cloud primaries).
 * Never throws and never touches the network — offline / logged-out
 * sessions simply get the system agents.
 */
export declare function discoverAgents(teamId?: string): AgentConfig[];
export declare function discoverPrimaryAgent(teamId?: string): AgentConfig | null;
/**
 * Resolve the primary agent for a session.
 *
 * Legacy / unset values (`undefined`, `null`, `"__auto__"`, `"__inherit__"`) are
 * treated as "no agent" — sessions are fully explicit; the settings-level
 * auto-detect no longer applies per-session. An unknown agent name also
 * resolves to `null` (no fallback to auto-detect), so a stale selection never
 * silently injects an arbitrary primary agent.
 */
export declare function resolveSelectedPrimaryAgent(selectedName: string | null | undefined, teamId?: string): AgentConfig | null;
/**
 * Minimal reference to an active PRIMARY agent used to anchor parent-aware
 * subagent name resolution.
 */
export type AgentSubtreeRef = Pick<AgentConfig, "id" | "name">;
/**
 * Filter a flat agent list down to the subtree of an active primary agent:
 * the primary itself plus its direct children (subagents whose `parentId`
 * points at it).
 *
 * Returns the list UNCHANGED when no primary ref is given — standalone
 * sessions and system primaries (built-in ghost has no backend id) fall
 * back to team-wide resolution.
 */
export declare function agentsInSubtree(agents: AgentConfig[], activePrimary?: AgentSubtreeRef | null): AgentConfig[];
/**
 * The set of agents a session can actually reach:
 *
 * - Scoped (an `activePrimary` cloud primary): the primary's subtree plus
 *   the built-in system agents — a same-named cloud subagent in the
 *   subtree intentionally shadows the system agent, so system agents are
 *   only appended when their name is free in the subtree.
 * - Team-wide (no active primary): system agents win over same-named
 *   cloud agents (dedupe keeps the system row, first).
 */
export declare function reachableAgents(agents: AgentConfig[], activePrimary?: AgentSubtreeRef | null): AgentConfig[];
/**
 * Outcome of resolving an agent name against a discovered agent list,
 * optionally scoped to an active primary's subtree.
 */
export type AgentResolution = {
    status: "ok";
    agent: AgentConfig;
} | {
    status: "not-found";
    name: string;
    candidates: AgentConfig[];
} | {
    status: "ambiguous";
    name: string;
    conflicting: AgentConfig[];
};
/**
 * Resolve an agent name to a single agent.
 *
 * - Team-wide (no `activePrimary`, e.g. the built-in ghost session):
 *   SYSTEM agents always win over same-named cloud agents, so a cloud
 *   subagent named "executor" can no longer hijack the system executor.
 *   Only when no system agent has that name does resolution fall through
 *   to the cloud first-match (historical behavior for team-wide
 *   duplicates — not an error in fallback mode).
 * - Scoped (an `activePrimary` cloud primary with a backend id):
 *   candidates are scoped to the primary's subtree (the primary itself +
 *   its direct children, plus any other agent sharing the primary's name),
 *   so same-named subagents under different primaries resolve to the
 *   caller's own subtree. A same-named cloud subagent in the subtree
 *   intentionally shadows the system agent (that primary's own
 *   "executor"). If the name is NOT in the subtree, resolution falls back
 *   to SYSTEM agents (never to cloud agents of other trees). A name that
 *   matches multiple agents within the subtree (legacy data) is
 *   ambiguous — the caller must surface the conflict, never silently
 *   pick one.
 */
export declare function resolveAgentByName(name: string, agents: AgentConfig[], activePrimary?: AgentSubtreeRef | null): AgentResolution;
/**
 * Prepend the primary agent's system prompt above the base system prompt.
 *
 * - Returns the base unchanged when no primary agent is provided.
 * - Idempotent: if the base already starts with the primary agent header,
 *   the base is returned unchanged (guards against double-injection).
 */
export declare function injectPrimaryAgentPrompt(base: string | undefined, primaryAgent: Pick<AgentConfig, "name" | "description" | "systemPrompt" | "model" | "source"> | null): string | undefined;
/**
 * Render a small, soft metadata block about an agent (model, source)
 * that is appended below the agent.s own system prompt. This is purely
 * informational . it tells the model what the agent declares and where it
 * lives (e.g. the cloud backend), so it does not go hunting for agent
 * files in local folders.
 */
export declare function agentMetadataBlock(agent: Pick<AgentConfig, "name" | "description" | "systemPrompt" | "model" | "source"> | null): string;
//# sourceMappingURL=agents.d.ts.map