agent-planner-mcp 1.4.0 → 1.5.0

package/AGENT_GUIDE.md

@@ -42,13 +42,14 @@ get_started()
 ### Intentions — creation (v1.0)
 | Tool | When |
 |---|---|
-| `form_intention` | Create plan + initial tree under a goal, atomically |
+| `form_intention` | Create plan + initial tree under a goal, atomically. Declare order inline with `ref`/`depends_on` (→ `blocks` edges); warns `created_without_dependencies` |
 | `extend_intention` | Add children under existing parent (lightweight, no queue) |
 | `propose_research_chain` | RPI triple with 2 blocking edges in one call |
 
 ### Intentions — structural mutation (v1.0)
 | Tool | When |
 |---|---|
+| `list_plans` | List plans (filter by status / visibility / workspace) |
 | `update_plan` | Edit plan title/description/status/visibility/metadata |
 | `update_node` | Edit any node property except status |
 | `move_node` | Reparent within plan; cycle-safe |
@@ -148,9 +149,9 @@ Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue
 ## Atomic patterns to remember
 
 - `update_task` does status + log + claim release + learning in one call. Don't decompose.
-- `claim_next_task` does suggest + claim + context. Don't decompose.
+- `claim_next_task` does suggest + claim + context. Don't decompose. Fails closed — an empty result is structured: `reason: no_work_in_scope` (nothing left) vs `blocked_on_dep` (work remains but all of it is dependency-blocked). Don't treat empty as "done" without checking `reason`.
 - `briefing` does goals + decisions + tasks + activity + recommendation. Don't decompose.
-- `form_intention` creates plan + tree atomically. Don't trickle node-by-node.
+- `form_intention` creates plan + tree atomically — and declares execution order inline via `ref`/`depends_on` (don't ship a bare hierarchy with no edges). Don't trickle node-by-node.
 - `share_plan` does visibility + add + remove in one call. Don't fan out.
 
 ## Output discipline

package/SKILL.md

@@ -54,11 +54,12 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 - `add_learning` — record a knowledge episode for future recall
 
 **Creation (v1.0):**
-- `form_intention` — create a plan + initial phase/task tree under a goal, atomically
+- `form_intention` — create a plan + initial phase/task tree under a goal, atomically. **Declare execution order inline:** give nodes a `ref` and list prerequisites in `depends_on` (refs or titles) to create `blocks` edges in the same call. Returns a `structure` summary and warns `created_without_dependencies` when a multi-task plan has no edges — don't ship a bare hierarchy with no executable ordering. Every plan it creates is provenance-stamped (`created_by: agent-planner-mcp@<version>`) for version-drift diagnosis.
 - `extend_intention` — add children under an existing phase or task (lightweight, no decision-queue gate)
 - `propose_research_chain` — Research → Plan → Implement triple with two blocking edges, in one call
 
 **Structural mutation (v1.0):**
+- `list_plans` — list plans (filter by status / visibility / workspace)
 - `update_plan` — edit any plan property (title, description, status, visibility, metadata)
 - `update_node` — edit any node property except status (status routes through `update_task`)
 - `move_node` — reparent within the same plan; cycle-safe
@@ -85,7 +86,7 @@ A Workspace is a folder under an Organization that owns goals + plans — a grou
 
 ### Utility
 
-- `get_started` — dynamic reference; call this if you're new to AgentPlanner
+- `get_started` — dynamic reference; call this if you're new to AgentPlanner. Reports `mcp_version` so you can self-report your build (diagnose version drift across OpenClaw / Claude Code / local checkouts).
 
 ## Canonical workflows
 
@@ -138,6 +139,8 @@ claim_next_task({ scope: { plan_id }, dry_run: true })
 claim_next_task({ scope: { plan_id } })  // dry_run defaults to false
 ```
 
+**Fails closed.** When nothing is claimable, `claim_next_task` never hands back a dependency-blind task — it returns a structured no-work result whose `reason` distinguishes `no_work_in_scope` (nothing left to do) from `blocked_on_dep` (work remains, but every remaining task is blocked on an incomplete dependency). Check `reason` before treating an empty result as "done."
+
 ### Proposing subtasks for human approval (v0.9.1+)
 
 For high-touch proposals (entire new directions, structural changes the human should review before they materialize), use `queue_decision` with `proposed_subtasks` — tasks only get created on `resolve_decision({action: 'approve'})`.
@@ -176,11 +179,17 @@ form_intention({
   title: 'Ship new auth flow',
   rationale: 'User-requested plan to migrate auth to passkeys',
   tree: [
-    { node_type: 'phase', title: 'Discovery', children: [...] },
-    { node_type: 'phase', title: 'Implementation', children: [...] },
+    { node_type: 'phase', title: 'Discovery', children: [
+      { ref: 'research', title: 'Research passkey libraries', task_mode: 'research' },
+    ]},
+    { node_type: 'phase', title: 'Implementation', children: [
+      { title: 'Implement passkey flow', task_mode: 'implement', depends_on: ['research'] },
+    ]},
   ]
 })
-// Plan lands as active. No approval needed — user already approved by asking.
+// Active, with a `blocks` edge (research → implement) created inline from depends_on.
+// Response carries a `structure` summary; a multi-task plan with zero edges would
+// return created_without_dependencies + a warning instead.
 ```
 
 ```

package/package.json

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

package/src/tools/bdi/intentions.js

@@ -14,6 +14,11 @@
  */
 
 const { asOf, formatResponse, errorResponse, isV1Unavailable } = require('./_shared');
+const { version: PKG_VERSION } = require('../../../package.json');
+
+// Provenance tag stamped onto every plan this server creates, so a plan stays
+// debuggable later even if this MCP build is stale relative to the API.
+const CLIENT_TAG = `agent-planner-mcp@${PKG_VERSION}`;
 
 // ─────────────────────────────────────────────────────────────────────────
 // queue_decision — real decision queue. Replaces add_learning workaround.
@@ -482,8 +487,8 @@ async function claimNextTaskHandler(args, apiClient) {
   if (!fresh) {
     try {
       const myTasks = await apiClient.users.getMyTasks({ plan_id });
-      const tasks = (myTasks.tasks || myTasks || []).filter((t) => t.status === 'in_progress');
-      if (plan_id) tasks.filter((t) => t.plan_id === plan_id);
+      let tasks = (myTasks.tasks || myTasks || []).filter((t) => t.status === 'in_progress');
+      if (plan_id) tasks = tasks.filter((t) => t.plan_id === plan_id);
       if (tasks[0]) {
         chosen = tasks[0];
         source = 'resume_in_progress';
@@ -491,20 +496,49 @@ async function claimNextTaskHandler(args, apiClient) {
     } catch {}
   }
 
-  // 2. suggest_next_tasks
+  // 2. Dependency-aware suggestion via /context/suggest — the real endpoint
+  //    (only ready, unclaimed tasks, in plan order). Track reachability so we
+  //    can fail closed below: an empty result from a reachable endpoint means
+  //    remaining work is dep-blocked, NOT "grab any not_started task".
+  let suggestReachable = false;
   if (!chosen && plan_id) {
     try {
       const params = new URLSearchParams({ plan_id, limit: '1' });
-      const r = await apiClient.axiosInstance.get(`/plans/${plan_id}/suggest-next-tasks?${params}`);
-      const suggested = (r.data?.tasks || r.data || [])[0];
+      const r = await apiClient.axiosInstance.get(`/context/suggest?${params}`);
+      suggestReachable = true;
+      const suggested = (r.data?.suggestions || r.data?.tasks || r.data || [])[0];
       if (suggested) {
         chosen = suggested;
         source = 'suggest_next_tasks';
       }
+    } catch {
+      // Endpoint unreachable (pre-suggest self-hosted API). Leave
+      // suggestReachable=false so the last-resort blind pick can run.
+    }
+  }
+
+  // 3. Fail-closed gate. When the dependency-aware endpoint is reachable but
+  //    returned nothing, all remaining not_started work is blocked on
+  //    incomplete dependencies — mirror the backend and refuse to hand out a
+  //    dep-blind task. Only the truly-unreachable case falls through to (4).
+  if (!chosen && plan_id && suggestReachable) {
+    let hasNotStarted = false;
+    try {
+      const myTasks = await apiClient.users.getMyTasks({ plan_id });
+      hasNotStarted = (myTasks.tasks || myTasks || []).some((t) => t.status === 'not_started');
     } catch {}
+    return errorResponse(
+      'not_found',
+      hasNotStarted
+        ? 'All remaining tasks are blocked on incomplete dependencies'
+        : 'No actionable task found in scope',
+      { reason: hasNotStarted ? 'blocked_on_dep' : 'no_work_in_scope' },
+    );
   }
 
-  // 3. my_tasks fallback (first not_started)
+  // 4. Last-resort blind fallback — ONLY when the dep-aware endpoint could not
+  //    be reached at all (ancient self-hosted API with neither work-sessions
+  //    nor /context/suggest). Against any current backend this never runs.
   if (!chosen) {
     try {
       const myTasks = await apiClient.users.getMyTasks({ plan_id });
@@ -708,10 +742,14 @@ const formIntentionDefinition = {
   name: 'form_intention',
   description:
     "Create a plan that achieves a goal, including an initial phase/task " +
-    "tree, in one call. Defaults to status='active' for human-directed " +
-    "creation; pass status='draft' for autonomous loops so a human can " +
-    "review before promotion. Drafts surface in the dashboard pending " +
-    "queue and auto-promote to active when work begins on any node.",
+    "tree, in one call. 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 " +
+    "multi-task plan has no edges. Defaults to status='active' for " +
+    "human-directed creation; pass status='draft' for autonomous loops so a " +
+    "human can review before promotion. Drafts surface in the dashboard " +
+    "pending queue and auto-promote to active when work begins on any node.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -740,6 +778,12 @@ const formIntentionDefinition = {
             description: { type: 'string' },
             task_mode: { type: 'string', enum: VALID_TASK_MODES, default: 'free' },
             agent_instructions: { type: 'string' },
+            ref: { type: 'string', description: "Optional stable key so other nodes can reference this one in depends_on. Falls back to title if omitted." },
+            depends_on: {
+              type: 'array',
+              items: { type: 'string' },
+              description: "Refs (or titles) of nodes that must complete before this one. Creates a 'blocks' edge from each prerequisite to this node.",
+            },
             children: { type: 'array' },
           },
           required: ['title'],
@@ -750,7 +794,10 @@ const formIntentionDefinition = {
   },
 };
 
-async function createSubtree(apiClient, planId, parentId, children, results) {
+// `ctx` (optional) collects ref/title → id maps and depends_on intents so the
+// caller can wire dependency edges after the whole tree exists. Omitted by
+// callers that don't support inline deps (e.g. extend_intention).
+async function createSubtree(apiClient, planId, parentId, children, results, ctx = null) {
   for (const child of children || []) {
     let createdNode;
     try {
@@ -772,8 +819,18 @@ async function createSubtree(apiClient, planId, parentId, children, results) {
       continue;
     }
 
+    if (ctx && createdNode?.id) {
+      if (child.ref) ctx.refMap.set(String(child.ref), createdNode.id);
+      const list = ctx.titleMap.get(child.title) || [];
+      list.push(createdNode.id);
+      ctx.titleMap.set(child.title, list);
+      if (Array.isArray(child.depends_on) && child.depends_on.length) {
+        ctx.edgeIntents.push({ dependsOn: child.depends_on.map(String), targetId: createdNode.id });
+      }
+    }
+
     if (child.children?.length && createdNode?.id) {
-      await createSubtree(apiClient, planId, createdNode.id, child.children, results);
+      await createSubtree(apiClient, planId, createdNode.id, child.children, results, ctx);
     }
   }
 }
@@ -795,6 +852,7 @@ async function formIntentionHandler(args, apiClient) {
         status,
         visibility,
         tree,
+        client_version: CLIENT_TAG,
       });
       return formatResponse({
         ...result,
@@ -837,6 +895,7 @@ async function formIntentionHandler(args, apiClient) {
       title,
       description: composedDescription,
       status,
+      metadata: { created_by: CLIENT_TAG },
     });
   } catch (err) {
     return errorResponse('create_failed', `Failed to create plan: ${err.response?.data?.error || err.message}`);
@@ -860,9 +919,48 @@ async function formIntentionHandler(args, apiClient) {
 
   // 3. Create tree (top-level children parent to root via omitted parent_id).
   const nodeResults = [];
-  await createSubtree(apiClient, plan.id, null, tree, 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.
+  const resolveRef = (ref) => {
+    if (ctx.refMap.has(ref)) return ctx.refMap.get(ref);
+    const byTitle = ctx.titleMap.get(ref);
+    return byTitle && byTitle.length === 1 ? byTitle[0] : null;
+  };
+  const dependencyWarnings = [];
+  let dependencyEdges = 0;
+  for (const intent of ctx.edgeIntents) {
+    for (const ref of intent.dependsOn) {
+      const sourceId = resolveRef(ref);
+      if (!sourceId || sourceId === intent.targetId) {
+        dependencyWarnings.push(`Unresolved, ambiguous, or self depends_on reference "${ref}"`);
+        continue;
+      }
+      try {
+        await apiClient.axiosInstance.post('/dependencies', {
+          source_node_id: sourceId,
+          target_node_id: intent.targetId,
+          dependency_type: 'blocks',
+        });
+        dependencyEdges += 1;
+      } catch (err) {
+        dependencyWarnings.push(`Edge ${ref}→task rejected: ${err.response?.data?.error || err.message}`);
+      }
+    }
+  }
 
-  return formatResponse({
+  const taskCount = nodeResults.filter((n) => n.id && (n.node_type === 'task' || n.node_type === 'milestone')).length;
+  const createdWithoutDependencies = taskCount >= 2 && dependencyEdges === 0;
+  const structure = {
+    task_count: taskCount,
+    dependency_edges: dependencyEdges,
+    created_without_dependencies: createdWithoutDependencies,
+    created_by: CLIENT_TAG,
+  };
+  if (dependencyWarnings.length) structure.dependency_warnings = dependencyWarnings;
+
+  const response = {
     as_of: asOf(),
     plan_id: plan.id,
     goal_id,
@@ -871,10 +969,18 @@ async function formIntentionHandler(args, apiClient) {
     nodes_created: nodeResults.filter((n) => n.id).length,
     node_failures: nodeResults.filter((n) => n.error),
     nodes: nodeResults,
+    structure,
     next_step: plan.status === 'draft'
       ? "Plan created as draft. Will surface in dashboard pending for human review. Auto-promotes to active when first task moves to in_progress."
       : "Plan active. Claim a task with claim_next_task({plan_id}) to begin work.",
-  });
+  };
+  if (createdWithoutDependencies) {
+    response.warning =
+      `Plan has ${taskCount} tasks but no dependency edges — execution order is implicit only.`;
+    response.next_required_action =
+      'Call link_intentions to add blocking edges, or confirm the tasks are order-independent.';
+  }
+  return formatResponse(response);
 }
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/tools/bdi/utility.js

@@ -3,6 +3,7 @@
  */
 
 const { asOf, formatResponse } = require('./_shared');
+const { version: MCP_VERSION } = require('../../../package.json');
 
 const getStartedDefinition = {
   name: 'get_started',
@@ -21,6 +22,7 @@ const getStartedDefinition = {
 async function getStartedHandler(args) {
   return formatResponse({
     as_of: asOf(),
+    mcp_version: MCP_VERSION,
     overview:
       "AgentPlanner exposes a BDI-aligned MCP surface. Tools are grouped by " +
       "Beliefs (state queries), Desires (goals), and Intentions (committed actions). " +