@goodandready/dsh-goal 0.2.8 → 0.2.10

package/lib/engine-intervention.js

@@ -0,0 +1,150 @@
+import { MilestoneStatus } from './goal-engine-constants.js';
+
+/**
+ * Apply human intervention to a paused goal
+ * @param {object} goal 
+ * @param {object} intervention 
+ * @returns {object} result
+ */
+export function applyIntervention(goal, intervention = {}) {
+  if (!goal) {
+    return { ok: false, error: 'No active goal' };
+  }
+
+  const { directive, milestones, deletedMilestoneIds } = intervention;
+
+  if (typeof directive === 'string' && directive.trim()) {
+    goal.userDirective = directive.trim();
+    goal.userDirectiveConsumed = false;
+  }
+
+  if (Array.isArray(deletedMilestoneIds) && deletedMilestoneIds.length > 0) {
+    const toDelete = new Set(deletedMilestoneIds.map(String));
+    goal.milestones = goal.milestones.filter((m) => {
+      // Do not allow deleting completed milestones
+      if (m.status === MilestoneStatus.COMPLETED) return true;
+      return !toDelete.has(String(m.id));
+    });
+  }
+
+  if (Array.isArray(milestones) && milestones.length > 0) {
+    for (const update of milestones) {
+      if (!update || !update.id) continue;
+      const target = goal.milestones.find((m) => String(m.id) === String(update.id));
+      if (target) {
+        if (typeof update.title === 'string' && update.title.trim()) {
+          target.title = update.title.trim();
+        }
+        if (typeof update.notes === 'string') {
+          target.notes = update.notes.trim();
+        }
+        if (update.status && Object.values(MilestoneStatus).includes(update.status)) {
+          target.status = update.status;
+        }
+        if (Array.isArray(update.dependsOn)) {
+          target.dependsOn = update.dependsOn.map(String);
+        }
+      } else if (typeof update.title === 'string' && update.title.trim()) {
+        goal.milestones.push({
+          id: String(update.id),
+          title: update.title.trim(),
+          status: update.status || MilestoneStatus.PENDING,
+          notes: update.notes ? String(update.notes).trim() : '',
+          checklist: Array.isArray(update.checklist) ? update.checklist : [],
+          dependsOn: Array.isArray(update.dependsOn) ? update.dependsOn.map(String) : [],
+        });
+      }
+    }
+  }
+
+  recordActivity(goal, {
+    type: 'intervention',
+    tool: 'user_intervention',
+    status: 'success',
+    details: directive ? `Directive: ${directive.slice(0, 60)}` : 'Plan adjusted by user',
+  });
+
+  return { ok: true, goal };
+}
+
+/**
+ * Record an activity entry in the goal's recent activity feed (max 10 entries)
+ * @param {object} goal 
+ * @param {object} entry 
+ */
+export function recordActivity(goal, entry = {}) {
+  if (!goal) return;
+  if (!Array.isArray(goal.activityFeed)) {
+    goal.activityFeed = [];
+  }
+
+  const actEntry = {
+    id: `act-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+    type: entry.type || 'tool',
+    tool: entry.tool || 'unknown',
+    status: entry.status || 'info',
+    details: entry.details ? String(entry.details).slice(0, 200) : '',
+    timestamp: entry.timestamp || Date.now(),
+  };
+
+  goal.activityFeed.push(actEntry);
+  if (goal.activityFeed.length > 10) {
+    goal.activityFeed.shift();
+  }
+}
+
+/**
+ * Check and enforce token budget limits and auto-scaling
+ * @param {object} goal 
+ * @param {object} options 
+ * @returns {{ paused: boolean }}
+ */
+export function processTokenBudget(goal, options = {}) {
+  const { maxTokenBudget = 0, budgetWarningThreshold = 80, autoScaleBudgetNearCompletion = false, GoalState } = options;
+  const budget = goal.maxTokenBudget || maxTokenBudget || 0;
+  if (budget <= 0 || !goal.tokensUsage) return { paused: false };
+
+  const currentTotal = goal.tokensUsage.totalTokens;
+  const warnThreshold = (budget * budgetWarningThreshold) / 100;
+
+  if (currentTotal >= warnThreshold && !goal.budgetWarningTriggered) {
+    goal.budgetWarningTriggered = true;
+    goal.logs.push({
+      timestamp: Date.now(),
+      type: 'warning',
+      message: `Token budget warning: ${currentTotal.toLocaleString('en-US')}/${budget.toLocaleString('en-US')} tokens consumed (${Math.round((currentTotal / budget) * 100)}%)`,
+    });
+    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  }
+
+  if (currentTotal >= budget && goal.state === (GoalState?.RUNNING || 'running')) {
+    const milestones = goal.milestones || [];
+    const completed = milestones.filter((m) => m.status === MilestoneStatus.COMPLETED).length;
+    const progress = milestones.length > 0 ? (completed / milestones.length) : 0;
+
+    if (autoScaleBudgetNearCompletion && !goal.budgetAutoScaled && (progress >= 0.8 || completed === milestones.length - 1)) {
+      const buffer = Math.round(budget * 0.2);
+      goal.maxTokenBudget = budget + buffer;
+      goal.budgetAutoScaled = true;
+      goal.logs.push({
+        timestamp: Date.now(),
+        type: 'info',
+        message: `Token budget auto-scaled by +${buffer.toLocaleString('en-US')} tokens near completion`,
+      });
+      if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+      return { paused: false };
+    }
+
+    goal.state = GoalState?.PAUSED || 'paused';
+    goal.pausedAt = Date.now();
+    goal.logs.push({
+      timestamp: Date.now(),
+      type: 'warning',
+      message: `Token budget reached: ${currentTotal.toLocaleString('en-US')}/${budget.toLocaleString('en-US')} tokens. Pausing autonomous loop.`,
+    });
+    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+    return { paused: true };
+  }
+
+  return { paused: false };
+}

package/lib/engine-issue-sync.js

@@ -0,0 +1,66 @@
+/**
+ * Parse issue identifier from goal title or string
+ * @param {string} input 
+ * @returns {object|null} { issueNumber, issueUrl }
+ */
+export function parseIssueRef(input) {
+  if (!input || typeof input !== 'string') return null;
+  const urlMatch = input.match(/https?:\/\/[^\s]+\/issues\/(\d+)/i);
+  if (urlMatch) {
+    return { issueNumber: parseInt(urlMatch[1], 10), issueUrl: urlMatch[0] };
+  }
+  const numMatch = input.match(/(?:issue:?|#)(\d+)\b/i);
+  if (numMatch) {
+    return { issueNumber: parseInt(numMatch[1], 10), issueUrl: null };
+  }
+  return null;
+}
+
+/**
+ * Parse checklist items from markdown text
+ * @param {string} markdown 
+ * @returns {Array<{ text: string, done: boolean, raw: string }>}
+ */
+export function parseIssueChecklist(markdown) {
+  if (!markdown || typeof markdown !== 'string') return [];
+  const items = [];
+  const lines = markdown.split('\n');
+  const regex = /^\s*-\s*\[([ xX])\]\s*(.+)$/;
+
+  for (const line of lines) {
+    const match = line.match(regex);
+    if (match) {
+      items.push({
+        done: match[1].toLowerCase() === 'x',
+        text: match[2].trim(),
+        raw: line,
+      });
+    }
+  }
+  return items;
+}
+
+/**
+ * Update checklist item status in markdown text
+ * @param {string} markdown 
+ * @param {string} itemText 
+ * @param {boolean} done 
+ * @returns {string} updated markdown
+ */
+export function updateChecklistInMarkdown(markdown, itemText, done) {
+  if (!markdown || typeof markdown !== 'string') return markdown || '';
+  if (!itemText) return markdown;
+
+  const targetClean = itemText.trim().toLowerCase();
+  const lines = markdown.split('\n');
+  const regex = /^(\s*-\s*\[)([ xX])(\]\s*)(.+)$/;
+
+  return lines.map((line) => {
+    const match = line.match(regex);
+    if (match && match[4].trim().toLowerCase() === targetClean) {
+      const checkChar = done ? 'x' : ' ';
+      return `${match[1]}${checkChar}${match[3]}${match[4]}`;
+    }
+    return line;
+  }).join('\n');
+}

package/lib/engine-milestones.js

@@ -32,6 +32,31 @@ export function parseChecklist(checklist) {
     .filter((item) => item.text.length > 0);
 }
 
+/**
+ * Check if a milestone is blocked by uncompleted prerequisite dependencies
+ * @param {object} milestone 
+ * @param {Array<object>} allMilestones 
+ * @returns {{ blocked: boolean, missingDependencies: string[] }}
+ */
+export function isMilestoneBlocked(milestone, allMilestones = []) {
+  if (!milestone || !Array.isArray(milestone.dependsOn) || milestone.dependsOn.length === 0) {
+    return { blocked: false, missingDependencies: [] };
+  }
+
+  const missing = [];
+  for (const depId of milestone.dependsOn) {
+    const parent = allMilestones.find((m) => matchMilestone(m, depId));
+    if (!parent || parent.status !== MilestoneStatus.COMPLETED) {
+      missing.push(String(depId));
+    }
+  }
+
+  return {
+    blocked: missing.length > 0,
+    missingDependencies: missing,
+  };
+}
+
 /**
  * Build and normalize milestone objects from list
  * @param {Array} milestonesList
@@ -54,6 +79,7 @@ export function parseMilestoneItems(milestonesList, startingCount = 0) {
       title: itemTitle.trim(),
       status: typeof item === 'object' && item?.status ? item.status : MilestoneStatus.PENDING,
       notes: typeof item === 'object' && item?.notes ? String(item.notes) : '',
+      dependsOn: typeof item === 'object' && Array.isArray(item?.dependsOn) ? item.dependsOn.map(String) : [],
     };
     if (typeof item === 'object' && Array.isArray(item?.checklist)) {
       mObj.checklist = parseChecklist(item.checklist);
@@ -71,12 +97,25 @@ export function parseMilestoneItems(milestonesList, startingCount = 0) {
  * @param {string} [notes] New notes
  * @param {Array} [checklist] New checklist
  * @param {Array<string>} [validStatuses] Allowed statuses
- * @returns {{ prevStatus: string, updatedStatus: string }}
+ * @param {object} [options] Validation options
+ * @returns {{ prevStatus: string, updatedStatus: string, blocked?: boolean, missingDependencies?: string[] }}
  */
-export function applyMilestoneUpdate(target, status, notes = '', checklist = null, validStatuses = []) {
+export function applyMilestoneUpdate(target, status, notes = '', checklist = null, validStatuses = [], options = {}) {
   if (!target) return { prevStatus: null, updatedStatus: null };
   const prevStatus = target.status;
 
+  if (options.enforceDependencies && (status === MilestoneStatus.IN_PROGRESS || status === MilestoneStatus.COMPLETED)) {
+    const depCheck = isMilestoneBlocked(target, options.allMilestones || []);
+    if (depCheck.blocked) {
+      return {
+        prevStatus,
+        updatedStatus: prevStatus,
+        blocked: true,
+        missingDependencies: depCheck.missingDependencies,
+      };
+    }
+  }
+
   if (status && (validStatuses.length === 0 || validStatuses.includes(status))) {
     target.status = status;
   }
@@ -87,7 +126,7 @@ export function applyMilestoneUpdate(target, status, notes = '', checklist = nul
     target.checklist = parseChecklist(checklist);
   }
 
-  return { prevStatus, updatedStatus: target.status };
+  return { prevStatus, updatedStatus: target.status, blocked: false };
 }
 
 /**

package/lib/engine-prompt.js

@@ -1,3 +1,5 @@
+import { isMilestoneBlocked } from './engine-milestones.js';
+
 /**
  * Prompt generation for DSH Goal Mode
  */
@@ -6,6 +8,15 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
   const hasMilestones = snapshot.milestones && snapshot.milestones.length > 0;
   const etaText = snapshot.formattedETA ? ` (ETA: ${snapshot.formattedETA})` : '';
 
+  let directiveText = '';
+  if (snapshot.userDirective && !snapshot.userDirectiveConsumed) {
+    if (lang === 'zh') {
+      directiveText = `\n\n🛑 用户干预指令 (USER INTERVENTION DIRECTIVE):\n"${snapshot.userDirective}"\n你必须无条件优先遵循此指令，调整接下来的执行决策与步骤！\n`;
+    } else {
+      directiveText = `\n\n🛑 USER INTERVENTION DIRECTIVE:\n"${snapshot.userDirective}"\nYou must prioritize and follow this directive immediately in your next decisions and actions!\n`;
+    }
+  }
+
   let nudgeText = '';
   if (pendingNudge) {
     if (lang === 'zh') {
@@ -16,7 +27,13 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
   }
 
   let budgetWarningText = '';
-  if (snapshot.budgetWarningTriggered) {
+  if (snapshot.budgetAutoScaled) {
+    if (lang === 'zh') {
+      budgetWarningText = `\n\n💡 TOKEN 预算自动延展通知:\n检测到目标已接近尾声，系统已自动按策略扩充了缓冲预算。请集中精力尽快完成最后阶段，不要展开多余任务！\n`;
+    } else {
+      budgetWarningText = `\n\n💡 TOKEN BUDGET AUTO-SCALED:\nGoal is near completion; an automatic buffer extension was granted. Focus strictly on wrapping up the remaining milestones!\n`;
+    }
+  } else if (snapshot.budgetWarningTriggered) {
     const total = snapshot.tokensUsage?.totalTokens || 0;
     const max = snapshot.maxTokenBudget || 0;
     const pct = max > 0 ? Math.round((total / max) * 100) : 0;
@@ -27,8 +44,13 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     }
   }
 
+  const allMilestones = snapshot.milestones || [];
   const formatMilestone = (m, i) => {
-    let line = `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`;
+    const depCheck = isMilestoneBlocked(m, allMilestones);
+    const blockedLabel = depCheck.blocked
+      ? ` (BLOCKED by ${depCheck.missingDependencies.join(', ')})`
+      : '';
+    let line = `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${blockedLabel}${m.notes ? ` (${m.notes})` : ''}`;
     if (Array.isArray(m.checklist) && m.checklist.length > 0) {
       const checkLines = m.checklist
         .map((item) => `      [${item.done ? 'x' : ' '}] ${item.text}`)
@@ -44,6 +66,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
       : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
 
     return (
+      directiveText +
       nudgeText +
       budgetWarningText +
       `\n\n[DSH GOAL MODE ACTIVE]\n` +
@@ -52,7 +75,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
       `工作计划:\n` +
       `${milestonesText}\n\n` +
       `Goal Mode 执行契约 (必须严格遵循):\n` +
-      `1. ${hasMilestones ? '按部就班推进当前进行中的里程碑。' : '第一步核心指令: 立即调用 goal_set_milestones 制定 3-7 个具体里程碑。在完成此工具调用前严禁执行其他操作！'}\n` +
+      `1. ${hasMilestones ? '按部就班推进当前进行中的里程碑。注意：标记为 [BLOCKED] 的里程碑在前置依赖完成前严禁推进。' : '第一步核心指令: 立即调用 goal_set_milestones 制定 3-7 个具体里程碑。在完成此工具调用前严禁执行其他操作！'}\n` +
       `2. 推进里程碑时，必须通过 goal_update_progress 工具更新状态（开始前标为 in_progress，完成后标为 completed 并附简要说明）。如有细分子任务，可通过 checklist 字段同步进度。\n` +
       `3. 当所有里程碑全部完成后，调用 goal_finish 工具提交详细成果总结。`
     );
@@ -63,6 +86,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
 
   return (
+    directiveText +
     nudgeText +
     budgetWarningText +
     `\n\n[DSH GOAL MODE ACTIVE]\n` +
@@ -71,7 +95,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     `Work Plan:\n` +
     `${milestonesText}\n\n` +
     `Goal Mode Instructions (MANDATORY TO FOLLOW):\n` +
-    `1. ${hasMilestones ? 'Execute the current active milestone from the work plan.' : 'YOUR FIRST STEP: Immediately call tool goal_set_milestones with the list of milestones (3-7 concrete steps). You must not execute work or finish turn without calling goal_set_milestones!'}\n` +
+    `1. ${hasMilestones ? 'Execute the current active milestone from the work plan. Note: Milestones marked [BLOCKED] must not be started until prerequisite milestones are COMPLETED.' : 'YOUR FIRST STEP: Immediately call tool goal_set_milestones with the list of milestones (3-7 concrete steps). You must not execute work or finish turn without calling goal_set_milestones!'}\n` +
     `2. As each milestone progresses, update its status via tool goal_update_progress (status: "in_progress" before starting, status: "completed" upon completion with brief notes). If sub-tasks exist, pass checklist array to track items.\n` +
     `3. When all milestones are completed, call tool goal_finish with a detailed summary of achieved results.`
   );

package/lib/engine-retrospective.js

@@ -0,0 +1,79 @@
+import { execFileSync } from 'node:child_process';
+import { MilestoneStatus, calculateElapsedSeconds } from './goal-engine-constants.js';
+
+/**
+ * Generate post-goal retrospective analytics card
+ * @param {object} goal 
+ * @param {string} cwd 
+ * @returns {object} retrospective summary
+ */
+export function generateRetrospectiveData(goal, cwd = process.cwd()) {
+  if (!goal) return null;
+
+  const elapsedSeconds = calculateElapsedSeconds(goal);
+  const totalTokens = goal.tokensUsage?.totalTokens || 0;
+  // Estimated cost based on blended DeepSeek API pricing (~$0.0000015/token)
+  const estimatedCostUsd = Number(((totalTokens * 0.0000015)).toFixed(4));
+
+  const milestones = Array.isArray(goal.milestones) ? goal.milestones : [];
+  const totalMilestones = milestones.length;
+  const completedMilestones = milestones.filter((m) => m.status === MilestoneStatus.COMPLETED).length;
+
+  const milestoneVelocity = completedMilestones > 0
+    ? Math.round(elapsedSeconds / completedMilestones)
+    : 0;
+
+  const activities = Array.isArray(goal.activityFeed) ? goal.activityFeed : [];
+  const totalToolCalls = activities.filter((a) => a.type === 'tool').length;
+  const failedToolCalls = activities.filter((a) => a.type === 'tool' && a.status === 'error').length;
+  const toolFailureRate = totalToolCalls > 0
+    ? Math.round((failedToolCalls / totalToolCalls) * 100)
+    : 0;
+
+  let gitDiffStat = '';
+  let filesChangedCount = 0;
+  try {
+    const startRef = goal.startCommit || 'HEAD~1';
+    const rawStat = execFileSync('git', ['diff', '--stat', `${startRef}..HEAD`], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    gitDiffStat = rawStat;
+    const match = rawStat.match(/(\d+)\s+file[s]?\s+changed/i);
+    if (match) {
+      filesChangedCount = parseInt(match[1], 10);
+    }
+  } catch (err) {
+    gitDiffStat = 'No git diff available';
+  }
+
+  const recommendations = [];
+  if (toolFailureRate > 20) {
+    recommendations.push('High tool error rate detected; check command arguments or environment paths.');
+  }
+  if (totalTokens > 100000) {
+    recommendations.push('Consider setting maxTokenBudget or decomposing goal into smaller sub-tasks.');
+  }
+  if (completedMilestones === totalMilestones && totalMilestones > 0) {
+    recommendations.push('All milestones completed cleanly. Recommended next step: run full test suite and verify git status.');
+  }
+
+  return {
+    title: goal.title || 'Untitled Goal',
+    elapsedSeconds,
+    totalTokens,
+    estimatedCostUsd,
+    totalMilestones,
+    completedMilestones,
+    milestoneVelocity,
+    totalToolCalls,
+    failedToolCalls,
+    toolFailureRate,
+    gitDiffStat,
+    filesChangedCount,
+    recommendations,
+    gitBranch: goal.gitBranch || null,
+    generatedAt: Date.now(),
+  };
+}

package/lib/engine-sessions.js

@@ -0,0 +1,82 @@
+import { GoalState } from './goal-engine-constants.js';
+
+/**
+ * Prune inactive sessions when exceeding maxSessions threshold
+ */
+export function pruneInactiveSessions(goals, stallCounters, toolFailureCounters, maxSessions = 100) {
+  if (!goals || goals.size < maxSessions) return;
+  const inactive = [];
+  for (const [sid, goal] of goals.entries()) {
+    if (sid === 'default') continue;
+    if (goal.state === GoalState.COMPLETED || goal.state === GoalState.CANCELLED || goal.state === GoalState.FAILED) {
+      inactive.push({ sid, completedAt: goal.completedAt || goal.startedAt || 0 });
+    }
+  }
+  inactive.sort((a, b) => a.completedAt - b.completedAt);
+  while (goals.size >= maxSessions && inactive.length > 0) {
+    const oldest = inactive.shift();
+    goals.delete(oldest.sid);
+    stallCounters?.delete(oldest.sid);
+    toolFailureCounters?.delete(oldest.sid);
+  }
+}
+
+/**
+ * Add a user steering nudge to a goal
+ */
+export function addNudgeToGoal(goal, text) {
+  if (!goal) return null;
+  const clean = String(text || '').trim();
+  if (!clean) return null;
+
+  if (!Array.isArray(goal.nudges)) goal.nudges = [];
+  const now = Date.now();
+  goal.nudges.push({ text: clean, timestamp: now });
+  goal.pendingNudge = clean;
+  goal.logs.push({
+    timestamp: now,
+    type: 'info',
+    message: `User steering / clarification: "${clean}"`,
+  });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return clean;
+}
+
+/**
+ * Consume and clear pending nudge
+ */
+export function consumeGoalNudge(goal) {
+  if (!goal || !goal.pendingNudge) return null;
+  const nudge = goal.pendingNudge;
+  goal.pendingNudge = null;
+  return nudge;
+}
+
+/**
+ * Extend token budget for a goal
+ */
+export function extendGoalBudget(goal, addTokens = 50000, defaultBudget = 0) {
+  if (!goal) return null;
+  const currentTotal = goal.tokensUsage?.totalTokens || 0;
+  const currentMax = goal.maxTokenBudget || defaultBudget || 0;
+  const newBudget = Math.max(currentTotal, currentMax) + Math.max(1000, Number(addTokens) || 50000);
+  goal.maxTokenBudget = newBudget;
+
+  const now = Date.now();
+  if (goal.state === GoalState.PAUSED) {
+    if (goal.pausedAt) {
+      goal.totalPausedDurationMs += now - goal.pausedAt;
+      goal.pausedAt = null;
+    }
+    goal.state = GoalState.RUNNING;
+  }
+
+  goal.budgetWarningTriggered = false;
+  goal.logs.push({
+    timestamp: now,
+    type: 'info',
+    message: `Token budget extended by +${addTokens.toLocaleString('en-US')} (new limit: ${newBudget.toLocaleString('en-US')})`,
+  });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return newBudget;
+}