agent-planner-mcp 0.8.1 → 0.9.0

package/src/tools/bdi/intentions.js

@@ -0,0 +1,532 @@
+/**
+ * BDI intentions — committed actions.
+ *
+ * v0.9.0 ships queue_decision, resolve_decision, and update_task first.
+ * Other intention tools (claim_next_task, release_task, add_learning) land in
+ * subsequent passes.
+ */
+
+const { asOf, formatResponse, errorResponse } = require('./_shared');
+
+// ─────────────────────────────────────────────────────────────────────────
+// queue_decision — real decision queue. Replaces add_learning workaround.
+// ─────────────────────────────────────────────────────────────────────────
+
+const queueDecisionDefinition = {
+  name: 'queue_decision',
+  description:
+    "Queue a decision for human review. Writes to the real decisions table " +
+    "(not the knowledge graph). Replaces the autopilot pattern of calling " +
+    "add_learning with entry_type=decision and a 'DECISION NEEDED:' title prefix. " +
+    "Resolves via resolve_decision.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      plan_id: {
+        type: 'string',
+        description: "Plan that owns this decision. Required if node_id is not provided.",
+      },
+      node_id: {
+        type: 'string',
+        description: "Task that prompted the decision. If provided, plan_id is inferred.",
+      },
+      title: { type: 'string', description: 'User-facing decision title' },
+      context: { type: 'string', description: 'Background — why this matters, what is at stake' },
+      options: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            label: { type: 'string' },
+            description: { type: 'string' },
+          },
+          required: ['label'],
+        },
+        description: 'Concrete options to choose between',
+      },
+      recommendation: {
+        type: 'string',
+        description: 'Agent\'s preferred option with one-line reasoning',
+      },
+      smallest_input_needed: {
+        type: 'string',
+        description: "Explicit ask for human, e.g. 'approve|defer'",
+      },
+      urgency: {
+        type: 'string',
+        enum: ['low', 'normal', 'high'],
+        default: 'normal',
+      },
+      goal_id: { type: 'string', description: 'Optional goal this decision serves' },
+    },
+    required: ['title', 'context', 'smallest_input_needed'],
+  },
+};
+
+async function queueDecisionHandler(args, apiClient) {
+  const { plan_id, node_id, title, context, options, recommendation, smallest_input_needed, urgency, goal_id } = args;
+
+  let planId = plan_id;
+  if (!planId && node_id) {
+    try {
+      const node = await apiClient.axiosInstance.get(`/nodes/${node_id}`).then((r) => r.data);
+      planId = node.plan_id || node.planId;
+    } catch (err) {
+      return errorResponse('not_found', `Could not resolve plan_id from node_id ${node_id}: ${err.message}`);
+    }
+  }
+  if (!planId) {
+    return errorResponse('invalid_arg', 'queue_decision requires either plan_id or node_id');
+  }
+
+  const body = {
+    title,
+    context,
+    options: options || [],
+    recommendation: recommendation || null,
+    urgency: urgency || 'normal',
+    metadata: { smallest_input_needed, goal_id: goal_id || null, source: 'bdi.queue_decision' },
+  };
+  if (node_id) body.node_id = node_id;
+
+  try {
+    const created = await apiClient.axiosInstance
+      .post(`/plans/${planId}/decisions`, body)
+      .then((r) => r.data);
+    return formatResponse({
+      as_of: asOf(),
+      decision_id: created.id,
+      plan_id: planId,
+      node_id: node_id || null,
+      status: created.status || 'pending',
+      title: created.title,
+    });
+  } catch (err) {
+    return errorResponse(
+      'upstream_unavailable',
+      `Failed to queue decision: ${err.response?.data?.error || err.message}`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// resolve_decision — mark a queued decision as approved/deferred/rejected.
+// ─────────────────────────────────────────────────────────────────────────
+
+const resolveDecisionDefinition = {
+  name: 'resolve_decision',
+  description:
+    "Resolve a pending decision. action is 'approve', 'defer', or 'reject'. " +
+    "Use this from Cowork artifact buttons or after a human responds in chat.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      decision_id: { type: 'string' },
+      plan_id: {
+        type: 'string',
+        description: 'Plan that owns the decision (required by API path)',
+      },
+      action: {
+        type: 'string',
+        enum: ['approve', 'defer', 'reject'],
+      },
+      message: { type: 'string', description: 'Optional resolution note' },
+      selected_option: {
+        type: 'string',
+        description: 'When the decision presented options, which was chosen',
+      },
+    },
+    required: ['decision_id', 'plan_id', 'action'],
+  },
+};
+
+async function resolveDecisionHandler(args, apiClient) {
+  const { decision_id, plan_id, action, message, selected_option } = args;
+  try {
+    const resolved = await apiClient.axiosInstance
+      .post(`/plans/${plan_id}/decisions/${decision_id}/resolve`, {
+        resolution: action,
+        message: message || null,
+        selected_option: selected_option || null,
+      })
+      .then((r) => r.data);
+    return formatResponse({
+      as_of: asOf(),
+      decision_id,
+      plan_id,
+      status: resolved.status || action,
+      resolved_at: resolved.resolved_at || asOf(),
+      message: resolved.message || message || null,
+    });
+  } catch (err) {
+    return errorResponse(
+      'upstream_unavailable',
+      `Failed to resolve decision: ${err.response?.data?.error || err.message}`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// update_task — atomic state transition. Replaces 3 calls.
+// ─────────────────────────────────────────────────────────────────────────
+
+const STATUS_TO_LOG_TYPE = {
+  blocked: 'challenge',
+  completed: 'progress',
+  in_progress: 'progress',
+  not_started: 'progress',
+  plan_ready: 'progress',
+};
+
+const updateTaskDefinition = {
+  name: 'update_task',
+  description:
+    "Atomic task state transition. Updates status, optionally appends a log " +
+    "entry, optionally releases the claim. Idempotent on identical inputs. " +
+    "Replaces quick_status + add_log + release_task fan-out.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string' },
+      plan_id: {
+        type: 'string',
+        description: 'Plan that owns the task (auto-resolved from task if omitted)',
+      },
+      status: {
+        type: 'string',
+        enum: ['not_started', 'in_progress', 'completed', 'blocked', 'plan_ready'],
+      },
+      log_message: { type: 'string', description: 'Optional progress note' },
+      log_type: {
+        type: 'string',
+        enum: ['progress', 'decision', 'blocker', 'completion', 'challenge'],
+        description: "Defaults from status: blocked→challenge, others→progress.",
+      },
+      release_claim: {
+        type: 'boolean',
+        description: "Default: auto (true if status is completed/blocked). Set explicitly to override.",
+      },
+      add_learning: {
+        type: 'string',
+        description: 'Optional: also write a knowledge episode (recommended on completion)',
+      },
+    },
+    required: ['task_id'],
+  },
+};
+
+async function updateTaskHandler(args, apiClient) {
+  const { task_id, status, log_message, add_learning, release_claim } = args;
+  let planId = args.plan_id;
+
+  // Resolve plan_id from task if not provided.
+  if (!planId) {
+    try {
+      const node = await apiClient.axiosInstance.get(`/nodes/${task_id}`).then((r) => r.data);
+      planId = node.plan_id || node.planId;
+    } catch (err) {
+      return errorResponse('not_found', `Could not resolve plan_id from task ${task_id}: ${err.message}`);
+    }
+  }
+
+  const result = {
+    as_of: asOf(),
+    task_id,
+    plan_id: planId,
+    applied: { status_changed: false, log_added: false, claim_released: false, learning_recorded: false },
+    failures: [],
+  };
+
+  // 1. Status update
+  if (status) {
+    try {
+      await apiClient.nodes.updateNode(planId, task_id, { status });
+      result.applied.status_changed = true;
+      result.status = status;
+    } catch (err) {
+      result.failures.push({ step: 'update_status', error: err.response?.data?.error || err.message });
+    }
+  }
+
+  // 2. Log entry
+  if (log_message) {
+    const logType = args.log_type || STATUS_TO_LOG_TYPE[status] || 'progress';
+    try {
+      const log = await apiClient.logs.addLog(planId, task_id, {
+        content: log_message,
+        log_type: logType,
+      });
+      result.applied.log_added = true;
+      result.log_id = log?.id || log?.log?.id;
+    } catch (err) {
+      result.failures.push({ step: 'add_log', error: err.response?.data?.error || err.message });
+    }
+  }
+
+  // 3. Claim release — auto if status is terminal, explicit override otherwise.
+  const shouldRelease =
+    typeof release_claim === 'boolean'
+      ? release_claim
+      : status === 'completed' || status === 'blocked';
+  if (shouldRelease) {
+    try {
+      await apiClient.axiosInstance.delete(`/nodes/${task_id}/claim`);
+      result.applied.claim_released = true;
+    } catch (err) {
+      // Releasing an unclaimed task is not a hard error — just record it.
+      result.failures.push({ step: 'release_claim', error: err.response?.data?.error || err.message });
+    }
+  }
+
+  // 4. Optional learning write to knowledge graph.
+  if (add_learning) {
+    try {
+      await apiClient.graphiti.addEpisode({
+        name: `Task: ${task_id}`,
+        content: add_learning,
+        source: 'task_update',
+        plan_id: planId,
+        node_id: task_id,
+      });
+      result.applied.learning_recorded = true;
+    } catch (err) {
+      result.failures.push({ step: 'add_learning', error: err.response?.data?.error || err.message });
+    }
+  }
+
+  return formatResponse(result);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// claim_next_task — bundle suggest + claim + load context.
+// ─────────────────────────────────────────────────────────────────────────
+
+const claimNextTaskDefinition = {
+  name: 'claim_next_task',
+  description:
+    "Pick the next task in scope, claim it, and return its context — all in " +
+    "one call. Resolution order: (1) resume any in_progress task, (2) suggest_next_tasks, " +
+    "(3) my_tasks fallback. Pass fresh:true to skip the resume step.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      scope: {
+        type: 'object',
+        properties: {
+          plan_id: { type: 'string' },
+          goal_id: { type: 'string' },
+        },
+      },
+      ttl_minutes: { type: 'integer', default: 30 },
+      fresh: { type: 'boolean', default: false },
+      context_depth: { type: 'integer', enum: [1, 2, 3, 4], default: 2 },
+    },
+    required: ['scope'],
+  },
+};
+
+async function claimNextTaskHandler(args, apiClient) {
+  const { scope = {}, ttl_minutes = 30, fresh = false, context_depth = 2 } = args;
+  const { plan_id, goal_id } = scope;
+
+  let chosen = null;
+  let source = null;
+
+  // 1. Resume in-progress (unless fresh)
+  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);
+      if (tasks[0]) {
+        chosen = tasks[0];
+        source = 'resume_in_progress';
+      }
+    } catch {}
+  }
+
+  // 2. suggest_next_tasks
+  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];
+      if (suggested) {
+        chosen = suggested;
+        source = 'suggest_next_tasks';
+      }
+    } catch {}
+  }
+
+  // 3. my_tasks fallback (first not_started)
+  if (!chosen) {
+    try {
+      const myTasks = await apiClient.users.getMyTasks({ plan_id });
+      const tasks = (myTasks.tasks || myTasks || []).filter((t) => t.status === 'not_started');
+      if (tasks[0]) {
+        chosen = tasks[0];
+        source = 'my_tasks_fallback';
+      }
+    } catch {}
+  }
+
+  if (!chosen) {
+    return errorResponse('not_found', 'No task available in scope');
+  }
+
+  const taskPlanId = chosen.plan_id || plan_id;
+  const taskId = chosen.id;
+
+  // Claim
+  let claim = null;
+  try {
+    claim = await apiClient.nodes.claimTask(taskPlanId, taskId, 'mcp-agent', ttl_minutes);
+  } catch (err) {
+    return errorResponse('claim_collision', `Could not claim task ${taskId}: ${err.response?.data?.error || err.message}`);
+  }
+
+  // Load context
+  let context = null;
+  try {
+    const params = new URLSearchParams({
+      node_id: taskId,
+      depth: String(context_depth),
+      log_limit: '10',
+      include_research: 'true',
+    });
+    const ctxResp = await apiClient.axiosInstance.get(`/context/progressive?${params}`);
+    context = ctxResp.data;
+  } catch (err) {
+    // Best-effort: still return claim with the bare task object
+  }
+
+  return formatResponse({
+    as_of: asOf(),
+    task: context || chosen,
+    plan_id: taskPlanId,
+    source,
+    claim: {
+      claimed_at: claim?.claimed_at || asOf(),
+      expires_at: claim?.expires_at,
+      ttl_minutes,
+    },
+    next_action_hint: chosen.task_mode === 'implement'
+      ? 'Task is implement mode — research and plan outputs are included in context if available'
+      : 'Task ready to start — call update_task with status=in_progress when work begins',
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// release_task — explicit handoff.
+// ─────────────────────────────────────────────────────────────────────────
+
+const releaseTaskDefinition = {
+  name: 'release_task',
+  description: 'Release a claimed task without changing status. Use for explicit handoff or abandonment.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string' },
+      plan_id: { type: 'string', description: 'Auto-resolved from task if omitted' },
+      message: { type: 'string', description: 'Optional log entry on release' },
+    },
+    required: ['task_id'],
+  },
+};
+
+async function releaseTaskHandler(args, apiClient) {
+  const { task_id, message } = args;
+  let planId = args.plan_id;
+  if (!planId) {
+    try {
+      const node = await apiClient.axiosInstance.get(`/nodes/${task_id}`).then((r) => r.data);
+      planId = node.plan_id || node.planId;
+    } catch (err) {
+      return errorResponse('not_found', `Could not resolve plan_id from task ${task_id}: ${err.message}`);
+    }
+  }
+  try {
+    await apiClient.nodes.releaseTask(planId, task_id, 'mcp-agent');
+  } catch (err) {
+    return errorResponse('upstream_unavailable', `release failed: ${err.message}`);
+  }
+  let logId = null;
+  if (message) {
+    try {
+      const log = await apiClient.logs.addLog(planId, task_id, { content: message, log_type: 'progress' });
+      logId = log?.id || log?.log?.id;
+    } catch {}
+  }
+  return formatResponse({ as_of: asOf(), task_id, plan_id: planId, released: true, log_id: logId });
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// add_learning — knowledge graph write.
+// ─────────────────────────────────────────────────────────────────────────
+
+const addLearningDefinition = {
+  name: 'add_learning',
+  description:
+    "Record a knowledge episode. Use after research, on decisions, or when discovering " +
+    "important context. Graphiti extracts entities/relationships automatically. " +
+    "Surfaces coherence_warnings if the new content contradicts existing facts.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      content: { type: 'string' },
+      scope: {
+        type: 'object',
+        properties: { plan_id: { type: 'string' }, goal_id: { type: 'string' }, node_id: { type: 'string' } },
+      },
+      entry_type: {
+        type: 'string',
+        enum: ['fact', 'decision', 'pattern', 'constraint', 'technique', 'learning'],
+        default: 'fact',
+      },
+      source_description: { type: 'string' },
+    },
+    required: ['content'],
+  },
+};
+
+async function addLearningHandler(args, apiClient) {
+  const { content, scope = {}, entry_type = 'fact', source_description } = args;
+  try {
+    const result = await apiClient.graphiti.addEpisode({
+      content,
+      name: content.slice(0, 80),
+      source: 'text',
+      source_description: source_description || 'BDI add_learning',
+      plan_id: scope.plan_id,
+      node_id: scope.node_id,
+      entity_type: entry_type,
+    });
+    return formatResponse({
+      as_of: asOf(),
+      episode_id: result.episode?.uuid || result.uuid || null,
+      coherence_warnings: result.coherence_warnings || [],
+      message: result.message || 'Knowledge recorded',
+    });
+  } catch (err) {
+    return errorResponse('upstream_unavailable', `add_learning failed: ${err.response?.data?.error || err.message}`);
+  }
+}
+
+module.exports = {
+  definitions: [
+    queueDecisionDefinition,
+    resolveDecisionDefinition,
+    updateTaskDefinition,
+    claimNextTaskDefinition,
+    releaseTaskDefinition,
+    addLearningDefinition,
+  ],
+  handlers: {
+    queue_decision: queueDecisionHandler,
+    resolve_decision: resolveDecisionHandler,
+    update_task: updateTaskHandler,
+    claim_next_task: claimNextTaskHandler,
+    release_task: releaseTaskHandler,
+    add_learning: addLearningHandler,
+  },
+};

package/src/tools/bdi/utility.js

@@ -0,0 +1,73 @@
+/**
+ * BDI utility — onboarding.
+ */
+
+const { asOf, formatResponse } = require('./_shared');
+
+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).",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      user_role: { type: 'string', enum: ['agent', 'human'], default: 'agent' },
+    },
+  },
+};
+
+async function getStartedHandler(args) {
+  return formatResponse({
+    as_of: asOf(),
+    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', 'task_context', 'goal_state', 'recall_knowledge', 'search', 'plan_analysis'],
+      desires: ['list_goals', 'update_goal'],
+      intentions: ['claim_next_task', 'update_task', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
+    },
+    recommended_workflows: [
+      {
+        name: 'Mission control loop (Cowork autopilot or scheduled task)',
+        steps: [
+          'briefing(scope="mission_control") — single read for full state',
+          'For each at_risk goal: goal_state(goal_id)',
+          'If action is reversible: do it via update_task or update_goal',
+          'If action needs human approval: queue_decision',
+          'Always: add_learning to record what you did and why',
+        ],
+      },
+      {
+        name: 'Single coding session (Claude Code, ap CLI)',
+        steps: [
+          'claim_next_task(scope={plan_id}) — pick + claim + load context',
+          'update_task(task_id, status="in_progress") when work starts',
+          'update_task(task_id, status="completed", log_message=..., add_learning=...) when done',
+        ],
+      },
+      {
+        name: 'Multi-agent server (OpenClaw)',
+        steps: [
+          'claim_next_task with explicit ttl_minutes',
+          'Periodic task_context refresh during long work',
+          'release_task on handoff',
+        ],
+      },
+    ],
+    key_principles: [
+      'Tools are intent-shaped, not CRUD-shaped',
+      'Reads are bundled to minimize round trips',
+      'Writes are atomic where possible (update_task does status+log+release)',
+      'as_of on every response — use for cache freshness',
+    ],
+  });
+}
+
+module.exports = {
+  definitions: [getStartedDefinition],
+  handlers: { get_started: getStartedHandler },
+};