@mndrk/agx 1.4.61 → 1.4.63

package/lib/notifications/webhooks.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { loadConfig } = require('../cli/configStore');
+
+const SUPPORTED_EVENTS = Object.freeze([
+  'task.created',
+  'task.stage_complete',
+  'task.completed',
+  'task.failed',
+  'task.blocked',
+]);
+
+const WILDCARD_EVENT = '*';
+
+function normalizeEventName(value) {
+  if (!value && value !== 0) return '';
+  const candidate = String(value || '').trim().toLowerCase();
+  if (!candidate) return '';
+  if (candidate === WILDCARD_EVENT) return WILDCARD_EVENT;
+  if (candidate.endsWith('.*')) {
+    return candidate;
+  }
+  return SUPPORTED_EVENTS.includes(candidate) ? candidate : '';
+}
+
+function normalizeEventsInput(value) {
+  if (value === undefined || value === null) {
+    return [WILDCARD_EVENT];
+  }
+  const parts = [];
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const normalized = normalizeEventName(item);
+      if (normalized) parts.push(normalized);
+    }
+  } else if (typeof value === 'string') {
+    for (const item of value.split(',')) {
+      const normalized = normalizeEventName(item);
+      if (normalized) parts.push(normalized);
+    }
+  }
+  if (parts.length === 0) {
+    return [WILDCARD_EVENT];
+  }
+  return Array.from(new Set(parts));
+}
+
+function normalizeWebhookEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const url = typeof entry.url === 'string' ? entry.url.trim() : '';
+  if (!url) return null;
+  const events = normalizeEventsInput(entry.events);
+  if (!events.length) return null;
+  return { url, events };
+}
+
+function parseWebhookEntries(config) {
+  const source = config ?? loadConfig();
+  if (!source || !Array.isArray(source.webhooks)) return [];
+  return source.webhooks
+    .map(normalizeWebhookEntry)
+    .filter((entry) => entry !== null);
+}
+
+function eventMatches(entry, eventName) {
+  if (!entry || !eventName) return false;
+  const normalized = String(eventName).trim().toLowerCase();
+  if (!normalized) return false;
+  if (!Array.isArray(entry.events)) return false;
+  if (entry.events.includes(WILDCARD_EVENT)) return true;
+  if (entry.events.includes(normalized)) return true;
+  return entry.events.some((event) => event.endsWith('.*') && normalized.startsWith(event.slice(0, -1)));
+}
+
+async function sendWebhookEvent(eventName, payload = null, options = {}) {
+  const normalizedEvent = normalizeEventName(eventName);
+  if (!normalizedEvent) return [];
+
+  const entries = Array.isArray(options.webhooks)
+    ? options.webhooks
+    : parseWebhookEntries(options.config);
+
+  if (!entries.length) return [];
+
+  const matches = entries.filter((entry) => eventMatches(entry, normalizedEvent));
+  if (!matches.length) return [];
+
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') return matches;
+
+  const timestamp = options.timestamp || new Date().toISOString();
+  const body = JSON.stringify({ event: normalizedEvent, timestamp, payload });
+  const logger = options.logger || console;
+
+  const results = await Promise.allSettled(
+    matches.map((match) => fetchFn(match.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-AGX-Event': normalizedEvent,
+      },
+      body,
+    }))
+  );
+
+  results.forEach((result, index) => {
+    if (result.status === 'rejected') {
+      if (logger && typeof logger.error === 'function') {
+        logger.error(`Webhook failed (${matches[index].url}): ${String(result.reason)}`);
+      }
+    }
+  });
+
+  return matches;
+}
+
+module.exports = {
+  SUPPORTED_EVENTS,
+  normalizeWebhookEntry,
+  parseWebhookEntries,
+  eventMatches,
+  sendWebhookEvent,
+};

package/lib/prompts/cloudTask.js

@@ -1,3 +1,5 @@
+const { interpolate, CONTINUE_CLOUD_TASK, NEW_AUTONOMOUS_CLOUD_TASK, LEGACY_INSTRUCTION_FOOTER } = require('./templates');
+
 function stripMarkdownSection(markdown, heading) {
   if (!markdown) return '';
   const h = String(heading || '').trim();
@@ -60,34 +62,21 @@ function buildContinueCloudTaskPrompt({
   const artifactsDir = typeof runContext?.artifacts_dir === 'string' ? runContext.artifacts_dir.trim() : '';
 
   const hasTaskPrompt = typeof task?.prompt === 'string' && task.prompt.trim();
-  let augmentedPrompt = hasTaskPrompt ? task.prompt.trim() : `## Cloud Task Context
-
-You are continuing a cloud task. Here is the current state:
-
-Task ID: ${task.id}
-Title: ${task.title || 'Untitled'}
-Stage: ${task.stage || 'ideation'}
-Stage Objective: ${stagePrompt}
-Stage Completion Requirement: ${stageRequirement}
-
-	User Request: 
-	"""
-	${task?.title}
-	${sanitizeTaskContentForPrompt(task?.content)}
-	---
-	Task Thread:
-	${(taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n')}
-	"""
-
-## Extracted State
-
-Goal: ${task.title || 'Untitled'}
-Plan: ${plan || '(none)'}
-Todo: ${todo || '(none)'}
-Checkpoints: ${checkpoints || '(none)'}
-Learnings: ${learnings || '(none)'}
-
-`;
+  let augmentedPrompt = hasTaskPrompt ? task.prompt.trim() : interpolate(CONTINUE_CLOUD_TASK, {
+    id: task.id,
+    title: task.title || 'Untitled',
+    stage: task.stage || 'ideation',
+    stagePrompt,
+    stageRequirement,
+    taskTitle: task?.title,
+    taskContent: sanitizeTaskContentForPrompt(task?.content),
+    taskComments: (taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n'),
+    goal: task.title || 'Untitled',
+    plan: plan || '(none)',
+    todo: todo || '(none)',
+    checkpoints: checkpoints || '(none)',
+    learnings: learnings || '(none)',
+  });
 
   if (!hasTaskPrompt && task?.engine) {
     augmentedPrompt += `Engine: ${task.engine}\n`;
@@ -169,37 +158,17 @@ function buildNewAutonomousCloudTaskPrompt({
   stagePrompt,
   stageRequirement,
 }) {
-  return `## Cloud Task Context
-
-	Task ID: ${task.id}
-	Title: ${task.title || finalPrompt}
-	Stage: ${task.stage}
-	Stage Objective: ${stagePrompt}
-	Stage Completion Requirement: ${stageRequirement}
-
-	User Request: 
-	"""
-	${task?.title}
-	${sanitizeTaskContentForPrompt(task?.content)}
-	---
-	Task Thread:
-	${(taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n')}
-	"""
-
----
-
-## Instructions
-
-You are starting a new autonomous task. Work until completion or blocked.
-Respect the Stage Completion Requirement before using [complete] or [done].
-
-To update the task:
-- [done] - Mark task complete
-- [complete: message] - Complete current stage
-- [log: message] - Add a log entry
-
-Goal: ${finalPrompt}
-`;
+  return interpolate(NEW_AUTONOMOUS_CLOUD_TASK, {
+    id: task.id,
+    title: task.title || finalPrompt,
+    stage: task.stage,
+    stagePrompt,
+    stageRequirement,
+    taskTitle: task?.title,
+    taskContent: sanitizeTaskContentForPrompt(task?.content),
+    taskComments: (taskComments || []).map(c => `${c.author}: ${c.content}`).join('\n'),
+    finalPrompt,
+  });
 }
 
 module.exports = {
@@ -214,23 +183,14 @@ function buildLegacyInstructionFooter({ runContext, finalPrompt } = {}) {
   const planDir = typeof runContext?.planDir === 'string' ? runContext.planDir.trim() : '';
   const artifactsDir = typeof runContext?.artifactsDir === 'string' ? runContext.artifactsDir.trim() : '';
 
-  return `## Instructions
-
-Continue working on this task. Use the cloud API to sync progress.
-Respect the Stage Completion Requirement before using [complete] or [done].
-
-${(runRoot || planDir || artifactsDir) ? `\nLocal run paths (scratch space):\n- Run root: ${runRoot || '(unset)'}\n- Plan dir: ${planDir || '(unset)'}\n- Artifacts dir: ${artifactsDir || '(unset)'}\n\nPrefer writing scratch planning docs under the run's Plan dir to avoid polluting the repo.\n` : ''}
-
-To update the task:
-- [done] - Mark task complete
-- [complete: message] - Complete current stage
-- [log: message] - Add a log entry
-- [checkpoint: message] - Save progress checkpoint
-- [learn: insight] - Record a learning
-- [plan: text] - Update plan
-- [todo: text] - Update todo list
+  const runPaths = (runRoot || planDir || artifactsDir)
+    ? `\nLocal run paths (scratch space):\n- Run root: ${runRoot || '(unset)'}\n- Plan dir: ${planDir || '(unset)'}\n- Artifacts dir: ${artifactsDir || '(unset)'}\n\nPrefer writing scratch planning docs under the run's Plan dir to avoid polluting the repo.\n`
+    : '';
 
-${finalPrompt ? `Your specific task: ${finalPrompt}` : ''}`.trim();
+  return interpolate(LEGACY_INSTRUCTION_FOOTER, {
+    runPaths,
+    finalPrompt: finalPrompt ? `Your specific task: ${finalPrompt}` : '',
+  }).trim();
 }
 
 function extractBodyFromContent(content) {

package/lib/prompts/templates.js

@@ -0,0 +1,356 @@
+'use strict';
+
+/**
+ * Centralized prompt templates for agx.
+ *
+ * All prompt string content lives here. Builder functions that assemble
+ * conditional logic stay in their original files and import these templates.
+ *
+ * Use `interpolate(template, vars)` to fill `{{key}}` placeholders.
+ */
+
+function interpolate(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+
+// ---------------------------------------------------------------------------
+// Static templates (no variables)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_STAGE_PROMPT = 'Execute this stage using the latest stage prompt from the cloud task context.';
+
+const PROJECT_CONTEXT = [
+  'AGX orchestrates autonomous AI agents with tasks defined via `agx new` and managed through `agx run`, `agx tasks`, `agx status`, and `agx context` so agents can wake, work, and sleep across sessions.',
+  'Task state lives in the cloud API (goal, criteria, progress, learnings) along with the orchestration worker (pg-boss); `agx info`/`agx context` expose structured project metadata.',
+  'Quick-start workflow: `agx new "<goal>"`, optionally `agx -a -p "<goal>"` for autonomous execution, then use `agx run`, `agx tasks`, `agx status`, and `agx context` to manage work.',
+  'Task management commands include `agx task ls`, `agx task logs`, `agx task stop`, `agx task rm`, `agx complete`, `agx pull`.',
+  'Daemon mode runs via `agx daemon start/stop/status/logs` so agents can poll for work continuously.',
+  'Providers: `agx claude` (alias `c`), `agx gemini` (alias `g`), and `agx ollama` (alias `o`).',
+  'Key flags: `-a/--autonomous`, `-p/--prompt`, `--prompt-file`, `-y/--yolo`, `--continue <task>`.',
+  'Key principles: persistent storage, criteria-driven completion, checkpoint often, ask when stuck, learn and adapt.',
+  'Agent workflow: orient on saved state, plan, execute, checkpoint, adapt to blockers, and report learnings.',
+  'State operations: define objectives via `agx new`, update learnings with `[learn: ...]`, mark completion via `agx complete`, and sync via `agx info`/`agx context`.',
+  'Project metadata: attach `--metadata key=value` and `--repo` info so `/api/projects` keeps structured context.',
+].join('\n');
+
+const AGX_SKILL = `---
+name: agx
+description: Task orchestrator for AI agents. Uses cloud API for persistence.
+---
+
+# agx - AI Agent Task Orchestrator
+
+agx manages tasks and coordinates AI agents. Uses cloud API for persistence.
+
+## Quick Start
+
+\`\`\`bash
+agx -a -p "Build a REST API"  # Autonomous: works until done
+agx -p "explain this code"     # One-shot question
+\`\`\`
+
+## Task Lifecycle
+
+\`\`\`bash
+agx new "goal"          # Create task
+agx run [task]          # Run a task
+agx complete <taskId>   # Mark task stage complete
+agx status <taskId>     # Show detailed info for a specific task
+agx status              # Show current status
+\`\`\`
+
+## Checking Tasks
+
+\`\`\`bash
+agx task ls             # List tasks
+agx task logs <id> [-f] # View/tail task logs
+agx task tail <id>      # Tail task logs
+agx comments tail <id>  # Tail task comments
+agx logs tail <id>      # Tail task logs
+agx watch               # Watch task updates in real-time (SSE)
+\`\`\`
+
+## Cloud
+
+\`\`\`bash
+AGX_CLOUD_URL=http://localhost:41741 agx status
+AGX_CLOUD_URL=http://localhost:41741 agx task ls
+agx daemon start  # Start local daemon
+\`\`\`
+
+## Providers
+
+claude (c), gemini (g), ollama (o), codex (x)
+
+## Key Flags
+
+-a  Autonomous mode (daemon + work until done)
+-p  Prompt/goal
+-y  Skip confirmations (implied by -a)
+-P, --provider <c|g|o|x>  Provider for new task (claude/gemini/ollama/codex)
+`;
+
+// ---------------------------------------------------------------------------
+// Parameterized templates (use with interpolate())
+// ---------------------------------------------------------------------------
+
+const CONTINUE_CLOUD_TASK = `## Cloud Task Context
+
+You are continuing a cloud task. Here is the current state:
+
+Task ID: {{id}}
+Title: {{title}}
+Stage: {{stage}}
+Stage Objective: {{stagePrompt}}
+Stage Completion Requirement: {{stageRequirement}}
+
+\tUser Request: 
+\t"""
+\t{{taskTitle}}
+\t{{taskContent}}
+\t---
+\tTask Thread:
+\t{{taskComments}}
+\t"""
+
+## Extracted State
+
+Goal: {{goal}}
+Plan: {{plan}}
+Todo: {{todo}}
+Checkpoints: {{checkpoints}}
+Learnings: {{learnings}}
+
+`;
+
+const NEW_AUTONOMOUS_CLOUD_TASK = `## Cloud Task Context
+
+\tTask ID: {{id}}
+\tTitle: {{title}}
+\tStage: {{stage}}
+\tStage Objective: {{stagePrompt}}
+\tStage Completion Requirement: {{stageRequirement}}
+
+\tUser Request: 
+\t"""
+\t{{taskTitle}}
+\t{{taskContent}}
+\t---
+\tTask Thread:
+\t{{taskComments}}
+\t"""
+
+---
+
+## Instructions
+
+You are starting a new autonomous task. Work until completion or blocked.
+Respect the Stage Completion Requirement before using [complete] or [done].
+
+To update the task:
+- [done] - Mark task complete
+- [complete: message] - Complete current stage
+- [log: message] - Add a log entry
+
+Goal: {{finalPrompt}}
+`;
+
+const LEGACY_INSTRUCTION_FOOTER = `## Instructions
+
+Continue working on this task. Use the cloud API to sync progress.
+Respect the Stage Completion Requirement before using [complete] or [done].
+
+{{runPaths}}
+
+To update the task:
+- [done] - Mark task complete
+- [complete: message] - Complete current stage
+- [log: message] - Add a log entry
+- [checkpoint: message] - Save progress checkpoint
+- [learn: insight] - Record a learning
+- [plan: text] - Update plan
+- [todo: text] - Update todo list
+
+{{finalPrompt}}`;
+
+const AGGREGATOR_PROMPT = `You are the decision aggregator for a {{role}} run.
+
+Task ID: {{taskId}}
+Title: {{title}}
+Stage: {{stage}}
+
+User Request: 
+"""
+{{taskTitle}}
+{{taskContent}}
+---
+Task Thread:
+{{taskComments}}
+"""
+
+Stage Objective: {{stagePrompt}}
+Stage Completion Requirement: {{stageRequirement}}
+
+Local run artifacts folder: {{runRoot}}
+Key run files:
+{{runFiles}}
+
+Relevant files referenced during execution (detected from output/logs):
+{{refsBlock}}
+
+Decide if the task is done. If not, provide the next instruction for another iteration.
+Only set "done": true when the Stage Completion Requirement is satisfied.
+
+You may think through your analysis first, but you MUST end your response with valid JSON.
+
+Output contract (strict):
+- You may include thinking/reasoning at the start of your response
+- Your response MUST end with exactly one raw JSON object
+- Do not use markdown/code fences/backticks around the JSON
+- Do not add commentary after the JSON
+- Use double-quoted keys and strings
+- Keep newlines escaped inside strings
+- If "done" is false, "next_prompt" must be a non-empty actionable instruction
+
+The final JSON in your response must have this exact shape:
+{
+  "done": false,
+  "decision": "done|blocked|not_done|failed",
+  "explanation": "clear explanation of the decision",
+  "final_result": "final result if done, empty string otherwise",
+  "next_prompt": "specific actionable instruction for next iteration",
+  "summary": "brief summary of current state"
+}
+
+If uncertain, still return valid JSON with decision "failed" and explain why in "explanation".
+`;
+
+const EXECUTE_ITERATION = `EXECUTE PHASE
+Iteration: {{iteration}}
+
+Keep output concise and avoid dumping full file contents or long logs.
+If you need to reference code, cite paths and describe changes instead of pasting whole files.
+
+Output contract:
+- Start with "PLAN:" then 2-5 bullets.
+- Do the work.
+- End with "IMPLEMENTATION SUMMARY:" bullets:
+  - Changed: (paths only, 10 max)
+  - Commands: (what you ran)
+  - Notes:
+
+Task for this iteration: {{instruction}}
+
+Do not output JSON in this phase.
+`;
+
+const VERIFY_PROMPT = `You are the verifier for an agx run.
+
+Task ID: {{taskId}}
+Title: {{title}}
+Stage: {{stage}}
+Iteration: {{iteration}}
+
+Stage Objective: {{stagePrompt}}
+Stage Completion Requirement: {{stageRequirement}}
+
+Local run artifacts folder: {{runRoot}}
+
+User Request: 
+"""
+{{requestTitle}}
+{{requestContent}}
+"""
+
+## Verification Strategy
+
+Your job is to determine whether the user request is actually satisfied in the codebase. Do NOT rely solely on git status/diff or agent output summaries — these can be misleading, incomplete, or refer to the wrong workspace.
+
+Follow this approach:
+
+1. **Understand the request.** What concrete outcome does the user want? (e.g., a function wired to an endpoint, a new component, a bug fix)
+
+2. **Read the actual source files.** Identify the key files that should contain the implementation and read them directly. Look for the specific functions, imports, routes, or components that the request describes. This is the primary evidence.
+
+3. **Check verification command output.** If tests or build commands were run, use their results as supporting evidence — but only after you've confirmed the implementation exists in the source.
+
+4. **Use git status/diff as secondary context.** Diff tells you what changed this iteration, but the feature may have been implemented in a prior iteration or already existed. Absence of a diff does NOT mean the work is incomplete.
+
+5. **Trace the full path.** For wiring tasks, verify both ends: the data source (API helper, service function) AND the consumer (page, component, hook). For bug fixes, verify the fix AND that the triggering condition is handled.
+
+Repo summary (git):
+Status (porcelain):
+{{statusShort}}
+
+Diff (stat):
+{{diffShort}}
+
+Verification commands:
+{{cmdLines}}
+
+Agent output (last iteration):
+{{agentOutputShort}}
+
+Decide if the stage is complete based on what you find in the source files.
+Ignore unrelated working tree changes; focus on whether the user request is satisfied.
+If not complete, provide the next smallest instruction for another iteration.
+Set "done": true when the user request is satisfied and the source code evidence supports it.
+
+Output contract (strict): your response MUST be exactly one raw JSON object with this shape:
+{
+  "done": false,
+  "decision": "done|blocked|not_done|failed",
+  "explanation": "clear explanation of the decision",
+  "final_result": "final result if done, empty string otherwise",
+  "next_prompt": "specific actionable instruction for next iteration",
+  "summary": "brief summary of current state",
+  "plan_md": "PLAN markdown for this iteration (newlines escaped)",
+  "implementation_summary_md": "IMPLEMENTATION SUMMARY markdown (newlines escaped)",
+  "verification_md": "VERIFICATION markdown (newlines escaped)"
+}
+
+Rules:
+- Use double-quoted keys and strings.
+- Keep newlines escaped inside strings (use \\n).
+- Keep the markdown fields short and checklist-style.
+- Always fill "explanation". For "blocked", include what is blocking and what input/action would unblock. For "failed", include what failed (command/tool/error) and a recovery step.
+`;
+
+const EXECUTOR_PROMPT = `# Task: {{title}}
+
+## Stage: {{stage}}
+
+{{stagePrompt}}
+
+## Project Context
+
+{{projectContext}}
+
+## Task Details
+
+{{content}}
+
+## Instructions
+
+1. Complete the work for this stage
+2. Use [checkpoint: message] to save progress
+3. Use [learn: insight] to record learnings
+4. Use [done] when stage is complete
+5. Use [blocked: reason] if you need human help
+
+Focus on this stage only. The task will automatically advance to the next stage when complete.
+`;
+
+module.exports = {
+  interpolate,
+  DEFAULT_STAGE_PROMPT,
+  PROJECT_CONTEXT,
+  AGX_SKILL,
+  CONTINUE_CLOUD_TASK,
+  NEW_AUTONOMOUS_CLOUD_TASK,
+  LEGACY_INSTRUCTION_FOOTER,
+  AGGREGATOR_PROMPT,
+  EXECUTE_ITERATION,
+  VERIFY_PROMPT,
+  EXECUTOR_PROMPT,
+};