agentic-orchestrator 0.1.25 → 0.1.26

package/agentic/orchestrator/defaults/policy.defaults.yaml

@@ -171,6 +171,7 @@ cleanup:
 dashboard:
   enabled: true
   port: 3000
+  quick_launch: false
 notifications:
   enabled: false
   channels:

package/agentic/orchestrator/policy.yaml

@@ -193,6 +193,7 @@ rbac:
 dashboard:
   enabled: true
   port: 3000
+  quick_launch: false
 reactions:
   gate_failed:
     enabled: true

package/agentic/orchestrator/schemas/policy.schema.json

@@ -496,6 +496,10 @@
           "minimum": 1,
           "maximum": 65535,
           "description": "Port the dashboard HTTP server listens on."
+        },
+        "quick_launch": {
+          "type": "boolean",
+          "description": "Enables dashboard quick-launch feature creation flow (`POST /api/run`)."
         }
       }
     },

package/agentic/orchestrator/schemas/policy.user.schema.json

@@ -71,6 +71,10 @@
           "minimum": 1,
           "maximum": 65535,
           "description": "Port the dashboard HTTP server listens on."
+        },
+        "quick_launch": {
+          "type": "boolean",
+          "description": "Enable dashboard quick-launch feature initialization flow."
         }
       }
     },

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

@@ -42,6 +42,36 @@ type ActivityFrontMatter = FeatureStateFrontMatter & {
 
 const DEFAULT_IDLE_THRESHOLD_MS = 300_000;
 
+/**
+ * Monitors feature activity and detects stuck agents.
+ *
+ * ## Responsibilities
+ * - Track last activity timestamp per feature
+ * - Detect idle/stuck agents based on threshold
+ * - Notify when agents are stuck
+ * - Persist activity state to feature metadata
+ *
+ * ## Dependencies
+ * - {@link SupervisorToolCaller} - for tool invocation
+ * - {@link NotifierService} - for stuck agent notifications
+ * - Operation ledger - for activity tracking
+ *
+ * ## Key Methods
+ * - `getActivityState()` - get current activity snapshot
+ * - `checkAndNotifyStuck()` - check if stuck and notify
+ *
+ * ## Error Conditions
+ * - Activity persistence failures are logged but don't block
+ *
+ * @example
+ * ```typescript
+ * const monitor = new ActivityMonitorService({ toolCaller, notifier });
+ * const state = await monitor.getActivityState('my_feature');
+ * if (state.state === 'idle') {
+ *   await monitor.checkAndNotifyStuck('my_feature');
+ * }
+ * ```
+ */
 export class ActivityMonitorService {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly operationLedger:
@@ -152,6 +182,12 @@ export class ActivityMonitorService {
     }
   }
 
+  /**
+   * Gets current activity snapshot for a feature.
+   *
+   * @param featureId - feature identifier
+   * @returns Activity snapshot with state and last event timestamp
+   */
   async getActivityState(featureId: string): Promise<ActivitySnapshot> {
     const response = await this.toolCaller.callTool<FeatureStatePayload>(
       'orchestrator',
@@ -169,6 +205,12 @@ export class ActivityMonitorService {
     };
   }
 
+  /**
+   * Checks if agent is stuck and sends notification.
+   *
+   * @param featureId - feature identifier
+   * @returns True if stuck notification was sent
+   */
   async checkAndNotifyStuck(featureId: string): Promise<boolean> {
     const snapshot = await this.getActivityState(featureId);
     await this.persistSnapshot(featureId, snapshot);

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

@@ -59,6 +59,37 @@ export interface CollisionQueueServicePort {
   ): Promise<{ data: { feature_id: string; accepted: boolean; plan_version: number } }>;
 }
 
+/**
+ * Manages blocked feature queue and collision re-drive.
+ *
+ * ## Responsibilities
+ * - Add features to blocked queue when collisions detected
+ * - Re-drive queue when locks released or plans updated
+ * - Retry plan submission for unblocked features
+ * - Remove resolved entries from queue
+ *
+ * ## Dependencies
+ * Depends on {@link CollisionQueueServicePort} for:
+ * - Index and state operations
+ * - Plan submission
+ * - Lock primitives
+ *
+ * ## Key Methods
+ * - `reDriveBlockedQueue()` - retry blocked features
+ * - `processSingleQueueEntry()` - process one queue entry
+ * - `clearQueueEntry()` - remove entry from queue
+ *
+ * ## Error Conditions
+ * - PLAN_COLLISION - collision still exists
+ * - LOCK_NOT_HELD - required locks not available
+ *
+ * @example
+ * ```typescript
+ * const queueService = new CollisionQueueService(port);
+ * const result = await queueService.reDriveBlockedQueue();
+ * console.log(`Retried: ${result.data.retried}, Still blocked: ${result.data.still_blocked}`);
+ * ```
+ */
 export class CollisionQueueService {
   private readonly port: CollisionQueueServicePort;
 
@@ -157,6 +188,17 @@ export class CollisionQueueService {
     }
   }
 
+  /**
+   * Re-drives blocked queue to retry unblocked features.
+   *
+   * @returns Result with processed/retried/still_blocked counts
+   *
+   * @example
+   * ```typescript
+   * const result = await queueService.reDriveBlockedQueue();
+   * console.log(`Retried: ${result.data.retried}`);
+   * ```
+   */
   async reDriveBlockedQueue(): Promise<{
     data: { processed: number; retried: number; still_blocked: number };
   }> {
@@ -219,6 +261,12 @@ export class CollisionQueueService {
     });
   }
 
+  /**
+   * Removes entry from blocked queue.
+   *
+   * @param featureId - feature identifier
+   * @returns Success response
+   */
   async clearQueueEntry(featureId: string): Promise<{ data: { removed: boolean } }> {
     return await this.port.withIndexLock(async () => {
       const index = await this.port.readIndex();

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

@@ -1,5 +1,9 @@
 import { atomicWriteJson, nowIso, readJson } from '../../core/fs.js';
 
+/**
+ * @fileoverview Cost tracking and budget enforcement service.
+ */
+
 export interface FeatureCost {
   feature_id: string;
   tokens_used: number;
@@ -25,6 +29,39 @@ export interface CostTrackingServicePort {
   getPolicySnapshot(): Record<string, unknown>;
 }
 
+/**
+ * Manages cost tracking and budget enforcement.
+ *
+ * ## Responsibilities
+ * - Record token usage and API costs per feature
+ * - Enforce per_feature_limit_usd budget
+ * - Aggregate costs by provider/model
+ * - Pause features exceeding budget
+ *
+ * ## Dependencies
+ * Depends on {@link CostTrackingServicePort} for:
+ * - Cost file path resolution
+ * - Policy budget configuration
+ *
+ * ## Key Methods
+ * - `recordCost()` - record cost entry
+ * - `getFeatureCost()` - retrieve accumulated costs
+ * - `checkBudget()` - enforce budget threshold
+ *
+ * ## Error Conditions
+ * - BUDGET_EXCEEDED - feature cost exceeds policy limit
+ * - FILE_NOT_FOUND - cost file does not exist
+ *
+ * @example
+ * ```typescript
+ * const costService = new CostTrackingService(port);
+ * await costService.recordCost('my_feature', { tokens: 1000, cost_usd: 0.02 });
+ * const costs = await costService.getFeatureCost('my_feature');
+ * ```
+ *
+ * ## Cost Format
+ * cost.json: { entries: [{ timestamp, tokens, cost_usd, provider, model }], total_usd }
+ */
 export class CostTrackingService {
   private readonly port: CostTrackingServicePort;
 
@@ -32,6 +69,18 @@ export class CostTrackingService {
     this.port = port;
   }
 
+  /**
+   * Retrieves accumulated costs for a feature.
+   *
+   * @param featureId - feature identifier
+   * @returns Cost summary with entries and total
+   *
+   * @example
+   * ```typescript
+   * const costs = await costService.getFeatureCost('my_feature');
+   * console.log(costs.total_cost_usd);
+   * ```
+   */
   async getFeatureCost(featureId: string): Promise<FeatureCost> {
     const existing = await readJson<FeatureCost>(this.port.featureCostPath(featureId), null);
     return (
@@ -44,6 +93,23 @@ export class CostTrackingService {
     );
   }
 
+  /**
+   * Records a cost entry for a feature.
+   *
+   * @param featureId - feature identifier
+   * @param entry - cost entry with tokens, USD amount, provider, model
+   * @returns Success response
+   *
+   * @example
+   * ```typescript
+   * await costService.recordCost('my_feature', {
+   *   tokens: 1000,
+   *   cost_usd: 0.02,
+   *   provider: 'claude',
+   *   model: 'claude-3-5-sonnet-20241022'
+   * });
+   * ```
+   */
   async recordCost(
     featureId: string,
     tokensDelta: number,
@@ -60,6 +126,20 @@ export class CostTrackingService {
     return updated;
   }
 
+  /**
+   * Checks if feature is within budget limits.
+   *
+   * @param featureId - feature identifier
+   * @returns Budget check result with over_budget and alert flags
+   *
+   * @example
+   * ```typescript
+   * const check = await costService.checkBudget('my_feature');
+   * if (check.over_budget) {
+   *   console.log('Budget exceeded!');
+   * }
+   * ```
+   */
   async checkBudget(featureId: string): Promise<BudgetCheckResult> {
     const policy = this.port.getPolicySnapshot();
     const budgetPolicy = (

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

@@ -155,6 +155,41 @@ export interface FeatureDeletionServicePort {
   locksRelease(resource: string, featureId: string): Promise<unknown>;
 }
 
+/**
+ * Manages feature deletion and cleanup.
+ *
+ * ## Responsibilities
+ * - Delete feature artifacts (state, plan, logs, evidence)
+ * - Remove worktree and branch (optional)
+ * - Clean up index references
+ * - Release held locks
+ * - Remove runtime session assignments
+ *
+ * ## Dependencies
+ * Depends on {@link FeatureDeletionServicePort} for:
+ * - File operations
+ * - Git operations
+ * - Index and run-lease updates
+ * - Lock release
+ *
+ * ## Key Methods
+ * - `featureDelete()` - delete feature with configurable cleanup
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - feature does not exist
+ * - RUN_ALREADY_ACTIVE - cannot delete during active run
+ * - GIT_ERROR - worktree/branch removal failed
+ *
+ * @example
+ * ```typescript
+ * const deletionService = new FeatureDeletionService(port);
+ * await deletionService.featureDelete('my_feature', {
+ *   dry_run: false,
+ *   remove_worktree: true,
+ *   remove_branch: 'safe'
+ * });
+ * ```
+ */
 export class FeatureDeletionService {
   private readonly port: FeatureDeletionServicePort;
 
@@ -162,6 +197,28 @@ export class FeatureDeletionService {
     this.port = port;
   }
 
+  /**
+   * Deletes feature artifacts with configurable cleanup options.
+   *
+   * @param featureId - feature identifier
+   * @param options - deletion options (dry_run, remove_worktree, remove_branch)
+   * @returns Deletion result with cleanup summary
+   * @throws FILE_NOT_FOUND - feature does not exist
+   * @throws RUN_ALREADY_ACTIVE - cannot delete during active run
+   *
+   * @example
+   * ```typescript
+   * // Preview deletion
+   * await deletionService.featureDelete('my_feature', { dry_run: true });
+   *
+   * // Execute deletion with worktree cleanup
+   * await deletionService.featureDelete('my_feature', {
+   *   dry_run: false,
+   *   remove_worktree: true,
+   *   remove_branch: 'safe'
+   * });
+   * ```
+   */
   async featureDelete(
     featureId: string | null,
     options: DeleteOptions = {},

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

@@ -24,6 +24,10 @@ function normalizeRepoPathForState(repoRoot: string, absolutePath: string): stri
   return relative;
 }
 
+/**
+ * @fileoverview Feature initialization and lifecycle management service.
+ */
+
 export interface FeatureLifecycleServicePort {
   getRepoRoot(): string;
   getFeaturesDir(): string;
@@ -45,6 +49,41 @@ export interface FeatureLifecycleServicePort {
   evidenceLatest(featureId: string): Promise<{ data: { latest?: unknown | null } }>;
 }
 
+/**
+ * Manages feature initialization and lifecycle.
+ *
+ * ## Responsibilities
+ * - Discover canonical feature specs
+ * - Initialize feature directories and state.md
+ * - Create feature branches and worktrees
+ * - Validate feature IDs
+ * - Handle spec ingestion (canonical and non-canonical)
+ *
+ * ## Dependencies
+ * Depends on {@link FeatureLifecycleServicePort} for:
+ * - File operations and path resolution
+ * - Index updates
+ * - State/plan/evidence access
+ *
+ * ## Key Methods
+ * - `featureDiscoverSpecs()` - discover canonical spec files
+ * - `featureInit()` - initialize feature folder and state
+ * - `featureGetContext()` - return spec + state + plan + evidence bundle
+ * - `featureLogAppend()` - append timestamped log entry
+ *
+ * ## Error Conditions
+ * - FEATURE_ALREADY_EXISTS - feature already initialized
+ * - INVALID_FEATURE_ID - feature ID format invalid
+ * - FILE_NOT_FOUND - spec or state file missing
+ *
+ * @example
+ * ```typescript
+ * const lifecycleService = new FeatureLifecycleService(port);
+ * const specs = await lifecycleService.featureDiscoverSpecs();
+ * await lifecycleService.featureInit('my_feature');
+ * const context = await lifecycleService.featureGetContext('my_feature');
+ * ```
+ */
 export class FeatureLifecycleService {
   private readonly port: FeatureLifecycleServicePort;
 
@@ -52,6 +91,11 @@ export class FeatureLifecycleService {
     this.port = port;
   }
 
+  /**
+   * Discovers canonical feature spec files.
+   *
+   * @returns Array of discovered specs with feature_id and path
+   */
   async featureDiscoverSpecs(): Promise<{
     data: { specs: Array<{ feature_id: string; spec_path: string }> };
   }> {
@@ -81,6 +125,13 @@ export class FeatureLifecycleService {
     return { data: { specs: discovered } };
   }
 
+  /**
+   * Initializes feature folder, state, branch, and worktree.
+   *
+   * @param featureId - feature identifier
+   * @returns Initialization result
+   * @throws FEATURE_ALREADY_EXISTS - feature already initialized
+   */
   async featureInit(featureId: string | null): Promise<{
     data: { feature_id: string | null; initialized: boolean; worktree_path: string };
   }> {
@@ -135,6 +186,12 @@ export class FeatureLifecycleService {
     };
   }
 
+  /**
+   * Returns complete feature context bundle.
+   *
+   * @param featureId - feature identifier
+   * @returns Context bundle with spec, state, plan, evidence, QA index
+   */
   async featureGetContext(featureId: string): Promise<{
     data: {
       feature_id: string;
@@ -163,6 +220,14 @@ export class FeatureLifecycleService {
     };
   }
 
+  /**
+   * Appends timestamped entry to feature decision log.
+   *
+   * @param featureId - feature identifier
+   * @param note - log entry content
+   * @param context - actor context
+   * @returns Success response
+   */
   async featureLogAppend(
     featureId: string,
     note: string,

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

@@ -40,12 +40,58 @@ function readVersion(frontMatter: AnyRecord): number {
   return 0;
 }
 
+/**
+ * @fileoverview Feature state persistence and version management service.
+ */
+
 export interface FeatureStateServicePort {
   withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
   readState(featureId: string): Promise<StateReadResult>;
   writeState(featureId: string, frontMatter: AnyRecord, body?: string): Promise<void>;
 }
 
+/**
+ * Manages feature state persistence with version control.
+ *
+ * ## Responsibilities
+ * - Read/write state.md files (YAML front matter + markdown body)
+ * - Parse and validate front matter
+ * - Enforce optimistic concurrency via version guards
+ * - Atomic state updates with file locking
+ *
+ * ## Dependencies
+ * Depends on {@link FeatureStateServicePort} for:
+ * - File operations and state path resolution
+ * - Feature-level locking primitives
+ *
+ * ## Key Methods
+ * - `featureStateGet()` - read parsed state
+ * - `featureStatePatch()` - update state with version guard
+ * - `updateState()` - internal atomic update with custom updater
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - state file does not exist
+ * - VERSION_CONFLICT - concurrent state update detected
+ * - INVALID_STATE_TRANSITION - illegal status transition
+ *
+ * @example
+ * ```typescript
+ * const stateService = new FeatureStateService(port);
+ * const state = await stateService.featureStateGet('my_feature');
+ * await stateService.featureStatePatch('my_feature', { status: 'building' }, 1);
+ * ```
+ *
+ * ## State Format
+ * ```markdown
+ * ---
+ * feature_id: my_feature
+ * version: 5
+ * status: building
+ * ---
+ * # Feature State
+ * Body content...
+ * ```
+ */
 export class FeatureStateService {
   private readonly port: FeatureStateServicePort;
 
@@ -53,6 +99,19 @@ export class FeatureStateService {
     this.port = port;
   }
 
+  /**
+   * Updates feature state atomically with version guard.
+   *
+   * Internal method used by public state operations. Acquires feature lock,
+   * validates version, applies updater function, and writes merged state.
+   *
+   * @param featureId - feature identifier
+   * @param expectedVersion - expected current version (null = no check)
+   * @param updater - function returning state updates
+   * @returns Updated state frontmatter
+   * @throws VERSION_CONFLICT - version mismatch
+   * @throws INVALID_STATE_TRANSITION - illegal status transition
+   */
   async updateState(
     featureId: string,
     expectedVersion: number | null,
@@ -99,6 +158,19 @@ export class FeatureStateService {
     });
   }
 
+  /**
+   * Reads and parses feature state.
+   *
+   * @param featureId - feature identifier
+   * @returns Parsed state with frontmatter and body
+   * @throws FILE_NOT_FOUND - state file does not exist
+   *
+   * @example
+   * ```typescript
+   * const state = await stateService.featureStateGet('my_feature');
+   * console.log(state.data.frontMatter.status);
+   * ```
+   */
   async featureStateGet(
     featureId: string,
   ): Promise<{ data: { front_matter: AnyRecord; body: string } }> {
@@ -111,6 +183,21 @@ export class FeatureStateService {
     };
   }
 
+  /**
+   * Updates feature state with partial updates and version guard.
+   *
+   * @param featureId - feature identifier
+   * @param updates - partial state updates
+   * @param expectedVersion - expected current version
+   * @returns Updated state
+   * @throws VERSION_CONFLICT - version mismatch
+   * @throws INVALID_STATE_TRANSITION - illegal status transition
+   *
+   * @example
+   * ```typescript
+   * await stateService.featureStatePatch('my_feature', { status: 'building' }, 1);
+   * ```
+   */
   async featureStatePatch(
     featureId: string,
     expectedVersion: number | null,

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

@@ -54,6 +54,34 @@ export interface CanonicalizedPlanInput {
   findings: GateSelectionFinding[];
 }
 
+/**
+ * Manages gate profile selection and resolution.
+ *
+ * ## Responsibilities
+ * - Select gate profile based on feature state
+ * - Resolve profile/mode configuration
+ * - Apply policy defaults and fallbacks
+ * - Auto-heal invalid state profiles
+ *
+ * ## Dependencies
+ * Depends on {@link GateSelectionServicePort} for:
+ * - Gates configuration
+ * - Policy snapshot
+ *
+ * ## Key Methods
+ * - `resolveProfileAndMode()` - resolve profile/mode configuration
+ * - `selectGateProfile()` - select profile from state or policy
+ * - `isAutoHealInvalidStateProfileEnabled()` - check auto-heal policy
+ *
+ * ## Error Conditions
+ * - INVALID_ARGUMENT - unknown profile or mode
+ *
+ * @example
+ * ```typescript
+ * const gateSelection = new GateSelectionService(port);
+ * const resolved = gateSelection.resolveProfileAndMode('fast', 'fast');
+ * ```
+ */
 export class GateSelectionService {
   private readonly port: GateSelectionServicePort;