agent-planner-mcp 1.1.1 → 1.4.1

package/AGENT_GUIDE.md

@@ -9,7 +9,7 @@ get_started()
 // → Returns the BDI tool surface map and recommended workflows
 ```
 
-## The 24 tools
+## The 29 tools
 
 ### Beliefs (read state)
 | Tool | When |
@@ -26,7 +26,8 @@ get_started()
 |---|---|
 | `list_goals` | Goal list with health summary |
 | `update_goal` | Atomic goal change (subsumes link/unlink/achievers) |
-| `derive_subgoal` | Propose a sub-goal under an existing parent (top-level goals stay UI-only) |
+| `create_goal` | Create a new top-level goal (no parent) — agents create goals directly when asked |
+| `derive_subgoal` | Create a sub-goal under an existing parent |
 
 ### Intentions — execution
 | Tool | When |
@@ -64,6 +65,17 @@ get_started()
 | `update_member_role` | Owner-only role change |
 | `remove_member` | Owner/admin removes non-owner member |
 
+### Workspaces & Blueprints (v1.1)
+A Workspace is a folder under an Organization that owns goals + plans. A Blueprint is a reusable shape that forks into a workspace as a new plan.
+
+| Tool | When |
+|---|---|
+| `list_workspaces` | List workspaces in an org (default and any user-created folders) |
+| `create_workspace` | Create a new workspace inside an org |
+| `list_blueprints` | List blueprints visible to user (owned + public/unlisted) |
+| `fork_blueprint` | Instantiate a plan-scope blueprint as a new plan in a target workspace |
+| `save_as_blueprint` | Snapshot a live plan as a reusable blueprint (excludes run-state) |
+
 ## status='active' vs status='draft' (v1.0)
 
 The single most important decision when calling a creation tool.
@@ -128,7 +140,8 @@ form_intention({goal_id: <new>, title, rationale, status: 'draft', tree: [...]})
 When in doubt between act and queue:
 - Reversible local action (status, log, learning, edit, decompose) → **act** via `update_task`, `update_node`, `extend_intention`, `add_learning`
 - External cost, public publish, strategy change, customer comm → **queue** via `queue_decision`
-- Whole new direction or sub-goal you weren't asked for → propose as **draft** via `form_intention` / `derive_subgoal` with `status='draft'`
+- A goal a human asked you to set up → just **create** it via `create_goal` (active) — no UI step, no approval gate
+- A whole new direction or sub-goal you weren't asked for → propose as **draft** via `create_goal` / `form_intention` / `derive_subgoal` with `status='draft'`
 
 Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue_decision` is the real tool.
 

package/README.md

@@ -255,7 +255,8 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 ### Desires (goals)
 - `list_goals` — goals with health rollup
 - `update_goal` — atomic goal update (subsumes link/unlink/achievers)
-- `derive_subgoal` *(v1.0)* — propose a sub-goal under an existing parent
+- `create_goal` — create a new top-level goal (no parent)
+- `derive_subgoal` *(v1.0)* — create a sub-goal under an existing parent
 
 ### Intentions — execution
 - `claim_next_task` — pick + claim + load context (one call)

package/SKILL.md

@@ -23,7 +23,7 @@ You have access to the AgentPlanner MCP tools. AgentPlanner is a collaborative p
 > - **Cursor / VS Code:** Add `npx agent-planner-mcp` to your MCP config with env vars `API_URL` and `USER_API_TOKEN`
 > - **ChatGPT:** HTTP endpoint at `https://agentplanner.io/mcp`
 
-## The 24 tools, organized by intent
+## The 29 tools, organized by intent
 
 AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desires (goal management), Intentions (committed actions). Each tool answers one whole agentic question and returns an `as_of` ISO 8601 timestamp. v1.0.0 completes the mutation surface so humans can steer entirely through agent conversation — no UI required for normal operations.
 
@@ -40,7 +40,8 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 
 - `list_goals` — goals with health rollup (`{ on_track, at_risk, stale, total }`)
 - `update_goal` — atomic goal update; subsumes link/unlink + achiever changes
-- `derive_subgoal` *(v1.0)* — propose a sub-goal under an existing parent. Top-level goal creation stays UI-only.
+- `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).
 
 ### Intentions — what am I committing to?
 
@@ -72,6 +73,16 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 - `update_member_role` — owner-only role change within an org
 - `remove_member` — owner/admin can remove non-owner members
 
+**Workspaces and Blueprints (v1.1):**
+
+A Workspace is a folder under an Organization that owns goals + plans — a grouping primitive so a single org isn't a flat soup of unrelated work. A Blueprint is a dehydrated, reusable shape (scope `plan` or `workspace`); forking instantiates it as a new plan inside a target workspace. v1 supports plan-scope only.
+
+- `list_workspaces` — list workspaces in an organization
+- `create_workspace` — create a new folder under an org (auto-slug)
+- `list_blueprints` — list blueprints visible to user (owned + public/unlisted), filterable by scope
+- `fork_blueprint` — instantiate a plan-scope blueprint as a new plan in a target workspace
+- `save_as_blueprint` — snapshot a live plan as a reusable blueprint. Captures structure, agent_instructions, and dependencies; excludes statuses, claims, knowledge episodes, logs, decisions, and agent assignments
+
 ### Utility
 
 - `get_started` — dynamic reference; call this if you're new to AgentPlanner
@@ -250,12 +261,14 @@ When a user expresses intent — "I want to launch a feature", "we need better t
 2. list_goals to check if a similar goal already exists
 3. Use update_goal({ add_linked_plans, add_achievers }) to wire it up
 
-Goal types:
-- desire — aspirational, no firm deadline
-- intention — promoted from desire when execution begins
+Goal commitment (`committed` boolean):
+- committed: false — aspirational, no firm commitment to execute yet
+- committed: true — promoted to active execution
 ```
 
-Promote desire → intention via `update_goal({ promote_to_intention: true })`.
+Commit a goal via `update_goal({ changes: { committed: true } })`. Coherence
+status on tasks reads as plain language: `ok` / `outdated` / `contradicted` /
+`unchecked` (with a `coherence_message`).
 
 ## Decision queueing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "1.1.1",
+  "version": "1.4.1",
   "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

@@ -550,6 +550,7 @@ const goals = {
     const params = new URLSearchParams();
     if (filters.organization_id) params.append('organization_id', filters.organization_id);
     if (filters.status) params.append('status', filters.status);
+    if (filters.workspaceId) params.append('workspace_id', filters.workspaceId);
     const response = await apiClient.get(`/goals?${params.toString()}`);
     return response.data.goals || response.data;
   },
@@ -744,6 +745,40 @@ const graphiti = {
   }
 };
 
+// ─── Workspaces ───────────────────────────────────────────────
+const workspaces = {
+  list: async ({ organizationId, includeArchived = false } = {}) => {
+    const params = new URLSearchParams();
+    if (organizationId) params.append('organization_id', organizationId);
+    if (includeArchived) params.append('include_archived', 'true');
+    return (await apiClient.get(`/workspaces?${params.toString()}`)).data;
+  },
+  get: async (workspaceId) => (await apiClient.get(`/workspaces/${workspaceId}`)).data,
+  create: async (data) => (await apiClient.post('/workspaces', data)).data,
+  update: async (workspaceId, data) => (await apiClient.patch(`/workspaces/${workspaceId}`, data)).data,
+  archive: async (workspaceId) => (await apiClient.post(`/workspaces/${workspaceId}/archive`)).data,
+  restore: async (workspaceId) => (await apiClient.post(`/workspaces/${workspaceId}/restore`)).data,
+  delete: async (workspaceId) => (await apiClient.delete(`/workspaces/${workspaceId}`)).data,
+};
+
+// ─── Blueprints ───────────────────────────────────────────────
+const blueprints = {
+  list: async ({ scope, visibility, ownerOnly = false } = {}) => {
+    const params = new URLSearchParams();
+    if (scope) params.append('scope', scope);
+    if (visibility) params.append('visibility', visibility);
+    if (ownerOnly) params.append('owner_only', 'true');
+    const qs = params.toString();
+    return (await apiClient.get(`/blueprints${qs ? `?${qs}` : ''}`)).data;
+  },
+  get: async (blueprintId) => (await apiClient.get(`/blueprints/${blueprintId}`)).data,
+  create: async (data) => (await apiClient.post('/blueprints', data)).data,
+  update: async (blueprintId, data) => (await apiClient.patch(`/blueprints/${blueprintId}`, data)).data,
+  delete: async (blueprintId) => (await apiClient.delete(`/blueprints/${blueprintId}`)).data,
+  fork: async (blueprintId, data) => (await apiClient.post(`/blueprints/${blueprintId}/fork`, data)).data,
+  saveFromPlan: async (planId, data = {}) => (await apiClient.post(`/blueprints/from_plan/${planId}`, data)).data,
+};
+
 // ─── Users (my-tasks queue) ────────────────────────────────────
 const users = {
   getMyTasks: async (options = {}) => {
@@ -764,6 +799,22 @@ const agentLoop = {
   createIntention: async (data = {}) => (await apiClient.post('/agent/intentions', data)).data,
 };
 
+// ─── v1 public API facades ────────────────────────────────────
+// Server-side compositions shipped with the API v1 consolidation. Each
+// replaces a client-side fan-out (goal_state: 5 calls → 1, recall_knowledge:
+// up to 4 → 1, update_task: 4 → 1, share_plan: N → 1). Tool handlers fall
+// back to the legacy fan-out when the backend predates /v1 — see
+// isV1Unavailable() in tools/bdi/_shared.js.
+const v1 = {
+  goalState: async (goalId) => (await apiClient.get(`/v1/goals/${goalId}/state`)).data,
+  planAnalysis: async (planId) => (await apiClient.get(`/v1/plans/${planId}/analysis`)).data,
+  knowledgeSearch: async (body = {}) => (await apiClient.post('/v1/knowledge/search', body)).data,
+  updateTask: async (nodeId, body = {}) => (await apiClient.post(`/v1/tasks/${nodeId}/update`, body)).data,
+  sharePlan: async (planId, body = {}) => (await apiClient.post(`/v1/plans/${planId}/share`, body)).data,
+  briefing: async (params = {}) => (await apiClient.get('/v1/briefing', { params })).data,
+  claimNext: async (body = {}) => (await apiClient.post('/v1/tasks/claim-next', body)).data,
+};
+
 // ─── Dependencies (cross-plan & external) ─────────────────────
 const dependencies = {
   /**
@@ -918,6 +969,7 @@ function createApiClient(token, options = {}) {
         const params = new URLSearchParams();
         if (filters.organization_id) params.append('organization_id', filters.organization_id);
         if (filters.status) params.append('status', filters.status);
+        if (filters.workspaceId) params.append('workspace_id', filters.workspaceId);
         const r = await client.get(`/goals?${params.toString()}`);
         return r.data.goals || r.data;
       },
@@ -973,6 +1025,15 @@ function createApiClient(token, options = {}) {
       listCrossPlan: async (planIds) => (await client.get('/dependencies/cross-plan', { params: { plan_ids: planIds.join(',') } })).data,
       createExternal: async (data) => (await client.post('/dependencies/external', data)).data,
     },
+    v1: {
+      goalState: async (goalId) => (await client.get(`/v1/goals/${goalId}/state`)).data,
+      planAnalysis: async (planId) => (await client.get(`/v1/plans/${planId}/analysis`)).data,
+      knowledgeSearch: async (body = {}) => (await client.post('/v1/knowledge/search', body)).data,
+      updateTask: async (nodeId, body = {}) => (await client.post(`/v1/tasks/${nodeId}/update`, body)).data,
+      sharePlan: async (planId, body = {}) => (await client.post(`/v1/plans/${planId}/share`, body)).data,
+      briefing: async (params = {}) => (await client.get('/v1/briefing', { params })).data,
+      claimNext: async (body = {}) => (await client.post('/v1/tasks/claim-next', body)).data,
+    },
     users: {
       getMyTasks: async (options = {}) => {
         const params = new URLSearchParams();
@@ -988,6 +1049,36 @@ function createApiClient(token, options = {}) {
       blockWorkSession: async (sessionId, data = {}) => (await client.post(`/agent/work-sessions/${sessionId}/block`, data)).data,
       createIntention: async (data = {}) => (await client.post('/agent/intentions', data)).data,
     },
+    workspaces: {
+      list: async ({ organizationId, includeArchived = false } = {}) => {
+        const params = new URLSearchParams();
+        if (organizationId) params.append('organization_id', organizationId);
+        if (includeArchived) params.append('include_archived', 'true');
+        return (await client.get(`/workspaces?${params.toString()}`)).data;
+      },
+      get: async (workspaceId) => (await client.get(`/workspaces/${workspaceId}`)).data,
+      create: async (data) => (await client.post('/workspaces', data)).data,
+      update: async (workspaceId, data) => (await client.patch(`/workspaces/${workspaceId}`, data)).data,
+      archive: async (workspaceId) => (await client.post(`/workspaces/${workspaceId}/archive`)).data,
+      restore: async (workspaceId) => (await client.post(`/workspaces/${workspaceId}/restore`)).data,
+      delete: async (workspaceId) => (await client.delete(`/workspaces/${workspaceId}`)).data,
+    },
+    blueprints: {
+      list: async ({ scope, visibility, ownerOnly = false } = {}) => {
+        const params = new URLSearchParams();
+        if (scope) params.append('scope', scope);
+        if (visibility) params.append('visibility', visibility);
+        if (ownerOnly) params.append('owner_only', 'true');
+        const qs = params.toString();
+        return (await client.get(`/blueprints${qs ? `?${qs}` : ''}`)).data;
+      },
+      get: async (blueprintId) => (await client.get(`/blueprints/${blueprintId}`)).data,
+      create: async (data) => (await client.post('/blueprints', data)).data,
+      update: async (blueprintId, data) => (await client.patch(`/blueprints/${blueprintId}`, data)).data,
+      delete: async (blueprintId) => (await client.delete(`/blueprints/${blueprintId}`)).data,
+      fork: async (blueprintId, data) => (await client.post(`/blueprints/${blueprintId}/fork`, data)).data,
+      saveFromPlan: async (planId, data = {}) => (await client.post(`/blueprints/from_plan/${planId}`, data)).data,
+    },
     axiosInstance: client,
   };
 }
@@ -1013,12 +1104,15 @@ module.exports = {
   tokens,
   organizations,
   goals,
+  workspaces,
+  blueprints,
   context,
   graphiti,
   dependencies,
   coherence,
   users,
   agentLoop,
+  v1,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)
 };

package/src/cli/local-client.js

@@ -195,13 +195,15 @@ function renderPlanHealth(plan) {
 function renderCoherenceWarning(task) {
   if (!task || !task.coherence_status) return [];
   const status = task.coherence_status;
-  if (status === 'clean' || status === 'unchecked') return [];
+  if (status === 'ok' || status === 'coherent' || status === 'clean' || status === 'unchecked') return [];
 
   const out = ['## Coherence warning', ''];
   out.push(`- Status: ${status}`);
-  if (status === 'contradiction_detected') {
+  // Accept both the public vocabulary and the legacy internal values so the
+  // CLI keeps working against older backends.
+  if (status === 'contradicted' || status === 'contradiction_detected') {
     out.push('- Supporting knowledge contains contradictions. Run `check_contradictions` (MCP) and re-verify before acting.');
-  } else if (status === 'stale_beliefs') {
+  } else if (status === 'outdated' || status === 'stale_beliefs') {
     out.push('- Knowledge backing this task may be outdated. Run `recall_knowledge` (MCP) to refresh before deciding.');
   }
   out.push('');

package/src/tools/bdi/_shared.js

@@ -26,4 +26,16 @@ function safeArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
-module.exports = { asOf, formatResponse, errorResponse, safeArray };
+/**
+ * True when an error means the backend has no /v1 surface (pre-consolidation
+ * self-hosted API). Express returns a default 404 with no structured body for
+ * unmatched routes, whereas v1 handlers always return JSON with an `error`
+ * field — so a bare 404 means "route missing", not "resource missing".
+ */
+function isV1Unavailable(err) {
+  if (err.response?.status !== 404) return false;
+  const body = err.response.data;
+  return !(body && typeof body === 'object' && body.error);
+}
+
+module.exports = { asOf, formatResponse, errorResponse, safeArray, isV1Unavailable };

package/src/tools/bdi/beliefs.js

@@ -5,7 +5,7 @@
  * plan_analysis. Each answers one whole agentic question and returns `as_of`.
  */
 
-const { asOf, formatResponse, errorResponse, safeArray } = require('./_shared');
+const { asOf, formatResponse, errorResponse, safeArray, isV1Unavailable } = require('./_shared');
 
 // ─────────────────────────────────────────────────────────────────────────
 // briefing — bundled mission control state. Replaces 4 round trips.
@@ -30,15 +30,24 @@ const briefingDefinition = {
 };
 
 async function briefingHandler(args, apiClient) {
+  const briefingParams = {
+    scope: args.scope,
+    goal_id: args.goal_id,
+    plan_id: args.plan_id,
+    recent_window_hours: args.recent_window_hours,
+  };
+
+  // v1 public path first; same server-side handler as /agent/briefing.
+  if (apiClient.v1) {
+    try {
+      return formatResponse(await apiClient.v1.briefing(briefingParams));
+    } catch {
+      // Fall through to the internal facade path, then the legacy fan-out.
+    }
+  }
+
   try {
-    const response = await apiClient.axiosInstance.get('/agent/briefing', {
-      params: {
-        scope: args.scope,
-        goal_id: args.goal_id,
-        plan_id: args.plan_id,
-        recent_window_hours: args.recent_window_hours,
-      },
-    });
+    const response = await apiClient.axiosInstance.get('/agent/briefing', { params: briefingParams });
     return formatResponse(response.data);
   } catch {
     // Fall back to the pre-facade fan-out for self-hosted older APIs.
@@ -232,6 +241,22 @@ const goalStateDefinition = {
 
 async function goalStateHandler(args, apiClient) {
   const { goal_id } = args;
+
+  // v1 facade: one server-side call replaces the 5-endpoint fan-out below.
+  // Same response shape — the server composition was ported from this handler.
+  if (apiClient.v1) {
+    try {
+      return formatResponse(await apiClient.v1.goalState(goal_id));
+    } catch (err) {
+      if (!isV1Unavailable(err)) {
+        const status = err.response?.status;
+        if (status === 404) return errorResponse('not_found', `Goal ${goal_id} not found`);
+        if (status === 403) return errorResponse('forbidden', 'Access denied to this goal');
+        // 5xx and friends: fall through to the legacy fan-out best-effort path.
+      }
+    }
+  }
+
   const [goalRes, qualityRes, progressRes, gapsRes, pathRes] = await Promise.allSettled([
     apiClient.goals.get(goal_id),
     apiClient.goals.getQuality(goal_id),
@@ -283,7 +308,7 @@ async function goalStateHandler(args, apiClient) {
     as_of: asOf(),
     goal: {
       id: goal.id, title: goal.title, description: goal.description,
-      type: goal.type, goal_type: goal.goalType || goal.goal_type,
+      type: goal.type, committed: Boolean(goal.committed ?? goal.promotedAt ?? goal.promoted_at),
       status: goal.status, priority: goal.priority,
       owner_id: goal.ownerId || goal.owner_id, success_criteria: goal.successCriteria || goal.success_criteria,
       promoted_at: goal.promotedAt || goal.promoted_at,
@@ -330,6 +355,22 @@ const recallKnowledgeDefinition = {
 
 async function recallKnowledgeHandler(args, apiClient) {
   const { query, scope = {}, since, entry_type = 'all', result_kind = 'all', max_results = 10, include_contradictions = false } = args;
+
+  // v1 facade: one server-side call replaces the 4-endpoint fan-out below.
+  if (apiClient.v1) {
+    try {
+      const data = await apiClient.v1.knowledgeSearch({
+        query, since, entry_type, result_kind, max_results, include_contradictions, ...scope,
+      });
+      return formatResponse(data);
+    } catch (err) {
+      if (!isV1Unavailable(err)) {
+        // v1 exists but errored — keep going with the legacy fan-out, which
+        // already treats every sub-call as best-effort.
+      }
+    }
+  }
+
   const wantFacts = result_kind === 'all' || result_kind === 'facts';
   const wantEntities = result_kind === 'all' || result_kind === 'entities';
   const wantEpisodes = result_kind === 'all' || result_kind === 'episodes';
@@ -399,6 +440,7 @@ const listPlansDefinition = {
           status: { type: 'array', items: { type: 'string' } },
           visibility: { type: 'array', items: { type: 'string', enum: ['private', 'unlisted', 'public'] } },
           query: { type: 'string', description: 'Substring match on title (case-insensitive)' },
+          workspace_id: { type: 'string', description: 'Scope to plans inside a single workspace' },
           limit: { type: 'integer', default: 50 },
         },
       },
@@ -414,6 +456,9 @@ async function listPlansHandler(args, apiClient) {
 
     if (filter.status?.length) plans = plans.filter((p) => filter.status.includes(p.status));
     if (filter.visibility?.length) plans = plans.filter((p) => filter.visibility.includes(p.visibility));
+    if (filter.workspace_id) {
+      plans = plans.filter((p) => (p.workspace_id || p.workspaceId) === filter.workspace_id);
+    }
     if (filter.query) {
       const q = filter.query.toLowerCase();
       plans = plans.filter((p) => (p.title || '').toLowerCase().includes(q));

package/src/tools/bdi/desires.js

@@ -1,9 +1,10 @@
 /**
  * BDI desires — goal management.
  *
- * 3 tools: list_goals (with health rollup), update_goal (atomic, subsumes
- * link/unlink and achiever changes), derive_subgoal (propose a sub-goal
- * under an existing parent; mandatory parent — top-level goals stay UI-only).
+ * 4 tools: list_goals (with health rollup), update_goal (atomic, subsumes
+ * link/unlink and achiever changes), create_goal (new top-level goal), and
+ * derive_subgoal (a sub-goal under an existing parent). Agents create goals
+ * directly — no UI round-trip and no forced approval gate.
  */
 
 const { asOf, formatResponse, errorResponse, safeArray } = require('./_shared');
@@ -21,6 +22,7 @@ const listGoalsDefinition = {
         properties: {
           health: { type: 'array', items: { type: 'string', enum: ['on_track', 'at_risk', 'stale'] } },
           status: { type: 'array', items: { type: 'string' } },
+          workspace_id: { type: 'string', description: 'Scope to goals inside a single workspace' },
           include_inactive: { type: 'boolean', default: false },
         },
       },
@@ -32,7 +34,7 @@ async function listGoalsHandler(args, apiClient) {
   const filter = args.filter || {};
   try {
     const [listRes, dashboardRes] = await Promise.allSettled([
-      apiClient.goals.list({ status: filter.include_inactive ? undefined : 'active' }),
+      apiClient.goals.list({ status: filter.include_inactive ? undefined : 'active', workspaceId: filter.workspace_id }),
       apiClient.goals.getDashboard(),
     ]);
 
@@ -88,9 +90,10 @@ const updateGoalDefinition = {
           description: { type: 'string' },
           priority: { type: 'integer' },
           status: { type: 'string' },
-          goal_type: { type: 'string', enum: ['desire', 'intention'] },
+          // Commitment: true once the goal is promoted to active execution
+          // (replaces the old desire/intention goal_type vocabulary).
+          committed: { type: 'boolean' },
           success_criteria: {},
-          promote_to_intention: { type: 'boolean' },
           add_linked_plans: { type: 'array', items: { type: 'string' } },
           remove_linked_plans: { type: 'array', items: { type: 'string' } },
           add_achievers: { type: 'array', items: { type: 'string' } },
@@ -112,8 +115,12 @@ async function updateGoalHandler(args, apiClient) {
   for (const k of ['title', 'description', 'priority', 'status', 'success_criteria']) {
     if (changes[k] !== undefined) directFields[k] = changes[k];
   }
-  if (changes.goal_type) directFields.goalType = changes.goal_type;
-  if (changes.promote_to_intention) directFields.goalType = 'intention';
+  // Map the public `committed` boolean onto the backend's commitment write
+  // (the API still accepts the legacy goalType field and translates it to
+  // promoted_at). committed:true ⇒ promoted, false ⇒ aspirational.
+  if (changes.committed !== undefined) {
+    directFields.goalType = changes.committed ? 'intention' : 'desire';
+  }
 
   if (Object.keys(directFields).length) {
     try {
@@ -156,8 +163,8 @@ async function updateGoalHandler(args, apiClient) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────
-// derive_subgoal — propose a sub-goal under an existing parent.
-// Top-level goals stay UI-only (strategic direction is human-set).
+// derive_subgoal — create a sub-goal under an existing parent. For a new
+// top-level goal use create_goal.
 // ─────────────────────────────────────────────────────────────────────────
 
 const VALID_GOAL_TYPES = ['outcome', 'constraint', 'metric', 'principle'];
@@ -166,11 +173,10 @@ const VALID_STATUSES = ['draft', 'active', 'achieved', 'paused', 'abandoned', 'a
 const deriveSubgoalDefinition = {
   name: 'derive_subgoal',
   description:
-    "Propose a sub-goal under an existing parent goal. parent_goal_id is " +
-    "mandatory — agents cannot create top-level goals (strategic direction is " +
-    "human-set). 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.",
+    "Create a sub-goal under an existing parent goal (parent_goal_id required). " +
+    "For a new top-level goal, use create_goal instead. Defaults to " +
+    "status='active'; pass status='draft' for autonomous loops so a human can " +
+    "review before promotion. Drafts surface in the dashboard pending queue.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -254,11 +260,85 @@ async function deriveSubgoalHandler(args, apiClient) {
   });
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// create_goal — create a top-level goal directly (no parent).
+// Agents create goals when a human asks them to; there is no UI round-trip and
+// no forced approval gate. Defaults to status='active'.
+// ─────────────────────────────────────────────────────────────────────────
+
+const createGoalDefinition = {
+  name: 'create_goal',
+  description:
+    "Create a new top-level goal (no parent). Use this when a human asks you to " +
+    "set up a goal — agents create goals directly, no UI step required. For a " +
+    "goal that contributes to an existing one, use derive_subgoal instead. " +
+    "Defaults to status='active' (live immediately); pass status='draft' only " +
+    "if you want it to sit in the pending queue for review. Lands in the user's " +
+    "active organization's default workspace unless workspace_id is given.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', description: "The goal statement." },
+      description: { type: 'string', description: "What the goal means / context." },
+      type: {
+        type: 'string',
+        enum: VALID_GOAL_TYPES,
+        default: 'outcome',
+        description: "outcome (end state), metric (quantitative target), constraint (must-not-violate), principle (durable invariant).",
+      },
+      status: {
+        type: 'string',
+        enum: VALID_STATUSES,
+        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.",
+      },
+      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." },
+    },
+    required: ['title'],
+  },
+};
+
+async function createGoalHandler(args, apiClient) {
+  const { title, description, type = 'outcome', status = 'active', success_criteria, priority, workspace_id } = args;
+
+  const payload = { title, type, status };
+  if (description) payload.description = description;
+  if (success_criteria) payload.successCriteria = { criteria: success_criteria };
+  if (typeof priority === 'number') payload.priority = priority;
+  if (workspace_id) payload.workspaceId = workspace_id;
+
+  let goal;
+  try {
+    goal = await apiClient.goals.create(payload);
+  } catch (err) {
+    const upstream = err.response?.data?.error || err.message;
+    return errorResponse('create_failed', `Failed to create goal: ${upstream}`);
+  }
+
+  return formatResponse({
+    as_of: asOf(),
+    goal_id: goal.id,
+    title: goal.title,
+    status: goal.status,
+    is_draft: goal.status === 'draft',
+    next_step: goal.status === 'draft'
+      ? "Goal created as draft. Promote via update_goal({status: 'active'}) once ready."
+      : "Goal is active. Add sub-goals with derive_subgoal, or link plans via update_goal({add_linked_plans: [...]}).",
+  });
+}
+
 module.exports = {
-  definitions: [listGoalsDefinition, updateGoalDefinition, deriveSubgoalDefinition],
+  definitions: [listGoalsDefinition, updateGoalDefinition, createGoalDefinition, deriveSubgoalDefinition],
   handlers: {
     list_goals: listGoalsHandler,
     update_goal: updateGoalHandler,
+    create_goal: createGoalHandler,
     derive_subgoal: deriveSubgoalHandler,
   },
 };

package/src/tools/bdi/index.js

@@ -12,12 +12,14 @@ const beliefs = require('./beliefs');
 const desires = require('./desires');
 const intentions = require('./intentions');
 const utility = require('./utility');
+const workspaces = require('./workspaces');
 
 const definitions = [
   ...beliefs.definitions,
   ...desires.definitions,
   ...intentions.definitions,
   ...utility.definitions,
+  ...workspaces.definitions,
 ];
 
 const handlers = {
@@ -25,6 +27,7 @@ const handlers = {
   ...desires.handlers,
   ...intentions.handlers,
   ...utility.handlers,
+  ...workspaces.handlers,
 };
 
 const names = new Set(definitions.map((t) => t.name));

package/src/tools/bdi/intentions.js

@@ -13,7 +13,7 @@
  * See ../../../docs/MCP_v1.0_FULL_SURFACE.md for design rationale.
  */
 
-const { asOf, formatResponse, errorResponse } = require('./_shared');
+const { asOf, formatResponse, errorResponse, isV1Unavailable } = require('./_shared');
 
 // ─────────────────────────────────────────────────────────────────────────
 // queue_decision — real decision queue. Replaces add_learning workaround.
@@ -312,6 +312,28 @@ async function updateTaskHandler(args, apiClient) {
     }
   }
 
+  // v1 facade: one atomic server-side call (status + log + claim release +
+  // learning) replaces the 4-endpoint fan-out below. Same response shape.
+  if (apiClient.v1) {
+    try {
+      const data = await apiClient.v1.updateTask(task_id, {
+        status,
+        log_message,
+        log_type: args.log_type,
+        release_claim,
+        add_learning,
+      });
+      return formatResponse(data);
+    } catch (err) {
+      if (!isV1Unavailable(err)) {
+        const s = err.response?.status;
+        if (s === 404) return errorResponse('not_found', `Task ${task_id} not found`);
+        if (s === 403) return errorResponse('forbidden', 'Access denied to this plan');
+        // 5xx: fall through to the legacy fan-out.
+      }
+    }
+  }
+
   // Resolve plan_id from task if not provided.
   if (!planId) {
     try {
@@ -345,7 +367,7 @@ async function updateTaskHandler(args, apiClient) {
   if (log_message) {
     const logType = args.log_type || STATUS_TO_LOG_TYPE[status] || 'progress';
     try {
-      const log = await apiClient.logs.addLog(planId, task_id, {
+      const log = await apiClient.logs.addLogEntry(planId, task_id, {
         content: log_message,
         log_type: logType,
       });
@@ -427,16 +449,27 @@ async function claimNextTaskHandler(args, apiClient) {
   const { scope = {}, ttl_minutes = 30, fresh = false, context_depth = 2, dry_run = false } = args;
   const { plan_id, goal_id } = scope;
 
+  const sessionBody = {
+    plan_id,
+    goal_id,
+    ttl_minutes,
+    fresh,
+    dry_run,
+    depth: context_depth,
+    agent_id: 'mcp-agent',
+  };
+
+  // v1 public path first; same server-side handler as /agent/work-sessions.
+  if (apiClient.v1) {
+    try {
+      return formatResponse(await apiClient.v1.claimNext(sessionBody));
+    } catch {
+      // Fall through to the internal facade path, then the legacy fan-out.
+    }
+  }
+
   try {
-    const response = await apiClient.axiosInstance.post('/agent/work-sessions', {
-      plan_id,
-      goal_id,
-      ttl_minutes,
-      fresh,
-      dry_run,
-      depth: context_depth,
-      agent_id: 'mcp-agent',
-    });
+    const response = await apiClient.axiosInstance.post('/agent/work-sessions', sessionBody);
     return formatResponse(response.data);
   } catch {
     // Fall back to the pre-facade fan-out for self-hosted older APIs.
@@ -449,8 +482,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';
@@ -458,20 +491,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 });
@@ -584,7 +646,7 @@ async function releaseTaskHandler(args, apiClient) {
   let logId = null;
   if (message) {
     try {
-      const log = await apiClient.logs.addLog(planId, task_id, { content: message, log_type: 'progress' });
+      const log = await apiClient.logs.addLogEntry(planId, task_id, { content: message, log_type: 'progress' });
       logId = log?.id || log?.log?.id;
     } catch {}
   }
@@ -1024,7 +1086,10 @@ async function proposeResearchChainHandler(args, apiClient) {
 // Cycle detection happens server-side; we surface the 409 cleanly.
 // ─────────────────────────────────────────────────────────────────────────
 
-const VALID_RELATIONS = ['blocks', 'requires', 'relates_to'];
+// Canonical node→node dependency vocabulary (backend ring-2 consolidation).
+// `requires` is still accepted by the API (mapped to `blocks`) but no longer
+// offered here.
+const VALID_RELATIONS = ['blocks', 'relates_to'];
 
 const linkIntentionsDefinition = {
   name: 'link_intentions',
@@ -1480,6 +1545,28 @@ const sharePlanDefinition = {
 
 async function sharePlanHandler(args, apiClient) {
   const { plan_id, visibility, add_collaborators = [], remove_collaborators = [] } = args;
+
+  // v1 facade: one atomic server-side call replaces the per-collaborator
+  // fan-out below. Same response shape (applied_changes + failures).
+  if (apiClient.v1) {
+    try {
+      const data = await apiClient.v1.sharePlan(plan_id, {
+        visibility,
+        add_collaborators,
+        remove_collaborators,
+      });
+      return formatResponse(data);
+    } catch (err) {
+      if (!isV1Unavailable(err)) {
+        const s = err.response?.status;
+        if (s === 400 || s === 403 || s === 404) {
+          return errorResponse('invalid_arg', err.response?.data?.error || err.message);
+        }
+        // 5xx: fall through to the legacy fan-out.
+      }
+    }
+  }
+
   const applied = [];
   const failures = [];
 

package/src/tools/bdi/utility.js

@@ -29,6 +29,7 @@ async function getStartedHandler(args) {
       beliefs: ['briefing', 'list_plans', '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'],
+      workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint'],
     },
     recommended_workflows: [
       {

package/src/tools/bdi/workspaces.js

@@ -0,0 +1,215 @@
+/**
+ * Workspaces and Blueprints — organizational structure tools.
+ *
+ * Workspace = live folder under an Organization (owns goals + plans).
+ * Blueprint = dehydrated reusable shape, forks into a Workspace or Plan.
+ *
+ * v1 supports plan-scope blueprints only. See
+ * agent-planner/docs/WORKSPACE_BLUEPRINT_SKETCH.md for the design.
+ */
+
+const { asOf, formatResponse, errorResponse, safeArray } = require('./_shared');
+
+// ─── Workspaces ──────────────────────────────────────────────────
+
+const listWorkspacesDefinition = {
+  name: 'list_workspaces',
+  description:
+    "List workspaces in an organization. A workspace is a folder that owns " +
+    "goals + plans. Returns archived workspaces only when include_archived=true.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      organization_id: { type: 'string', description: "Required. Organization to scope to." },
+      include_archived: { type: 'boolean', default: false },
+    },
+    required: ['organization_id'],
+  },
+};
+
+async function listWorkspacesHandler(args, apiClient) {
+  const { organization_id, include_archived } = args;
+  try {
+    const data = await apiClient.workspaces.list({
+      organizationId: organization_id,
+      includeArchived: include_archived === true,
+    });
+    return formatResponse({
+      as_of: asOf(),
+      workspaces: safeArray(data.workspaces || data),
+    });
+  } catch (err) {
+    return errorResponse('upstream_unavailable', `list_workspaces failed: ${err.message}`);
+  }
+}
+
+const createWorkspaceDefinition = {
+  name: 'create_workspace',
+  description:
+    "Create a new workspace inside an organization. Returns the new workspace " +
+    "row. The slug is auto-generated from the title and de-duplicated within " +
+    "the org.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      organization_id: { type: 'string' },
+      title: { type: 'string' },
+      description: { type: 'string' },
+      icon: { type: 'string', description: "Optional emoji or icon token." },
+      slug: { type: 'string', description: "Optional. Auto-generated from title if omitted." },
+    },
+    required: ['organization_id', 'title'],
+  },
+};
+
+async function createWorkspaceHandler(args, apiClient) {
+  const { organization_id, title, description, icon, slug } = args;
+  try {
+    const ws = await apiClient.workspaces.create({
+      organization_id,
+      title,
+      description,
+      icon,
+      slug,
+    });
+    return formatResponse({ as_of: asOf(), workspace: ws });
+  } catch (err) {
+    const upstream = err.response?.data?.error || err.message;
+    return errorResponse('create_failed', `create_workspace failed: ${upstream}`);
+  }
+}
+
+// ─── Blueprints ──────────────────────────────────────────────────
+
+const listBlueprintsDefinition = {
+  name: 'list_blueprints',
+  description:
+    "List blueprints visible to the user (owned + public/unlisted). Filter by " +
+    "scope ('plan' or 'workspace'), visibility, or owner_only=true.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      scope: { type: 'string', enum: ['plan', 'workspace'] },
+      visibility: { type: 'string', enum: ['private', 'public', 'unlisted'] },
+      owner_only: { type: 'boolean', default: false },
+    },
+  },
+};
+
+async function listBlueprintsHandler(args, apiClient) {
+  try {
+    const data = await apiClient.blueprints.list({
+      scope: args.scope,
+      visibility: args.visibility,
+      ownerOnly: args.owner_only === true,
+    });
+    return formatResponse({
+      as_of: asOf(),
+      blueprints: safeArray(data.blueprints || data),
+    });
+  } catch (err) {
+    return errorResponse('upstream_unavailable', `list_blueprints failed: ${err.message}`);
+  }
+}
+
+const forkBlueprintDefinition = {
+  name: 'fork_blueprint',
+  description:
+    "Fork a plan-scope blueprint into a target workspace. Creates a new plan " +
+    "inside that workspace with the blueprint's structure (nodes, " +
+    "dependencies, agent_instructions). All node statuses reset to " +
+    "'not_started'. The new plan's forked_from_blueprint_id records lineage.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      blueprint_id: { type: 'string' },
+      workspace_id: { type: 'string', description: "Target workspace the new plan will land in." },
+      title: { type: 'string', description: "Optional title override for the new plan." },
+    },
+    required: ['blueprint_id', 'workspace_id'],
+  },
+};
+
+async function forkBlueprintHandler(args, apiClient) {
+  const { blueprint_id, workspace_id, title } = args;
+  try {
+    const newPlan = await apiClient.blueprints.fork(blueprint_id, {
+      workspace_id,
+      title,
+    });
+    return formatResponse({
+      as_of: asOf(),
+      plan_id: newPlan.id,
+      workspace_id,
+      forked_from_blueprint_id: newPlan.forkedFromBlueprintId || blueprint_id,
+      title: newPlan.title,
+      next_step:
+        "Plan is in status='draft'. Open it, claim a task, or promote to 'active' once ready to execute.",
+    });
+  } catch (err) {
+    const upstream = err.response?.data?.error || err.message;
+    return errorResponse('fork_failed', `fork_blueprint failed: ${upstream}`);
+  }
+}
+
+const saveAsBlueprintDefinition = {
+  name: 'save_as_blueprint',
+  description:
+    "Snapshot a live plan as a new plan-scope blueprint. Captures structure, " +
+    "agent_instructions, and dependencies. Excludes run-state (statuses, " +
+    "claims, knowledge episodes, logs, decisions, agent assignments).",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      plan_id: { type: 'string' },
+      title: { type: 'string', description: "Optional. Defaults to the source plan's title." },
+      description: { type: 'string' },
+      visibility: { type: 'string', enum: ['private', 'public', 'unlisted'], default: 'private' },
+      tags: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['plan_id'],
+  },
+};
+
+async function saveAsBlueprintHandler(args, apiClient) {
+  const { plan_id, title, description, visibility, tags } = args;
+  try {
+    const bp = await apiClient.blueprints.saveFromPlan(plan_id, {
+      title,
+      description,
+      visibility,
+      tags,
+    });
+    return formatResponse({
+      as_of: asOf(),
+      blueprint_id: bp.id,
+      scope: bp.scope,
+      visibility: bp.visibility,
+      node_count: bp.payload?.nodes?.length ?? null,
+      dependency_count: bp.payload?.dependencies?.length ?? null,
+      next_step: bp.visibility === 'private'
+        ? "Blueprint saved privately. Share it via update visibility to 'public' or 'unlisted', or fork it directly via fork_blueprint."
+        : "Blueprint published. Anyone with the link (unlisted) or via discovery (public) can fork it.",
+    });
+  } catch (err) {
+    const upstream = err.response?.data?.error || err.message;
+    return errorResponse('snapshot_failed', `save_as_blueprint failed: ${upstream}`);
+  }
+}
+
+module.exports = {
+  definitions: [
+    listWorkspacesDefinition,
+    createWorkspaceDefinition,
+    listBlueprintsDefinition,
+    forkBlueprintDefinition,
+    saveAsBlueprintDefinition,
+  ],
+  handlers: {
+    list_workspaces: listWorkspacesHandler,
+    create_workspace: createWorkspaceHandler,
+    list_blueprints: listBlueprintsHandler,
+    fork_blueprint: forkBlueprintHandler,
+    save_as_blueprint: saveAsBlueprintHandler,
+  },
+};