@goodandready/dsh-goal 0.2.12 → 0.2.14

package/lib/token-budget-guard.js

@@ -0,0 +1,128 @@
+/**
+ * Token budget guard: monitors goal session tokens via ctx.tokenMeter,
+ * emits warning at threshold (default 80%), and calls ctx.goals.block() at 100%.
+ */
+export class TokenBudgetGuard {
+  constructor({
+    maxTokenBudget = 0,
+    warningThreshold = 80,
+    autoScaleNearCompletion = false,
+    logger = console,
+  } = {}) {
+    this.maxTokenBudget = maxTokenBudget;
+    this.warningThreshold = warningThreshold;
+    this.autoScaleNearCompletion = autoScaleNearCompletion;
+    this.logger = logger;
+    this.warnedGoals = new Set();
+    this.blockedGoals = new Set();
+    this.autoScaledGoals = new Set();
+    this.customBudgets = new Map(); // goalId -> maxTokenBudget override
+  }
+
+  updateConfig({ maxTokenBudget, warningThreshold, autoScaleNearCompletion }) {
+    if (typeof maxTokenBudget === 'number') this.maxTokenBudget = maxTokenBudget;
+    if (typeof warningThreshold === 'number') this.warningThreshold = warningThreshold;
+    if (typeof autoScaleNearCompletion === 'boolean') this.autoScaleNearCompletion = autoScaleNearCompletion;
+  }
+
+  setGoalBudget(goalId, limit) {
+    if (goalId && typeof limit === 'number') {
+      this.customBudgets.set(goalId, limit);
+    }
+  }
+
+  getEffectiveBudget(goalId) {
+    if (goalId && this.customBudgets.has(goalId)) {
+      return this.customBudgets.get(goalId);
+    }
+    return this.maxTokenBudget;
+  }
+
+  /**
+   * Evaluate token consumption and trigger warnings or goal blocking
+   * @param {object} params
+   * @param {object} params.agent
+   * @param {object} params.goal - current goal snapshot { id, revision, phase }
+   * @param {object} [params.tokenMeter] - ctx.tokenMeter
+   * @param {object} [params.goalsService] - ctx.goals
+   * @param {Array} [params.milestones] - milestone list to test near-completion
+   * @returns {{ status: 'ok'|'warning'|'blocked'|'auto_scaled', message?: string, tokensUsed: number, budget: number, pct: number }}
+   */
+  checkBudget({ agent, goal, tokenMeter, goalsService, milestones = [] }) {
+    if (!goal || !goal.id) return { status: 'ok', tokensUsed: 0, budget: 0, pct: 0 };
+    const goalId = goal.id;
+    const limit = this.getEffectiveBudget(goalId);
+    if (limit <= 0) return { status: 'ok', tokensUsed: 0, budget: 0, pct: 0 };
+
+    let tokensUsed = 0;
+    if (tokenMeter && agent?.session) {
+      try {
+        const measurement = tokenMeter.measure(agent.session);
+        tokensUsed = measurement?.totalTokens || 0;
+      } catch (err) {
+        this.logger.warn?.('[TokenBudgetGuard] Failed to measure tokens:', err.message);
+      }
+    }
+
+    const pct = Math.round((tokensUsed / limit) * 100);
+
+    // 1. Check if budget exceeded (>= 100%)
+    if (tokensUsed >= limit) {
+      // Check auto-scale buffer near completion (>= 75% milestones done)
+      if (this.autoScaleNearCompletion && !this.autoScaledGoals.has(goalId)) {
+        const total = milestones.length;
+        const done = milestones.filter(m => m.completed).length;
+        const nearDone = total > 0 && (done / total >= 0.75 || done === total - 1);
+        if (nearDone) {
+          const extension = Math.round(limit * 0.2); // +20%
+          const newLimit = limit + extension;
+          this.setGoalBudget(goalId, newLimit);
+          this.autoScaledGoals.add(goalId);
+          const msg = `⚡ Token budget auto-scaled: added +${extension.toLocaleString()} tokens buffer near goal completion (${newLimit.toLocaleString()} total).`;
+          this.logger.info?.(`[TokenBudgetGuard] ${msg}`);
+          return { status: 'auto_scaled', message: msg, tokensUsed, budget: newLimit, pct: Math.round((tokensUsed / newLimit) * 100) };
+        }
+      }
+
+      // Block goal via core GoalService
+      const msg = `Token budget limit (${limit.toLocaleString()}) reached (${tokensUsed.toLocaleString()} tokens used, ${pct}%). Goal execution is blocked.`;
+      if (!this.blockedGoals.has(goalId)) {
+        this.blockedGoals.add(goalId);
+        if (goalsService && typeof goalsService.block === 'function' && agent) {
+          try {
+            goalsService.block(agent, { id: goal.id, revision: goal.revision }, {
+              code: 'budget',
+              message: msg,
+            });
+            this.logger.info?.(`[TokenBudgetGuard] Blocked goal "${goalId}" via ctx.goals.block()`);
+          } catch (err) {
+            this.logger.warn?.('[TokenBudgetGuard] ctx.goals.block() failed:', err.message);
+          }
+        }
+      }
+      return { status: 'blocked', message: msg, tokensUsed, budget: limit, pct };
+    }
+
+    // 2. Check warning threshold (e.g. >= 80%)
+    if (pct >= this.warningThreshold) {
+      const msg = `⚠️ Token budget warning: ${tokensUsed.toLocaleString()} of ${limit.toLocaleString()} tokens used (${pct}%). Goal will block at 100%.`;
+      const isNewWarning = !this.warnedGoals.has(goalId);
+      if (isNewWarning) {
+        this.warnedGoals.add(goalId);
+        this.logger.warn?.(`[TokenBudgetGuard] Goal "${goalId}" reached ${pct}% of token budget.`);
+      }
+      return { status: 'warning', message: msg, tokensUsed, budget: limit, pct, isNewWarning };
+    }
+
+    return { status: 'ok', tokensUsed, budget: limit, pct };
+  }
+
+  resetGoal(goalId) {
+    if (goalId) {
+      this.warnedGoals.delete(goalId);
+      this.blockedGoals.delete(goalId);
+      this.autoScaledGoals.delete(goalId);
+      this.customBudgets.delete(goalId);
+    }
+  }
+}

package/lib/tools.js

@@ -1,327 +1,185 @@
-import { GoalState, sessionIdOf } from './goal-engine-constants.js';
-
-export const JSON_OUTPUT = {
-  schema: { type: 'object', additionalProperties: true },
-  render: (_args, val) => [{ type: 'text', text: JSON.stringify(val) }],
-};
-
-/**
- * Format goal snapshot into DSH core-compatible goal representation
- * @param {any} snap
- * @returns {object}
- */
-export function formatGoalValue(snap) {
-  if (!snap || !snap.hasActiveGoal) {
-    return { goal: null };
-  }
-
-  let phase = 'active';
-  if (snap.state === GoalState.PAUSED) phase = 'paused';
-  else if (snap.state === GoalState.COMPLETED) phase = 'complete';
-
-  const roundsStarted = Number.isInteger(snap.iterations) ? snap.iterations : 0;
-  const maxGoalRounds = Number.isInteger(snap.maxIterations) ? snap.maxIterations : 25;
-
-  return {
-    goal: {
-      id: snap.id || 'goal-active',
-      revision: 1,
-      objective: snap.title || 'Goal',
-      phase,
-      roundsStarted,
-      maxGoalRounds,
-    },
-    activation: snap.state === GoalState.RUNNING ? 'armed' : 'disarmed',
-  };
-}
+import { MilestoneManager } from './milestone-manager.js';
+import { AddonStore } from './addon-store.js';
 
 /**
- * Register goal management tools into Cordis tools service
+ * Tools module for @goodandready/dsh-goal (Core Addon).
+ *
+ * Register addon goal tools: goal_milestones and goal_checklist.
+ * Does NOT register create_goal, get_goal, update_goal (core provides them).
+ *
  * @param {any} ctx
- * @param {object} options
- * @param {any} options.engine
- * @param {Function} [options.resumeActiveAgent]
+ * @param {object} [options]
+ * @param {import('./milestone-manager.js').MilestoneManager} [options.milestoneManager]
+ * @param {object} [options.goalsService] - core GoalService (ctx.goals)
+ * @param {object} [options.logger]
  */
-export function registerTools(ctx, { engine, resumeActiveAgent, logger = console }) {
+export function registerTools(ctx, { milestoneManager, goalsService, logger = console } = {}) {
+  const mm = milestoneManager || new MilestoneManager(new AddonStore(null, logger), { logger });
+
   ctx.inject(['tools'], (tctx) => {
     if (!tctx.tools?.register) return;
 
-    const displacedTools = new Map();
     const safeRegister = (definition) => {
       try {
         const name = definition.name;
-        const globalTools = tctx.tools.layers?.global?.tools;
-        if (globalTools?.data instanceof Map && globalTools.data.has(name)) {
-          displacedTools.set(name, globalTools.data.get(name));
-          globalTools.data.delete(name);
-        }
         const unregister = tctx.tools.register(definition);
         if (typeof unregister === 'function') {
-          tctx.effect(() => () => {
-            unregister();
-            if (displacedTools.has(name) && globalTools?.data instanceof Map) {
-              globalTools.data.set(name, displacedTools.get(name));
-            }
+          tctx.effect?.(() => () => {
+            try { unregister(); } catch (e) { /* unregister error non-fatal */ }
           }, `dsh-goal: tool ${name}`);
         }
       } catch (err) {
-        logger.warn(`[dsh-goal] Tool ${definition.name} registration skipped:`, err.message);
+        logger.warn?.(`[dsh-goal] Tool ${definition.name} registration skipped:`, err.message);
       }
     };
 
-    // Tool 1: get_goal
-    const handleGetGoal = async (_args, toolCtx) => {
-      const sid = sessionIdOf(toolCtx, 'default');
-      const snap = engine.getSnapshot(sid);
-      return formatGoalValue(snap);
-    };
-
-    safeRegister({
-      name: 'get_goal',
-      description: 'Get current active goal and its execution phase.',
-      parameters: { type: 'object', properties: {} },
-      output: JSON_OUTPUT,
-      execute: handleGetGoal,
-      handler: handleGetGoal,
-    });
-
-    // Tool 2: create_goal
-    const handleCreateGoal = async (args, toolCtx) => {
-      const sid = sessionIdOf(toolCtx, 'default');
-      const maxIterations = Number(args.max_goal_rounds) || 25;
-      const snap = engine.startGoal(args.objective, { maxIterations }, sid);
-      return formatGoalValue(snap);
+    /** Helper to resolve current goal ID for a tool execution */
+    const resolveGoalId = (toolCtx) => {
+      if (goalsService) {
+        try {
+          const agent = toolCtx?.agent || (tctx.agents && toolCtx?.agentId ? tctx.agents.get(toolCtx.agentId) : null);
+          if (agent && typeof goalsService.get === 'function') {
+            const current = goalsService.get(agent);
+            if (current?.id) return current.id;
+          }
+        } catch (e) { /* ignore */ }
+      }
+      return toolCtx?.sessionId || toolCtx?.session?.id || 'default';
     };
 
-    safeRegister({
-      name: 'create_goal',
-      description: 'Initialize a new autonomous goal.',
-      parameters: {
-        type: 'object',
-        properties: {
-          objective: { type: 'string', description: 'The overarching objective to achieve' },
-          max_goal_rounds: { type: 'number', description: 'Maximum iterations allowed' },
-        },
-        required: ['objective'],
+    const JSON_OUTPUT = {
+      type: 'object',
+      properties: {
+        ok: { type: 'boolean' },
       },
-      output: JSON_OUTPUT,
-      execute: handleCreateGoal,
-      handler: handleCreateGoal,
-    });
+    };
 
-    // Tool 3: update_goal
-    const handleUpdateGoal = async (args, toolCtx) => {
-      const sid = sessionIdOf(toolCtx, 'default');
-      const action = args.action;
+    // Tool 1: goal_milestones
+    const handleGoalMilestones = async (args = {}, toolCtx = {}) => {
+      const goalId = args.goalId || args.goal_id || resolveGoalId(toolCtx);
+      const action = args.action || 'list';
+      const milestoneId = args.milestoneId || args.milestone_id;
 
-      if (action === 'complete') {
-        const summary = args.blocked_reason || args.objective || 'Goal marked complete';
-        const snap = engine.completeGoal(summary, sid);
-        if (toolCtx?.deferContext) {
-          try {
-            toolCtx.deferContext({
-              type: 'text',
-              text: `<goal_complete>\nObjective: ${JSON.stringify(snap.title || summary)}\nThe goal is marked complete. Summarize what was accomplished for the user.\n</goal_complete>`,
-            });
-          } catch (err) {
-            toolCtx?.logger?.debug?.('[dsh-goal] Failed to defer complete context:', err);
-          }
-        }
-        return formatGoalValue(snap);
+      if (action === 'list') {
+        const list = mm.getMilestones(goalId);
+        return { ok: true, goalId, milestones: list };
       }
 
-      if (action === 'pause') {
-        const reason = args.blocked_reason || 'Paused by model';
-        const snap = engine.pause(reason, sid);
-        return formatGoalValue(snap);
+      if (action === 'set') {
+        const list = mm.setMilestones(goalId, args.milestones);
+        return { ok: true, goalId, count: list.length, milestones: list };
       }
 
-      if (action === 'resume') {
-        const snap = engine.resume(sid);
-        if (typeof resumeActiveAgent === 'function') {
-          resumeActiveAgent(undefined, sid);
-        }
-        return formatGoalValue(snap);
-      }
-
-      if (action === 'edit') {
-        const snap = engine.getSnapshot(sid);
-        if (args.objective) snap.title = args.objective;
-        if (args.max_goal_rounds) snap.maxIterations = Number(args.max_goal_rounds);
-        engine.emit(sid, true);
-        return formatGoalValue(snap);
+      if (action === 'add') {
+        const item = mm.addMilestone(goalId, {
+          title: args.title,
+          checklist: args.checklist,
+          dependsOn: args.dependsOn || args.depends_on,
+        });
+        return { ok: true, goalId, milestone: item };
       }
 
-      if (action === 'blocked') {
-        const reason = args.blocked_reason || 'Goal blocked';
-        const snap = engine.pause('Blocked: ' + reason, sid);
-        if (toolCtx?.deferContext) {
-          try {
-            toolCtx.deferContext({
-              type: 'text',
-              text: `<goal_blocked>\nObjective: ${JSON.stringify(snap.title || 'Goal')}\nBlocked: ${JSON.stringify(reason)}\nExplain to the user what blocked progress.\n</goal_blocked>`,
-            });
-          } catch (err) {
-            toolCtx?.logger?.debug?.('[dsh-goal] Failed to defer blocked context:', err);
-          }
-        }
-        const res = formatGoalValue(snap);
-        if (res.goal) {
-          res.goal.phase = 'blocked';
-          res.goal.blockedReason = { code: 'model-reported', message: reason };
+      if (action === 'complete') {
+        if (!milestoneId) {
+          throw new Error('milestoneId is required for complete action');
         }
-        return res;
+        const completed = await mm.completeMilestone(goalId, milestoneId, {
+          cwd: toolCtx?.session?.cwd || toolCtx?.cwd || process.cwd(),
+        });
+        return { ok: true, goalId, milestoneId, milestone: completed };
       }
 
-      return formatGoalValue(engine.getSnapshot(sid));
+      throw new Error(`Unsupported action "${action}". Allowed: list, set, add, complete`);
     };
 
     safeRegister({
-      name: 'update_goal',
-      description: 'Update status or parameters of the current active goal.',
+      name: 'goal_milestones',
+      description: 'Manage milestones and work phases for the active goal. Supports list, set, add, and complete.',
       parameters: {
         type: 'object',
         properties: {
           action: {
             type: 'string',
-            enum: ['pause', 'resume', 'complete', 'edit', 'blocked'],
-            description: 'Action to perform on the goal',
+            enum: ['list', 'set', 'add', 'complete'],
+            description: 'Milestone action to perform',
           },
-          objective: { type: 'string', description: 'Updated goal title (for edit)' },
-          max_goal_rounds: { type: 'number', description: 'Updated iterations limit (for edit)' },
-          blocked_reason: { type: 'string', description: 'Reason for pause, blocked, or completion summary' },
-        },
-        required: ['action'],
-      },
-      output: JSON_OUTPUT,
-      execute: handleUpdateGoal,
-      handler: handleUpdateGoal,
-    });
-
-    // Tool 4: goal_set_milestones
-    const handleSetMilestones = async ({ milestones }, toolCtx) => {
-      const sid = sessionIdOf(toolCtx, 'default');
-      const snap = engine.setMilestones(milestones, sid);
-      if (typeof engine.recordToolActivity === 'function') {
-        engine.recordToolActivity('goal_set_milestones', 'success', 'Defined milestones', sid);
-      }
-      return {
-        success: true,
-        count: snap.milestones?.length || 0,
-        milestones: snap.milestones,
-      };
-    };
-
-    safeRegister({
-      name: 'goal_set_milestones',
-      description: 'Decompose the goal into 3-7 verifiable milestones.',
-      parameters: {
-        type: 'object',
-        properties: {
           milestones: {
             type: 'array',
             items: {
               type: 'object',
               properties: {
-                id: { type: 'string', description: 'Short identifier, e.g. M1, step-1' },
-                title: { type: 'string', description: 'Concise actionable title' },
-                dependsOn: { type: 'array', items: { type: 'string' }, description: 'Prerequisite milestone IDs' },
+                id: { type: 'string' },
+                title: { type: 'string' },
+                checklist: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      text: { type: 'string' },
+                      done: { type: 'boolean' },
+                    },
+                    required: ['text'],
+                  },
+                },
+                dependsOn: { type: 'array', items: { type: 'string' } },
               },
-              required: ['id', 'title'],
+              required: ['title'],
             },
-            description: 'List of milestones to achieve the goal',
+            description: 'Array of milestones when action is "set"',
           },
-        },
-        required: ['milestones'],
-      },
-      output: JSON_OUTPUT,
-      execute: handleSetMilestones,
-      handler: handleSetMilestones,
-    });
-
-    // Tool 5: goal_update_progress
-    const handleUpdateProgress = async ({ milestone_id, status, notes, checklist }, toolCtx) => {
-      const sid = sessionIdOf(toolCtx, 'default');
-      const ok = engine.updateMilestone(milestone_id, status, notes, sid, checklist);
-      if (typeof engine.recordToolActivity === 'function') {
-        engine.recordToolActivity('goal_update_progress', ok ? 'success' : 'error', String(milestone_id) + ' -> ' + String(status), sid);
-      }
-      const snap = engine.getSnapshot(sid);
-      const targetMilestone = snap.milestones?.find((m) => m.id === String(milestone_id) || m.id.toLowerCase().replace(/[^a-z0-9]/g, '') === String(milestone_id).toLowerCase().replace(/[^a-z0-9]/g, '') || m.id.toLowerCase().replace(/[^0-9]/g, '') === String(milestone_id).toLowerCase().replace(/[^0-9]/g, ''));
-      return {
-        success: true,
-        milestone_id,
-        status,
-        checklist: targetMilestone?.checklist || null,
-        checkpointCommit: targetMilestone?.checkpointCommit || null,
-        total_milestones: snap.milestones?.length,
-        completed: snap.milestones?.filter((m) => m.status === 'completed').length,
-      };
-    };
-
-    safeRegister({
-      name: 'goal_update_progress',
-      description: 'Update the progress of a specific milestone, optionally attaching a sub-tasks checklist.',
-      parameters: {
-        type: 'object',
-        properties: {
-          milestone_id: { type: 'string', description: 'Milestone ID (e.g. M1)' },
-          status: {
-            type: 'string',
-            enum: ['pending', 'in_progress', 'completed', 'failed'],
-            description: 'New milestone status',
-          },
-          notes: { type: 'string', description: 'Summary of actions completed or blocking issue' },
+          title: { type: 'string', description: 'Milestone title when action is "add"' },
+          milestoneId: { type: 'string', description: 'Target milestone ID when action is "complete"' },
           checklist: {
             type: 'array',
-            items: {
-              type: 'object',
-              properties: {
-                text: { type: 'string', description: 'Checklist task item description' },
-                done: { type: 'boolean', description: 'Whether the item is completed' },
-              },
-              required: ['text', 'done'],
-            },
-            description: 'Optional sub-tasks / checklist items within this milestone',
+            items: { type: 'string' },
+            description: 'Initial checklist items for added milestone',
           },
         },
-        required: ['milestone_id', 'status'],
+        required: ['action'],
       },
       output: JSON_OUTPUT,
-      execute: handleUpdateProgress,
-      handler: handleUpdateProgress,
+      execute: handleGoalMilestones,
+      handler: handleGoalMilestones,
     });
 
-    // Tool 6: goal_finish
-    const handleGoalFinish = async ({ summary }, toolCtx) => {
-      const sid = sessionIdOf(toolCtx, 'default');
-      const snap = engine.completeGoal(summary, sid);
-      if (typeof engine.recordToolActivity === 'function') {
-        engine.recordToolActivity('goal_finish', 'success', summary ? summary.slice(0, 80) : 'Goal finished', sid);
+    // Tool 2: goal_checklist
+    const handleGoalChecklist = async (args = {}, toolCtx = {}) => {
+      const goalId = args.goalId || args.goal_id || resolveGoalId(toolCtx);
+      const milestoneId = args.milestoneId || args.milestone_id;
+      const index = args.index !== undefined ? args.index : args.item_index;
+      const action = args.action || 'toggle';
+
+      if (!milestoneId) {
+        throw new Error('milestoneId is required for goal_checklist');
       }
-      return {
-        success: true,
-        completed: true,
-        summary,
-      };
+      if (index === undefined || index === null) {
+        throw new Error('index is required for goal_checklist');
+      }
+
+      if (action === 'toggle') {
+        const item = mm.toggleChecklist(goalId, milestoneId, index, args.done);
+        return { ok: true, goalId, milestoneId, index, item };
+      }
+
+      throw new Error(`Unsupported action "${action}". Allowed: toggle`);
     };
 
     safeRegister({
-      name: 'goal_finish',
-      description: 'Conclude the active goal successfully with a final summary and achievements.',
+      name: 'goal_checklist',
+      description: 'Toggle sub-task checklist items within a goal milestone.',
       parameters: {
         type: 'object',
         properties: {
-          summary: {
-            type: 'string',
-            description: 'Final summary of the goal outcome and deliverables.',
-          },
+          action: { type: 'string', enum: ['toggle'], description: 'Action to perform' },
+          milestoneId: { type: 'string', description: 'Target milestone ID' },
+          index: { type: 'number', description: 'Zero-based index of checklist item' },
+          done: { type: 'boolean', description: 'Explicit completion flag (optional, toggles if omitted)' },
         },
-        required: ['summary'],
+        required: ['action', 'milestoneId', 'index'],
       },
       output: JSON_OUTPUT,
-      execute: handleGoalFinish,
-      handler: handleGoalFinish,
+      execute: handleGoalChecklist,
+      handler: handleGoalChecklist,
     });
   });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goodandready/dsh-goal",
-  "version": "0.2.12",
-  "description": "Autonomous Goal Execution & Multi-Turn Task Tracking Engine with Sticky Header for DeepSeek Harness",
+  "version": "0.2.14",
+  "description": "Core Goal Addon (Token Budget, Milestones, Git Snapshots & Retrospective Reports) for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {
@@ -55,12 +55,18 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-goal": ">=0.1.5-rc.3"
   },
   "devDependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-goal": {
+      "optional": true
+    }
   }
 }