agent-planner-mcp 1.5.15 → 1.5.19

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?
 
@@ -334,6 +337,26 @@ recall_knowledge({
 - **v0.8.x → v0.9.0** — clean break. 63 legacy CRUD tools collapsed into 15 BDI-aligned tools. See [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping.
 - **v0.9.x → v1.0.0** — additive. v0.9 read/update tools unchanged. Adds the full mutation surface (creation, structural edits, sharing, collaboration) so humans can steer entirely through agent conversation. The previously planned `ap_admin_*` namespace is no longer needed — those operations are now first-class BDI tools, with the draft-status seam keeping autonomous agent creation reviewable. See [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
+## UI vocabulary → data model → tools
+
+The web UI (agentplanner.io) and these tools are the same system in two languages. When a human refers to something they see on a screen, map it here:
+
+| UI term | What it is | Tools |
+|---|---|---|
+| **Workspace** | Org-scoped folder that owns goals + plans | `list_workspaces`, `create_workspace` |
+| **Blueprint** | Dehydrated, reusable plan shape; forks into a workspace | `list_blueprints`, `save_as_blueprint`, `fork_blueprint`, `delete_blueprint` |
+| **Mission / Mission Control** | Home overview: goal health, decision queue, activity | `briefing` |
+| **Goal** (a *Desire*) | What you're pursuing | `create_goal`, `derive_subgoal`, `list_goals`, `goal_state`, `update_goal` |
+| **Plan** (an *Intention*) | Committed plan of action that achieves a goal | `form_intention` (create), `extend_intention` (add nodes), `update_plan`, `update_node`, `move_node` |
+| **Knowledge / episode** (a *Belief*) | Facts the agents have learned | `add_learning`, `recall_knowledge` |
+| **Health** | Per-goal `on_track` / `at_risk` / `stale` | `briefing`, `list_goals`, `goal_state` |
+| **Tension / Contradiction** | A coherence conflict — new knowledge contradicts existing facts or tasks (UI "Tensions" card) | `plan_analysis` (coherence), `recall_knowledge` (current vs superseded facts) |
+| **Decision queue / "Awaiting you"** | Human approvals pending | `queue_decision`, `resolve_decision` |
+| **Committed vs Proposed** | A goal is *committed* once promoted (`promoted_at` set), *proposed* before | `update_goal({ committed })` |
+| **Attainment vs Execution** | *Attainment* = success criteria met; *Execution* = tasks completed. Distinct numbers. | `record_criterion_progress` (attainment), `update_task` (execution) |
+| **Critical path / Bottlenecks** | Longest blocking chain / high-fan-out incomplete tasks | `plan_analysis` |
+| **RPI chain** | Research → Plan → Implement decomposition | `propose_research_chain` |
+
 ## Principles
 
 - Tools are intent-shaped, not CRUD-shaped — name what you want to accomplish, not which row to mutate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.5.15",
+  "version": "1.5.19",
   "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}` : '';

package/src/index.js

@@ -3,6 +3,7 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { MCPHTTPServer } = require('./server-http');
 const { setupTools } = require('./tools');
+const { SERVER_INSTRUCTIONS } = require('./server-instructions');
 const { version } = require('../package.json');
 require('dotenv').config();
 
@@ -77,7 +78,10 @@ async function main() {
       }, {
         capabilities: {
           tools: {}
-        }
+        },
+        // Shown to the model on connect — the no-skill safety net mapping plain
+        // intents to the BDI tool names + pointing at get_started.
+        instructions: SERVER_INSTRUCTIONS
       });
 
       console.error('MCP Server created');

package/src/server-http.js

@@ -15,6 +15,7 @@
 const express = require('express');
 const { SessionManager } = require('./session-manager');
 const { setupTools } = require('./tools');
+const { SERVER_INSTRUCTIONS } = require('./server-instructions');
 const { createApiClient } = require('./api-client');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { createOAuthMetadata, mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } = require('@modelcontextprotocol/sdk/server/auth/router.js');
@@ -522,7 +523,9 @@ class MCPHTTPServer {
     }, {
       capabilities: {
         tools: {}
-      }
+      },
+      // Shown to the model on connect — the no-skill safety net (see index.js).
+      instructions: SERVER_INSTRUCTIONS
     });
 
     // Get per-session API client (bound to user's token), or create one for initialize requests

package/src/server-instructions.js

@@ -0,0 +1,26 @@
+/**
+ * Server-level MCP instructions — surfaced to the model the moment the server
+ * connects, independent of any externally-loaded skill. This is the safety net
+ * for agents that do NOT have the AgentPlanner SKILL.md: it maps plain intents
+ * to the BDI tool names (which were renamed at v0.9, e.g. "create a plan" is
+ * `form_intention`, not `create_plan`) and points to `get_started` for the rest.
+ *
+ * Keep this short — it's read on every connect. Deeper guidance lives in
+ * `get_started` (auto-derived from the live tool set, so it can't drift).
+ */
+const SERVER_INSTRUCTIONS = [
+  'AgentPlanner uses an intent-shaped, BDI-aligned tool vocabulary (renamed at v0.9 — there is no create_plan/quick_plan/create_node/quick_status).',
+  'New here or unsure which tool? Call `get_started` first — it returns the full tool map and recommended workflows.',
+  '',
+  'Common intents → tool:',
+  '- Create a goal → `create_goal` (a sub-goal → `derive_subgoal`)',
+  '- Create a plan with its task tree → `form_intention` (add tasks later → `extend_intention`; an R→P→I chain → `propose_research_chain`)',
+  '- Find and claim the next task → `claim_next_task`',
+  '- Update status / log progress / finish a task → `update_task` (folds the old quick_status + quick_log + add_log + release)',
+  '- Read a goal (details, progress, quality, bottlenecks) → `goal_state`; all goals’ health → `briefing` / `list_goals`',
+  '- Read a task in context → `task_context`; analyze a plan (critical path, bottlenecks, impact, coherence) → `plan_analysis`',
+  '- Record / recall knowledge → `add_learning` / `recall_knowledge`',
+  '- Queue a human decision → `queue_decision`; resolve one → `resolve_decision`',
+].join('\n');
+
+module.exports = { SERVER_INSTRUCTIONS };

package/src/tools/bdi/beliefs.js

@@ -617,7 +617,8 @@ const planAnalysisDefinition = {
   name: 'plan_analysis',
   description:
     "Advanced plan reads: impact analysis (delay/block/remove), critical path, " +
-    "bottleneck list, or coherence check.",
+    "bottleneck list, or coherence check. Replaces the legacy analyze_impact / " +
+    "get_critical_path / run_coherence_check / check_coherence_pending tools.",
   inputSchema: {
     type: 'object',
     properties: {

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/intentions.js

@@ -791,7 +791,10 @@ const formIntentionDefinition = {
   name: 'form_intention',
   description:
     "Create a plan that achieves a goal, including an initial phase/task " +
-    "tree, in one call. Declare execution order inline: give nodes a `ref` and " +
+    "tree, in one call. This is the canonical way to CREATE A PLAN (replaces the " +
+    "legacy quick_plan / create_plan / import_plan_markdown; inline nodes replace " +
+    "create_node / quick_task; depends_on replaces create_dependency). " +
+    "Declare execution order inline: give nodes a `ref` and " +
     "list prerequisite refs/titles in `depends_on` to create 'blocks' edges in " +
     "the same call — don't ship a bare hierarchy. The response returns a " +
     "`structure` summary and warns (`created_without_dependencies`) when a " +
@@ -961,19 +964,22 @@ async function formIntentionHandler(args, apiClient) {
     }
   }
 
-  // 3. Link plan to goal (best-effort).
+  // 3. Create tree (top-level children parent to root via omitted parent_id).
+  const nodeResults = [];
+  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
+  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
+
+  // 4. Link plan to goal (best-effort) — AFTER the tree exists. The link
+  // endpoint cascades 'achieves' edges to all CURRENT task nodes, so linking
+  // before node creation wired zero achievers (goal_state then showed empty
+  // linked_tasks and fell back to coarse linked-plan stats). Order matters.
   try {
     await apiClient.goals.linkPlan(goal_id, plan.id);
   } catch (err) {
     // Non-fatal — plan exists, link can be retried by user.
   }
 
-  // 3. Create tree (top-level children parent to root via omitted parent_id).
-  const nodeResults = [];
-  const ctx = { refMap: new Map(), titleMap: new Map(), edgeIntents: [] };
-  await createSubtree(apiClient, plan.id, null, tree, nodeResults, ctx);
-
-  // 4. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
+  // 5. Wire inline dependency edges. depends_on:[X] on N means X blocks N.
   const resolveRef = (ref) => {
     if (ctx.refMap.has(ref)) return ctx.refMap.get(ref);
     const byTitle = ctx.titleMap.get(ref);

package/src/tools/bdi/utility.js

@@ -8,9 +8,11 @@ const { version: MCP_VERSION } = require('../../../package.json');
 const getStartedDefinition = {
   name: 'get_started',
   description:
-    "Onboarding for new agents. Returns the BDI tool surface map and recommended " +
-    "workflows: mission control loop (Cowork), single-task session (Code/CLI), " +
-    "multi-agent claiming (OpenClaw).",
+    "Call this FIRST when you are new to AgentPlanner or unsure which tool to use " +
+    "(e.g. looking for create_plan / quick_plan — the answer is form_intention). " +
+    "Returns the live BDI tool-surface map and recommended workflows: mission " +
+    "control loop (Cowork), single-task session (Code/CLI), multi-agent claiming " +
+    "(OpenClaw). The map is derived from the actual tool set, so it can't drift.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -29,6 +31,17 @@ async function getStartedHandler(args, apiClient) {
     api = { version: 'unavailable' };
   }
 
+  // Derived from the actual module definitions so this map can't drift from the
+  // real tool set (it silently did — delete_blueprint and record_criterion_progress
+  // were both missing at points). Lazy require avoids any load-order cycle.
+  const namesOf = (mod) => (mod.definitions || []).map((d) => d.name);
+  const toolsByNamespace = {
+    beliefs: namesOf(require('./beliefs')),
+    desires: namesOf(require('./desires')),
+    intentions: namesOf(require('./intentions')),
+    workspaces: namesOf(require('./workspaces')),
+  };
+
   return formatResponse({
     as_of: asOf(),
     mcp_version: MCP_VERSION,
@@ -39,12 +52,7 @@ async function getStartedHandler(args, apiClient) {
       "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'],
-      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', 'delete_blueprint'],
-    },
+    tools_by_namespace: toolsByNamespace,
     recommended_workflows: [
       {
         name: 'Set up new work a human asked for',