agent-planner-mcp 1.5.5 → 1.5.8

package/SKILL.md

@@ -123,7 +123,7 @@ The `update_task` call is atomic — status change, log entry, claim release, an
 
 ```
 1. claim_next_task(scope={ plan_id }, ttl_minutes=30) → exclusive ownership
-2. task_context(task_id, depth=4) periodically to refresh as work progresses
+2. task_context(node_id, depth=4) periodically to refresh as work progresses
 3. update_task(...) for state transitions
 4. release_task(task_id, message='handoff to teammate') for explicit handoff
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.5.5",
+  "version": "1.5.8",
   "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/beliefs.js

@@ -7,6 +7,21 @@
 
 const { asOf, formatResponse, errorResponse, safeArray, isV1Unavailable, planUrl } = require('./_shared');
 
+// A Graphiti fact is superseded once it has an `expired_at`, or an `invalid_at`
+// that is in the past — the temporal graph has replaced it with a newer truth.
+// recall_knowledge used to return these inline with current facts, undistinguished,
+// so an agent could act on stale knowledge. Tag each fact `status` and sort
+// current-first so the valid facts read first.
+function annotateFacts(facts, nowMs = Date.now()) {
+  const list = safeArray(facts).map((f) => {
+    const invalidMs = f.invalid_at ? new Date(f.invalid_at).getTime() : null;
+    const superseded = Boolean(f.expired_at) || (invalidMs != null && invalidMs <= nowMs);
+    return { ...f, status: superseded ? 'superseded' : 'current' };
+  });
+  list.sort((a, b) => (a.status === b.status ? 0 : a.status === 'current' ? -1 : 1));
+  return list;
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 // briefing — bundled mission control state. Replaces 4 round trips.
 // ─────────────────────────────────────────────────────────────────────────
@@ -197,18 +212,26 @@ const taskContextDefinition = {
   inputSchema: {
     type: 'object',
     properties: {
-      task_id: { type: 'string' },
+      // `node_id` is the canonical name (matches every other tool + the skill
+      // docs). `task_id` is kept as an accepted alias for back-compat.
+      node_id: { type: 'string', description: 'The task/node id to load context for.' },
+      task_id: { type: 'string', description: 'Alias for node_id (back-compat).' },
       depth: { type: 'integer', enum: [1, 2, 3, 4], default: 2 },
       token_budget: { type: 'integer', default: 0 },
     },
-    required: ['task_id'],
+    // Neither is strictly required at the schema level because either name is
+    // accepted; the handler validates that one was supplied with a clear error.
   },
 };
 
 async function taskContextHandler(args, apiClient) {
-  const { task_id, depth = 2, token_budget = 0 } = args;
+  const { node_id, task_id, depth = 2, token_budget = 0 } = args;
+  const nodeId = node_id || task_id;
+  if (!nodeId) {
+    return errorResponse('invalid_arg', 'task_context requires node_id (the task/node id).');
+  }
   const params = new URLSearchParams({
-    node_id: task_id,
+    node_id: nodeId,
     depth: String(depth),
     token_budget: String(token_budget),
     log_limit: '10',
@@ -335,6 +358,8 @@ const recallKnowledgeDefinition = {
   description:
     "Universal knowledge graph query. Returns facts, entities, recent episodes, " +
     "and contradictions in one shape. Use result_kind to control payload size. " +
+    "Each fact carries status: 'current' or 'superseded' (the graph has since " +
+    "replaced it) — facts are sorted current-first; prefer current facts. " +
     "Replaces recall_knowledge legacy + find_entities + get_recent_episodes + check_contradictions.",
   inputSchema: {
     type: 'object',
@@ -355,6 +380,9 @@ const recallKnowledgeDefinition = {
 
 async function recallKnowledgeHandler(args, apiClient) {
   const { query, scope = {}, since, entry_type = 'all', result_kind = 'all', max_results = 10, include_contradictions = false } = args;
+  if (!query || !String(query).trim()) {
+    return errorResponse('invalid_arg', 'recall_knowledge requires a non-empty query string');
+  }
 
   // v1 facade: one server-side call replaces the 4-endpoint fan-out below.
   if (apiClient.v1) {
@@ -362,6 +390,11 @@ async function recallKnowledgeHandler(args, apiClient) {
       const data = await apiClient.v1.knowledgeSearch({
         query, since, entry_type, result_kind, max_results, include_contradictions, ...scope,
       });
+      if (data && Array.isArray(data.facts)) {
+        data.facts = annotateFacts(data.facts);
+        const superseded = data.facts.filter((f) => f.status === 'superseded').length;
+        data.meta = { ...(data.meta || {}), superseded_fact_count: superseded };
+      }
       return formatResponse(data);
     } catch (err) {
       if (!isV1Unavailable(err)) {
@@ -399,7 +432,7 @@ async function recallKnowledgeHandler(args, apiClient) {
       return;
     }
     const v = s.value;
-    if (key === 'facts') out.facts = safeArray(v.facts || v);
+    if (key === 'facts') out.facts = annotateFacts(v.facts || v);
     if (key === 'entities') out.entities = safeArray(v.entities || v);
     if (key === 'episodes') {
       let eps = safeArray(v.episodes?.episodes || v.episodes || v);
@@ -415,6 +448,7 @@ async function recallKnowledgeHandler(args, apiClient) {
     if (key === 'contradictions') out.contradictions = v;
   });
 
+  out.meta.superseded_fact_count = out.facts.filter((f) => f.status === 'superseded').length;
   return formatResponse(out);
 }
 
@@ -531,6 +565,9 @@ const searchDefinition = {
 
 async function searchHandler(args, apiClient) {
   const { query, scope = 'global', scope_id, filters = {} } = args;
+  if (!query || !String(query).trim()) {
+    return errorResponse('invalid_arg', 'search requires a non-empty query string');
+  }
   const limit = filters.limit || 20;
   try {
     let result;
@@ -593,8 +630,17 @@ const planAnalysisDefinition = {
   },
 };
 
+const PLAN_ANALYSIS_TYPES = ['impact', 'critical_path', 'bottlenecks', 'coherence'];
+
 async function planAnalysisHandler(args, apiClient) {
   const { plan_id, type, node_id, scenario } = args;
+  // The hosted MCP transport does not enforce `required`, so a missing/unknown
+  // `type` would otherwise fall through every branch and return an empty
+  // `results: {}` with no explanation. Validate explicitly with a clear error.
+  if (!plan_id) return errorResponse('invalid_arg', 'plan_analysis requires plan_id');
+  if (!type || !PLAN_ANALYSIS_TYPES.includes(type)) {
+    return errorResponse('invalid_arg', `plan_analysis requires type (one of: ${PLAN_ANALYSIS_TYPES.join(', ')})`);
+  }
   try {
     let result;
     if (type === 'critical_path') {
@@ -608,7 +654,18 @@ async function planAnalysisHandler(args, apiClient) {
     } else if (type === 'coherence') {
       result = await apiClient.coherence.runCheck(plan_id);
     }
-    return formatResponse({ as_of: asOf(), type, results: result || {} });
+    const payload = { as_of: asOf(), type, results: result || {} };
+    // Critical-path / bottleneck analysis is driven by `blocks` dependency
+    // edges. A flat (edgeless) plan returns empty here — without a hint the
+    // agent can't tell "nothing blocking" from "this plan has no edges at all".
+    const emptyCriticalPath = type === 'critical_path' && !(result?.nodes?.length);
+    const emptyBottlenecks = type === 'bottlenecks'
+      && !((Array.isArray(result) ? result : result?.bottlenecks)?.length);
+    if (emptyCriticalPath || emptyBottlenecks) {
+      payload.note = 'No dependency edges drive this result — the plan may be flat (no blocks edges). '
+        + 'Use task_context (depth 2+) to read its tasks, or add dependencies with link_intentions.';
+    }
+    return formatResponse(payload);
   } catch (err) {
     return errorResponse('upstream_unavailable', `plan_analysis failed: ${err.response?.data?.error || err.message}`);
   }