agentic-orchestrator 0.1.25 → 0.1.26

package/apps/control-plane/src/application/services/reporting-service.ts

@@ -19,6 +19,10 @@ function createCollisionFingerprint(collisions: unknown): string {
   return stableHash(JSON.stringify(collisions));
 }
 
+/**
+ * @fileoverview Dashboard and feature summary reporting service.
+ */
+
 export interface ReportingServicePort {
   collectAcceptedPlans(excludeFeatureId?: string | null): Promise<AnyRecord[]>;
   getPolicySnapshot(): AnyRecord;
@@ -31,6 +35,44 @@ export interface ReportingServicePort {
   qaTestIndexGet(featureId: string): Promise<{ data: AnyRecord }>;
 }
 
+/**
+ * Manages dashboard and feature summary generation.
+ *
+ * ## Responsibilities
+ * - Generate report.dashboard with global index snapshot
+ * - Generate report.feature_summary with per-feature details
+ * - Aggregate cost and PR metadata
+ * - Provide gate profile summaries
+ *
+ * ## Dependencies
+ * Depends on {@link ReportingServicePort} for:
+ * - Index and state access
+ * - Cost and analytics data
+ * - PR monitor integration
+ * - Collision detection
+ *
+ * ## Key Methods
+ * - `reportDashboard()` - generate global dashboard
+ * - `reportFeatureSummary()` - generate per-feature summary
+ * - `collisionsScan()` - detect collisions across features
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - feature state or index missing
+ *
+ * @example
+ * ```typescript
+ * const reportingService = new ReportingService(port);
+ * const dashboard = await reportingService.reportDashboard();
+ * const summary = await reportingService.reportFeatureSummary('my_feature');
+ * ```
+ *
+ * ## Dashboard Contents
+ * - Active/blocked/merged feature counts
+ * - Lock ownership
+ * - Runtime session metadata
+ * - Cost analytics
+ * - PR status (if integrated)
+ */
 export class ReportingService {
   private readonly port: ReportingServicePort;
 
@@ -38,6 +80,17 @@ export class ReportingService {
     this.port = port;
   }
 
+  /**
+   * Detects collisions across all accepted plans.
+   *
+   * @returns Collision matrix with conflicts by feature
+   *
+   * @example
+   * ```typescript
+   * const collisions = await reportingService.collisionsScan();
+   * console.log(collisions.data.has_collisions);
+   * ```
+   */
   async collisionsScan() {
     const plans = await this.port.collectAcceptedPlans();
     const matrix = [];
@@ -69,6 +122,18 @@ export class ReportingService {
     };
   }
 
+  /**
+   * Generates global orchestration dashboard.
+   *
+   * @returns Dashboard with active/blocked/merged features, locks, costs, PR metadata
+   *
+   * @example
+   * ```typescript
+   * const dashboard = await reportingService.reportDashboard();
+   * console.log(dashboard.data.active);
+   * console.log(dashboard.data.locks);
+   * ```
+   */
   async reportDashboard() {
     const index = await this.port.readIndex();
     const featureIds = normalizeSet([
@@ -120,6 +185,20 @@ export class ReportingService {
     };
   }
 
+  /**
+   * Generates per-feature summary report.
+   *
+   * @param featureId - feature identifier
+   * @returns Feature summary with state, diff, evidence, costs, QA index
+   * @throws FILE_NOT_FOUND - feature does not exist
+   *
+   * @example
+   * ```typescript
+   * const summary = await reportingService.reportFeatureSummary('my_feature');
+   * console.log(summary.data.state);
+   * console.log(summary.data.diff);
+   * ```
+   */
   async reportFeatureSummary(featureId: string | null) {
     const state = await this.port.featureStateGet(featureId as unknown as string);
     const bundle = await this.port.repoDiffBundle(featureId as unknown as string);

package/apps/control-plane/src/application/services/run-lease-service.ts

@@ -43,6 +43,45 @@ export interface RunLeaseServicePort {
   emptyRuntimeSessions(at?: string): RuntimeSessionsSnapshot;
 }
 
+/**
+ * Manages run lease acquisition, renewal, and release.
+ *
+ * ## Responsibilities
+ * - Acquire exclusive run lease for orchestrator instance
+ * - Renew lease heartbeat to prevent staleness
+ * - Release lease on shutdown
+ * - Track orchestrator and feature session assignments
+ * - Prune stale session assignments
+ *
+ * ## Dependencies
+ * Depends on {@link RunLeaseServicePort} for:
+ * - Run lease file operations
+ * - Index operations
+ * - Lease TTL configuration
+ *
+ * ## Key Methods
+ * - `acquireRunLease()` - acquire exclusive run lease
+ * - `renewRunLease()` - renew lease heartbeat
+ * - `releaseRunLease()` - release lease
+ * - `updateOrchestratorSession()` - update orchestrator session metadata
+ * - `updateFeatureSessionAssignment()` - assign feature to sessions
+ * - `pruneFeatureSessionAssignments()` - remove stale assignments
+ *
+ * ## Error Conditions
+ * - RUN_ALREADY_ACTIVE - another instance holds fresh lease
+ * - STALE_LEASE - lease expired (can be taken over)
+ *
+ * @example
+ * ```typescript
+ * const leaseService = new RunLeaseService(port);
+ * const lease = await leaseService.acquireRunLease({
+ *   run_id: 'run_123',
+ *   owner_instance_id: 'instance_abc',
+ *   takeover_stale: false
+ * });
+ * await leaseService.renewRunLease(lease.data.run_id, lease.data.owner_instance_id);
+ * ```
+ */
 export class RunLeaseService {
   private readonly port: RunLeaseServicePort;
 
@@ -50,6 +89,22 @@ export class RunLeaseService {
     this.port = port;
   }
 
+  /**
+   * Acquires exclusive run lease for orchestrator instance.
+   *
+   * @param input - acquisition parameters (run_id, owner_instance_id, takeover_stale)
+   * @returns Lease acquisition result
+   * @throws RUN_ALREADY_ACTIVE - another instance holds fresh lease
+   *
+   * @example
+   * ```typescript
+   * const lease = await leaseService.acquireRunLease({
+   *   run_id: 'run_123',
+   *   owner_instance_id: 'instance_abc',
+   *   takeover_stale: false
+   * });
+   * ```
+   */
   async acquireRunLease(input: AcquireRunLeaseInput): Promise<{
     data: {
       runtime_sessions: RuntimeSessionsSnapshot;
@@ -152,6 +207,18 @@ export class RunLeaseService {
     });
   }
 
+  /**
+   * Renews run lease heartbeat to prevent staleness.
+   *
+   * @param runId - run identifier
+   * @param ownerInstanceId - instance identifier
+   * @returns Renewal result
+   *
+   * @example
+   * ```typescript
+   * await leaseService.renewRunLease('run_123', 'instance_abc');
+   * ```
+   */
   async renewRunLease(
     runId: string,
     ownerInstanceId: string,
@@ -204,6 +271,18 @@ export class RunLeaseService {
     });
   }
 
+  /**
+   * Releases run lease on shutdown.
+   *
+   * @param runId - run identifier
+   * @param ownerInstanceId - instance identifier
+   * @returns Release result
+   *
+   * @example
+   * ```typescript
+   * await leaseService.releaseRunLease('run_123', 'instance_abc');
+   * ```
+   */
   async releaseRunLease(
     runId: string,
     ownerInstanceId: string,

package/apps/control-plane/src/application/tools/tool-router.ts

@@ -1,29 +1,97 @@
+/**
+ * Context provided to tool handlers during execution.
+ *
+ * Contains actor identity information for authorization and logging.
+ */
 export interface ToolHandlerContext {
+  /** Actor type (e.g., 'orchestrator', 'planner', 'builder', 'qa', 'system') */
   actorType: string;
+  /** Unique actor identifier (e.g., session ID) */
   actorId: string;
 }
 
+/**
+ * Tool handler function signature.
+ *
+ * @param args - tool arguments (validated against input schema)
+ * @param context - execution context with actor identity
+ * @returns tool response (validated against output schema)
+ */
 export type ToolHandler = (
   args: Record<string, unknown>,
   context: ToolHandlerContext,
 ) => Promise<unknown>;
 
+/**
+ * Registry for tool handlers using Map-based dispatch.
+ *
+ * ## Purpose
+ * Provides O(1) handler lookup without switch statements.
+ * Enables dynamic tool registration and metadata-driven routing.
+ *
+ * ## Usage
+ * ```typescript
+ * const registry = new ToolHandlerRegistry();
+ * registry.register('feature.init', async (args, context) => {
+ *   return await featureInit(args);
+ * });
+ * const handler = registry.lookup('feature.init');
+ * ```
+ */
 export class ToolHandlerRegistry {
   private readonly handlers = new Map<string, ToolHandler>();
 
+  /**
+   * Registers a tool handler.
+   *
+   * @param toolName - tool identifier (e.g., 'feature.init')
+   * @param handler - handler function
+   */
   register(toolName: string, handler: ToolHandler): void {
     this.handlers.set(toolName, handler);
   }
 
+  /**
+   * Looks up a tool handler.
+   *
+   * @param toolName - tool identifier
+   * @returns handler function or undefined if not registered
+   */
   lookup(toolName: string): ToolHandler | undefined {
     return this.handlers.get(toolName);
   }
 }
 
+/**
+ * Routes tool calls to registered handlers.
+ *
+ * ## Responsibilities
+ * - Look up handler in registry
+ * - Invoke handler with args and context
+ * - Delegate to unknown tool handler if not found
+ *
+ * ## Error Handling
+ * Unknown tools are handled by the provided unknownToolHandler,
+ * which typically returns a normalized error response.
+ *
+ * @example
+ * ```typescript
+ * const router = new ToolRouter(registry, async (toolName) => {
+ *   return fail(ERROR_CODES.INVALID_ARGUMENT, `Unknown tool ${toolName}`);
+ * });
+ * const result = await router.route('feature.init', args, context);
+ * ```
+ */
 export class ToolRouter {
   private readonly registry: ToolHandlerRegistry;
   private readonly unknownToolHandler: (toolName: string) => Promise<unknown>;
 
+  /**
+   * Creates a new tool router.
+   *
+   * @param registry - handler registry
+   * @param unknownToolHandler - fallback for unknown tools
+   */
   constructor(
     registry: ToolHandlerRegistry,
     unknownToolHandler: (toolName: string) => Promise<unknown>,
@@ -32,6 +100,14 @@ export class ToolRouter {
     this.unknownToolHandler = unknownToolHandler;
   }
 
+  /**
+   * Routes a tool call to the appropriate handler.
+   *
+   * @param toolName - tool identifier
+   * @param args - tool arguments
+   * @param context - execution context
+   * @returns tool response
+   */
   async route(
     toolName: string,
     args: Record<string, unknown>,

package/apps/control-plane/src/mcp/tool-runtime.ts

@@ -78,6 +78,10 @@ function isFailResponse(response: ToolResponse): response is FailResponse {
   return response.ok === false;
 }
 
+/**
+ * @fileoverview MCP tool execution runtime with schema validation and authorization.
+ */
+
 export class ToolRuntime {
   readonly registry: LoadedToolRegistry;
   readonly loader: ToolRegistryLoader;

package/apps/control-plane/src/providers/providers.ts

@@ -4,6 +4,10 @@ import { ERROR_CODES } from '../core/error-codes.js';
 import { REGISTERED_PROVIDER_NAMES } from '../application/adapters/adapter-registry.js';
 import { PROVIDER_CLI_DEFAULTS, type ProviderCommandTemplate } from './provider-defaults.js';
 
+/**
+ * @fileoverview Worker provider interfaces and credential resolution.
+ */
+
 export interface AppError extends Error {
   code?: string;
   details?: Record<string, unknown>;
@@ -205,23 +209,90 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
   };
 };
 
+/**
+ * Worker session metadata.
+ *
+ * Represents an active agent session with role and feature assignment.
+ */
 export interface WorkerSession {
+  /** Unique session identifier */
   session_id: string;
+  /** Agent role (orchestrator, planner, builder, qa) */
   role: string;
+  /** Feature identifier (empty for orchestrator) */
   feature_id: string;
+  /** Whether system prompt was loaded */
   system_prompt_loaded: boolean;
 }
 
+/**
+ * Worker provider interface for agent session management.
+ *
+ * ## Contract
+ * All providers must implement:
+ * - Session lifecycle (create, close, reattach)
+ * - Worker execution with tool support
+ * - Optional message sending and session attachment
+ *
+ * ## Session Management
+ * - createSession: initialize new agent session with system prompt
+ * - closeSession: terminate session and cleanup resources
+ * - reattachSession: reconnect to existing session (if supported)
+ *
+ * ## Worker Execution
+ * - runWorker: execute agent with context and instructions
+ * - Returns tool calls and text responses
+ * - Supports iterative execution with last_tool_results
+ *
+ * ## Optional Features
+ * - sendMessage: send message to active session (interactive mode)
+ * - attachToSession: attach to session for real-time interaction
+ * - getSessionInfo: query session status
+ *
+ * @see CliWorkerProvider - CLI-based implementation
+ * @see ApiWorkerProvider - API-based implementation
+ */
 export interface WorkerProvider {
+  /** Provider mode (live or stub for testing) */
   mode: 'live' | 'stub';
+  /** Provider selection (provider, model, credentials) */
   selection: ProviderSelection;
+
+  /**
+   * Creates a new agent session.
+   *
+   * @param role - agent role (orchestrator, planner, builder, qa)
+   * @param featureId - feature identifier (empty for orchestrator)
+   * @param systemPrompt - role-specific system prompt (null = no prompt)
+   * @returns Session metadata
+   */
   createSession(
     role: string,
     featureId: string,
     systemPrompt: string | null,
   ): Promise<WorkerSession>;
+
+  /**
+   * Reattaches to an existing session.
+   *
+   * @param sessionId - session identifier
+   * @returns Session metadata or null if not found
+   */
   reattachSession(sessionId: string): Promise<WorkerSession | null>;
+
+  /**
+   * Closes a session and cleans up resources.
+   *
+   * @param sessionId - session identifier
+   */
   closeSession(sessionId: string): Promise<{ closed: true }>;
+
+  /**
+   * Executes worker with context and instructions.
+   *
+   * @param input - execution input with role, feature, context, instructions
+   * @returns Worker output with tool calls and text
+   */
   runWorker(input: {
     role: string;
     feature_id: string;
@@ -234,11 +305,36 @@ export interface WorkerProvider {
       provider_config_ref: string | null;
     };
   }): Promise<Record<string, unknown>>;
+
+  /**
+   * Sends a message to an active session (optional).
+   *
+   * @param sessionId - session identifier
+   * @param message - message text
+   */
   sendMessage?(sessionId: string, message: string): Promise<void>;
+
+  /**
+   * Attaches to a session for interactive mode (optional).
+   *
+   * @param sessionId - session identifier
+   */
   attachToSession?(sessionId: string): Promise<void>;
+
+  /**
+   * Queries session status (optional).
+   *
+   * @param sessionId - session identifier
+   * @returns Session status
+   */
   getSessionInfo?(sessionId: string): Promise<{ active: boolean; provider: string }>;
 }
 
+/**
+ * Provider capability flags.
+ *
+ * Indicates which optional features a provider supports.
+ */
 export interface WorkerCapabilities {
   supportsIdleDetection: boolean;
   supportsSpawnDetection: boolean;

package/apps/control-plane/src/providers/worker-provider-factory.ts

@@ -15,6 +15,10 @@ import {
   GenericCliOutputParser,
 } from './output-parsers/index.js';
 
+/**
+ * @fileoverview Worker provider factory for instantiating CLI and API providers.
+ */
+
 export type WorkerProviderMode = 'live' | 'stub';
 export type ProviderCommandContext = 'run' | 'resume' | 'send' | 'attach';
 

package/apps/control-plane/src/supervisor/build-wave-executor.ts

@@ -71,6 +71,10 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
   ERROR_CODES.PROVIDER_HARD_TIMEOUT,
 ]);
 
+/**
+ * @fileoverview Build phase wave executor.
+ */
+
 export class BuildWaveExecutor {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly workerDecisionRunner: WorkerDecisionRunner;

package/apps/control-plane/src/supervisor/planning-wave-executor.ts

@@ -139,6 +139,10 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
   ERROR_CODES.PROVIDER_HARD_TIMEOUT,
 ]);
 
+/**
+ * @fileoverview Planning phase wave executor.
+ */
+
 export class PlanningWaveExecutor {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly planGenerator: InitialPlanGenerator;

package/apps/control-plane/src/supervisor/qa-wave-executor.ts

@@ -85,6 +85,10 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
   ERROR_CODES.PROVIDER_HARD_TIMEOUT,
 ]);
 
+/**
+ * @fileoverview QA phase wave executor.
+ */
+
 export class QaWaveExecutor {
   private readonly kernel: FeatureOrchestrationPort;
   private readonly provider: WorkerProvider;

package/apps/control-plane/src/supervisor/run-coordinator.ts

@@ -39,6 +39,10 @@ interface RunCoordinatorDependencies {
   issueTracker?: IssueTracker;
 }
 
+/**
+ * @fileoverview Feature queue coordination and status transition detection.
+ */
+
 export class RunCoordinator {
   private readonly kernel: FeatureOrchestrationPort & RuntimeStateReader;
   private readonly provider: WorkerProvider;

package/apps/control-plane/src/supervisor/runtime.ts

@@ -79,6 +79,10 @@ function resolveAdapterName(
   }
 }
 
+/**
+ * @fileoverview Multi-agent supervisor runtime for orchestrating feature development.
+ */
+
 export class SupervisorRuntime
   implements SupervisorToolCaller, AgentPromptProvider, InitialPlanGenerator, FeatureClusterPatcher
 {

package/apps/control-plane/src/supervisor/session-orchestrator.ts

@@ -20,6 +20,10 @@ interface SessionOrchestratorDependencies {
   state: SupervisorRuntimeState;
 }
 
+/**
+ * @fileoverview Session lifecycle management for agent clusters.
+ */
+
 export class SessionOrchestrator {
   private readonly kernel: SupervisorKernelPort;
   private readonly runtimeStateReader: RuntimeStateReader;