agent-planner-mcp 1.5.14 → 1.5.17

package/SKILL.md

@@ -42,6 +42,9 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 - `update_goal` — atomic goal update; subsumes link/unlink + achiever changes
 - `create_goal` — create a new top-level goal (no parent). Agents create goals directly when asked — no UI step. Defaults to `status='active'`.
 - `derive_subgoal` *(v1.0)* — create a sub-goal under an existing parent (use `create_goal` for top-level).
+- `record_criterion_progress` — set the `current` value of a measurable success criterion (by `criterion_id` or 0-based `index`, both shown in `goal_state`). The write that drives goal attainment, e.g. "p99 latency: current 140 → 100".
+
+**Success criteria** (`success_criteria` on create/derive/update) accept either plain strings (qualitative) or structured measurable objects: `{ statement, metric?, target?, current?, unit?, direction: 'increase'|'decrease'|'boolean' }`. A criterion with **metric + target + direction** is *measurable* and counts toward goal attainment (`increase`: current ≥ target, `decrease`: current ≤ target, `boolean`: current truthy). Prefer measurable criteria — "p99 latency < 100ms" beats "make it fast".
 
 ### Intentions — what am I committing to?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.5.14",
+  "version": "1.5.17",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {

package/src/api-client.js

@@ -592,6 +592,11 @@ const goals = {
     return response.data;
   },
 
+  recordCriterionProgress: async (goalId, body) => {
+    const response = await apiClient.post(`/goals/${goalId}/criteria/progress`, body);
+    return response.data;
+  },
+
   // v2 goal-dependency endpoints
   getPath: async (goalId, maxDepth) => {
     const params = maxDepth ? `?max_depth=${maxDepth}` : '';
@@ -1087,6 +1092,12 @@ function createApiClient(token, options = {}) {
 // Export the axios instance for direct use
 const axiosInstance = apiClient;
 
+// ─── System ───────────────────────────────────────────────────
+// Operational metadata about the backend the MCP is talking to.
+const system = {
+  version: () => apiClient.get('/version').then(r => r.data),
+};
+
 // ─── Coherence ────────────────────────────────────────────────
 const coherence = {
   getPending: () => apiClient.get('/coherence/pending').then(r => r.data),
@@ -1112,6 +1123,7 @@ module.exports = {
   coherence,
   users,
   agentLoop,
+  system,
   v1,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)

package/src/tools/bdi/desires.js

@@ -9,6 +9,35 @@
 
 const { asOf, formatResponse, errorResponse, safeArray, apiErrorMessage } = require('./_shared');
 
+// Success criteria accept plain strings (qualitative) or structured measurable
+// units. A criterion with metric+target+direction becomes "measurable" and
+// drives goal attainment (see the backend's goalCriteria.normalizeCriteria,
+// which also maps legacy string[] / {criteria:[]} shapes onto this).
+const SUCCESS_CRITERIA_SCHEMA = {
+  type: 'array',
+  description:
+    "Each entry is a plain string (qualitative) OR a structured object " +
+    "{ statement, metric?, target?, current?, unit?, direction: 'increase'|'decrease'|'boolean' }. " +
+    "Give a criterion metric+target+direction to make it measurable so it counts toward goal attainment.",
+  items: {
+    oneOf: [
+      { type: 'string' },
+      {
+        type: 'object',
+        required: ['statement'],
+        properties: {
+          statement: { type: 'string', description: 'Human-readable condition.' },
+          metric: { type: 'string', description: 'What is measured, e.g. "p99 latency".' },
+          target: { description: 'Goal value (number or string).' },
+          current: { description: 'Latest observed value (number or string).' },
+          unit: { type: 'string', description: 'e.g. "ms", "%", "customers".' },
+          direction: { type: 'string', enum: ['increase', 'decrease', 'boolean'] },
+        },
+      },
+    ],
+  },
+};
+
 const listGoalsDefinition = {
   name: 'list_goals',
   description:
@@ -93,7 +122,7 @@ const updateGoalDefinition = {
           // Commitment: true once the goal is promoted to active execution
           // (replaces the old desire/intention goal_type vocabulary).
           committed: { type: 'boolean' },
-          success_criteria: {},
+          success_criteria: SUCCESS_CRITERIA_SCHEMA,
           add_linked_plans: { type: 'array', items: { type: 'string' } },
           remove_linked_plans: { type: 'array', items: { type: 'string' } },
           add_achievers: { type: 'array', items: { type: 'string' } },
@@ -210,11 +239,7 @@ const deriveSubgoalDefinition = {
         default: 'active',
         description: "Default 'active' for human-directed creation. Pass 'draft' when acting autonomously without explicit user direction.",
       },
-      success_criteria: {
-        type: 'array',
-        items: { type: 'string' },
-        description: "Concrete, observable conditions that mark this sub-goal achieved.",
-      },
+      success_criteria: SUCCESS_CRITERIA_SCHEMA,
       priority: { type: 'integer', default: 0 },
     },
     required: ['parent_goal_id', 'title', 'rationale'],
@@ -301,11 +326,7 @@ const createGoalDefinition = {
         default: 'active',
         description: "Default 'active' (live). Pass 'draft' to propose without activating.",
       },
-      success_criteria: {
-        type: 'array',
-        items: { type: 'string' },
-        description: "Concrete, observable conditions that mark this goal achieved.",
-      },
+      success_criteria: SUCCESS_CRITERIA_SCHEMA,
       priority: { type: 'integer', minimum: 0, maximum: 10, default: 0 },
       workspace_id: { type: 'string', description: "Optional. Target workspace; defaults to the active org's default workspace." },
     },
@@ -342,12 +363,66 @@ async function createGoalHandler(args, apiClient) {
   });
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// record_criterion_progress — set the current value of a measurable criterion.
+// This is the write that makes goal attainment real (metric moved 40→72).
+// ─────────────────────────────────────────────────────────────────────────
+
+const recordCriterionProgressDefinition = {
+  name: 'record_criterion_progress',
+  description:
+    "Record the latest observed value of one of a goal's success criteria " +
+    "(e.g. a metric moved 40→72). Identify the criterion by criterion_id " +
+    "(stable, like 'c0') or its 0-based index — both are visible in goal_state. " +
+    "Only measurable criteria (metric+target+direction) count toward attainment; " +
+    "this is the write that makes goal attainment real.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      goal_id: { type: 'string' },
+      criterion_id: { type: 'string', description: "Stable criterion id (e.g. 'c0'). Use this or index." },
+      index: { type: 'integer', description: '0-based position of the criterion. Alternative to criterion_id.' },
+      current: { description: 'Latest observed value (number or string). Required.' },
+    },
+    required: ['goal_id', 'current'],
+  },
+};
+
+async function recordCriterionProgressHandler(args, apiClient) {
+  const { goal_id, criterion_id, index, current } = args;
+  if (!goal_id) return errorResponse('invalid_arg', 'record_criterion_progress requires goal_id');
+  if (current === undefined) return errorResponse('invalid_arg', 'record_criterion_progress requires current');
+  if (!criterion_id && !Number.isInteger(index)) {
+    return errorResponse('invalid_arg', 'record_criterion_progress requires criterion_id or index');
+  }
+
+  const body = { current };
+  if (criterion_id) body.criterion_id = criterion_id;
+  if (Number.isInteger(index)) body.index = index;
+
+  try {
+    const result = await apiClient.goals.recordCriterionProgress(goal_id, body);
+    return formatResponse({ as_of: asOf(), goal_id, criterion: result.criterion, criteria: result.criteria });
+  } catch (err) {
+    const status = err.response?.status;
+    if (status === 404) return errorResponse('not_found', apiErrorMessage(err));
+    return errorResponse('upstream_unavailable', `record_criterion_progress failed: ${apiErrorMessage(err)}`);
+  }
+}
+
 module.exports = {
-  definitions: [listGoalsDefinition, updateGoalDefinition, createGoalDefinition, deriveSubgoalDefinition],
+  definitions: [
+    listGoalsDefinition,
+    updateGoalDefinition,
+    createGoalDefinition,
+    deriveSubgoalDefinition,
+    recordCriterionProgressDefinition,
+  ],
   handlers: {
     list_goals: listGoalsHandler,
     update_goal: updateGoalHandler,
     create_goal: createGoalHandler,
     derive_subgoal: deriveSubgoalHandler,
+    record_criterion_progress: recordCriterionProgressHandler,
   },
 };

package/src/tools/bdi/utility.js

@@ -19,19 +19,31 @@ const getStartedDefinition = {
   },
 };
 
-async function getStartedHandler(args) {
+async function getStartedHandler(args, apiClient) {
+  // Best-effort backend version so one call shows which builds are in play
+  // (the MCP and the API it is actually talking to are deployed separately).
+  let api = { version: 'unavailable' };
+  try {
+    if (apiClient?.system?.version) api = await apiClient.system.version();
+  } catch {
+    api = { version: 'unavailable' };
+  }
+
   return formatResponse({
     as_of: asOf(),
     mcp_version: MCP_VERSION,
+    api_url: process.env.API_URL || 'http://localhost:3000',
+    api_version: api.version,
+    api_build: api.commit ? { commit: api.commit, started_at: api.started_at } : undefined,
     overview:
       "AgentPlanner exposes a BDI-aligned MCP surface. Tools are grouped by " +
       "Beliefs (state queries), Desires (goals), and Intentions (committed actions). " +
       "Each tool answers one whole agentic question and returns an `as_of` timestamp.",
     tools_by_namespace: {
       beliefs: ['briefing', 'list_plans', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
-      desires: ['list_goals', 'create_goal', 'update_goal', 'derive_subgoal'],
+      desires: ['list_goals', 'create_goal', 'update_goal', 'derive_subgoal', 'record_criterion_progress'],
       intentions: ['form_intention', 'extend_intention', 'link_intentions', 'propose_research_chain', 'claim_next_task', 'update_task', 'update_node', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
-      workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint'],
+      workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint', 'delete_blueprint'],
     },
     recommended_workflows: [
       {