agentic-orchestrator 0.1.25 → 0.1.26

package/dist/apps/control-plane/application/services/notifier-service.d.ts

@@ -38,10 +38,28 @@ export interface NotificationConfig {
     channels?: NotificationChannelConfig;
     routing?: NotificationRoutingConfig;
 }
+/**
+ * Desktop notification channel using notify-send.
+ *
+ * @example
+ * ```typescript
+ * const channel = new DesktopNotifierChannel();
+ * await channel.send(payload);
+ * ```
+ */
 export declare class DesktopNotifierChannel implements NotifierChannel {
     readonly name = "desktop";
     send(payload: NotificationPayload): Promise<void>;
 }
+/**
+ * Slack notification channel using webhook.
+ *
+ * @example
+ * ```typescript
+ * const channel = new SlackNotifierChannel(webhookUrl, '#alerts');
+ * await channel.send(payload);
+ * ```
+ */
 export declare class SlackNotifierChannel implements NotifierChannel {
     readonly name = "slack";
     private readonly webhookUrl;
@@ -49,12 +67,51 @@ export declare class SlackNotifierChannel implements NotifierChannel {
     constructor(webhookUrl: string, channel: string);
     send(payload: NotificationPayload): Promise<void>;
 }
+/**
+ * Generic webhook notification channel.
+ *
+ * @example
+ * ```typescript
+ * const channel = new WebhookNotifierChannel('https://example.com/webhook');
+ * await channel.send(payload);
+ * ```
+ */
 export declare class WebhookNotifierChannel implements NotifierChannel {
     readonly name = "webhook";
     private readonly url;
     constructor(url: string);
     send(payload: NotificationPayload): Promise<void>;
 }
+/**
+ * Manages multi-channel notifications with priority routing.
+ *
+ * ## Responsibilities
+ * - Route notifications by priority (critical/warning/info)
+ * - Send to multiple channels (desktop/Slack/webhook)
+ * - Throttle duplicate notifications
+ * - Map events to priorities
+ *
+ * ## Dependencies
+ * - Notification channel implementations
+ * - Policy notification configuration
+ *
+ * ## Key Methods
+ * - `notify()` - send notification with priority routing
+ *
+ * ## Error Conditions
+ * - Channel send failures are logged but don't block
+ *
+ * @example
+ * ```typescript
+ * const notifier = new NotifierService(config, dashboardUrl);
+ * await notifier.notify('gate_failed', 'my_feature', 'Gate fast failed', { gate: 'fast' });
+ * ```
+ *
+ * ## Supported Channels
+ * - desktop: notify-send
+ * - slack: webhook
+ * - webhook: generic HTTP POST
+ */
 export declare class NotifierService {
     private readonly config;
     private readonly channels;
@@ -65,6 +122,19 @@ export declare class NotifierService {
     private buildRouting;
     private buildChannels;
     private isThrottled;
+    /**
+     * Sends notification with priority-based routing.
+     *
+     * @param event - notification event type
+     * @param featureId - optional feature identifier
+     * @param message - notification message
+     * @param details - optional additional details
+     *
+     * @example
+     * ```typescript
+     * await notifier.notify('gate_failed', 'my_feature', 'Gate fast failed', { gate: 'fast' });
+     * ```
+     */
     notify(event: NotificationEvent, context: {
         feature_id?: string;
         message: string;

package/dist/apps/control-plane/application/services/notifier-service.js

@@ -19,6 +19,15 @@ const EVENT_PRIORITY = {
     budget_alert: 'warning',
 };
 const THROTTLE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Desktop notification channel using notify-send.
+ *
+ * @example
+ * ```typescript
+ * const channel = new DesktopNotifierChannel();
+ * await channel.send(payload);
+ * ```
+ */
 export class DesktopNotifierChannel {
     name = 'desktop';
     async send(payload) {
@@ -42,6 +51,15 @@ export class DesktopNotifierChannel {
         }
     }
 }
+/**
+ * Slack notification channel using webhook.
+ *
+ * @example
+ * ```typescript
+ * const channel = new SlackNotifierChannel(webhookUrl, '#alerts');
+ * await channel.send(payload);
+ * ```
+ */
 export class SlackNotifierChannel {
     name = 'slack';
     webhookUrl;
@@ -79,6 +97,15 @@ export class SlackNotifierChannel {
         }
     }
 }
+/**
+ * Generic webhook notification channel.
+ *
+ * @example
+ * ```typescript
+ * const channel = new WebhookNotifierChannel('https://example.com/webhook');
+ * await channel.send(payload);
+ * ```
+ */
 export class WebhookNotifierChannel {
     name = 'webhook';
     url;
@@ -96,6 +123,36 @@ export class WebhookNotifierChannel {
         }
     }
 }
+/**
+ * Manages multi-channel notifications with priority routing.
+ *
+ * ## Responsibilities
+ * - Route notifications by priority (critical/warning/info)
+ * - Send to multiple channels (desktop/Slack/webhook)
+ * - Throttle duplicate notifications
+ * - Map events to priorities
+ *
+ * ## Dependencies
+ * - Notification channel implementations
+ * - Policy notification configuration
+ *
+ * ## Key Methods
+ * - `notify()` - send notification with priority routing
+ *
+ * ## Error Conditions
+ * - Channel send failures are logged but don't block
+ *
+ * @example
+ * ```typescript
+ * const notifier = new NotifierService(config, dashboardUrl);
+ * await notifier.notify('gate_failed', 'my_feature', 'Gate fast failed', { gate: 'fast' });
+ * ```
+ *
+ * ## Supported Channels
+ * - desktop: notify-send
+ * - slack: webhook
+ * - webhook: generic HTTP POST
+ */
 export class NotifierService {
     config;
     channels;
@@ -145,6 +202,19 @@ export class NotifierService {
         this.throttleCache.set(key, now);
         return false;
     }
+    /**
+     * Sends notification with priority-based routing.
+     *
+     * @param event - notification event type
+     * @param featureId - optional feature identifier
+     * @param message - notification message
+     * @param details - optional additional details
+     *
+     * @example
+     * ```typescript
+     * await notifier.notify('gate_failed', 'my_feature', 'Gate fast failed', { gate: 'fast' });
+     * ```
+     */
     async notify(event, context) {
         if (!this.config.enabled) {
             return;

package/dist/apps/control-plane/application/services/notifier-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifier-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/notifier-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notifier-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/notifier-service.ts"],"names":[],"mappings":"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"}

package/dist/apps/control-plane/application/services/patch-service.d.ts

@@ -4,6 +4,9 @@ type StateUpdater = (frontMatter: AnyRecord, body: string) => Promise<{
     frontMatter?: AnyRecord;
     body?: string;
 }>;
+/**
+ * @fileoverview Patch validation and application service.
+ */
 export interface PatchServicePort {
     getRepoRoot(): string;
     getPolicySnapshot(): AnyRecord;
@@ -20,14 +23,105 @@ export interface PatchServicePort {
     }>;
     updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
 }
+/**
+ * Manages patch validation and atomic application.
+ *
+ * ## Responsibilities
+ * - Validate unified diff format
+ * - Enforce plan area restrictions
+ * - Apply policy path rules
+ * - Verify lock requirements
+ * - Apply patches atomically to worktree
+ *
+ * ## Dependencies
+ * Depends on {@link PatchServicePort} for:
+ * - Plan and policy access
+ * - State operations
+ * - Worktree path resolution
+ *
+ * ## Key Methods
+ * - `repoApplyPatch()` - validate and apply unified diff
+ * - `validatePatchPaths()` - enforce plan/policy path rules
+ * - `assertPlanLocksHeld()` - verify required locks
+ *
+ * ## Error Conditions
+ * - PATCH_VALIDATION_FAILED - invalid diff format or path violations
+ * - LOCK_NOT_HELD - required locks not acquired
+ * - PLAN_NOT_FOUND - no accepted plan exists
+ *
+ * @example
+ * ```typescript
+ * const patchService = new PatchService(port);
+ * await patchService.repoApplyPatch('my_feature', unifiedDiff);
+ * ```
+ *
+ * ## Thread Safety
+ * Patch application is atomic within feature worktree.
+ */
 export declare class PatchService {
     private readonly port;
     private readonly gateSelectionService;
     constructor(port: PatchServicePort);
+    /**
+     * Loads accepted plan for a feature.
+     *
+     * @param featureId - feature identifier
+     * @returns Plan object or null if not found
+     */
     loadAcceptedPlan(featureId: string): Promise<AnyRecord | null>;
     requiredResourcesForPlan(plan: AnyRecord): string[];
+    /**
+     * Verifies required resource locks are held for plan.
+     *
+     * @param featureId - feature identifier
+     * @param plan - plan requiring locks
+     * @throws LOCK_NOT_HELD - required locks not held
+     */
     assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<void>;
+    /**
+     * Validates patch paths against plan areas and policy rules.
+     *
+     * Enforces:
+     * - Paths must be in plan allowed_areas
+     * - Paths must not be in plan forbidden_areas
+     * - Paths must not violate policy path rules
+     *
+     * @param featureId - feature identifier
+     * @param patch - unified diff content
+     * @param plan - accepted plan with area restrictions
+     * @throws PATCH_VALIDATION_FAILED - path violations detected
+     *
+     * @example
+     * ```typescript
+     * await patchService.validatePatchPaths('my_feature', diff, plan);
+     * ```
+     */
     validatePatchPaths(featureId: string, parsedDiff: ReturnType<typeof parseUnifiedDiff>, plan: AnyRecord | null): Promise<string[]>;
+    /**
+     * Validates and applies unified diff to feature worktree.
+     *
+     * Full validation pipeline:
+     * 1. Load accepted plan
+     * 2. Verify required locks held
+     * 3. Validate patch format
+     * 4. Enforce path restrictions
+     * 5. Apply patch atomically
+     * 6. Update state with patch metadata
+     *
+     * @param featureId - feature identifier
+     * @param patch - unified diff content
+     * @returns Success response with applied patch metadata
+     * @throws PLAN_NOT_FOUND - no accepted plan
+     * @throws LOCK_NOT_HELD - required locks not held
+     * @throws PATCH_VALIDATION_FAILED - invalid format or path violations
+     * @throws PATCH_APPLICATION_FAILED - git apply failed
+     *
+     * @example
+     * ```typescript
+     * const diff = `--- a/file.ts\n+++ b/file.ts\n...`;
+     * await patchService.repoApplyPatch('my_feature', diff);
+     * ```
+     */
     repoApplyPatch(featureId: string, unifiedDiff: string): Promise<{
         data: {
             feature_id: string;

package/dist/apps/control-plane/application/services/patch-service.js

@@ -26,6 +26,41 @@ function normalizeFromWorktree(worktreePath, repoRoot, repoRelativeFromWorktree)
     }
     return path.relative(repoRoot, absolute).replaceAll('\\\\', '/');
 }
+/**
+ * Manages patch validation and atomic application.
+ *
+ * ## Responsibilities
+ * - Validate unified diff format
+ * - Enforce plan area restrictions
+ * - Apply policy path rules
+ * - Verify lock requirements
+ * - Apply patches atomically to worktree
+ *
+ * ## Dependencies
+ * Depends on {@link PatchServicePort} for:
+ * - Plan and policy access
+ * - State operations
+ * - Worktree path resolution
+ *
+ * ## Key Methods
+ * - `repoApplyPatch()` - validate and apply unified diff
+ * - `validatePatchPaths()` - enforce plan/policy path rules
+ * - `assertPlanLocksHeld()` - verify required locks
+ *
+ * ## Error Conditions
+ * - PATCH_VALIDATION_FAILED - invalid diff format or path violations
+ * - LOCK_NOT_HELD - required locks not acquired
+ * - PLAN_NOT_FOUND - no accepted plan exists
+ *
+ * @example
+ * ```typescript
+ * const patchService = new PatchService(port);
+ * await patchService.repoApplyPatch('my_feature', unifiedDiff);
+ * ```
+ *
+ * ## Thread Safety
+ * Patch application is atomic within feature worktree.
+ */
 export class PatchService {
     port;
     gateSelectionService;
@@ -33,6 +68,12 @@ export class PatchService {
         this.port = port;
         this.gateSelectionService = new GateSelectionService(port);
     }
+    /**
+     * Loads accepted plan for a feature.
+     *
+     * @param featureId - feature identifier
+     * @returns Plan object or null if not found
+     */
     async loadAcceptedPlan(featureId) {
         const plan = await readJson(this.port.planPath(featureId), null);
         if (!plan && this.port.getPolicySnapshot().patch_policy.enforce_plan) {
@@ -61,6 +102,13 @@ export class PatchService {
         }
         return sortResourcesDeterministically(resources);
     }
+    /**
+     * Verifies required resource locks are held for plan.
+     *
+     * @param featureId - feature identifier
+     * @param plan - plan requiring locks
+     * @throws LOCK_NOT_HELD - required locks not held
+     */
     async assertPlanLocksHeld(featureId, plan) {
         const state = await this.port.readState(featureId);
         const held = new Set(readHeldLocks(state.frontMatter));
@@ -78,6 +126,24 @@ export class PatchService {
             };
         }
     }
+    /**
+     * Validates patch paths against plan areas and policy rules.
+     *
+     * Enforces:
+     * - Paths must be in plan allowed_areas
+     * - Paths must not be in plan forbidden_areas
+     * - Paths must not violate policy path rules
+     *
+     * @param featureId - feature identifier
+     * @param patch - unified diff content
+     * @param plan - accepted plan with area restrictions
+     * @throws PATCH_VALIDATION_FAILED - path violations detected
+     *
+     * @example
+     * ```typescript
+     * await patchService.validatePatchPaths('my_feature', diff, plan);
+     * ```
+     */
     async validatePatchPaths(featureId, parsedDiff, plan) {
         const policy = this.port.getPolicySnapshot();
         const repoRoot = this.port.getRepoRoot();
@@ -130,6 +196,31 @@ export class PatchService {
         }
         return normalizedTouched;
     }
+    /**
+     * Validates and applies unified diff to feature worktree.
+     *
+     * Full validation pipeline:
+     * 1. Load accepted plan
+     * 2. Verify required locks held
+     * 3. Validate patch format
+     * 4. Enforce path restrictions
+     * 5. Apply patch atomically
+     * 6. Update state with patch metadata
+     *
+     * @param featureId - feature identifier
+     * @param patch - unified diff content
+     * @returns Success response with applied patch metadata
+     * @throws PLAN_NOT_FOUND - no accepted plan
+     * @throws LOCK_NOT_HELD - required locks not held
+     * @throws PATCH_VALIDATION_FAILED - invalid format or path violations
+     * @throws PATCH_APPLICATION_FAILED - git apply failed
+     *
+     * @example
+     * ```typescript
+     * const diff = `--- a/file.ts\n+++ b/file.ts\n...`;
+     * await patchService.repoApplyPatch('my_feature', diff);
+     * ```
+     */
     async repoApplyPatch(featureId, unifiedDiff) {
         const plan = await this.loadAcceptedPlan(featureId);
         const state = await this.port.readState(featureId);

package/dist/apps/control-plane/application/services/patch-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"patch-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/patch-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"patch-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/patch-service.ts"],"names":[],"mappings":"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"}

package/dist/apps/control-plane/application/services/performance-analytics-service.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Performance analytics and outcome tracking service.
+ */
 export interface FeatureOutcome {
     feature_id: string;
     provider: string;
@@ -29,11 +32,97 @@ export interface PerformanceAnalyticsServicePort {
     analyticsPath(): string;
     getPolicySnapshot(): Record<string, unknown>;
 }
+/**
+ * Manages performance analytics and outcome tracking.
+ *
+ * ## Responsibilities
+ * - Record feature outcomes (status, retries, duration, cost)
+ * - Aggregate metrics by provider/model
+ * - Calculate success rates and averages
+ * - Provide analytics for dashboard
+ *
+ * ## Dependencies
+ * Depends on {@link PerformanceAnalyticsServicePort} for:
+ * - Analytics file path resolution
+ * - Timestamp utilities
+ *
+ * ## Key Methods
+ * - `recordOutcome()` - record feature outcome
+ * - `getAnalytics()` - retrieve aggregated metrics
+ * - `getProviderStats()` - get metrics by provider/model
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - analytics file does not exist
+ *
+ * @example
+ * ```typescript
+ * const perfService = new PerformanceAnalyticsService(port);
+ * await perfService.recordOutcome({
+ *   feature_id: 'my_feature',
+ *   status: 'merged',
+ *   provider: 'claude',
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   retries: 2,
+ *   duration_ms: 300000,
+ *   cost_usd: 1.50
+ * });
+ * const analytics = await perfService.getAnalytics();
+ * ```
+ *
+ * ## Metrics Tracked
+ * - Success rate by provider/model
+ * - Average cost per feature
+ * - Average duration per phase
+ * - Retry counts and reasons
+ */
 export declare class PerformanceAnalyticsService {
     private readonly port;
     constructor(port: PerformanceAnalyticsServicePort);
+    /**
+     * Records feature outcome for analytics.
+     *
+     * @param outcome - outcome data (status, retries, duration, cost, provider, model)
+     * @returns Updated analytics snapshot
+     *
+     * @example
+     * ```typescript
+     * await perfService.recordOutcome({
+     *   feature_id: 'my_feature',
+     *   status: 'merged',
+     *   provider: 'claude',
+     *   model: 'claude-3-5-sonnet-20241022',
+     *   retries: 2,
+     *   duration_ms: 300000,
+     *   cost_usd: 1.50
+     * });
+     * ```
+     */
     recordOutcome(outcome: FeatureOutcome): Promise<AnalyticsSnapshot>;
+    /**
+     * Retrieves aggregated performance analytics.
+     *
+     * @returns Analytics snapshot with provider/model metrics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await perfService.getAnalytics();
+     * console.log(analytics.by_provider);
+     * ```
+     */
     getAnalytics(): Promise<AnalyticsSnapshot>;
+    /**
+     * Retrieves provider/model statistics with optional filtering.
+     *
+     * @param provider - optional provider filter
+     * @param model - optional model filter
+     * @returns Array of provider/model stats
+     *
+     * @example
+     * ```typescript
+     * const stats = await perfService.getProviderStats('claude');
+     * console.log(stats[0].success_rate);
+     * ```
+     */
     getProviderStats(provider?: string, model?: string): Promise<ProviderModelStats[]>;
     private readSnapshot;
 }