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.
- package/dist/base-agent.d.ts +172 -0
- package/dist/base-agent.d.ts.map +1 -0
- package/dist/base-agent.js +255 -0
- package/dist/base-agent.js.map +1 -0
- package/dist/base-bot.d.ts +282 -0
- package/dist/base-bot.d.ts.map +1 -0
- package/dist/base-bot.js +375 -0
- package/dist/base-bot.js.map +1 -0
- package/dist/common/result.d.ts +51 -0
- package/dist/common/result.d.ts.map +1 -0
- package/dist/common/result.js +45 -0
- package/dist/common/result.js.map +1 -0
- package/dist/common/types.d.ts +57 -0
- package/dist/common/types.d.ts.map +1 -0
- package/dist/common/types.js +42 -0
- package/dist/common/types.js.map +1 -0
- package/dist/index.d.ts +94 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +108 -0
- package/dist/index.js.map +1 -0
- package/dist/kadi-event-publisher.d.ts +163 -0
- package/dist/kadi-event-publisher.d.ts.map +1 -0
- package/dist/kadi-event-publisher.js +286 -0
- package/dist/kadi-event-publisher.js.map +1 -0
- package/dist/memory/arcadedb-adapter.d.ts +159 -0
- package/dist/memory/arcadedb-adapter.d.ts.map +1 -0
- package/dist/memory/arcadedb-adapter.js +314 -0
- package/dist/memory/arcadedb-adapter.js.map +1 -0
- package/dist/memory/file-storage-adapter.d.ts +122 -0
- package/dist/memory/file-storage-adapter.d.ts.map +1 -0
- package/dist/memory/file-storage-adapter.js +352 -0
- package/dist/memory/file-storage-adapter.js.map +1 -0
- package/dist/memory/memory-service.d.ts +208 -0
- package/dist/memory/memory-service.d.ts.map +1 -0
- package/dist/memory/memory-service.js +410 -0
- package/dist/memory/memory-service.js.map +1 -0
- package/dist/memory/types.d.ts +126 -0
- package/dist/memory/types.d.ts.map +1 -0
- package/dist/memory/types.js +41 -0
- package/dist/memory/types.js.map +1 -0
- package/dist/producer-tool-utils.d.ts +474 -0
- package/dist/producer-tool-utils.d.ts.map +1 -0
- package/dist/producer-tool-utils.js +664 -0
- package/dist/producer-tool-utils.js.map +1 -0
- package/dist/providers/anthropic-provider.d.ts +160 -0
- package/dist/providers/anthropic-provider.d.ts.map +1 -0
- package/dist/providers/anthropic-provider.js +527 -0
- package/dist/providers/anthropic-provider.js.map +1 -0
- package/dist/providers/model-manager-provider.d.ts +91 -0
- package/dist/providers/model-manager-provider.d.ts.map +1 -0
- package/dist/providers/model-manager-provider.js +355 -0
- package/dist/providers/model-manager-provider.js.map +1 -0
- package/dist/providers/provider-manager.d.ts +111 -0
- package/dist/providers/provider-manager.d.ts.map +1 -0
- package/dist/providers/provider-manager.js +337 -0
- package/dist/providers/provider-manager.js.map +1 -0
- package/dist/providers/types.d.ts +145 -0
- package/dist/providers/types.d.ts.map +1 -0
- package/dist/providers/types.js +23 -0
- package/dist/providers/types.js.map +1 -0
- package/dist/shadow-agent-factory.d.ts +623 -0
- package/dist/shadow-agent-factory.d.ts.map +1 -0
- package/dist/shadow-agent-factory.js +1117 -0
- package/dist/shadow-agent-factory.js.map +1 -0
- package/dist/types/agent-config.d.ts +307 -0
- package/dist/types/agent-config.d.ts.map +1 -0
- package/dist/types/agent-config.js +15 -0
- package/dist/types/agent-config.js.map +1 -0
- package/dist/types/event-schemas.d.ts +358 -0
- package/dist/types/event-schemas.d.ts.map +1 -0
- package/dist/types/event-schemas.js +188 -0
- package/dist/types/event-schemas.js.map +1 -0
- package/dist/types/tool-schemas.d.ts +498 -0
- package/dist/types/tool-schemas.d.ts.map +1 -0
- package/dist/types/tool-schemas.js +457 -0
- package/dist/types/tool-schemas.js.map +1 -0
- package/dist/utils/logger.d.ts +135 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +205 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/timer.d.ts +186 -0
- package/dist/utils/timer.d.ts.map +1 -0
- package/dist/utils/timer.js +211 -0
- package/dist/utils/timer.js.map +1 -0
- package/dist/worker-agent-factory.d.ts +688 -0
- package/dist/worker-agent-factory.d.ts.map +1 -0
- package/dist/worker-agent-factory.js +1517 -0
- package/dist/worker-agent-factory.js.map +1 -0
- 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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"}
|