agents-library 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of agents-library might be problematic. Click here for more details.

Files changed (89) hide show
  1. package/dist/base-agent.d.ts +172 -0
  2. package/dist/base-agent.d.ts.map +1 -0
  3. package/dist/base-agent.js +255 -0
  4. package/dist/base-agent.js.map +1 -0
  5. package/dist/base-bot.d.ts +282 -0
  6. package/dist/base-bot.d.ts.map +1 -0
  7. package/dist/base-bot.js +375 -0
  8. package/dist/base-bot.js.map +1 -0
  9. package/dist/common/result.d.ts +51 -0
  10. package/dist/common/result.d.ts.map +1 -0
  11. package/dist/common/result.js +45 -0
  12. package/dist/common/result.js.map +1 -0
  13. package/dist/common/types.d.ts +57 -0
  14. package/dist/common/types.d.ts.map +1 -0
  15. package/dist/common/types.js +42 -0
  16. package/dist/common/types.js.map +1 -0
  17. package/dist/index.d.ts +94 -0
  18. package/dist/index.d.ts.map +1 -0
  19. package/dist/index.js +108 -0
  20. package/dist/index.js.map +1 -0
  21. package/dist/kadi-event-publisher.d.ts +163 -0
  22. package/dist/kadi-event-publisher.d.ts.map +1 -0
  23. package/dist/kadi-event-publisher.js +286 -0
  24. package/dist/kadi-event-publisher.js.map +1 -0
  25. package/dist/memory/arcadedb-adapter.d.ts +159 -0
  26. package/dist/memory/arcadedb-adapter.d.ts.map +1 -0
  27. package/dist/memory/arcadedb-adapter.js +314 -0
  28. package/dist/memory/arcadedb-adapter.js.map +1 -0
  29. package/dist/memory/file-storage-adapter.d.ts +122 -0
  30. package/dist/memory/file-storage-adapter.d.ts.map +1 -0
  31. package/dist/memory/file-storage-adapter.js +352 -0
  32. package/dist/memory/file-storage-adapter.js.map +1 -0
  33. package/dist/memory/memory-service.d.ts +208 -0
  34. package/dist/memory/memory-service.d.ts.map +1 -0
  35. package/dist/memory/memory-service.js +410 -0
  36. package/dist/memory/memory-service.js.map +1 -0
  37. package/dist/memory/types.d.ts +126 -0
  38. package/dist/memory/types.d.ts.map +1 -0
  39. package/dist/memory/types.js +41 -0
  40. package/dist/memory/types.js.map +1 -0
  41. package/dist/producer-tool-utils.d.ts +474 -0
  42. package/dist/producer-tool-utils.d.ts.map +1 -0
  43. package/dist/producer-tool-utils.js +664 -0
  44. package/dist/producer-tool-utils.js.map +1 -0
  45. package/dist/providers/anthropic-provider.d.ts +160 -0
  46. package/dist/providers/anthropic-provider.d.ts.map +1 -0
  47. package/dist/providers/anthropic-provider.js +527 -0
  48. package/dist/providers/anthropic-provider.js.map +1 -0
  49. package/dist/providers/model-manager-provider.d.ts +91 -0
  50. package/dist/providers/model-manager-provider.d.ts.map +1 -0
  51. package/dist/providers/model-manager-provider.js +355 -0
  52. package/dist/providers/model-manager-provider.js.map +1 -0
  53. package/dist/providers/provider-manager.d.ts +111 -0
  54. package/dist/providers/provider-manager.d.ts.map +1 -0
  55. package/dist/providers/provider-manager.js +337 -0
  56. package/dist/providers/provider-manager.js.map +1 -0
  57. package/dist/providers/types.d.ts +145 -0
  58. package/dist/providers/types.d.ts.map +1 -0
  59. package/dist/providers/types.js +23 -0
  60. package/dist/providers/types.js.map +1 -0
  61. package/dist/shadow-agent-factory.d.ts +623 -0
  62. package/dist/shadow-agent-factory.d.ts.map +1 -0
  63. package/dist/shadow-agent-factory.js +1117 -0
  64. package/dist/shadow-agent-factory.js.map +1 -0
  65. package/dist/types/agent-config.d.ts +307 -0
  66. package/dist/types/agent-config.d.ts.map +1 -0
  67. package/dist/types/agent-config.js +15 -0
  68. package/dist/types/agent-config.js.map +1 -0
  69. package/dist/types/event-schemas.d.ts +358 -0
  70. package/dist/types/event-schemas.d.ts.map +1 -0
  71. package/dist/types/event-schemas.js +188 -0
  72. package/dist/types/event-schemas.js.map +1 -0
  73. package/dist/types/tool-schemas.d.ts +498 -0
  74. package/dist/types/tool-schemas.d.ts.map +1 -0
  75. package/dist/types/tool-schemas.js +457 -0
  76. package/dist/types/tool-schemas.js.map +1 -0
  77. package/dist/utils/logger.d.ts +135 -0
  78. package/dist/utils/logger.d.ts.map +1 -0
  79. package/dist/utils/logger.js +205 -0
  80. package/dist/utils/logger.js.map +1 -0
  81. package/dist/utils/timer.d.ts +186 -0
  82. package/dist/utils/timer.d.ts.map +1 -0
  83. package/dist/utils/timer.js +211 -0
  84. package/dist/utils/timer.js.map +1 -0
  85. package/dist/worker-agent-factory.d.ts +688 -0
  86. package/dist/worker-agent-factory.d.ts.map +1 -0
  87. package/dist/worker-agent-factory.js +1517 -0
  88. package/dist/worker-agent-factory.js.map +1 -0
  89. package/package.json +38 -0
@@ -0,0 +1,623 @@
1
+ /**
2
+ * Shadow Agent Factory
3
+ * =====================
4
+ *
5
+ * Factory for creating shadow agents (backup/monitoring agents) with
6
+ * configuration-driven instantiation and shared infrastructure.
7
+ *
8
+ * Architecture Pattern: **Composition over Inheritance**
9
+ * - BaseShadowAgent COMPOSES with BaseBot (does NOT extend)
10
+ * - Uses delegation pattern to access BaseBot's circuit breaker and retry logic
11
+ * - This avoids tight coupling and allows flexible behavior customization
12
+ *
13
+ * Design Principles:
14
+ * - Factory pattern for consistent agent creation
15
+ * - Composition over inheritance for flexibility
16
+ * - Template method pattern for lifecycle management (start/stop)
17
+ * - Observer pattern for filesystem and git ref watching
18
+ *
19
+ * Shadow Agent Responsibilities:
20
+ * - Monitor worker agent worktrees for file changes
21
+ * - Create granular backup commits in shadow worktrees
22
+ * - Mirror worker commits to shadow branch
23
+ * - Publish backup events to KĀDI broker
24
+ *
25
+ * @module shadow-agent-factory
26
+ */
27
+ import { KadiClient, z } from '@kadi.build/core';
28
+ import type { ShadowAgentConfig } from './types/agent-config.js';
29
+ import { BaseAgent } from './base-agent.js';
30
+ /**
31
+ * Base class for shadow agents (backup/monitoring agents)
32
+ *
33
+ * **CIRCUIT BREAKER PATTERN**: This class implements its own circuit breaker for git operations.
34
+ * - Tracks consecutive failures and opens circuit after threshold
35
+ * - Prevents cascading failures from overwhelming the system
36
+ * - Auto-resets circuit after timeout period
37
+ * - Provides resilient git operations with retry logic
38
+ *
39
+ * Why Not Use BaseBot?
40
+ * - BaseBot is designed for chat bots and requires Anthropic API key
41
+ * - Shadow agents don't need Claude integration, just git operations
42
+ * - Simpler, focused circuit breaker implementation for git-specific needs
43
+ *
44
+ * Shadow Agent Architecture:
45
+ * 1. **Filesystem Watcher**: Monitors worker worktree for file operations (create/modify/delete)
46
+ * 2. **Git Ref Watcher**: Monitors worker commits to mirror them in shadow worktree
47
+ * 3. **Atomic Git Operations**: add + commit for each monitored event
48
+ * 4. **Circuit Breaker**: Error handling with retry and fallback via BaseBot
49
+ * 5. **Event Publishing**: Publishes backup completion/failure events
50
+ *
51
+ * Lifecycle:
52
+ * 1. Constructor: Initialize configuration and compose utilities
53
+ * 2. start(): Connect to broker, initialize watchers, subscribe to events
54
+ * 3. [Monitoring happens asynchronously via filesystem/git watchers]
55
+ * 4. stop(): Cleanup watchers, unsubscribe, disconnect from broker
56
+ *
57
+ * @example
58
+ * ```typescript
59
+ * const config: ShadowAgentConfig = {
60
+ * role: 'artist',
61
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
62
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-agent-playground-artist',
63
+ * workerBranch: 'agent-artist',
64
+ * shadowBranch: 'shadow-agent-artist',
65
+ * brokerUrl: 'ws://localhost:8080/kadi',
66
+ * networks: ['kadi'],
67
+ * debounceMs: 1000
68
+ * };
69
+ *
70
+ * const agent = new BaseShadowAgent(config);
71
+ * await agent.start();
72
+ * // Agent now monitors worker worktree and creates shadow backups
73
+ * ```
74
+ */
75
+ export declare class BaseShadowAgent {
76
+ /**
77
+ * KĀDI client for broker communication
78
+ *
79
+ * Used for:
80
+ * - Subscribing to events
81
+ * - Publishing backup completion/failure events
82
+ * - Accessing broker protocol for tool invocation
83
+ */
84
+ protected client: KadiClient;
85
+ /**
86
+ * Agent role (matches corresponding worker agent)
87
+ *
88
+ * Used for:
89
+ * - Event payload agent identification (shadow-agent-{role})
90
+ * - Logging and identification
91
+ */
92
+ protected role: string;
93
+ /**
94
+ * Absolute path to worker agent's git worktree
95
+ *
96
+ * Shadow agent watches this directory for file changes.
97
+ * This is the source of truth for file operations.
98
+ *
99
+ * @example 'C:/p4/Personal/SD/agent-playground-artist'
100
+ */
101
+ protected workerWorktreePath: string;
102
+ /**
103
+ * Absolute path to shadow agent's git worktree
104
+ *
105
+ * Shadow agent creates mirror commits in this directory.
106
+ * Must be a separate git repository from worker worktree.
107
+ *
108
+ * @example 'C:/p4/Personal/SD/shadow-agent-playground-artist'
109
+ */
110
+ protected shadowWorktreePath: string;
111
+ /**
112
+ * Git branch name in worker worktree to monitor
113
+ *
114
+ * Shadow agent watches for commits on this branch.
115
+ *
116
+ * @example 'agent-artist'
117
+ */
118
+ protected workerBranch: string;
119
+ /**
120
+ * Git branch name in shadow worktree for mirror commits
121
+ *
122
+ * Shadow agent creates commits on this branch.
123
+ *
124
+ * @example 'shadow-agent-artist'
125
+ */
126
+ protected shadowBranch: string;
127
+ /**
128
+ * Debounce delay in milliseconds for file change events
129
+ *
130
+ * Prevents creating multiple commits for rapid file changes.
131
+ * Shadow agent waits this duration after last change before creating commit.
132
+ *
133
+ * @default 1000
134
+ */
135
+ protected debounceMs: number;
136
+ /**
137
+ * Circuit breaker state for git operations
138
+ *
139
+ * Tracks consecutive failures and blocks operations when threshold exceeded.
140
+ * Prevents cascading failures and allows system to recover.
141
+ */
142
+ private gitCircuitOpen;
143
+ /**
144
+ * Consecutive git operation failure count
145
+ *
146
+ * Incremented on each failure, reset to 0 on success.
147
+ * Circuit opens when count reaches MAX_GIT_FAILURES threshold.
148
+ */
149
+ private gitFailureCount;
150
+ /**
151
+ * Maximum git failures before circuit opens
152
+ *
153
+ * @default 5
154
+ */
155
+ private readonly MAX_GIT_FAILURES;
156
+ /**
157
+ * Circuit breaker reset timeout in milliseconds
158
+ *
159
+ * After this duration, circuit automatically closes and retries are allowed.
160
+ *
161
+ * @default 60000 (1 minute)
162
+ */
163
+ private readonly CIRCUIT_RESET_TIME;
164
+ /**
165
+ * Full agent configuration
166
+ *
167
+ * Stored for reference and potential reconfiguration.
168
+ * Currently unused but reserved for future features (e.g., hot-reloading config).
169
+ */
170
+ private readonly config;
171
+ /**
172
+ * Whether this agent delegates connection management to a BaseAgent instance.
173
+ * When true, start() skips broker connection and stop() skips disconnection.
174
+ */
175
+ private readonly usesBaseAgent;
176
+ /**
177
+ * Filesystem watcher instance for monitoring worker worktree
178
+ *
179
+ * Monitors file operations (create, modify, delete) in worker worktree.
180
+ * Null until start() is called.
181
+ */
182
+ private fsWatcher;
183
+ /**
184
+ * Git ref watcher instance for monitoring worker branch commits
185
+ *
186
+ * Watches .git/refs/heads/{workerBranch} file for commit SHA changes.
187
+ * Uses fs.watch (not chokidar) for lightweight ref monitoring.
188
+ * Null until start() is called.
189
+ */
190
+ private refWatcher;
191
+ /**
192
+ * Previous commit SHA from worker branch
193
+ *
194
+ * Stores last known commit SHA to detect actual commit changes.
195
+ * Used to differentiate real commits from other ref updates.
196
+ * Null until first commit is detected.
197
+ */
198
+ private previousCommitSha;
199
+ /**
200
+ * Set of changed file paths awaiting backup processing
201
+ *
202
+ * Stores relative file paths from worker worktree for batch processing.
203
+ * Debounced to avoid rapid-fire commits for the same file.
204
+ *
205
+ * Key: Absolute file path
206
+ * Value: Debounce timeout handle
207
+ */
208
+ private debounceMap;
209
+ /**
210
+ * Debounce timeout for git ref watcher
211
+ *
212
+ * Stores timeout handle for debouncing ref change events.
213
+ * Prevents processing rapid ref updates.
214
+ */
215
+ private refDebounceTimeout;
216
+ /**
217
+ * Create a new BaseShadowAgent instance
218
+ *
219
+ * Initializes all configuration properties and composes utility classes
220
+ * (BaseBot, KadiEventPublisher). Does NOT connect to broker or start watchers yet -
221
+ * call start() to begin monitoring.
222
+ *
223
+ * @param config - Shadow agent configuration with all required fields
224
+ *
225
+ * @example
226
+ * ```typescript
227
+ * const agent = new BaseShadowAgent({
228
+ * role: 'artist',
229
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
230
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-agent-playground-artist',
231
+ * workerBranch: 'agent-artist',
232
+ * shadowBranch: 'shadow-agent-artist',
233
+ * brokerUrl: 'ws://localhost:8080/kadi',
234
+ * networks: ['kadi'],
235
+ * debounceMs: 1000
236
+ * });
237
+ * ```
238
+ */
239
+ constructor(config: ShadowAgentConfig, baseAgent?: BaseAgent);
240
+ /**
241
+ * Start the shadow agent
242
+ *
243
+ * Performs initialization sequence:
244
+ * 1. Connect to KĀDI broker
245
+ * 2. Initialize broker protocol
246
+ * 3. Connect event publisher
247
+ * 4. Setup filesystem watcher for worker worktree
248
+ * 5. Setup git ref watcher for worker branch
249
+ * 6. Enter monitoring loop (non-blocking)
250
+ *
251
+ * After start() completes, the agent is ready to monitor file changes and create backups.
252
+ *
253
+ * @throws {Error} If broker connection fails after all retries
254
+ *
255
+ * @example
256
+ * ```typescript
257
+ * const agent = new BaseShadowAgent(config);
258
+ * await agent.start();
259
+ * console.log('Shadow agent is now monitoring worker worktree');
260
+ * ```
261
+ */
262
+ start(): Promise<void>;
263
+ /**
264
+ * Stop the shadow agent
265
+ *
266
+ * Performs cleanup sequence:
267
+ * 1. Stop filesystem watcher
268
+ * 2. Stop git ref watcher
269
+ * 3. Clear debounce timers
270
+ * 4. Disconnect event publisher
271
+ * 5. Disconnect KĀDI client
272
+ * 6. Clear protocol reference
273
+ *
274
+ * After stop() completes, the agent is fully shut down and can be safely destroyed.
275
+ *
276
+ * @example
277
+ * ```typescript
278
+ * await agent.stop();
279
+ * console.log('Shadow agent has been stopped');
280
+ * ```
281
+ */
282
+ stop(): Promise<void>;
283
+ /**
284
+ * Setup filesystem watcher for worker worktree
285
+ *
286
+ * Monitors worker worktree for file operations (create, modify, delete) using chokidar.
287
+ * File changes are debounced and stored for batch backup processing.
288
+ *
289
+ * Configuration:
290
+ * - Watches: config.workerWorktreePath
291
+ * - Excludes: .git directory, node_modules, .env files
292
+ * - Debounce: config.debounceMs (default: 1000ms)
293
+ * - Stability threshold: Waits for file writes to complete
294
+ *
295
+ * Event Handling:
296
+ * - 'add': File created in worktree
297
+ * - 'change': Existing file modified
298
+ * - 'unlink': File deleted from worktree
299
+ * - 'error': Watcher errors (logged but non-fatal)
300
+ * - 'ready': Watcher initialization complete
301
+ *
302
+ * Debouncing Strategy:
303
+ * - Stores timeout handle in debounceMap for each file
304
+ * - Clears previous timeout if file changes again before debounce completes
305
+ * - Only processes file after debounceMs of inactivity
306
+ * - Prevents rapid-fire commits for the same file
307
+ *
308
+ * @throws {Error} If watcher initialization fails
309
+ *
310
+ * @example
311
+ * ```typescript
312
+ * await this.setupFilesystemWatcher();
313
+ * // Watcher is now monitoring worker worktree for file changes
314
+ * ```
315
+ */
316
+ protected setupFilesystemWatcher(): Promise<void>;
317
+ /**
318
+ * Setup git ref watcher for worker branch commits
319
+ *
320
+ * Monitors worker branch ref file (.git/refs/heads/{workerBranch}) for commit SHA changes
321
+ * using fs.watch. Detects new commits and triggers createShadowBackup after debounce period.
322
+ *
323
+ * Architecture:
324
+ * - Uses fs.watch (not chokidar) for lightweight ref monitoring
325
+ * - Reads commit SHA from ref file on each change
326
+ * - Compares with previousCommitSha to detect actual commits
327
+ * - Debounces to handle rapid ref updates (e.g., during rebase)
328
+ * - Triggers backup only for real commit changes
329
+ *
330
+ * Ref File Location:
331
+ * - {workerWorktreePath}/.git/refs/heads/{workerBranch}
332
+ * - Contains commit SHA as plain text (40 hex characters)
333
+ * - Updated by git on each commit to branch
334
+ *
335
+ * Change Detection Strategy:
336
+ * 1. fs.watch fires on any ref file modification
337
+ * 2. Read current SHA from ref file
338
+ * 3. Compare with previousCommitSha
339
+ * 4. If different, debounce and trigger backup
340
+ * 5. Update previousCommitSha for next comparison
341
+ *
342
+ * Debouncing:
343
+ * - Uses config.debounceMs delay (default: 1000ms)
344
+ * - Clears previous timeout if ref changes again
345
+ * - Prevents multiple backups during rapid commits
346
+ *
347
+ * @throws {Error} If ref file doesn't exist or can't be watched
348
+ *
349
+ * @example
350
+ * ```typescript
351
+ * await this.setupGitRefWatcher();
352
+ * // Watcher is now monitoring worker branch for commits
353
+ * ```
354
+ */
355
+ protected setupGitRefWatcher(): Promise<void>;
356
+ /**
357
+ * Create shadow backup commit
358
+ *
359
+ * Creates a mirror commit in shadow worktree by:
360
+ * 1. Parsing latest commit from worker worktree (git log)
361
+ * 2. Getting list of changed files (git diff)
362
+ * 3. Copying changed files from worker to shadow worktree
363
+ * 4. Creating mirror commit with format: Shadow: {operation} {fileName}
364
+ *
365
+ * Uses circuit breaker pattern to prevent cascading failures on git errors.
366
+ * Publishes backup completion/failure events to KĀDI broker.
367
+ *
368
+ * @param operation - Type of operation (e.g., 'Created', 'Modified', 'Deleted', 'COMMIT')
369
+ * @param fileName - File name or commit description
370
+ *
371
+ * @example
372
+ * ```typescript
373
+ * await this.createShadowBackup('Created', 'artwork.png');
374
+ * await this.createShadowBackup('COMMIT', 'Commit abc1234');
375
+ * ```
376
+ */
377
+ protected createShadowBackup(operation: string, fileName: string): Promise<void>;
378
+ /**
379
+ * Publish backup status event to KĀDI broker
380
+ *
381
+ * Publishes standardized BackupEvent with schema compliance for both success
382
+ * and failure scenarios. Events follow generic topic pattern: backup.{completed|failed} with agent identity in payload.
383
+ *
384
+ * Uses KadiEventPublisher for resilient event publishing with connection retry logic.
385
+ * Handles publishing failures gracefully without throwing errors.
386
+ *
387
+ * @param success - True for backup success, false for failure
388
+ * @param filesBackedUp - Array of file paths that were backed up
389
+ * @param operation - Backup operation type (e.g., 'mirror-commit', 'file-create')
390
+ * @param error - Error object if backup failed (optional)
391
+ *
392
+ * @example
393
+ * ```typescript
394
+ * // Success case
395
+ * await this.publishBackupStatus(true, ['artwork.png', 'logo.svg'], 'mirror-commit');
396
+ *
397
+ * // Failure case
398
+ * await this.publishBackupStatus(false, [], 'mirror-commit', new Error('Git operation failed'));
399
+ * ```
400
+ */
401
+ protected publishBackupStatus(success: boolean, filesBackedUp: string[], operation: string, error?: Error): Promise<void>;
402
+ /**
403
+ * Check circuit breaker state for git operations
404
+ *
405
+ * Returns true if circuit is open (blocking requests).
406
+ * Circuit opens after MAX_GIT_FAILURES consecutive failures and auto-resets after CIRCUIT_RESET_TIME.
407
+ *
408
+ * @returns True if circuit is open, false if closed
409
+ *
410
+ * @example
411
+ * ```typescript
412
+ * if (this.checkCircuitBreaker()) {
413
+ * console.log('Circuit open - skipping backup operation');
414
+ * return;
415
+ * }
416
+ * ```
417
+ */
418
+ protected checkCircuitBreaker(): boolean;
419
+ /**
420
+ * Record git operation failure and potentially open circuit breaker
421
+ *
422
+ * Increments failure count and opens circuit if threshold exceeded.
423
+ * Auto-resets circuit after timeout period.
424
+ *
425
+ * @param operation - Operation name for logging
426
+ * @param error - Error that occurred
427
+ */
428
+ protected recordGitFailure(operation: string, error: Error): void;
429
+ /**
430
+ * Record git operation success and reset failure count
431
+ *
432
+ * Resets failure counter on successful operation.
433
+ */
434
+ protected recordGitSuccess(): void;
435
+ }
436
+ /**
437
+ * Zod schema for ShadowAgentConfig validation
438
+ *
439
+ * Validates all required configuration fields for shadow agent instantiation.
440
+ * Ensures type safety and provides descriptive error messages for invalid configurations.
441
+ *
442
+ * Required Fields:
443
+ * - role: Agent role type (non-empty string)
444
+ * - workerWorktreePath: Absolute path to worker agent's git worktree (non-empty string)
445
+ * - shadowWorktreePath: Absolute path to shadow agent's git worktree (non-empty string)
446
+ * - workerBranch: Git branch name in worker worktree (non-empty string)
447
+ * - shadowBranch: Git branch name in shadow worktree (non-empty string)
448
+ * - brokerUrl: KĀDI broker WebSocket URL (non-empty string)
449
+ * - networks: Array of network names (at least one network required)
450
+ *
451
+ * Optional Fields:
452
+ * - debounceMs: Debounce delay in milliseconds (positive number, default: 1000)
453
+ *
454
+ * @example
455
+ * ```typescript
456
+ * const validConfig = {
457
+ * role: 'artist',
458
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
459
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-artist-backup',
460
+ * workerBranch: 'main',
461
+ * shadowBranch: 'shadow-main',
462
+ * brokerUrl: 'ws://localhost:8080/kadi',
463
+ * networks: ['kadi'],
464
+ * debounceMs: 2000 // optional
465
+ * };
466
+ *
467
+ * ShadowAgentConfigSchema.parse(validConfig); // ✅ Passes validation
468
+ * ```
469
+ */
470
+ export declare const ShadowAgentConfigSchema: z.ZodObject<{
471
+ role: z.ZodString;
472
+ workerWorktreePath: z.ZodString;
473
+ shadowWorktreePath: z.ZodString;
474
+ workerBranch: z.ZodString;
475
+ shadowBranch: z.ZodString;
476
+ brokerUrl: z.ZodString;
477
+ networks: z.ZodArray<z.ZodString>;
478
+ debounceMs: z.ZodOptional<z.ZodNumber>;
479
+ }, z.core.$strip>;
480
+ /**
481
+ * Factory class for creating shadow agents
482
+ *
483
+ * Provides a clean API for shadow agent instantiation with validated configuration.
484
+ * Follows the same factory pattern as WorkerAgentFactory for consistency.
485
+ *
486
+ * The factory performs Zod schema validation on configuration before creating agents,
487
+ * ensuring type safety and providing descriptive error messages for invalid configurations.
488
+ *
489
+ * Usage Pattern:
490
+ * 1. Call ShadowAgentFactory.createAgent(config) with your configuration
491
+ * 2. If validation passes, receive a configured BaseShadowAgent instance
492
+ * 3. Call agent.start() to begin monitoring and backup operations
493
+ * 4. Call agent.stop() when done to cleanup resources
494
+ *
495
+ * @example Minimal Configuration
496
+ * ```typescript
497
+ * const agent = ShadowAgentFactory.createAgent({
498
+ * role: 'artist',
499
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
500
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-artist-backup',
501
+ * workerBranch: 'main',
502
+ * shadowBranch: 'shadow-main',
503
+ * brokerUrl: 'ws://localhost:8080/kadi',
504
+ * networks: ['kadi']
505
+ * });
506
+ *
507
+ * await agent.start();
508
+ * console.log('Shadow agent is now monitoring worker worktree');
509
+ * ```
510
+ *
511
+ * @example With Optional Debounce Configuration
512
+ * ```typescript
513
+ * const agent = ShadowAgentFactory.createAgent({
514
+ * role: 'designer',
515
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-designer',
516
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-designer-backup',
517
+ * workerBranch: 'develop',
518
+ * shadowBranch: 'shadow-develop',
519
+ * brokerUrl: 'ws://localhost:8080/kadi',
520
+ * networks: ['kadi', 'production'],
521
+ * debounceMs: 2000 // Wait 2 seconds after last change
522
+ * });
523
+ *
524
+ * await agent.start();
525
+ * // Agent monitors for 2 seconds after each change before creating backup
526
+ * ```
527
+ *
528
+ * @example Error Handling with Validation
529
+ * ```typescript
530
+ * try {
531
+ * const agent = ShadowAgentFactory.createAgent({
532
+ * role: '', // ❌ Empty role will fail validation
533
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
534
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-artist-backup',
535
+ * workerBranch: 'main',
536
+ * shadowBranch: 'shadow-main',
537
+ * brokerUrl: 'ws://localhost:8080/kadi',
538
+ * networks: [] // ❌ Empty networks array will fail validation
539
+ * });
540
+ * } catch (error) {
541
+ * console.error('Configuration validation failed:', error.message);
542
+ * // Output: "Role is required and cannot be empty"
543
+ * }
544
+ * ```
545
+ */
546
+ export declare class ShadowAgentFactory {
547
+ /**
548
+ * Create a shadow agent with validated configuration
549
+ *
550
+ * Static factory method for instantiating shadow agents with Zod schema validation.
551
+ * Validates all required configuration fields and provides descriptive error messages
552
+ * for invalid configurations.
553
+ *
554
+ * The method performs the following steps:
555
+ * 1. Validates configuration using ShadowAgentConfigSchema
556
+ * 2. If validation passes, creates BaseShadowAgent instance
557
+ * 3. Returns fully configured agent ready for start()
558
+ *
559
+ * Note: This method does NOT automatically start the agent. Caller must explicitly
560
+ * call agent.start() to begin monitoring and backup operations.
561
+ *
562
+ * @param config - Shadow agent configuration to validate and use
563
+ * @returns Configured BaseShadowAgent instance ready for start()
564
+ * @throws {ZodError} If configuration validation fails with detailed error messages
565
+ *
566
+ * @example Minimal Configuration
567
+ * ```typescript
568
+ * const agent = ShadowAgentFactory.createAgent({
569
+ * role: 'artist',
570
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
571
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-artist-backup',
572
+ * workerBranch: 'main',
573
+ * shadowBranch: 'shadow-main',
574
+ * brokerUrl: 'ws://localhost:8080/kadi',
575
+ * networks: ['kadi']
576
+ * });
577
+ *
578
+ * await agent.start();
579
+ * ```
580
+ *
581
+ * @example With Optional Configuration
582
+ * ```typescript
583
+ * const agent = ShadowAgentFactory.createAgent({
584
+ * role: 'programmer',
585
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-programmer',
586
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-programmer-backup',
587
+ * workerBranch: 'feature/new-api',
588
+ * shadowBranch: 'shadow-feature',
589
+ * brokerUrl: 'ws://localhost:8080/kadi',
590
+ * networks: ['kadi', 'staging'],
591
+ * debounceMs: 3000 // Custom debounce delay
592
+ * });
593
+ *
594
+ * await agent.start();
595
+ * ```
596
+ */
597
+ static createAgent(config: ShadowAgentConfig, baseAgent?: BaseAgent): BaseShadowAgent;
598
+ }
599
+ /**
600
+ * Create a shadow agent with configuration
601
+ *
602
+ * Convenience function for instantiating shadow agents.
603
+ * Delegates to ShadowAgentFactory.createAgent().
604
+ *
605
+ * @param config - Shadow agent configuration
606
+ * @returns Configured BaseShadowAgent instance
607
+ *
608
+ * @example
609
+ * ```typescript
610
+ * const agent = createShadowAgent({
611
+ * role: 'artist',
612
+ * workerWorktreePath: 'C:/p4/Personal/SD/agent-playground-artist',
613
+ * shadowWorktreePath: 'C:/p4/Personal/SD/shadow-agent-playground-artist',
614
+ * workerBranch: 'agent-artist',
615
+ * shadowBranch: 'shadow-agent-artist',
616
+ * brokerUrl: 'ws://localhost:8080/kadi',
617
+ * networks: ['kadi']
618
+ * });
619
+ * await agent.start();
620
+ * ```
621
+ */
622
+ export declare function createShadowAgent(config: ShadowAgentConfig, baseAgent?: BaseAgent): BaseShadowAgent;
623
+ //# sourceMappingURL=shadow-agent-factory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shadow-agent-factory.d.ts","sourceRoot":"","sources":["../src/shadow-agent-factory.ts"],"names":[],"mappings":"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"}