/**
 * Agent Types - Role definitions for AI agents in the orchestration system
 *
 * This module defines the core types for agents in the Stoneforge Smithy:
 * - AgentRole: The primary role classification (director, steward, worker)
 * - WorkerMode: Whether a worker is ephemeral (short-lived) or persistent
 * - StewardFocus: The specialty area for steward agents (merge, docs, custom)
 * - StewardTrigger: How stewards are activated (cron or event)
 *
 * Agents are stored as Entity elements with additional metadata in their
 * `metadata` field to track orchestrator-specific properties.
 */
import type { EntityId, ChannelId, Timestamp, ElementId } from '@stoneforge/core';
/**
 * The primary role classification for agents in the orchestration system.
 *
 * - `director`: Strategic agent that creates and assigns tasks, reports to Human
 * - `steward`: Support agent that performs maintenance tasks (merge, docs, custom)
 * - `worker`: Execution agent that produces code and completes tasks
 */
export type AgentRole = 'director' | 'steward' | 'worker';
/**
 * All valid agent role values
 */
export declare const AgentRoleValues: readonly ["director", "steward", "worker"];
/**
 * Type guard to check if a value is a valid AgentRole
 */
export declare function isAgentRole(value: unknown): value is AgentRole;
/**
 * The lifecycle mode for worker agents.
 *
 * - `ephemeral`: Short-lived workers spawned per task, reports to Director
 * - `persistent`: Long-lived workers that can handle multiple tasks, reports to Human
 */
export type WorkerMode = 'ephemeral' | 'persistent';
/**
 * All valid worker mode values
 */
export declare const WorkerModeValues: readonly ["ephemeral", "persistent"];
/**
 * Type guard to check if a value is a valid WorkerMode
 */
export declare function isWorkerMode(value: unknown): value is WorkerMode;
/**
 * The specialty area for steward agents.
 *
 * - `merge`: Handles merging completed branches, running tests, cleanup
 * - `docs`: Scans and fixes documentation issues, auto-merges fixes
 * - `recovery`: Diagnoses and recovers tasks left in broken state by workers
 * - `custom`: User-defined steward with a custom playbook and trigger configuration
 */
export type StewardFocus = 'merge' | 'docs' | 'recovery' | 'custom';
/**
 * All valid steward focus values
 */
export declare const StewardFocusValues: readonly ["merge", "docs", "recovery", "custom"];
/**
 * Type guard to check if a value is a valid StewardFocus
 */
export declare function isStewardFocus(value: unknown): value is StewardFocus;
/**
 * Cron-based trigger for stewards - activates on a schedule
 */
export interface CronTrigger {
    /** Trigger type discriminator */
    readonly type: 'cron';
    /** Cron expression (e.g., "0 2 * * *" for 2 AM daily) */
    readonly schedule: string;
}
/**
 * Event-based trigger for stewards - activates when matching events occur
 */
export interface EventTrigger {
    /** Trigger type discriminator */
    readonly type: 'event';
    /** Event name to listen for (e.g., "task_completed", "branch_ready") */
    readonly event: string;
    /** Optional JavaScript-like condition expression */
    readonly condition?: string;
}
/**
 * Steward trigger - either cron-based or event-based
 */
export type StewardTrigger = CronTrigger | EventTrigger;
/**
 * Type guard to check if a trigger is a CronTrigger
 */
export declare function isCronTrigger(trigger: StewardTrigger): trigger is CronTrigger;
/**
 * Type guard to check if a trigger is an EventTrigger
 */
export declare function isEventTrigger(trigger: StewardTrigger): trigger is EventTrigger;
/**
 * Type guard to check if a value is a valid StewardTrigger
 */
export declare function isStewardTrigger(value: unknown): value is StewardTrigger;
/**
 * Base metadata shared by all agent types
 */
export interface BaseAgentMetadata {
    /** The agent's role in the orchestration system */
    readonly agentRole: AgentRole;
    /** Direct channel ID for receiving messages */
    readonly channelId?: ChannelId;
    /** Provider session ID for resumption */
    readonly sessionId?: string;
    /** Path to the agent's worktree (for workers) */
    readonly worktree?: string;
    /** Current session status */
    readonly sessionStatus?: 'idle' | 'running' | 'suspended' | 'terminated';
    /** Timestamp of last activity */
    readonly lastActivityAt?: Timestamp;
    /**
     * Maximum number of tasks this agent can work on concurrently.
     * Default is 1 for most agents.
     */
    readonly maxConcurrentTasks?: number;
    /**
     * Reference to the role definition Document that defines this agent's
     * system prompt and behavioral configuration. If not set, the agent
     * uses default behavior.
     */
    readonly roleDefinitionRef?: ElementId;
    /** Agent provider name (e.g., 'claude-code', 'opencode'). Defaults to 'claude-code'. */
    readonly provider?: string;
    /** Model identifier to use (e.g., 'claude-sonnet-4-20250514'). If not set, uses provider default. */
    readonly model?: string;
    /** Custom executable path for the agent's provider CLI (e.g., '/usr/local/bin/claude'). If not set, uses provider default. */
    readonly executablePath?: string;
}
/**
 * Director-specific metadata
 */
export interface DirectorMetadata extends BaseAgentMetadata {
    readonly agentRole: 'director';
}
/**
 * Worker-specific metadata
 */
export interface WorkerMetadata extends BaseAgentMetadata {
    readonly agentRole: 'worker';
    /** Whether this is an ephemeral or persistent worker */
    readonly workerMode: WorkerMode;
    /** Current branch the worker is working on */
    readonly branch?: string;
}
/**
 * Steward-specific metadata
 */
export interface StewardMetadata extends BaseAgentMetadata {
    readonly agentRole: 'steward';
    /** The steward's specialty area */
    readonly stewardFocus: StewardFocus;
    /** Triggers that activate this steward */
    readonly triggers?: StewardTrigger[];
    /**
     * Custom playbook content (markdown/plain text) for 'custom' stewards.
     * Describes what the steward should do when triggered.
     * Only used when stewardFocus is 'custom'.
     * @deprecated Prefer `playbookId` for new stewards. Kept for backward compatibility.
     */
    readonly playbook?: string;
    /**
     * Reference to a Workflow Template (playbook) for 'custom' stewards.
     * Preferred over inline `playbook`. The template content is resolved at execution time.
     */
    readonly playbookId?: string;
    /** Timestamp of last execution */
    readonly lastExecutedAt?: Timestamp;
    /** Timestamp of next scheduled execution (for cron triggers) */
    readonly nextScheduledAt?: Timestamp;
}
/**
 * Union type for all agent metadata types
 */
export type AgentMetadata = DirectorMetadata | WorkerMetadata | StewardMetadata;
/**
 * Type guard to check if metadata is DirectorMetadata
 */
export declare function isDirectorMetadata(metadata: AgentMetadata): metadata is DirectorMetadata;
/**
 * Type guard to check if metadata is WorkerMetadata
 */
export declare function isWorkerMetadata(metadata: AgentMetadata): metadata is WorkerMetadata;
/**
 * Type guard to check if metadata is StewardMetadata
 */
export declare function isStewardMetadata(metadata: AgentMetadata): metadata is StewardMetadata;
/**
 * Input for registering a Director agent
 */
export interface RegisterDirectorInput {
    /** Agent name (must be unique) */
    readonly name: string;
    /** Optional tags for the agent entity */
    readonly tags?: string[];
    /** Entity ID of the creator (usually a human) */
    readonly createdBy: EntityId;
    /** Maximum concurrent tasks (default: 1) */
    readonly maxConcurrentTasks?: number;
    /** Optional reference to a role definition for system prompt and behaviors */
    readonly roleDefinitionRef?: ElementId;
    /** Agent provider (e.g., 'claude-code', 'opencode'). Defaults to 'claude-code'. */
    readonly provider?: string;
    /** Model identifier to use (e.g., 'claude-sonnet-4-20250514'). If not set, uses provider default. */
    readonly model?: string;
    /** Custom executable path for the agent's provider CLI. If not set, uses provider default. */
    readonly executablePath?: string;
}
/**
 * Input for registering a Worker agent
 */
export interface RegisterWorkerInput {
    /** Agent name (must be unique) */
    readonly name: string;
    /** Whether this is an ephemeral or persistent worker */
    readonly workerMode: WorkerMode;
    /** Optional tags for the agent entity */
    readonly tags?: string[];
    /** Entity ID of the creator */
    readonly createdBy: EntityId;
    /** Optional manager entity (Director for ephemeral, Human for persistent) */
    readonly reportsTo?: EntityId;
    /** Maximum concurrent tasks (default: 1) */
    readonly maxConcurrentTasks?: number;
    /** Optional reference to a role definition for system prompt and behaviors */
    readonly roleDefinitionRef?: ElementId;
    /** Agent provider (e.g., 'claude-code', 'opencode'). Defaults to 'claude-code'. */
    readonly provider?: string;
    /** Model identifier to use (e.g., 'claude-sonnet-4-20250514'). If not set, uses provider default. */
    readonly model?: string;
    /** Custom executable path for the agent's provider CLI. If not set, uses provider default. */
    readonly executablePath?: string;
}
/**
 * Input for registering a Steward agent
 */
export interface RegisterStewardInput {
    /** Agent name (must be unique) */
    readonly name: string;
    /** The steward's specialty area */
    readonly stewardFocus: StewardFocus;
    /** Triggers that activate this steward */
    readonly triggers?: StewardTrigger[];
    /**
     * Custom playbook content (markdown/plain text) for 'custom' stewards.
     * Describes what the steward should do when triggered.
     * @deprecated Prefer `playbookId` for new stewards. Kept for backward compatibility.
     */
    readonly playbook?: string;
    /**
     * Reference to a Workflow Template (playbook) for 'custom' stewards.
     * Preferred over inline `playbook`. The template content is resolved at execution time.
     */
    readonly playbookId?: string;
    /** Optional tags for the agent entity */
    readonly tags?: string[];
    /** Entity ID of the creator */
    readonly createdBy: EntityId;
    /** Optional manager entity (usually the Director) */
    readonly reportsTo?: EntityId;
    /** Maximum concurrent tasks (default: 1) */
    readonly maxConcurrentTasks?: number;
    /** Optional reference to a role definition for system prompt and behaviors */
    readonly roleDefinitionRef?: ElementId;
    /** Agent provider (e.g., 'claude-code', 'opencode'). Defaults to 'claude-code'. */
    readonly provider?: string;
    /** Model identifier to use (e.g., 'claude-sonnet-4-20250514'). If not set, uses provider default. */
    readonly model?: string;
    /** Custom executable path for the agent's provider CLI. If not set, uses provider default. */
    readonly executablePath?: string;
}
/**
 * Filter options for querying agents
 */
export interface AgentFilter {
    /** Filter by role */
    readonly role?: AgentRole;
    /** Filter by worker mode (only applies when role is 'worker') */
    readonly workerMode?: WorkerMode;
    /** Filter by steward focus (only applies when role is 'steward') */
    readonly stewardFocus?: StewardFocus;
    /** Filter by session status */
    readonly sessionStatus?: 'idle' | 'running' | 'suspended' | 'terminated';
    /** Filter by manager */
    readonly reportsTo?: EntityId;
    /** Include only agents with sessions */
    readonly hasSession?: boolean;
}
/**
 * Validates agent metadata structure
 */
export declare function validateAgentMetadata(metadata: unknown): metadata is AgentMetadata;
//# sourceMappingURL=agent.d.ts.map