@mndrk/agx 1.4.64 → 2.0.0-next.0

package/lib/prompts/resume.js

@@ -0,0 +1,353 @@
+'use strict';
+
+const { estimateTokens } = require('../storage/prompt_builder');
+
+const SECTION_TOKEN_BUDGETS = {
+  objective: 600,
+  criteria: 500,
+  plan: 400,
+  dontRepeat: 200,
+  constraints: 100,
+};
+
+const STABILITY_INSTRUCTIONS =
+  'Continue from current step. Do not rewrite the plan structure. Complete steps in order.';
+
+const PASS_STATUSES = new Set(['pass', 'passed', 'done', 'complete', 'success', 'ok']);
+const FAIL_STATUSES = new Set(['fail', 'failed', 'blocked', 'error', 'halt', 'abort']);
+
+function buildResumePrompt(checkpoint = {}) {
+  const sections = [];
+
+  const objectiveSection = buildObjectiveSection(checkpoint);
+  if (objectiveSection) {
+    sections.push(applyBudget('objective', objectiveSection));
+  }
+
+  const criteriaSection = buildCriteriaSection(checkpoint);
+  if (criteriaSection) {
+    sections.push(applyBudget('criteria', criteriaSection));
+  }
+
+  const planSection = buildPlanSection(checkpoint);
+  if (planSection) {
+    sections.push(applyBudget('plan', planSection));
+  }
+
+  const dontRepeatSection = buildListSection(
+    'Dont Repeat',
+    extractListFromCheckpoint(checkpoint, ['dontRepeat', 'dont_repeat', 'dont_repeat_items', 'dont_repeat_notes'])
+  );
+  if (dontRepeatSection) {
+    sections.push(applyBudget('dontRepeat', dontRepeatSection));
+  }
+
+  const constraintsSection = buildListSection(
+    'Dont Break',
+    extractListFromCheckpoint(checkpoint, ['constraints', 'constraint', 'dont_break', 'limits'])
+  );
+  if (constraintsSection) {
+    sections.push(applyBudget('constraints', constraintsSection));
+  }
+
+  const body = sections.filter(Boolean).join('\n\n').trim();
+  if (body) {
+    return `${body}\n\n${STABILITY_INSTRUCTIONS}`;
+  }
+
+  return STABILITY_INSTRUCTIONS;
+}
+
+function buildObjectiveSection(checkpoint) {
+  const objective = firstAvailableString(checkpoint, [
+    'objective',
+    'goal',
+    'summary',
+    'task',
+    'description',
+    'stageObjective',
+    'stage_obj',
+  ]);
+
+  return `## Task\n${objective || 'Objective not captured yet.'}`;
+}
+
+function buildCriteriaSection(checkpoint) {
+  const rawItems = extractCriteriaEntries(checkpoint);
+  const lines = normalizeCriteriaItems(rawItems);
+
+  if (!lines.length) {
+    return '## Done When\n- (criteria list not provided)';
+  }
+
+  return `## Done When\n${lines.map(({ marker, text, suffix }) => `- ${marker} ${text}${suffix}`).join('\n')}`;
+}
+
+function buildPlanSection(checkpoint) {
+  const rawSteps = resolvePlanSteps(checkpoint);
+  if (!rawSteps.length) {
+    return '## Plan\n- (plan steps not available)';
+  }
+
+  const normalized = normalizePlanSteps(rawSteps, checkpoint);
+  if (!normalized.length) {
+    return '## Plan\n- (plan steps not available)';
+  }
+
+  const lines = normalized.map((step) => {
+    const marker = planMarker(step);
+    return `- ${marker} ${step.text}`;
+  });
+
+  return `## Plan\n${lines.join('\n')}`;
+}
+
+function buildListSection(title, entries) {
+  const normalized = normalizeSimpleList(entries);
+  const header = `## ${title}`;
+  if (!normalized.length) {
+    return `${header}\n- (none recorded)`;
+  }
+  return `${header}\n${normalized.map((entry) => `- ${entry}`).join('\n')}`;
+}
+
+function applyBudget(sectionName, text) {
+  const trimmed = (text || '').trim();
+  if (!trimmed) return '';
+  const budget = SECTION_TOKEN_BUDGETS[sectionName];
+  if (!budget || estimateTokens(trimmed) <= budget) {
+    return trimmed;
+  }
+  return truncateToTokens(trimmed, budget);
+}
+
+function truncateToTokens(text, maxTokens) {
+  const trimmed = (text || '').trim();
+  if (!trimmed) return '';
+  if (!Number.isFinite(maxTokens) || maxTokens <= 0) {
+    return trimmed;
+  }
+
+  if (estimateTokens(trimmed) <= maxTokens) {
+    return trimmed;
+  }
+
+  let approxChars = Math.min(trimmed.length, Math.max(64, Math.floor(maxTokens * 4)));
+  let truncated = trimmed.slice(0, approxChars).trim();
+
+  while (estimateTokens(truncated) > maxTokens && approxChars > 0) {
+    approxChars = Math.max(0, approxChars - 128);
+    truncated = trimmed.slice(0, approxChars).trim();
+  }
+
+  if (!truncated) return '';
+  return `${truncated}\n\n(Truncated to stay within resume prompt budget)`;
+}
+
+function extractCriteriaEntries(checkpoint) {
+  const candidates = [checkpoint.criteria, checkpoint.criteria_list, checkpoint.criteriaList];
+  for (const candidate of candidates) {
+    const entries = normalizeGenericList(candidate);
+    if (entries.length) {
+      return entries;
+    }
+  }
+  return [];
+}
+
+function normalizeCriteriaItems(rawEntries) {
+  const items = [];
+
+  for (const entry of rawEntries) {
+    const source = typeof entry === 'string' ? { text: entry } : entry;
+    if (!source) continue;
+
+    const text = firstAvailableString(source, ['text', 'title', 'description', 'label']);
+    if (!text) continue;
+
+    const lowerStatus = (source.status || source.state || '').toString().toLowerCase();
+    const passed = Boolean(source.passed || source.pass || PASS_STATUSES.has(lowerStatus));
+    const failed = Boolean(source.failed || source.fail || FAIL_STATUSES.has(lowerStatus));
+
+    const marker = passed ? '[x]' : failed ? '[!]' : '[ ]';
+    const suffix = passed ? ' (pass)' : failed ? ' (fail)' : '';
+
+    items.push({ marker, text: text.trim(), suffix });
+  }
+
+  return items;
+}
+
+function resolvePlanSteps(checkpoint) {
+  const aliases = [
+    checkpoint.plan,
+    checkpoint.plan?.steps,
+    checkpoint.planSteps,
+    checkpoint.plan_entries,
+    checkpoint.planEntries,
+    checkpoint.steps,
+  ];
+
+  for (const candidate of aliases) {
+    const normalized = normalizeGenericList(candidate);
+    if (normalized.length) {
+      return normalized;
+    }
+  }
+
+  return [];
+}
+
+function normalizePlanSteps(entries, checkpoint) {
+  const normalized = entries
+    .map((entry) => {
+      const source = typeof entry === 'string' ? { text: entry } : entry;
+      if (!source) return null;
+
+      const text = firstAvailableString(source, ['text', 'title', 'description', 'label', 'name']);
+      if (!text) return null;
+
+      const lowerStatus = (source.status || source.state || '').toString().toLowerCase();
+      const done = Boolean(source.done || source.completed || PASS_STATUSES.has(lowerStatus));
+      const failed = Boolean(source.failed || FAIL_STATUSES.has(lowerStatus));
+      const explicitCurrent = Boolean(source.current || source.isCurrent || lowerStatus === 'current');
+
+      return {
+        text: text.trim(),
+        done,
+        failed,
+        explicitCurrent,
+      };
+    })
+    .filter(Boolean);
+
+  if (!normalized.length) {
+    return [];
+  }
+
+  const currentIndex = resolveCurrentStepIndex(normalized, checkpoint);
+
+  return normalized.map((step, index) => ({
+    text: step.text,
+    done: step.done,
+    failed: step.failed,
+    current: index === currentIndex,
+  }));
+}
+
+function resolveCurrentStepIndex(steps, checkpoint) {
+  const flaggedIndex = steps.findIndex((step) => step.explicitCurrent);
+  if (flaggedIndex >= 0) {
+    return flaggedIndex;
+  }
+
+  const indexKeys = [
+    'currentStepIndex',
+    'current_step_index',
+    'currentPlanStepIndex',
+    'current_plan_step_index',
+    'currentPlanIndex',
+    'currentPlan',
+  ];
+
+  for (const key of indexKeys) {
+    const value = checkpoint[key];
+    const parsed = typeof value === 'number' ? value : parseInt(value, 10);
+    if (Number.isInteger(parsed) && parsed >= 0 && parsed < steps.length) {
+      return parsed;
+    }
+  }
+
+  const currentName = firstAvailableString(checkpoint, [
+    'currentStep',
+    'current_step',
+    'currentPlanStep',
+    'current_plan_step',
+  ]);
+  if (currentName) {
+    const lowered = currentName.toLowerCase();
+    const byName = steps.findIndex((step) => step.text.toLowerCase() === lowered || step.text.toLowerCase().includes(lowered));
+    if (byName >= 0) {
+      return byName;
+    }
+  }
+
+  const firstPending = steps.findIndex((step) => !step.done && !step.failed);
+  if (firstPending >= 0) {
+    return firstPending;
+  }
+
+  return 0;
+}
+
+function planMarker(step) {
+  if (step.current) return '[→]';
+  if (step.failed) return '[!]';
+  if (step.done) return '[x]';
+  return '[ ]';
+}
+
+function extractListFromCheckpoint(checkpoint, keys) {
+  if (!checkpoint) return [];
+  for (const key of keys) {
+    const value = checkpoint[key];
+    const normalized = normalizeSimpleList(value);
+    if (normalized.length) {
+      return normalized;
+    }
+  }
+  return [];
+}
+
+function normalizeGenericList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string') {
+    return value
+      .split(/\r?\n/)
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+  if (typeof value === 'object') {
+    const items = [];
+    if (Array.isArray(value.items)) {
+      items.push(...value.items);
+    } else if (Array.isArray(value.list)) {
+      items.push(...value.list);
+    } else {
+      items.push(...Object.values(value));
+    }
+    return items;
+  }
+  return [];
+}
+
+function normalizeSimpleList(value) {
+  const generic = normalizeGenericList(value);
+  return generic
+    .map((entry) => {
+      if (!entry) return '';
+      if (typeof entry === 'string') return entry.trim();
+      if (typeof entry === 'object') {
+        return firstAvailableString(entry, ['text', 'content', 'description', 'note']) || '';
+      }
+      return String(entry).trim();
+    })
+    .filter(Boolean);
+}
+
+function firstAvailableString(source, keys) {
+  if (!source || typeof source !== 'object') {
+    return '';
+  }
+  for (const key of keys) {
+    if (typeof source[key] === 'string' && source[key].trim()) {
+      return source[key].trim();
+    }
+  }
+  return '';
+}
+
+module.exports = {
+  buildResumePrompt,
+};

package/lib/prompts/templates.js

@@ -17,18 +17,18 @@ function interpolate(template, vars) {
 // Static templates (no variables)
 // ---------------------------------------------------------------------------
 
-const DEFAULT_STAGE_PROMPT = 'Execute this stage using the latest stage prompt from the cloud task context.';
+const DEFAULT_STAGE_PROMPT = 'Carry out this scope using the latest objective 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.',
+  'Quick-start workflow: `agx new "<goal>"`, optionally `agx -a -p "<goal>"` for autonomous operation, 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.',
+  'Agent workflow: orient on saved state, outline, implement, 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');
@@ -59,6 +59,17 @@ agx status <taskId>     # Show detailed info for a specific task
 agx status              # Show current status
 \`\`\`
 
+## Task Dependencies (ordering)
+
+\`\`\`bash
+agx new "Task C" --depends-on <taskA-id> --depends-on <taskB-id>
+agx deps <task-c>                                  # Show depends_on + dependents
+agx deps <task-c> --depends-on <taskA> --depends-on <taskB>  # Set dependencies
+agx deps <task-c> --clear                          # Remove all dependencies
+\`\`\`
+
+Use task UUIDs, slugs, or \`agx task ls\` index references.
+
 ## Checking Tasks
 
 \`\`\`bash
@@ -160,6 +171,10 @@ 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].
 
+Follow-up work policy:
+- If you identify follow-up tasks, create them in AGX via CLI ("agx new") and include the owning project id using "--project <project_id>".
+- Do not leave follow-up work only as local ticket/markdown notes.
+
 {{runPaths}}
 
 To update the task:
@@ -195,7 +210,7 @@ Local run artifacts folder: {{runRoot}}
 Key run files:
 {{runFiles}}
 
-Relevant files referenced during execution (detected from output/logs):
+Relevant files referenced during recent runs (detected from output/logs):
 {{refsBlock}}
 
 Decide if the task is done. If not, provide the next instruction for another iteration.
@@ -225,7 +240,7 @@ The final JSON in your response must have this exact shape:
 If uncertain, still return valid JSON with decision "failed" and explain why in "explanation".
 `;
 
-const EXECUTE_ITERATION = `EXECUTE PHASE
+const EXECUTE_ITERATION = `WORK PHASE
 Iteration: {{iteration}}
 
 Keep output concise and avoid dumping full file contents or long logs.
@@ -244,7 +259,7 @@ Task for this iteration: {{instruction}}
 Do not output JSON in this phase.
 `;
 
-const VERIFY_PROMPT = `You are the verifier for an agx run.
+const VERIFY_PROMPT = `You are the validator for an agx run.
 
 Task ID: {{taskId}}
 Title: {{title}}
@@ -262,7 +277,7 @@ User Request:
 {{requestContent}}
 """
 
-## Verification Strategy
+## Validation 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.
 
@@ -272,11 +287,11 @@ Follow this approach:
 
 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.
+3. **Check validation 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.
+5. **Trace the full path.** For wiring tasks, confirm both ends: the data source (API helper, service function) AND the consumer (page, component, hook). For bug fixes, confirm the fix AND that the triggering condition is handled.
 
 Repo summary (git):
 Status (porcelain):
@@ -285,7 +300,7 @@ Status (porcelain):
 Diff (stat):
 {{diffShort}}
 
-Verification commands:
+Validation commands:
 {{cmdLines}}
 
 Agent output (last iteration):
@@ -306,7 +321,7 @@ Output contract (strict): your response MUST be exactly one raw JSON object with
   "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)"
+  "validation_md": "VALIDATION markdown (newlines escaped)"
 }
 
 Rules:
@@ -337,6 +352,7 @@ const EXECUTOR_PROMPT = `# Task: {{title}}
 3. Use [learn: insight] to record learnings
 4. Use [done] when stage is complete
 5. Use [blocked: reason] if you need human help
+6. If follow-up tasks are needed, create them with "agx new --project <project_id>" instead of only writing them to local ticket files.
 
 Focus on this stage only. The task will automatically advance to the next stage when complete.
 `;

package/lib/stage-requirements.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const STAGE_REQUIREMENTS = {
-  ideation: {
+  intake: {
     artifact: 'idea',
     guidance: 'A concrete idea with scope, approach, and key unknowns.'
   },
@@ -105,7 +105,7 @@ function enforceStageRequirement(decision, { stage, stagePrompt }) {
   if (!decision.done) return decision;
 
   const req = getStageRequirement(stage);
-  // Only enforce explicit artifact requirements (ideation/planning today). For other stages, the
+  // Only enforce explicit artifact requirements (intake/planning today). For other stages, the
   // verifier/aggregator decision stands; we should not require keyword echoes from stage prompts.
   if (!req) return decision;
   if (hasRequiredArtifact(stage, decision, stagePrompt)) return decision;