@shepai/cli 1.8.1 → 1.9.0

package/dist/src/application/ports/output/agent-executor-factory.interface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Agent Executor Factory Interface
+ *
+ * Output port for creating agent executor instances based on agent type.
+ * Infrastructure layer provides concrete implementations that wire up
+ * the appropriate executor for each supported agent.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * const factory: IAgentExecutorFactory = container.resolve('IAgentExecutorFactory');
+ * const supported = factory.getSupportedAgents();
+ * const executor = factory.createExecutor(AgentType.ClaudeCode, settings.agent);
+ * ```
+ */
+import type { AgentType, AgentConfig } from '../../../domain/generated/output.js';
+import type { IAgentExecutor } from './agent-executor.interface.js';
+/**
+ * Port interface for creating agent executor instances.
+ *
+ * Implementations must:
+ * - Create the correct executor for the given agent type
+ * - Configure the executor with the provided auth configuration
+ * - Report which agent types are supported
+ */
+export interface IAgentExecutorFactory {
+    /**
+     * Create an executor for the specified agent type.
+     *
+     * @param agentType - The type of agent to create an executor for
+     * @param authConfig - Agent authentication and configuration
+     * @returns A configured agent executor
+     */
+    createExecutor(agentType: AgentType, authConfig: AgentConfig): IAgentExecutor;
+    /**
+     * Get the list of agent types this factory can create executors for.
+     *
+     * @returns Array of supported agent types
+     */
+    getSupportedAgents(): AgentType[];
+}
+//# sourceMappingURL=agent-executor-factory.interface.d.ts.map

package/dist/src/application/ports/output/agent-executor-factory.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-executor-factory.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/agent-executor-factory.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,GAAG,cAAc,CAAC;IAE9E;;;;OAIG;IACH,kBAAkB,IAAI,SAAS,EAAE,CAAC;CACnC"}

package/dist/src/application/ports/output/agent-executor-factory.interface.js

@@ -0,0 +1,19 @@
+/**
+ * Agent Executor Factory Interface
+ *
+ * Output port for creating agent executor instances based on agent type.
+ * Infrastructure layer provides concrete implementations that wire up
+ * the appropriate executor for each supported agent.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * const factory: IAgentExecutorFactory = container.resolve('IAgentExecutorFactory');
+ * const supported = factory.getSupportedAgents();
+ * const executor = factory.createExecutor(AgentType.ClaudeCode, settings.agent);
+ * ```
+ */
+export {};

package/dist/src/application/ports/output/agent-executor.interface.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Agent Executor Interface
+ *
+ * Output port for executing AI agent operations (prompts, streaming).
+ * Infrastructure layer provides concrete implementations for each agent type.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * // Resolve an executor from the factory and run a prompt
+ * const executor = factory.createExecutor(AgentType.ClaudeCode, agentConfig);
+ * const result = await executor.execute('Analyze this codebase');
+ *
+ * // Stream results for real-time output
+ * for await (const event of executor.executeStream('Implement feature X')) {
+ *   console.log(event.content);
+ * }
+ * ```
+ */
+import type { AgentType, AgentFeature } from '../../../domain/generated/output.js';
+/**
+ * Result returned after an agent execution completes.
+ */
+export interface AgentExecutionResult {
+    /** The agent's output text */
+    result: string;
+    /** Session ID for resuming conversations */
+    sessionId?: string;
+    /** Token usage statistics */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Additional metadata from the agent */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Event emitted during streamed agent execution.
+ */
+export interface AgentExecutionStreamEvent {
+    /** Event type: progress updates, final result, or error */
+    type: 'progress' | 'result' | 'error';
+    /** Event content text */
+    content: string;
+    /** When the event was emitted */
+    timestamp: Date;
+}
+/**
+ * Options for controlling agent execution behavior.
+ */
+export interface AgentExecutionOptions {
+    /** Working directory for the agent */
+    cwd?: string;
+    /** Tools the agent is allowed to use */
+    allowedTools?: string[];
+    /** Session ID to resume a previous conversation */
+    resumeSession?: string;
+    /** Maximum number of agent turns */
+    maxTurns?: number;
+    /** Model to use for execution */
+    model?: string;
+    /** System prompt to prepend */
+    systemPrompt?: string;
+    /** JSON schema for structured output */
+    outputSchema?: object;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Port interface for executing prompts against an AI agent.
+ *
+ * Implementations must:
+ * - Execute prompts and return structured results
+ * - Support streaming execution via async iterables
+ * - Report which agent features are supported
+ *
+ * @example
+ * ```typescript
+ * const executor: IAgentExecutor = container.resolve('IAgentExecutor');
+ * if (executor.supportsFeature(AgentFeature.Streaming)) {
+ *   for await (const event of executor.executeStream('Plan this feature')) {
+ *     process.stdout.write(event.content);
+ *   }
+ * }
+ * ```
+ */
+export interface IAgentExecutor {
+    /** The type of agent this executor handles */
+    readonly agentType: AgentType;
+    /**
+     * Execute a prompt and return the complete result.
+     *
+     * @param prompt - The prompt to send to the agent
+     * @param options - Optional execution configuration
+     * @returns The agent's execution result
+     */
+    execute(prompt: string, options?: AgentExecutionOptions): Promise<AgentExecutionResult>;
+    /**
+     * Execute a prompt and stream events as they arrive.
+     *
+     * @param prompt - The prompt to send to the agent
+     * @param options - Optional execution configuration
+     * @returns An async iterable of stream events
+     */
+    executeStream(prompt: string, options?: AgentExecutionOptions): AsyncIterable<AgentExecutionStreamEvent>;
+    /**
+     * Check if this executor supports a specific agent feature.
+     *
+     * @param feature - The feature to check
+     * @returns true if the feature is supported
+     */
+    supportsFeature(feature: AgentFeature): boolean;
+}
+//# sourceMappingURL=agent-executor.interface.d.ts.map

package/dist/src/application/ports/output/agent-executor.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-executor.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/agent-executor.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAE9B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAExF;;;;;;OAMG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,aAAa,CAAC,yBAAyB,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;CACjD"}

package/dist/src/application/ports/output/agent-executor.interface.js

@@ -0,0 +1,23 @@
+/**
+ * Agent Executor Interface
+ *
+ * Output port for executing AI agent operations (prompts, streaming).
+ * Infrastructure layer provides concrete implementations for each agent type.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * // Resolve an executor from the factory and run a prompt
+ * const executor = factory.createExecutor(AgentType.ClaudeCode, agentConfig);
+ * const result = await executor.execute('Analyze this codebase');
+ *
+ * // Stream results for real-time output
+ * for await (const event of executor.executeStream('Implement feature X')) {
+ *   console.log(event.content);
+ * }
+ * ```
+ */
+export {};

package/dist/src/application/ports/output/agent-registry.interface.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Agent Registry Interface
+ *
+ * Output port for managing agent workflow definitions. The registry holds
+ * all registered agent definitions including their LangGraph graph factories,
+ * enabling runtime discovery and instantiation of agent workflows.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * const registry: IAgentRegistry = container.resolve('IAgentRegistry');
+ *
+ * // Register an agent definition with its graph factory
+ * registry.register({
+ *   name: 'analyze-repository',
+ *   description: 'Analyze repository structure and technologies',
+ *   graphFactory: () => createAnalyzeGraph(),
+ * });
+ *
+ * // Look up a registered agent
+ * const agent = registry.get('analyze-repository');
+ * if (agent) {
+ *   const graph = agent.graphFactory();
+ * }
+ *
+ * // List all registered agents
+ * const agents = registry.list();
+ * ```
+ */
+import type { AgentDefinition } from '../../../domain/generated/output.js';
+/**
+ * Extended agent definition that includes a graph factory function.
+ *
+ * Extends the TypeSpec-generated AgentDefinition with a runtime-only
+ * `graphFactory` property that creates LangGraph StateGraph instances.
+ * This property is TypeScript-only and not represented in TypeSpec
+ * since it's a runtime concern.
+ */
+export interface AgentDefinitionWithFactory extends AgentDefinition {
+    /** Factory function that creates the LangGraph StateGraph for this agent */
+    graphFactory: (...args: any[]) => any;
+}
+/**
+ * Port interface for managing agent workflow registrations.
+ *
+ * Implementations must:
+ * - Store agent definitions keyed by name
+ * - Prevent duplicate registrations (or overwrite silently)
+ * - Return undefined for unknown agent names
+ *
+ * @example
+ * ```typescript
+ * const registry: IAgentRegistry = container.resolve('IAgentRegistry');
+ *
+ * // Register agents at application startup
+ * registry.register({
+ *   name: 'gather-requirements',
+ *   description: 'Gather and refine user requirements',
+ *   graphFactory: createRequirementsGraph,
+ * });
+ *
+ * // Query available agents
+ * const all = registry.list();
+ * console.log(`${all.length} agents registered`);
+ * ```
+ */
+export interface IAgentRegistry {
+    /**
+     * Register an agent definition with the registry.
+     *
+     * @param definition - The agent definition including its graph factory
+     */
+    register(definition: AgentDefinitionWithFactory): void;
+    /**
+     * Retrieve a registered agent definition by name.
+     *
+     * @param name - The unique agent name (e.g., 'analyze-repository')
+     * @returns The agent definition, or undefined if not registered
+     */
+    get(name: string): AgentDefinitionWithFactory | undefined;
+    /**
+     * List all registered agent definitions.
+     *
+     * @returns Array of all registered agent definitions
+     */
+    list(): AgentDefinitionWithFactory[];
+}
+//# sourceMappingURL=agent-registry.interface.d.ts.map

package/dist/src/application/ports/output/agent-registry.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/agent-registry.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE3E;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA2B,SAAQ,eAAe;IACjE,4EAA4E;IAE5E,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAEvD;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,GAAG,SAAS,CAAC;IAE1D;;;;OAIG;IACH,IAAI,IAAI,0BAA0B,EAAE,CAAC;CACtC"}

package/dist/src/application/ports/output/agent-registry.interface.js

@@ -0,0 +1,33 @@
+/**
+ * Agent Registry Interface
+ *
+ * Output port for managing agent workflow definitions. The registry holds
+ * all registered agent definitions including their LangGraph graph factories,
+ * enabling runtime discovery and instantiation of agent workflows.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * const registry: IAgentRegistry = container.resolve('IAgentRegistry');
+ *
+ * // Register an agent definition with its graph factory
+ * registry.register({
+ *   name: 'analyze-repository',
+ *   description: 'Analyze repository structure and technologies',
+ *   graphFactory: () => createAnalyzeGraph(),
+ * });
+ *
+ * // Look up a registered agent
+ * const agent = registry.get('analyze-repository');
+ * if (agent) {
+ *   const graph = agent.graphFactory();
+ * }
+ *
+ * // List all registered agents
+ * const agents = registry.list();
+ * ```
+ */
+export {};

package/dist/src/application/ports/output/agent-run-repository.interface.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Agent Run Repository Interface
+ *
+ * Output port for AgentRun persistence operations.
+ * Implementations handle database-specific logic (SQLite, etc.).
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ */
+import type { AgentRun, AgentRunStatus } from '../../../domain/generated/output.js';
+/**
+ * Repository interface for AgentRun entity persistence.
+ *
+ * Implementations must:
+ * - Handle database connection management
+ * - Provide thread-safe operations
+ * - Support query by thread ID and PID for crash recovery
+ */
+export interface IAgentRunRepository {
+    /**
+     * Create a new agent run record.
+     *
+     * @param agentRun - The agent run to persist
+     */
+    create(agentRun: AgentRun): Promise<void>;
+    /**
+     * Find an agent run by its unique ID.
+     *
+     * @param id - The agent run ID
+     * @returns The agent run or null if not found
+     */
+    findById(id: string): Promise<AgentRun | null>;
+    /**
+     * Find an agent run by its LangGraph thread ID.
+     *
+     * @param threadId - The LangGraph thread ID
+     * @returns The agent run or null if not found
+     */
+    findByThreadId(threadId: string): Promise<AgentRun | null>;
+    /**
+     * Update agent run status with optional additional field updates.
+     *
+     * @param id - The agent run ID
+     * @param status - The new status
+     * @param updates - Optional additional fields to update
+     */
+    updateStatus(id: string, status: AgentRunStatus, updates?: Partial<AgentRun>): Promise<void>;
+    /**
+     * Find all running agent runs for a given process ID.
+     * Used for crash recovery to detect orphaned processes.
+     *
+     * @param pid - The process ID to search for
+     * @returns Array of running agent runs with the given PID
+     */
+    findRunningByPid(pid: number): Promise<AgentRun[]>;
+    /**
+     * List all agent runs.
+     *
+     * @returns Array of all agent runs
+     */
+    list(): Promise<AgentRun[]>;
+    /**
+     * Delete an agent run by ID.
+     *
+     * @param id - The agent run ID to delete
+     */
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=agent-run-repository.interface.d.ts.map

package/dist/src/application/ports/output/agent-run-repository.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-run-repository.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/agent-run-repository.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAEpF;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAE3D;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7F;;;;;;OAMG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEnD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC"}

package/dist/src/application/ports/output/agent-run-repository.interface.js

@@ -0,0 +1,11 @@
+/**
+ * Agent Run Repository Interface
+ *
+ * Output port for AgentRun persistence operations.
+ * Implementations handle database-specific logic (SQLite, etc.).
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ */
+export {};

package/dist/src/application/ports/output/agent-runner.interface.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Agent Runner Interface
+ *
+ * Output port for running named agent workflows (e.g., analyze-repository,
+ * gather-requirements). The runner resolves the agent from the registry
+ * and orchestrates execution, producing an AgentRun record.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * const runner: IAgentRunner = container.resolve('IAgentRunner');
+ * const run = await runner.runAgent('analyze-repository', 'Analyze the codebase', {
+ *   repositoryPath: '/path/to/repo',
+ *   model: 'claude-sonnet-4-5-20250929',
+ *   timeout: 60000,
+ * });
+ * console.log(run.status); // 'running' | 'completed' | 'failed'
+ * ```
+ */
+import type { AgentRun, AgentRunEvent } from '../../../domain/generated/output.js';
+/**
+ * Options for controlling agent run behavior.
+ */
+export interface AgentRunOptions {
+    /** Working directory / repository path for the agent */
+    repositoryPath?: string;
+    /** Model to use for this run */
+    model?: string;
+    /** Session ID to resume a previous agent session */
+    resumeSession?: string;
+    /** Whether to run the agent in the background */
+    background?: boolean;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Port interface for running named agent workflows.
+ *
+ * Implementations must:
+ * - Resolve the agent by name from the registry
+ * - Execute the agent graph with the provided prompt and options
+ * - Return a fully-populated AgentRun record
+ *
+ * @example
+ * ```typescript
+ * const runner: IAgentRunner = container.resolve('IAgentRunner');
+ *
+ * // Run an agent with default options
+ * const run = await runner.runAgent('gather-requirements', 'What are the user needs?');
+ *
+ * // Run with specific options
+ * const run = await runner.runAgent('implement-feature', 'Build the login form', {
+ *   repositoryPath: '/workspace/my-app',
+ *   background: true,
+ *   timeout: 120000,
+ * });
+ * ```
+ */
+export interface IAgentRunner {
+    /**
+     * Run a named agent workflow with the given prompt.
+     *
+     * @param agentName - The registered agent name (e.g., 'analyze-repository')
+     * @param prompt - The prompt to send to the agent
+     * @param options - Optional run configuration
+     * @returns The agent run record tracking execution
+     */
+    runAgent(agentName: string, prompt: string, options?: AgentRunOptions): Promise<AgentRun>;
+    /**
+     * Run a named agent workflow and stream events as they arrive.
+     *
+     * @param agentName - The registered agent name (e.g., 'analyze-repository')
+     * @param prompt - The prompt to send to the agent
+     * @param options - Optional run configuration
+     * @returns An async iterable of agent run events
+     */
+    runAgentStream(agentName: string, prompt: string, options?: AgentRunOptions): AsyncIterable<AgentRunEvent>;
+}
+//# sourceMappingURL=agent-runner.interface.d.ts.map

package/dist/src/application/ports/output/agent-runner.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.interface.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/agent-runner.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1F;;;;;;;OAOG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,eAAe,GACxB,aAAa,CAAC,aAAa,CAAC,CAAC;CACjC"}

package/dist/src/application/ports/output/agent-runner.interface.js

@@ -0,0 +1,23 @@
+/**
+ * Agent Runner Interface
+ *
+ * Output port for running named agent workflows (e.g., analyze-repository,
+ * gather-requirements). The runner resolves the agent from the registry
+ * and orchestrates execution, producing an AgentRun record.
+ *
+ * Following Clean Architecture:
+ * - Domain and Application layers depend on this interface
+ * - Infrastructure layer provides concrete implementations
+ *
+ * @example
+ * ```typescript
+ * const runner: IAgentRunner = container.resolve('IAgentRunner');
+ * const run = await runner.runAgent('analyze-repository', 'Analyze the codebase', {
+ *   repositoryPath: '/path/to/repo',
+ *   model: 'claude-sonnet-4-5-20250929',
+ *   timeout: 60000,
+ * });
+ * console.log(run.status); // 'running' | 'completed' | 'failed'
+ * ```
+ */
+export {};

package/dist/src/application/ports/output/index.d.ts

@@ -8,4 +8,9 @@ export type { ISettingsRepository } from './settings.repository.interface.js';
 export type { IAgentValidator, AgentValidationResult } from './agent-validator.interface.js';
 export type { IVersionService } from './version-service.interface.js';
 export type { IWebServerService } from './web-server-service.interface.js';
+export type { IAgentExecutor, AgentExecutionResult, AgentExecutionStreamEvent, AgentExecutionOptions, } from './agent-executor.interface.js';
+export type { IAgentExecutorFactory } from './agent-executor-factory.interface.js';
+export type { IAgentRunner, AgentRunOptions } from './agent-runner.interface.js';
+export type { IAgentRegistry, AgentDefinitionWithFactory } from './agent-registry.interface.js';
+export type { IAgentRunRepository } from './agent-run-repository.interface.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/application/ports/output/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC7F,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/application/ports/output/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC7F,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AACnF,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACjF,YAAY,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChG,YAAY,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/src/application/use-cases/agents/run-agent.use-case.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Run Agent Use Case
+ *
+ * Executes a named agent workflow by resolving it from the registry
+ * and delegating to the agent runner.
+ *
+ * Business Rules:
+ * - Agent must be registered in the registry before running
+ * - Error messages include available agent names for discoverability
+ * - Options are passed through to the runner as-is
+ */
+import type { AgentRun, AgentRunEvent } from '../../../domain/generated/output.js';
+import type { IAgentRunner, AgentRunOptions } from '../../ports/output/agent-runner.interface.js';
+import type { IAgentRegistry } from '../../ports/output/agent-registry.interface.js';
+/**
+ * Input for running an agent workflow.
+ */
+export interface RunAgentInput {
+    agentName: string;
+    prompt: string;
+    options?: AgentRunOptions;
+}
+/**
+ * Use case for running a named agent workflow.
+ *
+ * Algorithm:
+ * 1. Validate agent exists in the registry
+ * 2. Delegate to agent runner with name, prompt, and options
+ * 3. Return the resulting AgentRun record
+ */
+export declare class RunAgentUseCase {
+    private readonly agentRunner;
+    private readonly agentRegistry;
+    constructor(agentRunner: IAgentRunner, agentRegistry: IAgentRegistry);
+    /**
+     * Execute the run agent use case.
+     *
+     * @param input - Agent run input including name, prompt, and options
+     * @returns AgentRun record tracking the execution
+     * @throws Error if the agent name is not registered
+     */
+    execute(input: RunAgentInput): Promise<AgentRun>;
+    /**
+     * Execute the run agent use case with streaming events.
+     *
+     * @param input - Agent run input including name, prompt, and options
+     * @returns An async iterable of agent run events
+     * @throws Error if the agent name is not registered
+     */
+    executeStream(input: RunAgentInput): AsyncIterable<AgentRunEvent>;
+}
+//# sourceMappingURL=run-agent.use-case.d.ts.map

package/dist/src/application/use-cases/agents/run-agent.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.use-case.d.ts","sourceRoot":"","sources":["../../../../../src/application/use-cases/agents/run-agent.use-case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAC;AAClG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gDAAgD,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,qBACa,eAAe;IAGxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAE5B,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAFb,WAAW,EAAE,YAAY,EAEzB,aAAa,EAAE,cAAc;IAGhD;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAYtD;;;;;;OAMG;IACI,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAAC,aAAa,CAAC;CAWzE"}