@aion0/forge 0.4.15 → 0.5.0

package/lib/help-docs/11-workspace.md

@@ -0,0 +1,204 @@
+# Workspace (Forge Smiths)
+
+## Overview
+
+Workspace is a multi-agent orchestration system. You define a team of **Smiths** (agents) with roles, dependencies, and steps. Smiths run as long-lived daemons, communicate via a message bus, and can be controlled manually or automatically.
+
+## Concepts
+
+| Term | Description |
+|------|-------------|
+| **Smith** | A long-running agent instance in the workspace |
+| **Agent Profile** | A reusable configuration (CLI type + env vars + model) that can be assigned to any smith |
+| **Message Bus** | Inter-agent communication system with two message categories |
+| **Input Node** | User-provided requirements node (append-only history) |
+| **Daemon** | Background execution loop that keeps smiths alive and consuming messages |
+
+## Three-Layer State Model
+
+Each smith has three independent status layers displayed on the node:
+
+| Layer | Values | Description |
+|-------|--------|-------------|
+| **Smith Status** | `down` / `active` | Whether the daemon process is running |
+| **Mode** | `auto` / `manual` | `auto` = daemon-driven, `manual` = user in terminal (purple) |
+| **Task Status** | `idle` / `running` / `done` / `failed` | Current work status |
+
+- **Mode controls message consumption**: `manual` pauses inbox processing (same as `running`)
+- **Smith Status controls the daemon loop**: `down` stops the message loop entirely
+- **Task Status tracks work**: unaffected by mode changes
+
+## Dependencies (DAG)
+
+Dependencies must form a **directed acyclic graph** (DAG). Circular dependencies are rejected when adding or editing agents.
+
+```
+Input → PM → Engineer → QA → Reviewer
+```
+
+- Upstream agents complete first, then broadcast to downstream
+- Each agent knows its upstream (dependsOn) and the system prevents cycles
+
+## Message System
+
+### Two Message Categories
+
+| Category | Direction | Behavior | Use Case |
+|----------|-----------|----------|----------|
+| **Notification** | Follows DAG (upstream → downstream) | Auto-broadcast on completion, downstream discards reverse notifications | "I'm done, here's what I did" |
+| **Ticket** | Any direction (ignores DAG) | 1-to-1, independent lifecycle, retry limits | Bug reports, fix requests |
+
+### Notification Messages (Default)
+
+When a smith completes:
+- If it was processing an **upstream** message → broadcast to all downstream agents
+- If it was processing a **downstream** message → no broadcast, just mark the message done (sender checks outbox status)
+- Each message carries a `causedBy` field tracing which inbox message triggered it
+
+### Ticket Messages
+
+- Created via `create_ticket` API or forge skills
+- Have their own lifecycle: `open → in_progress → fixed → verified → closed`
+- Retry limit (default 3), exceeding marks ticket as failed
+- Not affected by DAG direction — any agent can ticket any agent
+
+### CausedBy Chain
+
+Every outgoing message carries `causedBy` linking to the inbox message that triggered it:
+
+```json
+{
+  "from": "qa-123",
+  "to": "reviewer-456",
+  "action": "upstream_complete",
+  "causedBy": {
+    "messageId": "msg-789",
+    "from": "engineer-111",
+    "to": "qa-123"
+  }
+}
+```
+
+This enables:
+- **Loop prevention**: Notifications from downstream are silently discarded
+- **Outbox tracking**: Sender can verify their message was processed
+- **Audit trail**: Every message traces back to its trigger
+
+### Message Receive Rules
+
+When a message arrives at an agent's inbox:
+
+1. **Tickets** → always accepted (with retry limit check)
+2. **Notification with causedBy matching own outbox** → accepted (response to my request)
+3. **Notification from downstream agent** → silently discarded (prevents reverse flow)
+4. **Notification from upstream or no causedBy** → accepted (normal DAG flow)
+
+### Message Status Flow
+
+`pending` → `running` → `done` / `failed`
+
+- Only one message processed at a time per agent
+- `currentMessageId` persisted in agent state for crash recovery
+
+## Manual Mode
+
+Click the **⌨️** button on any smith to open a terminal:
+- Mode switches to `manual` (purple indicator on node)
+- Inbox message processing pauses (messages stay pending)
+- A tmux session opens with CLI + profile env + forge env vars (`FORGE_AGENT_ID`, `FORGE_WORKSPACE_ID`, `FORGE_PORT`)
+- Forge Skills auto-installed for inter-agent communication
+- Close terminal → mode returns to `auto`, pending messages resume processing
+
+### Forge Skills in Terminal
+
+| Skill | Description |
+|-------|-------------|
+| `/forge-send` | Send a message to another smith (blocked if replying to current sender — use for NEW issues only) |
+| `/forge-inbox` | Check incoming messages |
+| `/forge-status` | Check all smiths' status |
+| `/forge-workspace-sync` | Sync progress back to workspace |
+
+**Note**: When processing a message from another agent, do NOT use `/forge-send` to reply — the system auto-delivers results via `markMessageDone`. Only use `/forge-send` for new issues to other agents.
+
+## Inbox Management
+
+Each smith has an inbox panel with two tabs:
+
+### Inbox Tab
+- Messages received from other smiths
+- Status badges: pending (yellow), running (blue), done (green), failed (red)
+- Ticket messages have purple border + TICKET badge + lifecycle status
+- CausedBy trace shows which agent triggered the message
+
+### Outbox Tab
+- Messages sent by this smith
+- Track delivery status and responses
+
+### Batch Operations
+- **Select all completed** → batch delete done/failed messages
+- **Abort all pending (N)** → cancel all pending messages at once
+- Checkbox selection on individual done/failed messages
+
+## Controls
+
+| Action | Description |
+|--------|-------------|
+| **Start** | Launch daemon, begin executing all agents |
+| **Stop** | Stop daemon, kill all workers |
+| **Pause** | Pause a specific smith (stops consuming messages) |
+| **Resume** | Resume a paused smith |
+| **Retry** | Retry a failed smith |
+| **Reset** | Reset smith to idle, clear history |
+| **Open Terminal** | Switch to manual mode, open floating terminal |
+| **Close Terminal** | Return to auto mode, resume message processing |
+
+## Workspace API
+
+```bash
+# List workspaces
+curl http://localhost:8403/api/workspace
+
+# Get workspace state
+curl http://localhost:8403/api/workspace/<id>
+
+# Agent operations
+curl -X POST http://localhost:8403/api/workspace/<id>/agents \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"start"}'                                        # start daemon
+  -d '{"action":"stop"}'                                         # stop daemon
+  -d '{"action":"run", "agentId":"engineer-123"}'                # run one smith
+  -d '{"action":"open_terminal", "agentId":"engineer-123"}'      # manual mode
+  -d '{"action":"close_terminal", "agentId":"engineer-123"}'     # back to auto
+  -d '{"action":"reset", "agentId":"engineer-123"}'              # reset to idle
+
+# Smith API (via workspace daemon)
+curl -X POST http://localhost:8403/api/workspace/<id>/smith \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"send","agentId":"$ID","to":"QA","msgAction":"review","content":"Please check"}'
+  -d '{"action":"inbox","agentId":"$ID"}'
+  -d '{"action":"status","agentId":"$ID"}'
+  -d '{"action":"create_ticket","agentId":"$FROM","targetId":"$TO","content":"Bug found"}'
+  -d '{"action":"update_ticket","messageId":"$ID","ticketStatus":"fixed"}'
+
+# Stream real-time events (SSE)
+curl http://localhost:8403/api/workspace/<id>/stream
+```
+
+## Persistence
+
+- Workspace state: `~/.forge/workspaces/<id>/state.json`
+- Auto-saved every 10 seconds
+- Atomic writes (temp file → rename) for crash safety
+- Synchronous save on daemon shutdown
+- `currentMessageId` persisted per agent for crash recovery
+
+## Tips
+
+1. **Dependencies must be a DAG** — no circular dependencies allowed
+2. **Start with Input nodes** — define requirements before adding agent smiths
+3. **Use profiles** for agents that need custom API endpoints or models
+4. **Notifications flow downstream** — upstream agents won't receive downstream broadcasts
+5. **Use tickets for bugs** — tickets ignore DAG direction, have retry limits
+6. **Open Terminal** for manual intervention — mode switches to manual, inbox pauses
+7. **Check Inbox** when a smith is stuck — it may have unprocessed messages
+8. **Batch delete** completed messages to keep inbox clean

package/lib/help-docs/CLAUDE.md

@@ -25,6 +25,7 @@ Your job is to answer user questions about Forge features, configuration, and tr
 | `08-rules.md` | CLAUDE.md templates and rule injection |
 | `09-issue-autofix.md` | GitHub issue auto-fix pipeline |
 | `10-troubleshooting.md` | Common issues and solutions |
+| `11-workspace.md` | Workspace (Forge Smiths) — multi-agent orchestration, daemon, message bus, profiles |
 
 ## Matching questions to docs
 
@@ -33,9 +34,11 @@ Your job is to answer user questions about Forge features, configuration, and tr
 - Telegram/notification → `02-telegram.md`
 - Tunnel/remote/cloudflare → `03-tunnel.md`
 - Task/background/queue → `04-tasks.md`
-- Settings/config → `01-settings.md`
+- Settings/config/agent/profile/provider → `01-settings.md`
 - Install/start/update → `00-overview.md`
 - Error/bug/crash → `10-troubleshooting.md`
 - Skill/marketplace → `06-skills.md`
-- Project/favorite → `07-projects.md`
+- Project/favorite/terminal → `07-projects.md`
 - Rules/CLAUDE.md/template → `08-rules.md`
+- Workspace/smith/daemon/multi-agent/bus/message → `11-workspace.md`
+- Agent profile/env/model/cliType → `01-settings.md` + `11-workspace.md`

package/lib/init.ts

@@ -45,18 +45,25 @@ function migrateSecrets() {
   }
 }
 
-/** Auto-detect claude binary path if not configured */
-function autoDetectClaude() {
+/** Auto-detect agent binaries */
+function autoDetectAgents() {
   try {
     const settings = loadSettings();
-    if (settings.claudePath) return; // already configured
-    const { execSync } = require('node:child_process');
-    const path = execSync('which claude', { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-    if (path) {
-      settings.claudePath = path;
-      saveSettings(settings);
-      console.log(`[init] Auto-detected claude: ${path}`);
+    // Backward compat: detect claude if not configured
+    if (!settings.claudePath) {
+      const { execSync } = require('node:child_process');
+      try {
+        const path = execSync('which claude', { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (path) {
+          settings.claudePath = path;
+          saveSettings(settings);
+          console.log(`[init] Auto-detected claude: ${path}`);
+        }
+      } catch {}
     }
+    // Detect all agents
+    const { autoDetectAgents: detect } = require('./agents');
+    detect();
   } catch {}
 }
 
@@ -80,7 +87,14 @@ export function ensureInitialized() {
   } catch {}
 
   // Auto-detect claude path if not configured
-  autoDetectClaude();
+  autoDetectAgents();
+
+  // Install/update forge skills to ~/.claude/skills/ on every startup
+  try {
+    const { installForgeSkills } = require('./workspace/skill-installer');
+    installForgeSkills('', '', '', Number(process.env.PORT) || 8403);
+    console.log('[init] Forge skills installed/updated');
+  } catch {}
 
   // Sync help docs + CLAUDE.md to data dir on startup
   try {
@@ -148,6 +162,7 @@ export function ensureInitialized() {
   startTelegramBot(); // registers task event listener only
   startTerminalProcess();
   startTelegramProcess(); // spawns telegram-standalone
+  startWorkspaceProcess(); // spawns workspace-standalone
 
   const settings = loadSettings();
   if (settings.tunnelAutoStart) {
@@ -182,7 +197,7 @@ function startTelegramProcess() {
   const script = join(process.cwd(), 'lib', 'telegram-standalone.ts');
   telegramChild = spawn('npx', ['tsx', script], {
     stdio: ['ignore', 'inherit', 'inherit'],
-    env: { ...process.env, PORT: String(process.env.PORT || 3000) },
+    env: { ...process.env, PORT: String(process.env.PORT || 8403) },
     detached: false,
   });
   telegramChild.on('exit', () => { telegramChild = null; });
@@ -194,7 +209,7 @@ let terminalChild: ReturnType<typeof spawn> | null = null;
 function startTerminalProcess() {
   if (terminalChild) return;
 
-  const termPort = Number(process.env.TERMINAL_PORT) || 3001;
+  const termPort = Number(process.env.TERMINAL_PORT) || 8404;
 
   const net = require('node:net');
   const tester = net.createServer();
@@ -214,3 +229,38 @@ function startTerminalProcess() {
   });
   tester.listen(termPort);
 }
+
+let workspaceChild: ReturnType<typeof spawn> | null = null;
+
+function startWorkspaceProcess() {
+  if (workspaceChild) return;
+
+  const wsPort = Number(process.env.WORKSPACE_PORT) || 8405;
+
+  const net = require('node:net');
+  const tester = net.createServer();
+  tester.once('error', () => {
+    // Port in use — kill stale process and retry after 2s
+    console.log(`[workspace] Port ${wsPort} in use, killing stale process...`);
+    try { require('node:child_process').execSync(`lsof -ti:${wsPort} | xargs kill -9 2>/dev/null`, { timeout: 3000 }); } catch {}
+    setTimeout(() => {
+      if (!workspaceChild) launchWorkspaceDaemon();
+    }, 2000);
+  });
+  tester.once('listening', () => {
+    tester.close();
+    launchWorkspaceDaemon();
+  });
+  tester.listen(wsPort);
+}
+
+function launchWorkspaceDaemon() {
+  const script = join(process.cwd(), 'lib', 'workspace-standalone.ts');
+  workspaceChild = spawn('npx', ['tsx', script], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+    env: { ...process.env },
+    detached: false,
+  });
+  workspaceChild.on('exit', () => { workspaceChild = null; });
+  console.log('[workspace] Started daemon (pid:', workspaceChild.pid, ')');
+}