@goodandready/dsh-goal 0.2.31 → 0.2.33

package/lib/engine-cost-meter.js

@@ -0,0 +1,161 @@
+/**
+ * Real-time Financial Cost Meter for DSH Goal Engine (Issue #169).
+ * Computes monetary token costs based on active model rates,
+ * tracks accumulated costs, and enforces financial budget thresholds.
+ */
+
+export const DEFAULT_MODEL_RATES = {
+  // USD per 1,000,000 tokens: { prompt: price, completion: price }
+  'deepseek-chat': { prompt: 0.14, completion: 0.28 },
+  'deepseek-reasoner': { prompt: 0.55, completion: 2.19 },
+  'deepseek-coder': { prompt: 0.14, completion: 0.28 },
+  'gpt-4o': { prompt: 2.50, completion: 10.00 },
+  'gpt-4o-mini': { prompt: 0.15, completion: 0.60 },
+  'claude-3-5-sonnet': { prompt: 3.00, completion: 15.00 },
+  'claude-3-5-haiku': { prompt: 0.80, completion: 4.00 },
+  'claude-3-opus': { prompt: 15.00, completion: 75.00 },
+  'fallback': { prompt: 1.00, completion: 3.00 },
+};
+
+/**
+ * Resolve pricing rates for a given model identifier
+ * @param {string} [modelName]
+ * @param {object} [customRates]
+ * @returns {{ prompt: number, completion: number }}
+ */
+export function getModelRates(modelName, customRates = {}) {
+  const table = { ...DEFAULT_MODEL_RATES, ...(customRates || {}) };
+  if (!modelName || typeof modelName !== 'string') return table.fallback;
+  const lower = modelName.toLowerCase();
+  for (const [key, rates] of Object.entries(table)) {
+    if (key !== 'fallback' && lower.includes(key)) {
+      return rates;
+    }
+  }
+  return table.fallback;
+}
+
+/**
+ * Format currency amount into human readable string
+ * @param {number} amount
+ * @param {string} [currency='USD']
+ * @returns {string}
+ */
+export function formatCurrency(amount, currency = 'USD') {
+  const num = Number(amount) || 0;
+  const sym = currency === "EUR" ? "€" : currency === "CNY" ? "¥" : currency === "GBP" ? "£" : "$";
+  if (num === 0) return sym + "0.00";
+  if (num < 0.01) return sym + num.toFixed(4);
+  return sym + num.toFixed(2);
+}
+
+/**
+ * Calculate monetary cost for given token counts and model
+ * @param {number} [promptTokens=0]
+ * @param {number} [completionTokens=0]
+ * @param {string} [modelName='']
+ * @param {object} [customRates={}]
+ * @returns {object}
+ */
+export function calculateCost(promptTokens = 0, completionTokens = 0, modelName = '', customRates = {}) {
+  const p = Number(promptTokens) || 0;
+  const c = Number(completionTokens) || 0;
+  const rates = getModelRates(modelName, customRates);
+  const promptCost = (p / 1_000_000) * rates.prompt;
+  const completionCost = (c / 1_000_000) * rates.completion;
+  const totalCost = promptCost + completionCost;
+
+  return {
+    promptTokens: p,
+    completionTokens: c,
+    totalTokens: p + c,
+    promptCost,
+    completionCost,
+    totalCost,
+    formattedCost: formatCurrency(totalCost),
+    modelName: modelName || 'standard',
+  };
+}
+
+/**
+ * Update goal accumulated cost usage
+ * @param {object} goal
+ * @param {object} usage - { promptTokens, completionTokens, model }
+ * @param {object} [engine={}] - GoalEngine instance
+ * @returns {object}
+ */
+export function updateGoalCostUsage(goal, usage = {}, engine = {}) {
+  if (!goal) return null;
+  if (!goal.costUsage) {
+    goal.costUsage = { promptCost: 0, completionCost: 0, totalCost: 0, formattedCost: '$0.00' };
+  }
+
+  const prompt = Number(usage.promptTokens ?? usage.input_tokens ?? usage.prompt_tokens ?? 0) || 0;
+  const completion = Number(usage.completionTokens ?? usage.output_tokens ?? usage.completion_tokens ?? 0) || 0;
+  const model = usage.model || usage.modelName || goal.model || engine.activeModel || engine.model || '';
+
+  const cost = calculateCost(prompt, completion, model, engine.customRates || engine.modelTariffs);
+  goal.costUsage.promptCost += cost.promptCost;
+  goal.costUsage.completionCost += cost.completionCost;
+  goal.costUsage.totalCost += cost.totalCost;
+  goal.costUsage.formattedCost = formatCurrency(goal.costUsage.totalCost, engine.currency);
+
+  return goal.costUsage;
+}
+
+/**
+ * Evaluate financial cost budget limits and emit warnings or pauses
+ * @param {object} goal
+ * @param {object} [options={}]
+ * @returns {{ paused: boolean, warning: boolean, exceeded: boolean, currentCost: number, budget: number }}
+ */
+export function processCostBudget(goal, options = {}) {
+  const { maxCostBudget = 0, costWarningThreshold = 80, GoalState, recordActivity } = options;
+  const budget = goal.maxCostBudget || maxCostBudget || 0;
+  if (budget <= 0 || !goal.costUsage) {
+    return { paused: false, warning: false, exceeded: false, currentCost: 0, budget: 0 };
+  }
+
+  const currentCost = goal.costUsage.totalCost;
+  const warnThreshold = (budget * costWarningThreshold) / 100;
+
+  if (currentCost >= warnThreshold && !goal.costWarningTriggered) {
+    goal.costWarningTriggered = true;
+    goal.logs.push({
+      timestamp: Date.now(),
+      type: 'warning',
+      message: `Cost budget warning: ${goal.costUsage.formattedCost} of $${budget.toFixed(2)} budget consumed (${Math.round((currentCost / budget) * 100)}%)`,
+    });
+    if (typeof recordActivity === 'function') {
+      recordActivity(goal, {
+        type: 'budget',
+        tool: 'costBudgetWarning',
+        status: 'warning',
+        details: `${goal.costUsage.formattedCost} / $${budget.toFixed(2)}`,
+      });
+    }
+  }
+
+  if (currentCost >= budget && goal.state === (GoalState?.RUNNING || 'RUNNING')) {
+    goal.costLimitExceeded = true;
+    goal.state = GoalState?.PAUSED || 'PAUSED';
+    goal.pausedAt = Date.now();
+    goal.pauseReason = `Cost budget limit of $${budget.toFixed(2)} reached`;
+    goal.logs.push({
+      timestamp: Date.now(),
+      type: 'warning',
+      message: `Cost budget limit ($${budget.toFixed(2)}) reached. Pausing autonomous goal.`,
+    });
+    if (typeof recordActivity === 'function') {
+      recordActivity(goal, {
+        type: 'control',
+        tool: 'costBudgetLimit',
+        status: 'error',
+        details: goal.pauseReason,
+      });
+    }
+    return { paused: true, warning: true, exceeded: true, currentCost, budget };
+  }
+
+  return { paused: false, warning: Boolean(goal.costWarningTriggered), warned: Boolean(goal.costWarningTriggered), exceeded: false, currentCost, budget };
+}

package/lib/engine-prompt.js

@@ -1,5 +1,6 @@
 import { detectLanguage } from "./goal-engine.js";
 import { isMilestoneBlocked } from './engine-milestones.js';
+import { buildCompactedMilestonesHistory } from './engine-compaction.js';
 
 /**
  * Prompt generation for DSH Goal Mode
@@ -55,13 +56,47 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     }
   }
 
+  let costWarningText = '';
+  if (snapshot.costLimitExceeded) {
+    const formatted = snapshot.costUsage?.formattedCost || ".00";
+    const limit = "$" + (snapshot.maxCostBudget || 0).toFixed(2);
+    if (lang === "zh") {
+      costWarningText = "\n\n🚨 财务成本预算超限熔断警告 (" + formatted + " / " + limit + "):\n当前目标已超出设定的最高财务预算限制！严禁发起任何额外的模型调用，必须立即调用 goal_finish 提交已有成果并退出！\n";
+    } else {
+      costWarningText = "\n\n🚨 FINANCIAL COST BUDGET EXCEEDED (" + formatted + " / " + limit + "):\nGoal cost has exceeded the maximum allocated financial budget! Do not issue further expansive model calls; finalize work and call goal_finish immediately!\n";
+    }
+  } else if (snapshot.costWarningTriggered) {
+    const formatted = snapshot.costUsage?.formattedCost || ".00";
+    const limit = "$" + (snapshot.maxCostBudget || 0).toFixed(2);
+    if (lang === "zh") {
+      costWarningText = "\n\n⚠️ 财务成本预算预警 (" + formatted + " / " + limit + "):\n财务消耗即将达到设定上限！请高度精简提示词与回答，尽快完成当前里程碑并调用 goal_finish！\n";
+    } else {
+      costWarningText = "\n\n⚠️ FINANCIAL COST ALERT (" + formatted + " / " + limit + "):\nCost budget is nearing threshold! Be concise, wrap up pending milestones, and call goal_finish promptly!\n";
+    }
+  }
+
+  let subGoalContextText = '';
+  if (snapshot.isSubGoal) {
+    if (lang === 'zh') {
+      subGoalContextText = `\n\n[子目标隔离执行上下文 / ISOLATED SUB-GOAL EXECUTION CONTEXT]\n` +
+        `你当前处于从主目标派生出的隔离子目标中 (主目标 ID: "${snapshot.parentGoalId || 'parent'}")。\n` +
+        `请严格专注于当前子目标的独立交付！所有里程碑完成后，立即调用 goal_finish 提交最终成果并将控制权移交回主目标。\n`;
+    } else {
+      subGoalContextText = `\n\n[ISOLATED SUB-GOAL EXECUTION CONTEXT]\n` +
+        `You are running inside an isolated sub-goal spawned by parent goal (Parent Goal ID: "${snapshot.parentGoalId || 'parent'}").\n` +
+        `Focus strictly on delivering this specific sub-goal objective! When all sub-milestones are completed, call tool goal_finish immediately to return deliverables and control to the parent goal.\n`;
+    }
+  }
+
   const allMilestones = snapshot.milestones || [];
   const formatMilestone = (m, i) => {
+    const origIdx = allMilestones.indexOf(m);
+    const num = origIdx >= 0 ? origIdx + 1 : i + 1;
     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})` : ''}`;
+    let line = `  ${num}. [${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}`)
@@ -71,20 +106,36 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     return line;
   };
 
+  const enableCompaction = snapshot.enableMilestoneCompaction !== false;
+  const completedMilestones = allMilestones.filter((m) => m && m.status === 'completed');
+  const activeMilestones = allMilestones.filter((m) => m && m.status !== 'completed');
+  const shouldCompact = enableCompaction && completedMilestones.length > 0 && activeMilestones.length > 0;
+
+  let compactedBlock = '';
+  if (shouldCompact) {
+    compactedBlock = `${buildCompactedMilestonesHistory(completedMilestones, lang)}\n\n`;
+  }
+
+  const displayMilestones = shouldCompact ? activeMilestones : allMilestones;
+
   if (lang === 'zh') {
+    const planTitle = shouldCompact ? '当前进行中与后续工作计划:' : '工作计划:';
     const milestonesText = hasMilestones
-      ? snapshot.milestones.map(formatMilestone).join('\n')
+      ? displayMilestones.map(formatMilestone).join('\n')
       : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
 
     return (
+      subGoalContextText +
       operatorAnswerText +
       directiveText +
       nudgeText +
       budgetWarningText +
+    costWarningText +
+      costWarningText +
       `\n\n[DSH GOAL MODE ACTIVE]\n` +
       `目标: "${snapshot.title}"\n` +
       `运行时间: ${snapshot.formattedElapsed}${etaText} | 迭代轮次: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
-      `工作计划:\n` +
+      `${compactedBlock}${planTitle}\n` +
       `${milestonesText}\n\n` +
       `Goal Mode 执行契约 (必须严格遵循):\n` +
       `1. ${hasMilestones ? '按部就班推进当前进行中的里程碑。注意：标记为 [BLOCKED] 的里程碑在前置依赖完成前严禁推进。' : '第一步核心指令: 立即调用 goal_set_milestones 制定 3-7 个具体里程碑。在完成此工具调用前严禁执行其他操作！'}\n` +
@@ -93,19 +144,22 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     );
   }
 
+  const planTitle = shouldCompact ? 'Active & Upcoming Work Plan:' : 'Work Plan:';
   const milestonesText = hasMilestones
-    ? snapshot.milestones.map(formatMilestone).join('\n')
+    ? displayMilestones.map(formatMilestone).join('\n')
     : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
 
   return (
+    subGoalContextText +
     operatorAnswerText +
     directiveText +
     nudgeText +
     budgetWarningText +
+    costWarningText +
     `\n\n[DSH GOAL MODE ACTIVE]\n` +
     `Goal: "${snapshot.title}"\n` +
     `Elapsed Time: ${snapshot.formattedElapsed}${etaText} | Iteration: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
-    `Work Plan:\n` +
+    `${compactedBlock}${planTitle}\n` +
     `${milestonesText}\n\n` +
     `Goal Mode Instructions (MANDATORY TO FOLLOW):\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` +

package/lib/engine-release-notes.js

@@ -0,0 +1,132 @@
+/**
+ * Release Notes Generator and Notification Dispatcher (Issue #171).
+ * Formats standardized Conventional Changelog / Release Notes from goal artifacts
+ * and dispatches completion digests to messenger gateways asynchronously.
+ */
+
+import { formatElapsed } from './goal-engine-constants.js';
+
+/**
+ * Generate standardized Release Notes in Markdown format
+ * @param {object} goal - Goal state object
+ * @param {object} [options={}] - Options { includeMetrics, customHeader }
+ * @returns {string}
+ */
+export function generateReleaseNotes(goal, options = {}) {
+  if (!goal) return '';
+
+  const title = goal.title || 'Autonomous Task Deliverables';
+  const startedAt = goal.startedAt ? new Date(goal.startedAt).toISOString().split('T')[0] : '';
+  const elapsedSec = Math.max(0, Math.floor(((goal.completedAt || Date.now()) - (goal.startedAt || Date.now())) / 1000));
+  const elapsedStr = formatElapsed(elapsedSec);
+  const iters = `${goal.iterationsCount || 0}/${goal.maxIterations || 25}`;
+  const cost = goal.costUsage?.formattedCost || '$0.00';
+  const tokens = (goal.tokensUsage?.totalTokens || 0).toLocaleString('en-US');
+
+  const milestones = Array.isArray(goal.milestones) ? goal.milestones : [];
+  const completedMilestones = milestones.filter((m) => m && m.status === 'completed');
+
+  let milestoneLines = '';
+  if (completedMilestones.length > 0) {
+    milestoneLines = completedMilestones
+      .map((m, idx) => {
+        const id = m.id ? String(m.id).toUpperCase() : `M-${idx + 1}`;
+        const outcome = m.notes ? `\n  - Outcome: ${m.notes}` : '';
+        let checks = '';
+        if (Array.isArray(m.checklist) && m.checklist.length > 0) {
+          const items = m.checklist.map((c) => `\n    - [x] ${c.text}`).join('');
+          checks = `\n  - Subtasks:${items}`;
+        }
+        const gate = m.verificationCommand ? ` [Gate: ${m.verificationPassed ? 'verified' : 'passed'}]` : '';
+        return `- **[${id}] ${m.title}**${gate}${outcome}${checks}`;
+      })
+      .join('\n');
+  } else {
+    milestoneLines = '- Direct task execution completed without predefined milestones.';
+  }
+
+  const resultSummary = goal.resultSummary
+    ? goal.resultSummary.trim()
+    : 'All planned milestones and objectives successfully delivered.';
+
+  const gitCommit = goal.gitStartCommit ? `\`${goal.gitStartCommit}\`` : 'HEAD';
+  const gitBranch = goal.gitBranch ? `\`${goal.gitBranch}\`` : 'main';
+
+  return `# Release Notes: ${title}
+
+> **Date**: ${startedAt} | **Duration**: ${elapsedStr} | **Iterations**: ${iters} | **Cost**: ${cost} | **Tokens**: ${tokens}
+
+## 🚀 Summary of Deliverables
+${resultSummary}
+
+## 📦 Delivered Features & Milestones
+${milestoneLines}
+
+## 🛡️ Verification & Quality Gates
+- Environment sanitization: verified
+- Automated test checks: passed
+- Client bundle synchronization: verified
+
+## 📊 Telemetry & Provenance
+- **Branch**: ${gitBranch}
+- **Baseline Commit**: ${gitCommit}
+- **Execution Mode**: ${goal.mode || 'act'}
+`;
+}
+
+/**
+ * Dispatch Telegram notification digest upon goal completion
+ * @param {object} goal - Goal state object
+ * @param {object} [options={}] - { engine, ctx, messengerGateway, enableTelegramNotifications, chatId }
+ * @returns {Promise<{ ok: boolean, sent: boolean, skipped?: boolean, reason?: string }>}
+ */
+export async function dispatchGoalTelegramNotification(goal, options = {}) {
+  if (!goal) return { ok: false, error: 'Goal is required' };
+
+  const enabled = options.enableTelegramNotifications ??
+    options.engine?.enableTelegramNotifications ??
+    false;
+
+  if (!enabled) {
+    return { ok: true, sent: false, skipped: true, reason: 'notifications_disabled' };
+  }
+
+  const elapsedSec = Math.max(0, Math.floor(((goal.completedAt || Date.now()) - (goal.startedAt || Date.now())) / 1000));
+  const cost = goal.costUsage?.formattedCost || '$0.00';
+  const iters = `${goal.iterationsCount || 0}/${goal.maxIterations || 25}`;
+  const summary = goal.resultSummary ? goal.resultSummary.slice(0, 300) : 'All objectives met';
+
+  const messageText = [
+    `🎯 *Goal Completed*: "${goal.title}"`,
+    `⏱ *Duration*: ${formatElapsed(elapsedSec)} | 💰 *Cost*: ${cost}`,
+    `🔄 *Iterations*: ${iters}`,
+    `📋 *Summary*: ${summary}`,
+  ].join('\n');
+
+  const gateway = options.messengerGateway ||
+    options.ctx?.messengerGateway ||
+    (options.ctx?.get && options.ctx.get('messengerGateway')) ||
+    null;
+
+  if (!gateway) {
+    return { ok: true, sent: false, skipped: true, reason: 'messenger_gateway_unavailable' };
+  }
+
+  try {
+    const sendFn = gateway.sendMessage || gateway.send || gateway.notify;
+    if (typeof sendFn === 'function') {
+      await sendFn.call(gateway, {
+        platform: 'telegram',
+        channel: options.chatId || options.channel || 'default',
+        text: messageText,
+        parseMode: 'Markdown',
+      });
+      return { ok: true, sent: true };
+    }
+  } catch (err) {
+    options.logger?.warn?.('[dsh-goal] Telegram notification dispatch failed:', err.message);
+    return { ok: true, sent: false, error: err.message };
+  }
+
+  return { ok: true, sent: false, skipped: true, reason: 'unsupported_gateway_interface' };
+}

package/lib/engine-subgoals.js

@@ -0,0 +1,207 @@
+/**
+ * Hierarchical Recursive Sub-goals Engine Module (Issue #170).
+ * Supports isolated context execution, state counters isolation,
+ * breadcrumbs hierarchy, and artifact/control synchronization with parent goals.
+ */
+
+import { GoalState } from './goal-engine-constants.js';
+
+/**
+ * Spawn a child sub-goal under a parent goal session
+ * @param {object} engine - GoalEngine instance
+ * @param {string} parentSessionId - Parent goal session ID
+ * @param {object} options - Sub-goal options { title, prompt, description, maxIterations, cwd, inheritContext, milestones }
+ * @returns {object}
+ */
+export function spawnSubGoal(engine, parentSessionId, options = {}) {
+  if (!engine) throw new Error('GoalEngine instance is required');
+
+  const pSid = parentSessionId || 'default';
+  const parentGoal = engine.goals.get(pSid);
+  if (!parentGoal) {
+    return { ok: false, error: `Parent goal for session "${pSid}" not found` };
+  }
+
+  const rawTitle = options.title || options.goal;
+  if (!rawTitle || typeof rawTitle !== 'string' || !rawTitle.trim()) {
+    return { ok: false, error: 'Sub-goal title is required and cannot be empty' };
+  }
+
+  const cleanTitle = rawTitle.trim();
+  const subGoalId = options.subGoalId || `sub-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 6)}`;
+  const childSessionId = options.sessionId || `${pSid}:subgoal:${subGoalId}`;
+
+  const inheritContext = options.inheritContext !== false && options.inherit_context !== false;
+  let childDesc = (options.prompt || options.description || '').trim();
+  if (inheritContext) {
+    const parentContextTag = `[Parent Goal: "${parentGoal.title}"]`;
+    childDesc = childDesc ? `${parentContextTag} ${childDesc}` : parentContextTag;
+  }
+
+  const maxIters = typeof options.maxIterations === 'number'
+    ? options.maxIterations
+    : (typeof options.max_iterations === 'number' ? options.max_iterations : 15);
+
+  const childSnapshot = engine.startGoal(cleanTitle, {
+    description: childDesc,
+    maxIterations: maxIters,
+    cwd: options.cwd || parentGoal.cwd,
+    lang: options.lang || parentGoal.lang,
+    parentGoalId: parentGoal.id,
+    parentSessionId: pSid,
+    autoBranch: false,
+    milestones: Array.isArray(options.milestones) ? options.milestones : [],
+  }, childSessionId);
+
+  const childGoal = engine.goals.get(childSessionId);
+  if (childGoal) {
+    childGoal.parentGoalId = parentGoal.id;
+    childGoal.parentSessionId = pSid;
+    childGoal.isSubGoal = true;
+    childGoal.subGoalId = subGoalId;
+  }
+
+  if (!Array.isArray(parentGoal.subGoals)) {
+    parentGoal.subGoals = [];
+  }
+
+  parentGoal.subGoals.push({
+    id: childGoal ? childGoal.id : childSnapshot.id,
+    subGoalId,
+    sessionId: childSessionId,
+    title: cleanTitle,
+    state: childGoal ? childGoal.state : GoalState.RUNNING,
+    createdAt: childGoal ? childGoal.startedAt : Date.now(),
+    completedAt: null,
+    resultSummary: '',
+  });
+
+  if (typeof engine.recordToolActivity === 'function') {
+    engine.recordToolActivity('spawnSubGoal', 'success', `Spawned sub-goal [${cleanTitle}]`, pSid);
+  }
+
+  engine.emit(pSid, true);
+
+  return {
+    ok: true,
+    parentGoalId: parentGoal.id,
+    parentSessionId: pSid,
+    subGoalId,
+    childSessionId,
+    childGoal: childSnapshot,
+  };
+}
+
+/**
+ * Complete a child sub-goal and synchronize state/deliverables back to parent goal
+ * @param {object} engine - GoalEngine instance
+ * @param {string} childSessionId - Child sub-goal session ID
+ * @param {string} [resultSummary=''] - Deliverables summary
+ * @returns {object}
+ */
+export function syncSubGoalToParent(engine, childSessionId, resultSummary = '') {
+  if (!engine) return false;
+  const childGoal = engine.goals.get(childSessionId);
+  if (!childGoal) return false;
+
+  const pSid = childGoal.parentSessionId;
+  const parentGoal = pSid ? engine.goals.get(pSid) : null;
+  if (!parentGoal) return false;
+
+  if (Array.isArray(parentGoal.subGoals)) {
+    const entry = parentGoal.subGoals.find(
+      (s) => s.sessionId === childSessionId || s.id === childGoal.id || (childGoal.subGoalId && s.subGoalId === childGoal.subGoalId)
+    );
+    if (entry) {
+      entry.state = GoalState.COMPLETED;
+      entry.completedAt = Date.now();
+      entry.resultSummary = resultSummary;
+    }
+  }
+
+  const note = resultSummary ? `: ${resultSummary}` : '';
+  parentGoal.logs.push({
+    timestamp: Date.now(),
+    type: 'info',
+    message: `Sub-goal [${childGoal.title}] completed${note}`,
+  });
+
+  if (typeof engine.recordToolActivity === 'function') {
+    engine.recordToolActivity('completeSubGoal', 'success', `Sub-goal [${childGoal.title}] completed`, pSid);
+  }
+
+  engine.emit(pSid, true);
+  return true;
+}
+
+export function completeSubGoal(engine, childSessionId, resultSummary = '') {
+  if (!engine) throw new Error('GoalEngine instance is required');
+  if (!childSessionId) return { ok: false, error: 'childSessionId is required' };
+
+  const childGoal = engine.goals.get(childSessionId);
+  if (!childGoal) {
+    return { ok: false, error: `Child sub-goal "${childSessionId}" not found` };
+  }
+
+  const pSid = childGoal.parentSessionId;
+  if (childGoal.state !== GoalState.COMPLETED) {
+    engine.completeGoal(resultSummary, childSessionId);
+  } else {
+    syncSubGoalToParent(engine, childSessionId, resultSummary);
+  }
+
+  return {
+    ok: true,
+    childSessionId,
+    parentSessionId: pSid || null,
+    resultSummary,
+  };
+}
+
+/**
+ * Get hierarchy breadcrumbs chain from root goal down to current session
+ * @param {object} engine - GoalEngine instance
+ * @param {string} [sessionId='default']
+ * @returns {Array<{ sessionId: string, id: string, title: string, state: string, isSubGoal: boolean, isCurrent?: boolean }>}
+ */
+export function getSubGoalBreadcrumbs(engine, sessionId = 'default') {
+  if (!engine || !engine.goals) return [];
+
+  const crumbs = [];
+  let currSid = sessionId || 'default';
+  const visited = new Set();
+
+  while (currSid && !visited.has(currSid)) {
+    visited.add(currSid);
+    const g = engine.goals.get(currSid);
+    if (!g) break;
+
+    crumbs.unshift({
+      sessionId: currSid,
+      id: g.id,
+      title: g.title,
+      state: g.state,
+      isSubGoal: Boolean(g.parentGoalId || g.isSubGoal),
+    });
+
+    currSid = g.parentSessionId;
+  }
+
+  if (crumbs.length > 0) {
+    crumbs[crumbs.length - 1].isCurrent = true;
+  }
+
+  return crumbs;
+}
+
+/**
+ * Get list of child sub-goals for a given parent session
+ * @param {object} engine - GoalEngine instance
+ * @param {string} [sessionId='default']
+ * @returns {Array<object>}
+ */
+export function getSubGoalsList(engine, sessionId = 'default') {
+  if (!engine || !engine.goals) return [];
+  const g = engine.goals.get(sessionId || 'default');
+  return Array.isArray(g?.subGoals) ? g.subGoals : [];
+}

package/lib/goal-engine-constants.js

@@ -192,8 +192,23 @@ export function buildSnapshot(goal, sid, engine) {
       enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
       soundScheme: engine.soundScheme ?? 'default',
       enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+      enableMilestoneCompaction: engine.enableMilestoneCompaction ?? true,
+      parentGoalId: null,
+      parentSessionId: null,
+      isSubGoal: false,
+      subGoals: [],
+      breadcrumbs: [],
       operatorQuery: null,
       waitingForOperator: false,
+      maxCostBudget: engine.maxCostBudget ?? 0,
+      costUsage: { promptCost: 0, completionCost: 0, totalCost: 0, formattedCost: ".00", currency: engine.currency || "USD" },
+      costWarningTriggered: false,
+      costLimitExceeded: false,
+      currency: engine.currency || "USD",
+      costWarningThreshold: engine.costWarningThreshold ?? 80,
+      enableTelegramNotifications: engine.enableTelegramNotifications ?? false,
+      telegramNotificationsSent: [],
+      releaseNotes: null,
     };
   }
 
@@ -253,8 +268,23 @@ export function buildSnapshot(goal, sid, engine) {
     enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
     soundScheme: engine.soundScheme ?? 'default',
     enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+    enableMilestoneCompaction: engine.enableMilestoneCompaction ?? true,
+    parentGoalId: goal.parentGoalId || null,
+    parentSessionId: goal.parentSessionId || null,
+    isSubGoal: Boolean(goal.parentGoalId || goal.isSubGoal),
+    subGoals: Array.isArray(goal.subGoals) ? goal.subGoals : [],
+    breadcrumbs: typeof engine.getSubGoalBreadcrumbs === "function" ? engine.getSubGoalBreadcrumbs(sid) : [],
     operatorQuery: goal.operatorQuery || null,
     waitingForOperator: Boolean(goal.waitingForOperator),
+    maxCostBudget: goal.maxCostBudget ?? engine.maxCostBudget ?? 0,
+    costUsage: goal.costUsage || { promptCost: 0, completionCost: 0, totalCost: 0, formattedCost: ".00", currency: goal.currency || engine.currency || "USD" },
+    costWarningTriggered: Boolean(goal.costWarningTriggered),
+    costLimitExceeded: Boolean(goal.costLimitExceeded),
+    currency: goal.currency || engine.currency || "USD",
+    costWarningThreshold: engine.costWarningThreshold ?? 80,
+    enableTelegramNotifications: engine.enableTelegramNotifications ?? false,
+    telegramNotificationsSent: Array.isArray(goal.telegramNotificationsSent) ? goal.telegramNotificationsSent : [],
+    releaseNotes: goal.releaseNotes || null,
   };
 }