@goodandready/dsh-goal 0.2.2 → 0.2.3

package/lib/routes.js

@@ -0,0 +1,294 @@
+import { MilestoneStatus, detectLanguage, sessionIdOf } from './goal-engine-constants.js';
+
+/**
+ * Register webServer HTTP routes and SSE stream for DSH Goal
+ * @param {any} ctx Cordis context
+ * @param {object} deps Dependencies
+ * @param {any} deps.engine GoalEngine instance
+ * @param {Function} deps.getConfig Function returning current config
+ * @param {Function} deps.stopRunningAgents Stop agents function
+ * @param {Function} deps.resumeActiveAgent Resume agent function
+ * @param {Map} deps.sessionAgents Session agent map
+ * @param {Map} [deps.sseClients] SSE clients map (sid -> Set)
+ */
+export function registerRoutes(ctx, {
+  engine,
+  getConfig,
+  stopRunningAgents,
+  resumeActiveAgent,
+  sessionAgents,
+  sseClients = new Map(),
+}) {
+  // Subscribe to engine changes for realtime Server-Sent Events broadcasting
+  engine.subscribe((snapshot, sid) => {
+    const clients = sseClients.get(sid);
+    if (clients && clients.size > 0) {
+      const payload = `data: ${JSON.stringify(snapshot)}\n\n`;
+      for (const clientRes of Array.from(clients)) {
+        try {
+          clientRes.write(payload);
+        } catch (err) {
+          clients.delete(clientRes);
+          try { clientRes.end(); } catch (e) { /* closed */ }
+        }
+      }
+      if (clients.size === 0) sseClients.delete(sid);
+    }
+    if (sid !== 'default' && sseClients.has('default')) {
+      const defClients = sseClients.get('default');
+      if (defClients && defClients.size > 0) {
+        const payload = `data: ${JSON.stringify(snapshot)}\n\n`;
+        for (const clientRes of Array.from(defClients)) {
+          try {
+            clientRes.write(payload);
+          } catch (err) {
+            defClients.delete(clientRes);
+            try { clientRes.end(); } catch (e) { /* closed */ }
+          }
+        }
+        if (defClients.size === 0) sseClients.delete('default');
+      }
+    }
+  });
+
+  ctx.effect(() => {
+    if (!ctx.webServer?.register) return () => {};
+
+    // Keepalive ping timer for SSE connections (every 20s)
+    const keepaliveTimer = setInterval(() => {
+      for (const [sid, clients] of sseClients.entries()) {
+        for (const res of Array.from(clients)) {
+          try {
+            res.write(': keepalive\n\n');
+          } catch (err) {
+            clients.delete(res);
+            try { res.end(); } catch (e) { /* closed */ }
+          }
+        }
+        if (clients.size === 0) {
+          sseClients.delete(sid);
+        }
+      }
+    }, 20000);
+    if (typeof keepaliveTimer.unref === 'function') keepaliveTimer.unref();
+
+    const unreg = ctx.webServer.register({
+      kind: 'prefix',
+      path: '/dsh-goal',
+      handler: (req, res) => {
+        const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+        const pathname = url.pathname;
+
+        // GET /dsh-goal/events: Server-Sent Events realtime snapshot stream
+        if (req.method === 'GET' && (pathname === '/dsh-goal/events' || pathname === '/dsh-goal/events/')) {
+          const sid = sessionIdOf(req, 'default');
+          res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no',
+          });
+
+          if (!sseClients.has(sid)) {
+            sseClients.set(sid, new Set());
+          }
+          sseClients.get(sid).add(res);
+
+          const initialSnap = engine.getSnapshot(sid);
+          res.write(`data: ${JSON.stringify(initialSnap)}\n\n`);
+
+          req.on('close', () => {
+            const set = sseClients.get(sid);
+            if (set) {
+              set.delete(res);
+              if (set.size === 0) sseClients.delete(sid);
+            }
+          });
+          return;
+        }
+
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+
+        // GET /dsh-goal/state
+        if (req.method === 'GET' && (pathname === '/dsh-goal/state' || pathname === '/dsh-goal/state/')) {
+          const sid = sessionIdOf(req, 'default');
+          res.statusCode = 200;
+          return res.end(JSON.stringify(engine.getSnapshot(sid)));
+        }
+
+        // POST /dsh-goal/action
+        // CSRF & Same-Origin guard
+        if (req.method === 'POST' && (pathname === '/dsh-goal/action' || pathname === '/dsh-goal/action/')) {
+          const secFetchSite = req.headers['sec-fetch-site'];
+          if (secFetchSite && secFetchSite !== 'same-origin' && secFetchSite !== 'same-site' && secFetchSite !== 'none') {
+            res.statusCode = 403;
+            return res.end(JSON.stringify({ error: 'Forbidden: cross-site requests are rejected' }));
+          }
+
+          const origin = req.headers.origin;
+          const host = req.headers.host;
+          if (origin && host) {
+            try {
+              const originHost = new URL(origin).host;
+              if (originHost !== host) {
+                res.statusCode = 403;
+                return res.end(JSON.stringify({ error: 'Forbidden: origin mismatch' }));
+              }
+            } catch (err) {
+              res.statusCode = 403;
+              return res.end(JSON.stringify({ error: 'Forbidden: invalid origin' }));
+            }
+          }
+
+          let body = '';
+          let bodySize = 0;
+          const MAX_PAYLOAD_BYTES = 256 * 1024;
+          let limitExceeded = false;
+
+          req.on('data', (chunk) => {
+            bodySize += chunk.length;
+            if (bodySize > MAX_PAYLOAD_BYTES) {
+              limitExceeded = true;
+              req.pause();
+              res.statusCode = 413;
+              return res.end(JSON.stringify({ error: 'Payload too large: max 256 KB allowed' }));
+            }
+            body += chunk;
+          });
+
+          req.on('end', () => {
+            if (limitExceeded) return;
+            try {
+              const data = JSON.parse(body || '{}');
+              const sid = data.sessionId || sessionIdOf(req, 'default');
+              const { action, title, description, reason, milestoneId, status, notes } = data;
+
+              let result = null;
+              switch (action) {
+                case 'start': {
+                  const cleanTitle = typeof title === 'string' ? title.trim() : '';
+                  if (!cleanTitle) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: 'Goal title cannot be empty' }));
+                  }
+                  const detectedLang = data.lang || detectLanguage(cleanTitle);
+                  const conf = typeof getConfig === 'function' ? getConfig() : { maxIterations: 25 };
+                  result = engine.startGoal(cleanTitle, {
+                    description: typeof description === 'string' ? description.trim() : '',
+                    maxIterations: conf.maxIterations || 25,
+                    lang: detectedLang,
+                  }, sid);
+
+                  const startPrompt = detectedLang === 'zh'
+                    ? `🎯 目标已确立：“${cleanTitle}”。请立即通过 goal_set_milestones 制定工作计划（3-7个具体步骤）并开始执行。`
+                    : `🎯 Goal established: "${cleanTitle}". Immediately formulate a work plan (3-7 concrete steps) via tool goal_set_milestones and start executing it.`;
+
+                  if (typeof resumeActiveAgent === 'function') {
+                    resumeActiveAgent(startPrompt, sid);
+                  }
+                  break;
+                }
+
+                case 'nudge': {
+                  const text = (typeof data.text === 'string' ? data.text : (data.notes || data.nudge || '')).trim();
+                  if (!text) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: 'Nudge text cannot be empty' }));
+                  }
+                  result = engine.nudge(text, sid);
+                  if (data.resume) {
+                    engine.resume(sid);
+                    const prompt = engine.getStatePromptInjection(sid);
+                    if (typeof resumeActiveAgent === 'function') {
+                      resumeActiveAgent(prompt, sid);
+                    }
+                  }
+                  break;
+                }
+
+                case 'pause':
+                  result = engine.pause(reason || 'Paused by user interface', sid);
+                  if (typeof stopRunningAgents === 'function') {
+                    stopRunningAgents(sid);
+                  }
+                  break;
+
+                case 'resume':
+                  result = engine.resume(sid);
+                  if (typeof resumeActiveAgent === 'function') {
+                    resumeActiveAgent(undefined, sid);
+                  }
+                  break;
+
+                case 'cancel':
+                  result = engine.cancel(reason || 'Goal cancelled by user', sid);
+                  if (typeof stopRunningAgents === 'function') {
+                    stopRunningAgents(sid);
+                  }
+                  break;
+
+                case 'clear':
+                  result = engine.clear(sid);
+                  if (typeof stopRunningAgents === 'function') {
+                    stopRunningAgents(sid);
+                  }
+                  if (sessionAgents) {
+                    sessionAgents.delete(sid);
+                  }
+                  break;
+
+                case 'update_milestone': {
+                  if (!milestoneId || !status) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: 'milestoneId and status are required' }));
+                  }
+                  const validStatuses = Object.values(MilestoneStatus);
+                  if (!validStatuses.includes(status)) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: `Invalid status: ${status}. Must be one of: ${validStatuses.join(', ')}` }));
+                  }
+                  const ok = engine.updateMilestone(milestoneId, status, notes, sid);
+                  if (!ok) {
+                    res.statusCode = 404;
+                    return res.end(JSON.stringify({ error: `Milestone with id "${milestoneId}" not found` }));
+                  }
+                  result = engine.getSnapshot(sid);
+                  break;
+                }
+
+                default:
+                  res.statusCode = 400;
+                  return res.end(JSON.stringify({ error: `Unknown action: ${action}` }));
+              }
+
+              res.statusCode = 200;
+              return res.end(JSON.stringify({ ok: true, state: result || engine.getSnapshot(sid) }));
+            } catch (parseErr) {
+              res.statusCode = 400;
+              return res.end(JSON.stringify({ error: parseErr.message }));
+            }
+          });
+          return;
+        }
+
+        res.statusCode = 404;
+        res.end(JSON.stringify({ error: 'Endpoint not found' }));
+      },
+    });
+
+    return () => {
+      clearInterval(keepaliveTimer);
+      if (typeof unreg === 'function') unreg();
+      for (const clients of sseClients.values()) {
+        for (const res of clients) {
+          try {
+            res.end();
+          } catch (err) {
+            // Already closed
+          }
+        }
+      }
+      sseClients.clear();
+    };
+  }, 'dsh-goal: HTTP WebServer Routes & SSE');
+}

package/lib/tools.js

@@ -0,0 +1,294 @@
+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',
+  };
+}
+
+/**
+ * Register goal management tools into Cordis tools service
+ * @param {any} ctx
+ * @param {object} options
+ * @param {any} options.engine
+ * @param {Function} [options.resumeActiveAgent]
+ */
+export function registerTools(ctx, { engine, resumeActiveAgent }) {
+  ctx.inject(['tools'], (tctx) => {
+    if (!tctx.tools?.register) return;
+
+    const safeRegister = (definition) => {
+      try {
+        const name = definition.name;
+        const globalTools = tctx.tools.layers?.global?.tools;
+        if (globalTools?.data instanceof Map && globalTools.data.has(name)) {
+          globalTools.data.delete(name);
+        }
+        const unregister = tctx.tools.register(definition);
+        if (typeof unregister === 'function') {
+          tctx.effect(() => () => unregister(), `dsh-goal: tool ${name}`);
+        }
+      } catch (err) {
+        console.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);
+    };
+
+    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'],
+      },
+      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;
+
+      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 === 'pause') {
+        const reason = args.blocked_reason || 'Paused by model';
+        const snap = engine.pause(reason, sid);
+        return formatGoalValue(snap);
+      }
+
+      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 === '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 };
+        }
+        return res;
+      }
+
+      return formatGoalValue(engine.getSnapshot(sid));
+    };
+
+    safeRegister({
+      name: 'update_goal',
+      description: 'Update status or parameters of the current active goal.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['pause', 'resume', 'complete', 'edit', 'blocked'],
+            description: 'Action to perform on the goal',
+          },
+          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);
+      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' },
+              },
+              required: ['id', 'title'],
+            },
+            description: 'List of milestones to achieve the goal',
+          },
+        },
+        required: ['milestones'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleSetMilestones,
+      handler: handleSetMilestones,
+    });
+
+    // Tool 5: goal_update_progress
+    const handleUpdateProgress = async ({ milestone_id, status, notes }, toolCtx) => {
+      const sid = sessionIdOf(toolCtx, 'default');
+      const snap = engine.updateMilestone(milestone_id, status, notes, sid);
+      return {
+        success: true,
+        milestone_id,
+        status,
+        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.',
+      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' },
+        },
+        required: ['milestone_id', 'status'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleUpdateProgress,
+      handler: handleUpdateProgress,
+    });
+
+    // Tool 6: goal_finish
+    const handleGoalFinish = async ({ summary }, toolCtx) => {
+      const sid = sessionIdOf(toolCtx, 'default');
+      const snap = engine.completeGoal(summary, sid);
+      return {
+        success: true,
+        completed: true,
+        summary,
+      };
+    };
+
+    safeRegister({
+      name: 'goal_finish',
+      description: 'Conclude the active goal successfully with a final summary and achievements.',
+      parameters: {
+        type: 'object',
+        properties: {
+          summary: {
+            type: 'string',
+            description: 'Final summary of the goal outcome and deliverables.',
+          },
+        },
+        required: ['summary'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleGoalFinish,
+      handler: handleGoalFinish,
+    });
+  });
+}