@goodandready/dsh-goal 0.2.31 → 0.2.33

package/lib/goal-engine.js

@@ -13,8 +13,12 @@ import { parseIssueRef, parseIssueChecklist, syncMilestoneWithIssue } from './en
 import { generateRetrospectiveData } from './engine-retrospective.js';
 import { generatePreplanDraft } from './engine-templates.js';
 import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget, setGoalMode, pauseGoal, resumeGoal, cancelGoal } from './engine-sessions.js';
+import { compactMilestone, estimateCompactionSavings } from './engine-compaction.js';
+import { spawnSubGoal, completeSubGoal, syncSubGoalToParent, getSubGoalBreadcrumbs, getSubGoalsList } from './engine-subgoals.js';
+import { updateGoalCostUsage, processCostBudget, calculateCost, formatCurrency } from './engine-cost-meter.js';
+import { generateReleaseNotes, dispatchGoalTelegramNotification } from './engine-release-notes.js';
 
-export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist, getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
+export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist, getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact, compactMilestone, estimateCompactionSavings, spawnSubGoal, completeSubGoal, getSubGoalBreadcrumbs, getSubGoalsList, calculateCost, formatCurrency, generateReleaseNotes, dispatchGoalTelegramNotification };
 
 /**
  * Isolated Goal Management Engine for DeepSeek Harness
@@ -34,8 +38,8 @@ export class GoalEngine {
       autoBranchOnGoalStart: options.autoBranchOnGoalStart ?? true, enablePostGoalRetrospective: options.enablePostGoalRetrospective ?? true,
       autoScaleBudgetNearCompletion: options.autoScaleBudgetNearCompletion ?? false, enableTemplatesDrawer: options.enableTemplatesDrawer ?? true,
       enableMilestoneDependencies: options.enableMilestoneDependencies ?? true, soundScheme: options.soundScheme ?? 'default', enableKanbanSync: options.enableKanbanSync ?? true, ctx: options.ctx || null, kanbanService: options.kanbanService || null, kanbanStore: options.kanbanStore || null,
-      enableVoiceAnnouncements: options.enableVoiceAnnouncements ?? false, approvalGate: options.approvalGate || null,
-      checkApproval: options.checkApproval || null, maxSessions: options.maxSessions ?? 100,
+      enableVoiceAnnouncements: options.enableVoiceAnnouncements ?? false, enableMilestoneCompaction: options.enableMilestoneCompaction ?? true, approvalGate: options.approvalGate || null,
+      checkApproval: options.checkApproval || null, maxSessions: options.maxSessions ?? 100, maxCostBudget: options.maxCostBudget ?? 0, costWarningThreshold: options.costWarningThreshold ?? 80, currency: options.currency || 'USD', enableTelegramNotifications: options.enableTelegramNotifications ?? false, activeModel: options.activeModel || '', customRates: options.customRates || {},
     });
     this.goals = new Map();
     this.listeners = new Set();
@@ -58,10 +62,7 @@ export class GoalEngine {
   flushSync() { this.store.flushSync(); }
   saveStateToDisk() { this.flushSync(); }
 
-  subscribe(callback) {
-    this.listeners.add(callback);
-    return () => this.listeners.delete(callback);
-  }
+  subscribe(callback) { this.listeners.add(callback); return () => this.listeners.delete(callback); }
 
   emit(sessionId = 'default', immediate = false) {
     this.scheduleSave(immediate);
@@ -76,21 +77,9 @@ export class GoalEngine {
     }
   }
 
-  recordProgress(sessionId = 'default') {
-    this.stallCounters.set(sessionId || 'default', 0);
-  }
-
-  incrementStallCount(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    const current = this.stallCounters.get(sid) || 0;
-    const next = current + 1;
-    this.stallCounters.set(sid, next);
-    return next;
-  }
-
-  getStallCount(sessionId = 'default') {
-    return this.stallCounters.get(sessionId || 'default') || 0;
-  }
+  recordProgress(sessionId = 'default') { this.stallCounters.set(sessionId || 'default', 0); }
+  incrementStallCount(sessionId = 'default') { const sid = sessionId || 'default'; const n = (this.stallCounters.get(sid) || 0) + 1; this.stallCounters.set(sid, n); return n; }
+  getStallCount(sessionId = 'default') { return this.stallCounters.get(sessionId || 'default') || 0; }
 
   updateConfig(config = {}) {
     const rawMax = config.defaultMaxIterations ?? config.maxIterations;
@@ -104,12 +93,17 @@ export class GoalEngine {
         }
       }
     }
-    const boolKeys = ['autoDrive', 'enableSound', 'showQuickLaunchButton', 'autoCheckpointOnMilestone', 'enableLiveActivityFeed', 'enablePreplanning', 'autoBranchOnGoalStart', 'enablePostGoalRetrospective', 'autoScaleBudgetNearCompletion', 'enableTemplatesDrawer', 'enableMilestoneDependencies', 'enableVoiceAnnouncements'];
+    const boolKeys = ['autoDrive', 'enableSound', 'showQuickLaunchButton', 'autoCheckpointOnMilestone', 'enableLiveActivityFeed', 'enablePreplanning', 'autoBranchOnGoalStart', 'enablePostGoalRetrospective', 'autoScaleBudgetNearCompletion', 'enableTemplatesDrawer', 'enableMilestoneDependencies', 'enableVoiceAnnouncements', 'enableMilestoneCompaction'];
     for (const k of boolKeys) if (typeof config[k] === 'boolean') this[k] = config[k];
     if (typeof config.consecutiveToolFailureLimit === 'number') this.consecutiveToolFailureLimit = Math.max(0, config.consecutiveToolFailureLimit);
     if (typeof config.maxTokenBudget === 'number') this.maxTokenBudget = Math.max(0, config.maxTokenBudget);
     if (typeof config.budgetWarningThreshold === 'number') this.budgetWarningThreshold = Math.max(1, Math.min(100, config.budgetWarningThreshold));
     if (typeof config.soundScheme === 'string') this.soundScheme = config.soundScheme;
+    if (typeof config.maxCostBudget === 'number') this.maxCostBudget = Math.max(0, config.maxCostBudget);
+    if (typeof config.costWarningThreshold === 'number') this.costWarningThreshold = Math.max(1, Math.min(100, config.costWarningThreshold));
+    if (typeof config.enableTelegramNotifications === 'boolean') this.enableTelegramNotifications = config.enableTelegramNotifications;
+    if (typeof config.currency === 'string') this.currency = config.currency;
+    if (typeof config.activeModel === 'string') this.activeModel = config.activeModel;
     this.emit();
   }
 
@@ -208,7 +202,17 @@ export class GoalEngine {
       issueRef: parseIssueRef(cleanTitle),
       operatorQuery: null,
       waitingForOperator: false,
+      parentGoalId: options.parentGoalId || null,
+      parentSessionId: options.parentSessionId || null,
+      isSubGoal: Boolean(options.parentGoalId),
+      subGoals: [],
       tokensUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      maxCostBudget: options.maxCostBudget ?? this.maxCostBudget ?? 0,
+      currency: options.currency || this.currency || 'USD',
+      costUsage: { promptCost: 0, completionCost: 0, totalCost: 0, formattedCost: '.00', currency: options.currency || this.currency || 'USD' },
+      costWarningTriggered: false,
+      costLimitExceeded: false,
+      telegramNotificationsSent: [],
       logs: [{
         timestamp: now,
         type: 'info',
@@ -305,16 +309,15 @@ export class GoalEngine {
         m.status = MilestoneStatus.COMPLETED;
       }
     }
+    if (goal.parentSessionId) syncSubGoalToParent(this, sid, summary);
+    if (this.enableTelegramNotifications) { dispatchGoalTelegramNotification(goal, { engine: this, ctx: this.ctx }).catch(() => {}); }
     this.stallCounters.delete(sid);
     this.toolFailureCounters.delete(sid);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
 
-  setMilestones(milestonesList, sessionId = 'default') {
-    this.addMilestones(milestonesList, true, sessionId);
-    return this.getSnapshot(sessionId);
-  }
+  setMilestones(milestonesList, sessionId = 'default') { this.addMilestones(milestonesList, true, sessionId); return this.getSnapshot(sessionId); }
 
   addMilestones(milestonesList, shouldEmit = true, sessionId = 'default') {
     const sid = typeof shouldEmit === 'string' ? shouldEmit : (sessionId || 'default');
@@ -365,6 +368,7 @@ export class GoalEngine {
     if (this.enableKanbanSync) syncMilestoneStatusToKanban(target, { goal, ctx: this.ctx, store: this.kanbanStore, kanbanService: this.kanbanService }).catch(() => {});
 
     if (target.status === MilestoneStatus.COMPLETED && prevStatus !== MilestoneStatus.COMPLETED) {
+      if (this.enableMilestoneCompaction !== false) compactMilestone(target, { goal, cwd: goal.cwd });
       if (this.autoCheckpointOnMilestone) {
         const commitHash = createMilestoneCheckpoint(target, sid);
         if (commitHash) {
@@ -439,9 +443,7 @@ export class GoalEngine {
     return true;
   }
 
-  getElapsedSeconds(sessionId = 'default') {
-    return calculateElapsedSeconds(this.goals.get(sessionId || 'default'));
-  }
+  getElapsedSeconds(sessionId = 'default') { return calculateElapsedSeconds(this.goals.get(sessionId || 'default')); }
 
   addTokenUsage(usage, sessionId = 'default') {
     if (!usage || typeof usage !== 'object') return;
@@ -458,32 +460,24 @@ export class GoalEngine {
     goal.tokensUsage.completionTokens += completion;
     goal.tokensUsage.totalTokens += total;
 
+    updateGoalCostUsage(goal, { promptTokens: prompt, completionTokens: completion, totalTokens: total, modelName: usage.modelName || usage.model || this.activeModel || '' }, this);
+    const costCheck = processCostBudget(goal, { maxCostBudget: goal.maxCostBudget ?? this.maxCostBudget, costWarningThreshold: this.costWarningThreshold, GoalState });
     const budgetCheck = processTokenBudget(goal, {
       maxTokenBudget: this.maxTokenBudget,
       budgetWarningThreshold: this.budgetWarningThreshold,
       autoScaleBudgetNearCompletion: this.autoScaleBudgetNearCompletion,
       GoalState,
     });
-    if (budgetCheck.paused) {
+    if (budgetCheck.paused || costCheck.paused) {
       this.emit(sid, true);
       return;
     }
     this.emit(sid);
   }
 
-  getEstimatedRemainingSeconds(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    return calculateRemainingSeconds(this.goals.get(sid), this.getElapsedSeconds(sid));
-  }
-
-  getSnapshot(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    return buildSnapshot(this.goals.get(sid), sid, this);
-  }
-
-  getGoalSnapshot(sessionId = 'default') {
-    return this.getSnapshot(sessionId);
-  }
+  getEstimatedRemainingSeconds(sessionId = 'default') { const sid = sessionId || 'default'; return calculateRemainingSeconds(this.goals.get(sid), this.getElapsedSeconds(sid)); }
+  getSnapshot(sessionId = 'default') { const sid = sessionId || 'default'; return buildSnapshot(this.goals.get(sid), sid, this); }
+  getGoalSnapshot(sessionId = 'default') { return this.getSnapshot(sessionId); }
 
   getStatePromptInjection(sessionId = 'default') {
     const sid = sessionId || 'default';
@@ -591,4 +585,11 @@ export class GoalEngine {
     const goal = this.goals.get(sessionId || 'default');
     return Boolean(goal && (goal.mode === GoalMode.PLAN || goal.state === GoalState.PLANNING));
   }
+  spawnSubGoal(options = {}, sessionId = 'default') { return spawnSubGoal(this, sessionId, options); }
+  completeSubGoal(sessionId, summary = '') { return completeSubGoal(this, sessionId, summary); }
+  getSubGoals(sessionId = 'default') { return getSubGoalsList(this, sessionId); }
+  getSubGoalBreadcrumbs(sessionId = 'default') { return getSubGoalBreadcrumbs(this, sessionId); }
+  getCompactionSavings(sessionId = 'default') { const g = this.goals.get(sessionId || 'default'); return estimateCompactionSavings(g?.milestones || [], g?.lang || 'en'); }
+  exportReleaseNotes(sessionId = 'default', options = {}) { return generateReleaseNotes(this.goals.get(sessionId || 'default'), options); }
+  getCostUsage(sessionId = 'default') { return this.goals.get(sessionId || 'default')?.costUsage || null; }
 }

package/lib/index.js

@@ -143,13 +143,6 @@ export function apply(ctx, config = {}) {
     logger.warn?.('[dsh-goal] Legacy migration check failed:', migErr.message);
   }
 
-  // Register addon tools: goal_milestones and goal_checklist
-  registerTools(ctx, {
-    milestoneManager,
-    goalsService: safeService(ctx, "goals"),
-    logger,
-  });
-
   // Support fallback engine for tests or non-core environments
   let fallbackEngine = null;
   if (!safeService(ctx, "goals")) {
@@ -168,12 +161,22 @@ export function apply(ctx, config = {}) {
       autoScaleBudgetNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
       enableTemplatesDrawer: currentSettings.enableTemplatesDrawer,
       enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
+      enableMilestoneCompaction: currentSettings.enableMilestoneCompaction,
       approvalGate: safeService(ctx, "approvalGate"),
       logger,
     });
+    ctx.goalEngine = fallbackEngine;
     registerPlanModeGuard(ctx, { engine: fallbackEngine, logger });
   }
 
+  // Register addon tools: goal_milestones, goal_checklist, goal_spawn_subgoal
+  registerTools(ctx, {
+    milestoneManager,
+    goalsService: safeService(ctx, "goals"),
+    engine: fallbackEngine,
+    logger,
+  });
+
   // 1. One-click auto-updater registration (Issue #99)
   if (ctx?.webServer?.register) {
     if (typeof ctx?.effect === 'function') {
@@ -335,7 +338,15 @@ export function apply(ctx, config = {}) {
 
     // Compatibility events for turn/end and approval/asked
     ctx.on('turn/end', (event) => {
-      // session isolation turn tracking
+      if (!fallbackEngine || !event) return;
+      const sid = sessionIdOf(event?.agent || event, 'default');
+      const usage = event?.usage || event?.tokenUsage || event?.tokens || event?.response?.usage;
+      if (usage) {
+        fallbackEngine.addTokenUsage({
+          ...usage,
+          modelName: event?.model || event?.modelName || event?.response?.model || '',
+        }, sid);
+      }
     });
 
     ctx.on('approval/asked', (event) => {

package/lib/routes.js

@@ -5,6 +5,7 @@ import { isValidGitRef } from './engine-git-branch.js';
 import { saveGoalArtifact, rollbackToCheckpoint } from './engine-reports.js';
 import { getTemplatesCatalogue, instantiateTemplate } from './engine-templates.js';
 import { parseIssueChecklist } from './engine-issue-sync.js';
+import { dispatchGoalTelegramNotification } from './engine-release-notes.js';
 
 export function isLoopback(value) {
   if (!value) return false;
@@ -490,6 +491,8 @@ export function registerRoutes(ctx, {
                       cwd: safeStartCwd,
                       issueBody: data.issueBody,
                       mode: data.mode,
+                      maxCostBudget: data.maxCostBudget,
+                      currency: data.currency,
                     }, sid);
                   } else {
                     let parsedMilestones = [];
@@ -873,6 +876,31 @@ export function registerRoutes(ctx, {
                   break;
                 }
 
+                case 'spawn_subgoal': {
+                  const subTitle = typeof data.title === 'string' ? data.title.trim() : '';
+                  if (!subTitle) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: 'Sub-goal title is required' }));
+                  }
+                  if (engine) {
+                    const spawnRes = engine.spawnSubGoal({
+                      title: subTitle,
+                      prompt: data.prompt || data.description,
+                      maxIterations: data.maxIterations ?? data.max_iterations,
+                      inheritContext: data.inheritContext ?? data.inherit_context,
+                    }, sid);
+                    if (!spawnRes.ok) {
+                      res.statusCode = 400;
+                      return res.end(JSON.stringify({ error: spawnRes.error || 'Failed to spawn sub-goal' }));
+                    }
+                    result = spawnRes;
+                  } else {
+                    res.statusCode = 404;
+                    result = { ok: false, error: 'Goal engine unavailable' };
+                  }
+                  break;
+                }
+
                 case 'instantiate_template': {
                   const tplId = data.templateId || data.id;
                   if (!tplId) {
@@ -888,6 +916,29 @@ export function registerRoutes(ctx, {
                   return res.end(JSON.stringify({ ok: true, template: instance }));
                 }
 
+                case 'export_release_notes': {
+                  const snap = engine ? engine.getSnapshot(sid) : null;
+                  if (engine && (!snap || !snap.hasActiveGoal)) {
+                    res.statusCode = 404;
+                    return res.end(JSON.stringify({ error: 'No active goal found to export release notes' }));
+                  }
+                  const markdown = engine ? engine.exportReleaseNotes(sid, data.options || {}) : '';
+                  res.statusCode = 200;
+                  return res.end(JSON.stringify({ ok: true, releaseNotes: markdown, state: snap || {} }));
+                }
+
+                case 'notify_telegram': {
+                  const snap = engine ? engine.getSnapshot(sid) : null;
+                  if (engine && (!snap || !snap.hasActiveGoal)) {
+                    res.statusCode = 404;
+                    return res.end(JSON.stringify({ error: 'No active goal found to dispatch notification' }));
+                  }
+                  const goal = engine ? engine.getGoal(sid) : null;
+                  const notifyRes = await dispatchGoalTelegramNotification(goal, { engine, ctx, ...(data.options || {}) });
+                  res.statusCode = notifyRes.ok ? 200 : 500;
+                  return res.end(JSON.stringify(notifyRes));
+                }
+
                 default:
                   res.statusCode = 400;
                   return res.end(JSON.stringify({ error: `Unknown action: ${action}` }));

package/lib/tools.js

@@ -376,5 +376,74 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
       output: JSON_OUTPUT,
       execute: handleGoalAskOperator,
     });
+
+    // Tool 7: goal_spawn_subgoal (Issue #170)
+    const handleGoalSpawnSubgoal = async (args = {}, toolCtx = {}) => {
+      const parentSessionId = args.goalId || args.goal_id || resolveGoalId(toolCtx);
+      const title = args.title || args.goal;
+      if (!title || typeof title !== 'string' || !title.trim()) {
+        throw new Error('Field "title" is required and must be a non-empty string');
+      }
+
+      const engine = ctx.goalEngine || (ctx.get && ctx.get('goalEngine'));
+      if (engine && typeof engine.spawnSubGoal === 'function') {
+        const res = engine.spawnSubGoal({
+          title: title.trim(),
+          prompt: args.prompt || args.description,
+          maxIterations: args.max_iterations ?? args.maxIterations,
+          inheritContext: args.inherit_context ?? args.inheritContext,
+        }, parentSessionId);
+
+        if (!res.ok) {
+          throw new Error(`Failed to spawn sub-goal: ${res.error}`);
+        }
+
+        return {
+          ok: true,
+          parentGoalId: res.parentGoalId,
+          parentSessionId: res.parentSessionId,
+          subGoalId: res.subGoalId,
+          childSessionId: res.childSessionId,
+          title: title.trim(),
+          message: 'Sub-goal spawned with isolated execution context. Complete sub-milestones and invoke goal_finish to conclude.',
+        };
+      }
+
+      return {
+        ok: true,
+        parentSessionId,
+        title: title.trim(),
+        message: 'Sub-goal registered (fallback mode).',
+      };
+    };
+
+    safeRegister({
+      name: 'goal_spawn_subgoal',
+      description: 'Spawn a child sub-goal with isolated context and task checklist (#170). When all sub-milestones are completed, invoking goal_finish returns deliverables and control to the parent goal.',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: {
+            type: 'string',
+            description: 'Clear, actionable title of the sub-goal',
+          },
+          prompt: {
+            type: 'string',
+            description: 'Optional context, detailed instructions, or constraints for the sub-goal',
+          },
+          max_iterations: {
+            type: 'number',
+            description: 'Maximum iteration budget for the sub-goal (default: 15)',
+          },
+          inherit_context: {
+            type: 'boolean',
+            description: 'Whether the child sub-goal inherits parent goal context summary (default: true)',
+          },
+        },
+        required: ['title'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleGoalSpawnSubgoal,
+    });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-goal",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Core Goal Addon (Token Budget, Milestones, Git Snapshots & Retrospective Reports) for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",