@goodandready/dsh-goal 0.2.29 → 0.2.31

package/lib/goal-engine.js

@@ -1,4 +1,7 @@
 import { verifyMilestoneAcceptance } from './engine-verification.js';
+import { getEngineGoalDiff } from './engine-diff.js';
+import { syncGoalToKanban, syncMilestoneStatusToKanban, handleKanbanCardMoved } from './engine-kanban-sync.js';
+import { askOperatorQuery, answerOperatorQuery } from './engine-operator-query.js';
 import { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, calculateElapsedSeconds, calculateRemainingSeconds, buildSnapshot, getSafeCwd } from './goal-engine-constants.js';
 import { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact } from './engine-reports.js';
 import { EngineStore } from './engine-store.js';
@@ -11,8 +14,7 @@ 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';
 
-export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist };
-export { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
+export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist, getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
 
 /**
  * Isolated Goal Management Engine for DeepSeek Harness
@@ -22,25 +24,19 @@ export class GoalEngine {
     this.logger = options.logger || console;
     const rawDefIters = options.defaultMaxIterations ?? 25;
     this.defaultMaxIterations = typeof rawDefIters === "number" ? rawDefIters : (typeof rawDefIters?.value === "number" ? rawDefIters.value : 25);
-    this.autoDrive = options.autoDrive ?? true;
-    this.enableSound = options.enableSound ?? true;
-    this.showQuickLaunchButton = options.showQuickLaunchButton ?? true;
-    this.consecutiveToolFailureLimit = options.consecutiveToolFailureLimit ?? 3;
-    this.maxTokenBudget = options.maxTokenBudget ?? 0;
-    this.budgetWarningThreshold = options.budgetWarningThreshold ?? 80;
-    this.autoCheckpointOnMilestone = options.autoCheckpointOnMilestone ?? false;
-    this.enableLiveActivityFeed = options.enableLiveActivityFeed ?? true;
-    this.enablePreplanning = options.enablePreplanning ?? true;
-    this.autoBranchOnGoalStart = options.autoBranchOnGoalStart ?? true;
-    this.enablePostGoalRetrospective = options.enablePostGoalRetrospective ?? true;
-    this.autoScaleBudgetNearCompletion = options.autoScaleBudgetNearCompletion ?? false;
-    this.enableTemplatesDrawer = options.enableTemplatesDrawer ?? true;
-    this.enableMilestoneDependencies = options.enableMilestoneDependencies ?? true;
-    this.soundScheme = options.soundScheme ?? 'default';
-    this.enableVoiceAnnouncements = options.enableVoiceAnnouncements ?? false;
-    this.approvalGate = options.approvalGate || null;
-    this.checkApproval = options.checkApproval || null;
-    this.maxSessions = options.maxSessions ?? 100;
+    Object.assign(this, {
+      autoDrive: options.autoDrive ?? true, enableSound: options.enableSound ?? true,
+      showQuickLaunchButton: options.showQuickLaunchButton ?? true,
+      consecutiveToolFailureLimit: options.consecutiveToolFailureLimit ?? 3,
+      maxTokenBudget: options.maxTokenBudget ?? 0, budgetWarningThreshold: options.budgetWarningThreshold ?? 80,
+      autoCheckpointOnMilestone: options.autoCheckpointOnMilestone ?? false,
+      enableLiveActivityFeed: options.enableLiveActivityFeed ?? true, enablePreplanning: options.enablePreplanning ?? true,
+      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,
+    });
     this.goals = new Map();
     this.listeners = new Set();
     this.stallCounters = new Map();
@@ -54,10 +50,7 @@ export class GoalEngine {
   set storagePath(val) { this.store.setStoragePath(val); }
   get saveTimer() { return this.store.saveTimer; }
   get currentGoal() { return this.goals.get('default') || null; }
-  set currentGoal(val) {
-    if (val) this.goals.set('default', val);
-    else this.goals.delete('default');
-  }
+  set currentGoal(val) { if (val) this.goals.set('default', val); else this.goals.delete('default'); }
 
   loadStateFromDisk() { this.store.loadStateFromDisk(); }
   scheduleSave(immediate = false) { this.store.scheduleSave(immediate); }
@@ -111,22 +104,12 @@ export class GoalEngine {
         }
       }
     }
-    if (typeof config.autoDrive === 'boolean') this.autoDrive = config.autoDrive;
-    if (typeof config.enableSound === 'boolean') this.enableSound = config.enableSound;
-    if (typeof config.showQuickLaunchButton === 'boolean') this.showQuickLaunchButton = config.showQuickLaunchButton;
+    const boolKeys = ['autoDrive', 'enableSound', 'showQuickLaunchButton', 'autoCheckpointOnMilestone', 'enableLiveActivityFeed', 'enablePreplanning', 'autoBranchOnGoalStart', 'enablePostGoalRetrospective', 'autoScaleBudgetNearCompletion', 'enableTemplatesDrawer', 'enableMilestoneDependencies', 'enableVoiceAnnouncements'];
+    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.autoCheckpointOnMilestone === 'boolean') this.autoCheckpointOnMilestone = config.autoCheckpointOnMilestone;
-    if (typeof config.enableLiveActivityFeed === 'boolean') this.enableLiveActivityFeed = config.enableLiveActivityFeed;
-    if (typeof config.enablePreplanning === 'boolean') this.enablePreplanning = config.enablePreplanning;
-    if (typeof config.autoBranchOnGoalStart === 'boolean') this.autoBranchOnGoalStart = config.autoBranchOnGoalStart;
-    if (typeof config.enablePostGoalRetrospective === 'boolean') this.enablePostGoalRetrospective = config.enablePostGoalRetrospective;
-    if (typeof config.autoScaleBudgetNearCompletion === 'boolean') this.autoScaleBudgetNearCompletion = config.autoScaleBudgetNearCompletion;
-    if (typeof config.enableTemplatesDrawer === 'boolean') this.enableTemplatesDrawer = config.enableTemplatesDrawer;
-    if (typeof config.enableMilestoneDependencies === 'boolean') this.enableMilestoneDependencies = config.enableMilestoneDependencies;
     if (typeof config.soundScheme === 'string') this.soundScheme = config.soundScheme;
-    if (typeof config.enableVoiceAnnouncements === 'boolean') this.enableVoiceAnnouncements = config.enableVoiceAnnouncements;
     this.emit();
   }
 
@@ -140,14 +123,8 @@ export class GoalEngine {
     this.toolFailureCounters.set(sid, next);
     return next;
   }
-
-  resetToolFailureCount(sessionId = 'default') {
-    this.toolFailureCounters.set(sessionId || 'default', 0);
-  }
-
-  getToolFailureCount(sessionId = 'default') {
-    return this.toolFailureCounters.get(sessionId || 'default') || 0;
-  }
+  resetToolFailureCount(sessionId = 'default') { this.toolFailureCounters.set(sessionId || 'default', 0); }
+  getToolFailureCount(sessionId = 'default') { return this.toolFailureCounters.get(sessionId || 'default') || 0; }
 
   nudge(text, sessionId = 'default') {
     const sid = sessionId || 'default';
@@ -205,7 +182,7 @@ export class GoalEngine {
       title: cleanTitle,
       description: options.description?.trim() || '',
       lang: options.lang || detectLanguage(cleanTitle),
-      cwd: options.cwd ? getSafeCwd(options.cwd) : null,
+      cwd: options.cwd ? getSafeCwd(options.cwd, options.allowedRoots || this.allowedRoots || []) : null,
       mode: initialMode,
       state: initialState,
       startedAt: now,
@@ -218,7 +195,7 @@ export class GoalEngine {
       budgetWarningTriggered: false,
       budgetAutoScaled: false,
       gitStartCommit: gitCommit || null,
-      gitBranch: null,
+      gitBranch: options.gitBranch || options.branchName || null,
       gitParentBranch: null,
       pendingNudge: null,
       nudges: [],
@@ -229,6 +206,8 @@ export class GoalEngine {
       preplan: null,
       retrospective: null,
       issueRef: parseIssueRef(cleanTitle),
+      operatorQuery: null,
+      waitingForOperator: false,
       tokensUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
       logs: [{
         timestamp: now,
@@ -338,7 +317,8 @@ export class GoalEngine {
   }
 
   addMilestones(milestonesList, shouldEmit = true, sessionId = 'default') {
-    const sid = sessionId || 'default';
+    const sid = typeof shouldEmit === 'string' ? shouldEmit : (sessionId || 'default');
+    const shouldEmitFlag = typeof shouldEmit === 'boolean' ? shouldEmit : true;
     const goal = this.goals.get(sid);
     if (!goal || !Array.isArray(milestonesList)) return [];
 
@@ -348,7 +328,7 @@ export class GoalEngine {
     }
     this.recordProgress(sid);
     recordActivity(goal, { type: 'milestone', tool: 'addMilestones', status: 'success', details: `Added ${newMilestones.length} milestones` });
-    if (shouldEmit) this.emit(sid);
+    if (shouldEmitFlag) this.emit(sid);
     return newMilestones;
   }
 
@@ -382,6 +362,7 @@ export class GoalEngine {
 
     const prevStatus = res.prevStatus;
     recordActivity(goal, { type: 'milestone', tool: 'updateMilestone', status: 'success', details: `${id} -> ${status}` });
+    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.autoCheckpointOnMilestone) {
@@ -584,6 +565,28 @@ export class GoalEngine {
     return this.goals.get(sessionId || 'default') || null;
   }
 
+  askOperator(query = {}, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) return { ok: false, error: 'Goal not found' };
+    const res = askOperatorQuery(goal, query);
+    this.emit(sid, true);
+    return res;
+  }
+
+  answerOperator(payload = {}, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) return { ok: false, error: 'Goal not found' };
+    const res = answerOperatorQuery(goal, payload);
+    this.emit(sid, true);
+    return res;
+  }
+
+  getDiff(sessionId = 'default', options = {}) { return getEngineGoalDiff(this, sessionId, options); }
+  syncKanban(sessionId = 'default', options = {}) { return syncGoalToKanban(this, sessionId, options); }
+  handleKanbanCardMove(payload = {}, sessionId = 'default') { return handleKanbanCardMoved(this, payload, sessionId); }
+
   isPlanMode(sessionId = 'default') {
     const goal = this.goals.get(sessionId || 'default');
     return Boolean(goal && (goal.mode === GoalMode.PLAN || goal.state === GoalState.PLANNING));

package/lib/routes.js

@@ -383,6 +383,28 @@ export function registerRoutes(ctx, {
           }));
         }
 
+        // GET /dsh-goal/diff
+        if (req.method === 'GET' && (pathname === '/dsh-goal/diff' || pathname === '/dsh-goal/diff/')) {
+          const rejection = getRequestRejection(req, { ctx });
+          if (rejection !== undefined) {
+            res.statusCode = rejection;
+            return res.end(JSON.stringify({ error: rejection === 401 ? 'Unauthorized: authentication required' : 'Forbidden: untrusted caller origin' }));
+          }
+          const sid = sessionIdOf(req, 'default');
+          const target = url.searchParams.get('target') || undefined;
+          const base = url.searchParams.get('base') || undefined;
+          const file = url.searchParams.get('file') || undefined;
+          const cwd = url.searchParams.get('cwd') || undefined;
+
+          if (engine) {
+            const diffResult = engine.getDiff(sid, { target, base, file, cwd });
+            res.statusCode = diffResult.ok ? 200 : 400;
+            return res.end(JSON.stringify(diffResult));
+          }
+          res.statusCode = 404;
+          return res.end(JSON.stringify({ ok: false, error: 'Goal engine unavailable' }));
+        }
+
         // POST /dsh-goal/action
         // CSRF & Same-Origin guard
         if (req.method === 'POST' && (pathname === '/dsh-goal/action' || pathname === '/dsh-goal/action/')) {
@@ -429,7 +451,7 @@ export function registerRoutes(ctx, {
             body += chunk;
           };
 
-          const onEnd = () => {
+          const onEnd = async () => {
             if (limitExceeded) return;
             try {
               const data = JSON.parse(body || '{}');
@@ -750,6 +772,30 @@ export function registerRoutes(ctx, {
                   break;
                 }
 
+                case 'answer_operator': {
+                  const answer = typeof data.answer === 'string' ? data.answer.trim() : '';
+                  const optionIndex = typeof data.optionIndex === 'number' ? data.optionIndex : (typeof data.option_index === 'number' ? data.option_index : null);
+                  if (engine && typeof engine.answerOperator === 'function') {
+                    const ansRes = engine.answerOperator({ answer, optionIndex }, sid);
+                    if (!ansRes.ok) {
+                      res.statusCode = 400;
+                      return res.end(JSON.stringify({ error: ansRes.error || 'Failed to submit operator answer' }));
+                    }
+                    result = { ok: true, answer: ansRes.answer, state: engine.getSnapshot(sid) };
+                    const snap = engine.getSnapshot(sid);
+                    const detectedLang = snap?.lang || 'en';
+                    const prompt = detectedLang === 'zh'
+                      ? `✅ 操作员已答复你的提问: "${ansRes.answer}"。请继续执行任务。`
+                      : `✅ Operator answered your query: "${ansRes.answer}". Proceed with task execution.`;
+                    if (typeof resumeActiveAgent === 'function') {
+                      resumeActiveAgent(prompt, sid);
+                    }
+                  } else {
+                    result = { ok: true, answer };
+                  }
+                  break;
+                }
+
                 case 'approve_plan': {
                   if (engine) {
                     const snap = engine.getSnapshot(sid);
@@ -805,6 +851,28 @@ export function registerRoutes(ctx, {
                   res.statusCode = 200;
                   return res.end(JSON.stringify({ ok: true, templates: getTemplatesCatalogue() }));
 
+                case 'kanban_move': {
+                  if (engine) {
+                    result = engine.handleKanbanCardMove(data, sid);
+                    if (!result.ok) res.statusCode = 400;
+                  } else {
+                    res.statusCode = 404;
+                    result = { ok: false, error: 'Goal engine unavailable' };
+                  }
+                  break;
+                }
+
+                case 'kanban_sync': {
+                  if (engine) {
+                    result = await engine.syncKanban(sid, { ctx });
+                    if (!result.ok && !result.skipped) res.statusCode = 400;
+                  } else {
+                    res.statusCode = 404;
+                    result = { ok: false, error: 'Goal engine unavailable' };
+                  }
+                  break;
+                }
+
                 case 'instantiate_template': {
                   const tplId = data.templateId || data.id;
                   if (!tplId) {
@@ -846,6 +914,7 @@ export function registerRoutes(ctx, {
           '/dsh-goal/events': ['GET'],
           '/dsh-goal/templates': ['GET'],
           '/dsh-goal/state': ['GET'],
+          '/dsh-goal/diff': ['GET'],
           '/dsh-goal/action': ['POST'],
         };
         const cleanPath = pathname.replace(/\/+$/, '') || '/';

package/lib/tools.js

@@ -311,5 +311,70 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
       output: JSON_OUTPUT,
       execute: handleGoalFinish,
     });
+
+    // Tool 6: goal_ask_operator (#166)
+    const handleGoalAskOperator = async (args = {}, toolCtx = {}) => {
+      const goalId = args.goalId || args.goal_id || resolveGoalId(toolCtx);
+      const question = args.question || args.prompt;
+      if (!question || typeof question !== 'string' || !question.trim()) {
+        throw new Error('Field "question" is required and must be a non-empty string');
+      }
+
+      const options = Array.isArray(args.options) ? args.options : [];
+      const isBlocking = args.isBlocking !== false && args.is_blocking !== false;
+
+      const engine = ctx.goalEngine || (ctx.get && ctx.get('goalEngine'));
+      if (engine && typeof engine.askOperator === 'function') {
+        const res = engine.askOperator({ question, options, isBlocking }, goalId);
+        if (!res.ok) {
+          throw new Error(`Failed to present question to operator: ${res.error}`);
+        }
+        return {
+          ok: true,
+          goalId,
+          queryId: res.queryId,
+          question: res.question,
+          options: res.options,
+          isBlocking: res.isBlocking,
+          message: isBlocking
+            ? 'Question submitted to human operator. Goal is paused awaiting operator input.'
+            : 'Question submitted to human operator in non-blocking mode.',
+        };
+      }
+
+      return {
+        ok: true,
+        goalId,
+        question,
+        options,
+        message: 'Question logged.',
+      };
+    };
+
+    safeRegister({
+      name: 'goal_ask_operator',
+      description: 'Ask the human operator a clarification question or present architectural choices when encountering blockers (#166). Pauses autonomous execution without consuming iterations until the operator responds.',
+      parameters: {
+        type: 'object',
+        properties: {
+          question: {
+            type: 'string',
+            description: 'The clarification question, design decision, or blocker to ask the human operator',
+          },
+          options: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional list of predefined choices or alternative options for the operator to select with one click',
+          },
+          is_blocking: {
+            type: 'boolean',
+            description: 'Whether to pause goal execution awaiting operator response (default: true)',
+          },
+        },
+        required: ['question'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleGoalAskOperator,
+    });
   });
 }

package/package.json

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