sugarai 3.0.1__tar.gz → 3.1.1.dev2__tar.gz

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.
Files changed (83) hide show
  1. {sugarai-3.0.1/sugarai.egg-info → sugarai-3.1.1.dev2}/PKG-INFO +64 -1
  2. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/README.md +63 -0
  3. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/pyproject.toml +1 -1
  4. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/agent/__init__.py +3 -0
  5. sugarai-3.1.1.dev2/sugar/agent/subagent_manager.py +329 -0
  6. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/agent/tools.py +92 -0
  7. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/integrations/github.py +9 -1
  8. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/main.py +599 -93
  9. sugarai-3.1.1.dev2/sugar/orchestration/__init__.py +25 -0
  10. sugarai-3.1.1.dev2/sugar/orchestration/agent_router.py +238 -0
  11. sugarai-3.1.1.dev2/sugar/orchestration/task_orchestrator.py +953 -0
  12. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/storage/work_queue.py +181 -8
  13. sugarai-3.1.1.dev2/sugar/utils/toon_encoder.py +159 -0
  14. {sugarai-3.0.1 → sugarai-3.1.1.dev2/sugarai.egg-info}/PKG-INFO +64 -1
  15. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugarai.egg-info/SOURCES.txt +9 -0
  16. sugarai-3.1.1.dev2/tests/test_issue_responder_cli.py +739 -0
  17. sugarai-3.1.1.dev2/tests/test_orchestration.py +1141 -0
  18. sugarai-3.1.1.dev2/tests/test_subagent_manager.py +713 -0
  19. sugarai-3.1.1.dev2/tests/test_toon_encoder.py +155 -0
  20. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/LICENSE +0 -0
  21. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/setup.cfg +0 -0
  22. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/__init__.py +0 -0
  23. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/__version__.py +0 -0
  24. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/agent/base.py +0 -0
  25. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/agent/hooks.py +0 -0
  26. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/billing/__init__.py +0 -0
  27. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/billing/api_keys.py +0 -0
  28. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/billing/tiers.py +0 -0
  29. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/billing/usage.py +0 -0
  30. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/core/__init__.py +0 -0
  31. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/core/loop.py +0 -0
  32. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/discovery/__init__.py +0 -0
  33. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/discovery/code_quality.py +0 -0
  34. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/discovery/error_monitor.py +0 -0
  35. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/discovery/github_watcher.py +0 -0
  36. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/discovery/test_coverage.py +0 -0
  37. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/executor/__init__.py +0 -0
  38. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/executor/agent_sdk_executor.py +0 -0
  39. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/executor/base.py +0 -0
  40. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/executor/claude_wrapper.py +0 -0
  41. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/executor/structured_request.py +0 -0
  42. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/integrations/__init__.py +0 -0
  43. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/learning/__init__.py +0 -0
  44. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/learning/adaptive_scheduler.py +0 -0
  45. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/learning/feedback_processor.py +0 -0
  46. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/mcp/__init__.py +0 -0
  47. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/mcp/server.py +0 -0
  48. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/profiles/__init__.py +0 -0
  49. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/profiles/base.py +0 -0
  50. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/profiles/default.py +0 -0
  51. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/profiles/issue_responder.py +0 -0
  52. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/__init__.py +0 -0
  53. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/coordinator.py +0 -0
  54. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/diff_validator.py +0 -0
  55. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/evidence.py +0 -0
  56. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/failure_handler.py +0 -0
  57. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/functional_verifier.py +0 -0
  58. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/preflight_checks.py +0 -0
  59. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/success_criteria.py +0 -0
  60. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/test_validator.py +0 -0
  61. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/quality_gates/truth_enforcer.py +0 -0
  62. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/storage/__init__.py +0 -0
  63. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/storage/task_type_manager.py +0 -0
  64. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/utils/__init__.py +0 -0
  65. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/utils/git_operations.py +0 -0
  66. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/workflow/__init__.py +0 -0
  67. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugar/workflow/orchestrator.py +0 -0
  68. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugarai.egg-info/dependency_links.txt +0 -0
  69. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugarai.egg-info/entry_points.txt +0 -0
  70. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugarai.egg-info/requires.txt +0 -0
  71. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/sugarai.egg-info/top_level.txt +0 -0
  72. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_agent.py +0 -0
  73. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_billing.py +0 -0
  74. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_cli.py +0 -0
  75. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_core_loop.py +0 -0
  76. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_goose_integration.py +0 -0
  77. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_hold_functionality.py +0 -0
  78. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_hooks.py +0 -0
  79. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_profiles.py +0 -0
  80. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_quality_gates.py +0 -0
  81. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_storage.py +0 -0
  82. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_task_types.py +0 -0
  83. {sugarai-3.0.1 → sugarai-3.1.1.dev2}/tests/test_v3_benchmarks.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sugarai
3
- Version: 3.0.1
3
+ Version: 3.1.1.dev2
4
4
  Summary: Sugar 🍰 - A dev team that never stops. Delegate full tasks to AI in the background.
5
5
  Author-email: Steven Leggett <contact@roboticforce.io>
6
6
  License: MIT
@@ -180,6 +180,12 @@ sugar list --status completed
180
180
  - Custom task types for your workflow
181
181
  - Queue management and filtering
182
182
 
183
+ **Task Orchestration** *(New in v3.0)*
184
+ - Auto-decomposes complex features into subtasks
185
+ - 4-stage workflow: Research → Planning → Implementation → Review
186
+ - Specialist agent routing (frontend, backend, QA, security, DevOps)
187
+ - Parallel execution with dependency management
188
+
183
189
  **Autonomous Execution**
184
190
  - Specialized Claude agents (UX, backend, QA)
185
191
  - Automatic retries on failures
@@ -196,6 +202,34 @@ sugar list --status completed
196
202
  - Identifies missing tests
197
203
  - Auto-creates tasks from findings
198
204
 
205
+ **Issue Responder**
206
+ - AI-powered GitHub issue analysis
207
+ - Generates contextual responses
208
+ - Confidence-based auto-posting
209
+ - Searchable issue history
210
+
211
+ ## Issue Responder
212
+
213
+ Automatically analyze and respond to GitHub issues with AI-powered insights. Sugar understands issue context, codebase structure, and project patterns to generate helpful responses.
214
+
215
+ ```bash
216
+ # List open issues
217
+ sugar issue list
218
+
219
+ # Analyze an issue
220
+ sugar issue analyze 42
221
+
222
+ # Generate AI response (preview)
223
+ sugar issue respond 42
224
+
225
+ # Generate and post if confident
226
+ sugar issue respond 42 --post
227
+ ```
228
+
229
+ The Issue Responder evaluates confidence before posting. Use `--force-post` to override the confidence check, or adjust the threshold with `--confidence-threshold`.
230
+
231
+ **Full documentation:** [docs/issue-responder.md](docs/issue-responder.md)
232
+
199
233
  ## How It Works
200
234
 
201
235
  ```
@@ -381,12 +415,41 @@ Sugar 3.0 is built natively on the **Claude Agent SDK**, providing:
381
415
 
382
416
  - **[Quick Start](docs/user/quick-start.md)** - Get running in 5 minutes
383
417
  - **[CLI Reference](docs/user/cli-reference.md)** - All commands
418
+ - **[Task Orchestration](docs/task_orchestration.md)** - Complex feature decomposition
384
419
  - **[GitHub Integration](docs/user/github-integration.md)** - Connect to GitHub
385
420
  - **[Configuration Guide](docs/user/configuration-best-practices.md)** - Best practices
386
421
  - **[Claude Code Plugin](.claude-plugin/README.md)** - Native integration
387
422
 
388
423
  ## Advanced Usage
389
424
 
425
+ **Task Orchestration**
426
+
427
+ For complex features, Sugar can automatically decompose work and route to specialist agents:
428
+
429
+ ```bash
430
+ # Add a feature that will be orchestrated
431
+ sugar add "Add user authentication with OAuth" --type feature --orchestrate
432
+
433
+ # Sugar will:
434
+ # 1. RESEARCH - Search best practices, analyze codebase
435
+ # 2. PLAN - Create implementation plan with subtasks
436
+ # 3. IMPLEMENT - Route subtasks to specialists in parallel
437
+ # 4. REVIEW - Code review and test verification
438
+
439
+ # Check orchestration status
440
+ sugar orchestrate <task_id> --stages
441
+
442
+ # View accumulated context
443
+ sugar context <task_id>
444
+ ```
445
+
446
+ Specialist agents are automatically assigned based on task content:
447
+ - `frontend-designer` - UI, components, styling
448
+ - `backend-developer` - APIs, databases, services
449
+ - `qa-engineer` - Testing, test strategies
450
+ - `security-engineer` - Auth, vulnerabilities
451
+ - `devops-engineer` - CI/CD, infrastructure
452
+
390
453
  **Custom Task Types**
391
454
  ```bash
392
455
  sugar task-type add deployment --name "Deployment" --emoji "🚀"
@@ -126,6 +126,12 @@ sugar list --status completed
126
126
  - Custom task types for your workflow
127
127
  - Queue management and filtering
128
128
 
129
+ **Task Orchestration** *(New in v3.0)*
130
+ - Auto-decomposes complex features into subtasks
131
+ - 4-stage workflow: Research → Planning → Implementation → Review
132
+ - Specialist agent routing (frontend, backend, QA, security, DevOps)
133
+ - Parallel execution with dependency management
134
+
129
135
  **Autonomous Execution**
130
136
  - Specialized Claude agents (UX, backend, QA)
131
137
  - Automatic retries on failures
@@ -142,6 +148,34 @@ sugar list --status completed
142
148
  - Identifies missing tests
143
149
  - Auto-creates tasks from findings
144
150
 
151
+ **Issue Responder**
152
+ - AI-powered GitHub issue analysis
153
+ - Generates contextual responses
154
+ - Confidence-based auto-posting
155
+ - Searchable issue history
156
+
157
+ ## Issue Responder
158
+
159
+ Automatically analyze and respond to GitHub issues with AI-powered insights. Sugar understands issue context, codebase structure, and project patterns to generate helpful responses.
160
+
161
+ ```bash
162
+ # List open issues
163
+ sugar issue list
164
+
165
+ # Analyze an issue
166
+ sugar issue analyze 42
167
+
168
+ # Generate AI response (preview)
169
+ sugar issue respond 42
170
+
171
+ # Generate and post if confident
172
+ sugar issue respond 42 --post
173
+ ```
174
+
175
+ The Issue Responder evaluates confidence before posting. Use `--force-post` to override the confidence check, or adjust the threshold with `--confidence-threshold`.
176
+
177
+ **Full documentation:** [docs/issue-responder.md](docs/issue-responder.md)
178
+
145
179
  ## How It Works
146
180
 
147
181
  ```
@@ -327,12 +361,41 @@ Sugar 3.0 is built natively on the **Claude Agent SDK**, providing:
327
361
 
328
362
  - **[Quick Start](docs/user/quick-start.md)** - Get running in 5 minutes
329
363
  - **[CLI Reference](docs/user/cli-reference.md)** - All commands
364
+ - **[Task Orchestration](docs/task_orchestration.md)** - Complex feature decomposition
330
365
  - **[GitHub Integration](docs/user/github-integration.md)** - Connect to GitHub
331
366
  - **[Configuration Guide](docs/user/configuration-best-practices.md)** - Best practices
332
367
  - **[Claude Code Plugin](.claude-plugin/README.md)** - Native integration
333
368
 
334
369
  ## Advanced Usage
335
370
 
371
+ **Task Orchestration**
372
+
373
+ For complex features, Sugar can automatically decompose work and route to specialist agents:
374
+
375
+ ```bash
376
+ # Add a feature that will be orchestrated
377
+ sugar add "Add user authentication with OAuth" --type feature --orchestrate
378
+
379
+ # Sugar will:
380
+ # 1. RESEARCH - Search best practices, analyze codebase
381
+ # 2. PLAN - Create implementation plan with subtasks
382
+ # 3. IMPLEMENT - Route subtasks to specialists in parallel
383
+ # 4. REVIEW - Code review and test verification
384
+
385
+ # Check orchestration status
386
+ sugar orchestrate <task_id> --stages
387
+
388
+ # View accumulated context
389
+ sugar context <task_id>
390
+ ```
391
+
392
+ Specialist agents are automatically assigned based on task content:
393
+ - `frontend-designer` - UI, components, styling
394
+ - `backend-developer` - APIs, databases, services
395
+ - `qa-engineer` - Testing, test strategies
396
+ - `security-engineer` - Auth, vulnerabilities
397
+ - `devops-engineer` - CI/CD, infrastructure
398
+
336
399
  **Custom Task Types**
337
400
  ```bash
338
401
  sugar task-type add deployment --name "Deployment" --emoji "🚀"
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "sugarai"
7
- version = "3.0.1"
7
+ version = "3.1.1.dev2"
8
8
  description = "Sugar 🍰 - A dev team that never stops. Delegate full tasks to AI in the background."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -12,6 +12,7 @@ from .hooks import (
12
12
  create_audit_hook,
13
13
  create_security_hook,
14
14
  )
15
+ from .subagent_manager import SubAgentManager, SubAgentResult
15
16
 
16
17
  __all__ = [
17
18
  "SugarAgent",
@@ -20,4 +21,6 @@ __all__ = [
20
21
  "create_preflight_hook",
21
22
  "create_audit_hook",
22
23
  "create_security_hook",
24
+ "SubAgentManager",
25
+ "SubAgentResult",
23
26
  ]
@@ -0,0 +1,329 @@
1
+ """
2
+ SubAgent Manager for Sugar
3
+
4
+ Provides functionality for spawning and managing sub-agents with:
5
+ - Isolated execution contexts
6
+ - Parallel execution with concurrency control
7
+ - Timeout handling
8
+ - Result summarization and file tracking
9
+ """
10
+
11
+ import asyncio
12
+ import logging
13
+ from dataclasses import dataclass, field
14
+ from datetime import datetime, timezone
15
+ from typing import Any, Dict, List, Optional
16
+
17
+ from .base import SugarAgent, SugarAgentConfig, AgentResponse
18
+
19
+ logger = logging.getLogger(__name__)
20
+
21
+
22
+ @dataclass
23
+ class SubAgentResult:
24
+ """Result from a sub-agent execution"""
25
+
26
+ task_id: str
27
+ success: bool
28
+ summary: str
29
+ files_modified: List[str] = field(default_factory=list)
30
+ execution_time: float = 0.0
31
+ error: Optional[str] = None
32
+
33
+ def to_dict(self) -> Dict[str, Any]:
34
+ """Convert to dictionary"""
35
+ return {
36
+ "task_id": self.task_id,
37
+ "success": self.success,
38
+ "summary": self.summary,
39
+ "files_modified": self.files_modified,
40
+ "execution_time": self.execution_time,
41
+ "error": self.error,
42
+ }
43
+
44
+
45
+ class SubAgentManager:
46
+ """
47
+ Manages spawning and execution of sub-agents.
48
+
49
+ Sub-agents are isolated agent instances that can execute tasks
50
+ independently or in parallel, with results summarized back to
51
+ the parent agent.
52
+ """
53
+
54
+ def __init__(
55
+ self,
56
+ parent_config: SugarAgentConfig,
57
+ max_concurrent: int = 3,
58
+ default_timeout: int = 300,
59
+ ):
60
+ """
61
+ Initialize the SubAgent manager.
62
+
63
+ Args:
64
+ parent_config: Configuration from parent agent to inherit
65
+ max_concurrent: Maximum number of concurrent sub-agents
66
+ default_timeout: Default timeout for sub-agent tasks (seconds)
67
+ """
68
+ self.parent_config = parent_config
69
+ self.max_concurrent = max_concurrent
70
+ self.default_timeout = default_timeout
71
+ self._semaphore = asyncio.Semaphore(max_concurrent)
72
+ self._active_subagents: Dict[str, SugarAgent] = {}
73
+
74
+ logger.debug(
75
+ f"SubAgentManager initialized with max_concurrent={max_concurrent}"
76
+ )
77
+
78
+ def _create_subagent_config(
79
+ self, task_id: str, task_context: Optional[str] = None
80
+ ) -> SugarAgentConfig:
81
+ """
82
+ Create a config for a sub-agent based on parent config.
83
+
84
+ Args:
85
+ task_id: Unique identifier for this sub-agent task
86
+ task_context: Optional context to add to system prompt
87
+
88
+ Returns:
89
+ SugarAgentConfig for the sub-agent
90
+ """
91
+ # Inherit most settings from parent, but customize for sub-agent
92
+ config = SugarAgentConfig(
93
+ model=self.parent_config.model,
94
+ max_tokens=self.parent_config.max_tokens,
95
+ permission_mode=self.parent_config.permission_mode,
96
+ allowed_tools=self.parent_config.allowed_tools.copy(),
97
+ mcp_servers=self.parent_config.mcp_servers.copy(),
98
+ quality_gates_enabled=self.parent_config.quality_gates_enabled,
99
+ working_directory=self.parent_config.working_directory,
100
+ timeout=self.default_timeout,
101
+ max_retries=self.parent_config.max_retries,
102
+ retry_base_delay=self.parent_config.retry_base_delay,
103
+ retry_max_delay=self.parent_config.retry_max_delay,
104
+ )
105
+
106
+ # Add sub-agent context to system prompt
107
+ subagent_context = f"\n\nYou are a sub-agent working on task: {task_id}"
108
+ if task_context:
109
+ subagent_context += f"\n{task_context}"
110
+ subagent_context += (
111
+ "\n\nFocus on completing your specific task and providing a clear summary."
112
+ )
113
+
114
+ config.system_prompt_additions = (
115
+ self.parent_config.system_prompt_additions + subagent_context
116
+ )
117
+
118
+ return config
119
+
120
+ async def spawn(
121
+ self,
122
+ task_id: str,
123
+ prompt: str,
124
+ task_context: Optional[str] = None,
125
+ timeout: Optional[int] = None,
126
+ ) -> SubAgentResult:
127
+ """
128
+ Spawn a single sub-agent to execute a task.
129
+
130
+ Args:
131
+ task_id: Unique identifier for this task
132
+ prompt: Task prompt for the sub-agent
133
+ task_context: Optional context for the task
134
+ timeout: Optional timeout override (seconds)
135
+
136
+ Returns:
137
+ SubAgentResult with execution results
138
+ """
139
+ start_time = datetime.now(timezone.utc)
140
+ timeout_seconds = timeout or self.default_timeout
141
+
142
+ logger.info(f"Spawning sub-agent for task: {task_id}")
143
+
144
+ try:
145
+ # Acquire semaphore to respect concurrency limit
146
+ async with self._semaphore:
147
+ # Create sub-agent config and instance
148
+ config = self._create_subagent_config(task_id, task_context)
149
+ subagent = SugarAgent(config)
150
+ self._active_subagents[task_id] = subagent
151
+
152
+ # Execute with timeout
153
+ try:
154
+ response = await asyncio.wait_for(
155
+ subagent.execute(prompt, task_context),
156
+ timeout=timeout_seconds,
157
+ )
158
+ except asyncio.TimeoutError:
159
+ execution_time = (
160
+ datetime.now(timezone.utc) - start_time
161
+ ).total_seconds()
162
+ logger.warning(
163
+ f"Sub-agent task {task_id} timed out after {timeout_seconds}s"
164
+ )
165
+ return SubAgentResult(
166
+ task_id=task_id,
167
+ success=False,
168
+ summary=f"Task timed out after {timeout_seconds} seconds",
169
+ execution_time=execution_time,
170
+ error="Timeout exceeded",
171
+ )
172
+
173
+ # Extract summary from response
174
+ summary = self._extract_summary(response)
175
+ execution_time = (
176
+ datetime.now(timezone.utc) - start_time
177
+ ).total_seconds()
178
+
179
+ result = SubAgentResult(
180
+ task_id=task_id,
181
+ success=response.success,
182
+ summary=summary,
183
+ files_modified=response.files_modified.copy(),
184
+ execution_time=execution_time,
185
+ error=response.error,
186
+ )
187
+
188
+ logger.info(
189
+ f"Sub-agent task {task_id} completed in {execution_time:.2f}s, "
190
+ f"modified {len(result.files_modified)} files"
191
+ )
192
+
193
+ return result
194
+
195
+ except Exception as e:
196
+ execution_time = (datetime.now(timezone.utc) - start_time).total_seconds()
197
+ logger.error(f"Sub-agent task {task_id} failed: {e}")
198
+ return SubAgentResult(
199
+ task_id=task_id,
200
+ success=False,
201
+ summary=f"Sub-agent execution failed: {str(e)}",
202
+ execution_time=execution_time,
203
+ error=str(e),
204
+ )
205
+
206
+ finally:
207
+ # Clean up
208
+ if task_id in self._active_subagents:
209
+ del self._active_subagents[task_id]
210
+
211
+ async def spawn_parallel(
212
+ self,
213
+ tasks: List[Dict[str, Any]],
214
+ timeout: Optional[int] = None,
215
+ ) -> List[SubAgentResult]:
216
+ """
217
+ Spawn multiple sub-agents to execute tasks in parallel.
218
+
219
+ Tasks will be executed concurrently up to max_concurrent limit.
220
+
221
+ Args:
222
+ tasks: List of task dicts, each containing:
223
+ - task_id: Unique identifier
224
+ - prompt: Task prompt
225
+ - context: Optional task context
226
+ timeout: Optional timeout override for all tasks (seconds)
227
+
228
+ Returns:
229
+ List of SubAgentResults in the same order as input tasks
230
+ """
231
+ logger.info(f"Spawning {len(tasks)} sub-agents in parallel")
232
+ start_time = datetime.now(timezone.utc)
233
+
234
+ # Create coroutines for all tasks
235
+ coroutines = []
236
+ for task in tasks:
237
+ task_id = task.get("task_id", f"task-{len(coroutines)}")
238
+ prompt = task.get("prompt", "")
239
+ context = task.get("context")
240
+ task_timeout = task.get("timeout", timeout)
241
+
242
+ coro = self.spawn(task_id, prompt, context, task_timeout)
243
+ coroutines.append(coro)
244
+
245
+ # Execute all tasks concurrently
246
+ results = await asyncio.gather(*coroutines, return_exceptions=True)
247
+
248
+ # Convert any exceptions to error results
249
+ processed_results = []
250
+ for i, result in enumerate(results):
251
+ if isinstance(result, Exception):
252
+ task_id = tasks[i].get("task_id", f"task-{i}")
253
+ processed_results.append(
254
+ SubAgentResult(
255
+ task_id=task_id,
256
+ success=False,
257
+ summary=f"Task failed with exception: {str(result)}",
258
+ error=str(result),
259
+ )
260
+ )
261
+ else:
262
+ processed_results.append(result)
263
+
264
+ total_time = (datetime.now(timezone.utc) - start_time).total_seconds()
265
+ successful = sum(1 for r in processed_results if r.success)
266
+ logger.info(
267
+ f"Parallel execution completed in {total_time:.2f}s: "
268
+ f"{successful}/{len(tasks)} successful"
269
+ )
270
+
271
+ return processed_results
272
+
273
+ def _extract_summary(self, response: AgentResponse) -> str:
274
+ """
275
+ Extract a concise summary from agent response.
276
+
277
+ Args:
278
+ response: AgentResponse from sub-agent
279
+
280
+ Returns:
281
+ Summary string
282
+ """
283
+ if not response.success:
284
+ return response.error or "Task failed"
285
+
286
+ content = response.content.strip()
287
+ if not content:
288
+ return "Task completed (no output)"
289
+
290
+ # Take first meaningful paragraph or first 200 chars
291
+ lines = content.split("\n")
292
+ for line in lines:
293
+ line = line.strip()
294
+ if line and not line.startswith("#"):
295
+ # Found first content line
296
+ if len(line) > 200:
297
+ return line[:197] + "..."
298
+ return line
299
+
300
+ # Fallback to truncated content
301
+ if len(content) > 200:
302
+ return content[:197] + "..."
303
+ return content
304
+
305
+ def get_active_count(self) -> int:
306
+ """Get number of currently active sub-agents"""
307
+ return len(self._active_subagents)
308
+
309
+ def get_active_task_ids(self) -> List[str]:
310
+ """Get list of currently active task IDs"""
311
+ return list(self._active_subagents.keys())
312
+
313
+ async def cancel_all(self) -> None:
314
+ """
315
+ Cancel all active sub-agent tasks.
316
+
317
+ Note: This will attempt graceful shutdown but may not
318
+ interrupt tasks that are already executing.
319
+ """
320
+ logger.warning(f"Cancelling {len(self._active_subagents)} active sub-agents")
321
+
322
+ for task_id, subagent in self._active_subagents.items():
323
+ try:
324
+ await subagent.end_session()
325
+ logger.debug(f"Cancelled sub-agent task: {task_id}")
326
+ except Exception as e:
327
+ logger.error(f"Error cancelling sub-agent {task_id}: {e}")
328
+
329
+ self._active_subagents.clear()
@@ -122,6 +122,96 @@ async def sugar_learning_query(args: Dict[str, Any]) -> Dict[str, Any]:
122
122
  }
123
123
 
124
124
 
125
+ @tool(
126
+ "spawn_subagent",
127
+ "Spawn a single sub-agent to execute an isolated task with its own context",
128
+ {"task_id": str, "prompt": str, "context": str, "timeout": int},
129
+ )
130
+ async def spawn_subagent(args: Dict[str, Any]) -> Dict[str, Any]:
131
+ """
132
+ Spawn a single sub-agent to execute a task.
133
+
134
+ This creates an isolated agent instance that can work independently
135
+ on a specific task and return summarized results.
136
+ """
137
+ task_id = args.get("task_id", "")
138
+ prompt = args.get("prompt", "")
139
+ context = args.get("context")
140
+ timeout = args.get("timeout")
141
+
142
+ if not task_id or not prompt:
143
+ return {
144
+ "content": [
145
+ {
146
+ "type": "text",
147
+ "text": "Error: task_id and prompt are required",
148
+ }
149
+ ]
150
+ }
151
+
152
+ # This would integrate with SubAgentManager from the parent agent
153
+ # For now, return a placeholder response
154
+ result = {
155
+ "task_id": task_id,
156
+ "status": "pending",
157
+ "message": "Sub-agent spawning is managed by SubAgentManager",
158
+ "note": "Use SubAgentManager.spawn() in code for actual execution",
159
+ }
160
+
161
+ return {
162
+ "content": [
163
+ {
164
+ "type": "text",
165
+ "text": f"Sub-agent spawn requested: {json.dumps(result, indent=2)}",
166
+ }
167
+ ]
168
+ }
169
+
170
+
171
+ @tool(
172
+ "spawn_parallel_subagents",
173
+ "Spawn multiple sub-agents to execute tasks in parallel with concurrency control",
174
+ {"tasks": list, "timeout": int},
175
+ )
176
+ async def spawn_parallel_subagents(args: Dict[str, Any]) -> Dict[str, Any]:
177
+ """
178
+ Spawn multiple sub-agents to execute tasks in parallel.
179
+
180
+ Tasks are executed concurrently up to the configured limit (default 3).
181
+ Each task should have: task_id, prompt, and optionally context and timeout.
182
+ """
183
+ tasks = args.get("tasks", [])
184
+ timeout = args.get("timeout")
185
+
186
+ if not tasks:
187
+ return {
188
+ "content": [
189
+ {
190
+ "type": "text",
191
+ "text": "Error: tasks list is required and must not be empty",
192
+ }
193
+ ]
194
+ }
195
+
196
+ # This would integrate with SubAgentManager from the parent agent
197
+ # For now, return a placeholder response
198
+ result = {
199
+ "task_count": len(tasks),
200
+ "status": "pending",
201
+ "message": "Parallel sub-agent spawning is managed by SubAgentManager",
202
+ "note": "Use SubAgentManager.spawn_parallel() in code for actual execution",
203
+ }
204
+
205
+ return {
206
+ "content": [
207
+ {
208
+ "type": "text",
209
+ "text": f"Parallel sub-agent spawn requested: {json.dumps(result, indent=2)}",
210
+ }
211
+ ]
212
+ }
213
+
214
+
125
215
  def get_sugar_tools() -> List[Dict[str, Any]]:
126
216
  """
127
217
  Get all Sugar-specific tools for registration with the Agent SDK.
@@ -133,6 +223,8 @@ def get_sugar_tools() -> List[Dict[str, Any]]:
133
223
  sugar_task_status,
134
224
  sugar_quality_gate_check,
135
225
  sugar_learning_query,
226
+ spawn_subagent,
227
+ spawn_parallel_subagents,
136
228
  ]
137
229
 
138
230
  return [
@@ -388,8 +388,16 @@ class GitHubClient:
388
388
  limit: int = 5,
389
389
  ) -> List[GitHubIssue]:
390
390
  """Find issues similar to the given issue"""
391
+ import re
392
+
391
393
  # Build search query from issue title keywords
392
- keywords = issue.title.split()[:5] # First 5 words
394
+ # Remove special characters that break GitHub search
395
+ clean_title = re.sub(r"[\[\]\(\)\{\}:\"'`]", " ", issue.title)
396
+ keywords = [w for w in clean_title.split() if len(w) > 2][:5]
397
+
398
+ if not keywords:
399
+ return []
400
+
393
401
  query = " ".join(keywords)
394
402
 
395
403
  similar = self.search_issues(f"{query} is:issue", limit=limit + 1)