@neotx/core 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/index.js

@@ -2521,7 +2521,6 @@ import { randomUUID as randomUUID3 } from "crypto";
 import { readFile as readFile9, writeFile as writeFile5 } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import path12 from "path";
-import { fileURLToPath } from "url";
 
 // src/supervisor/memory.ts
 import { appendFile as appendFile5, readFile as readFile8, rename as rename2, writeFile as writeFile4 } from "fs/promises";
@@ -2658,23 +2657,74 @@ function buildHeartbeatPrompt(opts) {
 You orchestrate developer agents across repositories. You make decisions autonomously.
 
 Your job:
-1. Process any incoming events (webhooks, user messages, run completions)
-2. Decide what actions to take (dispatch agents, check status, respond to users)
-3. Update your memory with relevant context for future heartbeats
-4. If nothing to do, simply acknowledge and wait
+1. Process incoming events (webhooks, user messages, run completions)
+2. Dispatch agents, check status, or respond to users
+3. Update your memory with context for future heartbeats
+4. If nothing to do, acknowledge and wait
 
-Available commands (via bash):
-  neo run <agent> --prompt "..." [--repo <path>]   dispatch an agent
-  neo runs --short [--all]                         check recent runs
-  neo cost --short [--all]                         check budget
-  neo agents                                       list available agents
+## Commands
 
-IMPORTANT: Always include a <memory>...</memory> block at the end of your response with your updated memory.
+### Dispatching agents
+\`\`\`bash
+neo run <agent> --prompt "..." --repo <path> [--priority critical|high|medium|low] [--meta '<json>']
+\`\`\`
+
+The \`--meta\` flag accepts a JSON object attached to the run and all its events. It serves two purposes:
+1. **Traceability**: links every run to its source (ticket, PR, branch) for cost tracking and audit.
+2. **Idempotency**: neo deduplicates dispatches by metadata \u2014 same \`--meta\` twice is rejected.
+
+Always pass \`--meta\` when dispatching. Include at minimum the source identifier and pipeline stage. See your custom instructions for the exact fields required by your workflow.
+
+**Standard metadata fields:**
+
+| Field | When | Description |
+|-------|------|-------------|
+| \`ticketId\` | always | Source ticket identifier for traceability |
+| \`stage\` | always | Pipeline stage: \`refine\`, \`develop\`, \`review\`, \`fix\` |
+| \`branch\` | if exists | Git branch the agent should work on |
+| \`prNumber\` | if exists | GitHub PR number |
+| \`cycle\` | fix stage | Fixer\u2192review cycle count (for anti-loop guards) |
+
+**Branch & PR rules:**
+- First dispatch (develop): no branch/PR yet \u2014 instruct the agent in \`--prompt\` to create a feature branch and open a PR. Omit \`branch\` and \`prNumber\` from \`--meta\`.
+- Subsequent dispatches (review/fix): branch and PR exist \u2014 pass \`branch\` and \`prNumber\` in \`--meta\` and reference them in \`--prompt\`.
+
+Examples:
+\`\`\`bash
+# First dispatch \u2014 instruct agent to create branch + PR
+neo run developer --prompt "Implement feature X. Criteria: ... Create branch feat/PROJ-42-feature-x and open a PR when done." \\
+  --repo /path/to/repo \\
+  --meta '{"ticketId":"PROJ-42","stage":"develop"}'
+
+# Review \u2014 reference existing branch and PR
+neo run reviewer-quality --prompt "Review PR #73 on branch feat/PROJ-42-feature-x." \\
+  --repo /path/to/repo \\
+  --meta '{"ticketId":"PROJ-42","stage":"review","branch":"feat/PROJ-42-feature-x","prNumber":73}'
+
+# Fix \u2014 instruct to push to existing branch
+neo run fixer --prompt "Fix issues from review on PR #73 (branch feat/PROJ-42-feature-x): ... Push fixes to the existing branch." \\
+  --repo /path/to/repo \\
+  --meta '{"ticketId":"PROJ-42","stage":"fix","branch":"feat/PROJ-42-feature-x","prNumber":73,"cycle":2}'
+
+# Architect \u2014 read-only, no branch needed
+neo run architect --prompt "Design decomposition for feature Y" \\
+  --repo /path/to/repo \\
+  --meta '{"ticketId":"PROJ-99","stage":"refine"}'
+\`\`\`
+
+### Other commands
+\`\`\`bash
+neo runs --short [--all]     # check recent runs
+neo runs <runId>             # full run details
+neo cost --short [--all]     # check budget
+neo agents                   # list available agents
+neo log <type> "<message>"   # log a progress report (types: decision, action, blocker, progress)
+\`\`\`
 
 ## Reporting
-Use the \`mcp__neo__report_progress\` tool to log your decisions, actions and blockers.
-Always report what you're doing and why \u2014 these logs are your audit trail.
-Types: "decision" (what you chose), "action" (what you did), "blocker" (what's stuck), "progress" (status update).`);
+Log every decision and action with \`neo log\`. These logs are your audit trail.
+
+IMPORTANT: Always include a <memory>...</memory> block at the end of your response with your updated memory.`);
   if (opts.customInstructions) {
     sections.push(`## Custom instructions
 ${opts.customInstructions}`);
@@ -2891,32 +2941,19 @@ var HeartbeatLoop = class {
     let turnCount = 0;
     try {
       const sdk = await import("@anthropic-ai/claude-agent-sdk");
-      const allowedTools = ["Bash", "Read", "mcp__neo__*"];
+      const allowedTools = ["Bash", "Read"];
       if (this.config.mcpServers) {
         for (const name of Object.keys(this.config.mcpServers)) {
           allowedTools.push(`mcp__${name}__*`);
         }
       }
-      const mcpInternalPath = path12.join(
-        path12.dirname(fileURLToPath(import.meta.url)),
-        "mcp-internal.js"
-      );
-      const mcpServers = {
-        neo: {
-          type: "stdio",
-          command: "node",
-          args: [mcpInternalPath],
-          env: { NEO_ACTIVITY_PATH: this.activityLog.filePath }
-        },
-        ...this.config.mcpServers ?? {}
-      };
       const queryOptions = {
         cwd: homedir2(),
         maxTurns: 50,
         allowedTools,
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
-        mcpServers
+        mcpServers: this.config.mcpServers ?? {}
       };
       const stream = sdk.query({ prompt, options: queryOptions });
       for await (const message of stream) {