agent-planner-mcp 0.9.1 → 1.1.0

package/AGENT_GUIDE.md

@@ -1,6 +1,6 @@
-# AgentPlanner Quick Reference (v0.9.0)
+# AgentPlanner Quick Reference (v1.0.0)
 
-Tight cheat sheet for AI agents. Full docs: [SKILL.md](SKILL.md). Migration from 0.8.x: [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md).
+Tight cheat sheet for AI agents. Full docs: [SKILL.md](SKILL.md). Migration history: [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md), [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
 ## Start here
 
@@ -9,7 +9,7 @@ get_started()
 // → Returns the BDI tool surface map and recommended workflows
 ```
 
-## The 15 tools
+## The 24 tools
 
 ### Beliefs (read state)
 | Tool | When |
@@ -26,24 +26,66 @@ 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) |
 
-### Intentions (act)
+### Intentions — execution
 | Tool | When |
 |---|---|
 | `claim_next_task` | Pick + claim + load context (one call) |
 | `update_task` | Atomic status+log+release+learning |
 | `release_task` | Explicit handoff |
-| `queue_decision` | Escalate to human |
+| `queue_decision` | Escalate to human (real decision queue) |
 | `resolve_decision` | Pick up human's answer |
 | `add_learning` | Write to knowledge graph |
 
-## Three workflow templates
+### Intentions — creation (v1.0)
+| Tool | When |
+|---|---|
+| `form_intention` | Create plan + initial tree under a goal, atomically |
+| `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 |
+|---|---|
+| `update_plan` | Edit plan title/description/status/visibility/metadata |
+| `update_node` | Edit any node property except status |
+| `move_node` | Reparent within plan; cycle-safe |
+| `link_intentions` | Create dependency edge between two tasks |
+| `unlink_intentions` | Remove a dependency edge |
+| `delete_plan` | Soft-delete via status='archived' |
+| `delete_node` | Soft-delete via status='archived' |
+
+### Intentions — sharing & collaboration (v1.0)
+| Tool | When |
+|---|---|
+| `share_plan` | Atomic visibility change + add/remove collaborators |
+| `invite_member` | Add user to organization |
+| `update_member_role` | Owner-only role change |
+| `remove_member` | Owner/admin removes non-owner member |
+
+## status='active' vs status='draft' (v1.0)
+
+The single most important decision when calling a creation tool.
+
+| Origin | Default | Why |
+|---|---|---|
+| **Human said so in chat** | `status='active'` (omit) | User already approved by asking. Don't bury their request in drafts. |
+| **You're acting autonomously** | `status='draft'` (pass explicitly) | Let the human review before it activates. Drafts surface in the dashboard pending queue. |
+| **You're uncertain** | use `queue_decision` instead | Drafts are for "I'm proposing structure"; the queue is for "I need an answer." |
+
+Drafts auto-promote to active when work begins on any node (transitions to `in_progress`, `completed`, `blocked`, `plan_ready`). Promote explicitly via `update_plan({status: 'active'})` or `update_goal({status: 'active'})`.
+
+## Workflow templates
 
 ### A) Mission control (Cowork autopilot)
 ```
 briefing → check goal_health.summary
         → top_recommendation? act
-        → at_risk goals? goal_state(goal_id), then update_task or queue_decision
+        → at_risk goals? goal_state(goal_id)
+            → if you can plan it: derive_subgoal + form_intention (status='draft')
+            → if reversible: update_task or update_goal
+            → if uncertain: queue_decision
         → add_learning to record
 ```
 
@@ -63,22 +105,43 @@ update_task(...) for transitions
 release_task(message='handoff') for explicit handover
 ```
 
+### D) Human-directed restructure (v1.0)
+User: "Rename the launch plan to 'Public Beta', mark it active, and add me as editor on the auth plan."
+```
+update_plan({plan_id: '<launch>', title: 'Public Beta', status: 'active'})
+share_plan({plan_id: '<auth>', add_collaborators: [{user_id: '<user>', role: 'editor'}]})
+```
+No UI required.
+
+### E) Autonomous proposal (v1.0)
+You spotted a gap during a scheduled tick.
+```
+derive_subgoal({parent_goal_id, title, rationale, status: 'draft'})
+form_intention({goal_id: <new>, title, rationale, status: 'draft', tree: [...]})
+// Both surface in the dashboard pending queue. Human reviews and either:
+//   - tells you "approve them" → update_goal/update_plan({status: 'active'}) for each
+//   - tells you "archive" → update_plan({status: 'archived'}) for each
+```
+
 ## Decision rule
 
 When in doubt between act and queue:
-- Reversible local action (status, log, learning) → **act** via `update_task` / `add_learning`
+- 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'`
 
-Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue_decision` is a real tool now.
+Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue_decision` is the real tool.
 
 ## 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.
 - `briefing` does goals + decisions + tasks + activity + recommendation. Don't decompose.
+- `form_intention` creates plan + tree atomically. Don't trickle node-by-node.
+- `share_plan` does visibility + add + remove in one call. Don't fan out.
 
 ## Output discipline
 
 - Every response carries `as_of` — surface this on live artifacts to indicate freshness.
-- Every tool degrades gracefully on partial upstream failure — check `meta.failures` if present.
+- Every tool degrades gracefully on partial upstream failure — check `failures[]` if present.
 - Keep follow-up calls minimal — these tools are designed to bundle.

package/README.md

@@ -123,6 +123,28 @@ Beyond title, description, agent_instructions, and acceptance criteria, the gene
 
 The CLI is intentionally thin: it covers the read context + writeback loop and nothing else. For decomposition, dependency creation, knowledge graph queries, RPI chains, coherence runs, and goal management, use the MCP server (or the API directly).
 
+## Agent Loop Facade
+
+AgentPlanner API now exposes a narrow `/agent/*` facade for the main autonomous loop. MCP uses this facade when available and falls back to older domain endpoints for self-hosted older APIs.
+
+Primary mappings:
+
+| MCP tool | Preferred API endpoint |
+|---|---|
+| `briefing` | `GET /agent/briefing` |
+| `claim_next_task` | `POST /agent/work-sessions` |
+| `update_task` with `session_id` + `completed` | `POST /agent/work-sessions/:id/complete` |
+| `update_task` with `session_id` + `blocked` | `POST /agent/work-sessions/:id/block` |
+| `form_intention` | `POST /agent/intentions` when available, with domain-endpoint fallback |
+
+Validation:
+
+```bash
+npm run validate:mcp-loop
+```
+
+This checks that the MCP tools route through the facade for briefing, task claim/start, and session completion/blocking.
+
 
 ### Claude Desktop
 
@@ -210,59 +232,61 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 
 ## Key Features
 
-- **60+ tools** for planning, task management, dependencies, and knowledge
-- **Dependency graph** with cycle detection, impact analysis, and critical path
+- **24 BDI-aligned tools** for state, goals, and committed actions — no CRUD shapes, every tool answers a whole agentic question
+- **Full mutation surface (v1.0)** — agents and humans-via-agents can manage every plan/node/org property without leaving the conversation; UI is optional inspection
+- **Draft-status seam** — autonomous agent creation lands as drafts surfacing in the dashboard pending queue; human-directed creation defaults to active
+- **Dependency graph** — cycle detection, impact analysis, critical path
 - **Progressive context** — 4-layer context assembly with token budgeting
 - **Knowledge graph** — temporal knowledge via Graphiti (entities, facts, contradictions)
-- **RPI chains** — Research > Plan > Implement task decomposition
-- **Goal tracking** — health dashboard, briefings, bottleneck detection
+- **RPI chains** — Research → Plan → Implement task decomposition (one-call shortcut)
 - **Task claims** — TTL-based locking for multi-agent coordination
-- **Organizations** — multi-tenant isolation
-
-## Available Tools
-
-### Planning & Search
-- `search` - Universal search across all scopes with filters
-- `create_plan` / `update_plan` / `delete_plan` - Plan CRUD
-- `get_plan_structure` - Hierarchical plan tree
-- `get_plan_summary` - Statistics and summary
-
-### Node Management
-- `create_node` / `update_node` / `delete_node` - Node CRUD
-- `move_node` - Reorder or reparent nodes
-- `batch_update_nodes` - Update multiple nodes at once
-- `get_node_context` / `get_node_ancestry` - Rich context
-
-### Dependencies & Analysis
-- `create_dependency` / `delete_dependency` - Manage edges
-- `list_dependencies` / `get_node_dependencies` - Query graph
-- `analyze_impact` - Delay/block/remove scenario analysis
-- `get_critical_path` - Longest blocking chain
-- `create_rpi_chain` - Research > Plan > Implement chain
-
-### Progressive Context
-- `get_task_context` - Primary context tool (depth 1-4, token budget)
-- `suggest_next_tasks` - Dependency-aware suggestions
-- `get_agent_context` / `get_plan_context` - Focused views
-
-### Knowledge Graph
-- `add_learning` / `recall_knowledge` - Learn and retrieve
-- `find_entities` / `check_contradictions` - Graph queries
-- `get_recent_episodes` - Temporal episodes
-
-### Goals & Organizations
-- `create_goal` / `update_goal` / `list_goals` / `get_goal` - Goal management
-- `check_goals_health` - Health dashboard
-- `create_organization` / `get_organization` / `list_organizations` / `update_organization`
-
-### Collaboration
-- `add_log` / `get_logs` - Log entries (comments, progress, reasoning)
-- `claim_task` / `release_task` - Task locking
-- `share_plan` - Collaboration management
-
-### Alignment & Review
-- `check_coherence_pending` - See which plans/goals need alignment review (staleness check)
-- `run_coherence_check` - Evaluate plan quality and stamp as reviewed
+- **Organizations** — multi-tenant isolation with member management
+
+## Available Tools (v1.0.0)
+
+### Beliefs (read state)
+- `briefing` — bundled mission control state in one call
+- `task_context` — single task at progressive depth 1-4
+- `goal_state` — single goal deep-dive (details + quality + progress + bottlenecks + gaps)
+- `recall_knowledge` — knowledge graph query (facts, entities, episodes, contradictions)
+- `search` — text search across plans/nodes
+- `plan_analysis` — impact, critical path, bottlenecks, coherence
+
+### 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
+
+### Intentions — execution
+- `claim_next_task` — pick + claim + load context (one call)
+- `update_task` — atomic status + log + claim release + learning
+- `release_task` — explicit handoff
+- `queue_decision` — escalate to human (real decision queue)
+- `resolve_decision` — pick up human's answer (atomically materializes any `proposed_subtasks`)
+- `add_learning` — record knowledge episode
+
+### Intentions — creation *(v1.0)*
+- `form_intention` — create plan + initial tree under a goal, atomically
+- `extend_intention` — add children under an existing parent (lightweight)
+- `propose_research_chain` — RPI triple with 2 blocking edges, in one call
+
+### Intentions — structural mutation *(v1.0)*
+- `update_plan` — edit any plan property
+- `update_node` — edit any node property except status
+- `move_node` — reparent within plan; cycle-safe
+- `link_intentions` / `unlink_intentions` — manage dependency edges
+- `delete_plan` / `delete_node` — soft-delete via `status='archived'` (recoverable)
+
+### Intentions — sharing & collaboration *(v1.0)*
+- `share_plan` — atomic visibility + add/remove collaborators
+- `invite_member` — add user to org (by user_id or email)
+- `update_member_role` — owner-only role change
+- `remove_member` — owner/admin removes non-owner member
+
+### Utility
+- `get_started` — dynamic reference for new agents
+
+See [SKILL.md](./SKILL.md) for full descriptions, the human-steering scenarios (A/B/C), and `status='draft'` vs `status='active'` guidance.
 
 ## LLM Skill Reference
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentplanner
-description: "Agent orchestration skill for AgentPlanner — BDI-aligned tools for state, goals, and committed actions with human oversight"
-version: 0.9.0
+description: "Agent orchestration skill for AgentPlanner — BDI-aligned tools for state, goals, committed actions, and full mutation surface with human oversight"
+version: 1.0.0
 homepage: https://agentplanner.io
 metadata:
   openclaw:
@@ -15,7 +15,7 @@ metadata:
 
 You have access to the AgentPlanner MCP tools. AgentPlanner is a collaborative planning system where you track work, manage dependencies, and coordinate with humans. This document is your complete reference.
 
-> **Prerequisite:** This skill requires the `agent-planner-mcp` MCP server (v0.9.0+) to be connected. Create an API token at Settings → API Tokens on [agentplanner.io](https://agentplanner.io).
+> **Prerequisite:** This skill requires the `agent-planner-mcp` MCP server (v1.0.0+) to be connected. Create an API token at Settings → API Tokens on [agentplanner.io](https://agentplanner.io).
 >
 > **Setup by client:**
 > - **Claude Desktop:** Download the [.mcpb](https://github.com/TAgents/agent-planner-mcp/releases/latest), double-click to install
@@ -23,9 +23,9 @@ 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 15 tools, organized by intent
+## The 24 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.
+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.
 
 ### Beliefs — what is the state of the world?
 
@@ -40,9 +40,11 @@ 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.
 
 ### Intentions — what am I committing to?
 
+**Execution (existing in v0.9):**
 - `claim_next_task` — pick + claim + load context in one call (cornerstone for coding agents)
 - `update_task` — atomic state transition (status + log + claim release + optional learning)
 - `release_task` — explicit handoff
@@ -50,6 +52,26 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 - `resolve_decision` — pick up after human approval/deferral
 - `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
+- `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):**
+- `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
+- `link_intentions` — create a dependency edge between two existing tasks
+- `unlink_intentions` — remove a dependency edge by id
+- `delete_plan` — soft-delete via `status='archived'`; recoverable
+- `delete_node` — soft-delete via `status='archived'`
+
+**Sharing and collaboration (v1.0):**
+- `share_plan` — atomic visibility change + add/remove collaborators
+- `invite_member` — add user to organization (by user_id or email)
+- `update_member_role` — owner-only role change within an org
+- `remove_member` — owner/admin can remove non-owner members
+
 ### Utility
 
 - `get_started` — dynamic reference; call this if you're new to AgentPlanner
@@ -107,7 +129,7 @@ claim_next_task({ scope: { plan_id } })  // dry_run defaults to false
 
 ### Proposing subtasks for human approval (v0.9.1+)
 
-Agents can't create plan structure directly — that's the human's job. But agents *can* propose subtasks via `queue_decision` and have them materialize on approval. This preserves the "agents drive execution, humans steer structure" boundary while removing the manual follow-through tax.
+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'})`.
 
 ```
 queue_decision({
@@ -125,6 +147,100 @@ queue_decision({
 // and their IDs returned in created_subtasks[]. Defer/reject does nothing.
 ```
 
+For routine decomposition (a task you're working on needs subtasks), use `extend_intention` directly — no decision queue, no friction.
+
+## The human-steering loop (v1.0)
+
+v1.0 closes the creation gap. There are three distinct flows depending on who initiated the action:
+
+### Scenario A: Human directs you in conversation
+
+User says "create a plan to ship the new auth flow under the security goal" or "mark the BSL launch plan completed."
+
+Default to **`status='active'`** — the human asked for it, just do it.
+
+```
+form_intention({
+  goal_id: '<security-goal-id>',
+  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: [...] },
+  ]
+})
+// Plan lands as active. No approval needed — user already approved by asking.
+```
+
+```
+update_plan({ plan_id: '<bsl-plan>', status: 'completed' })
+// Done. No queue, no UI trip.
+```
+
+### Scenario B: You're acting autonomously (scheduled loop, etc.)
+
+No explicit human direction. You decided the workspace needs new structure.
+
+Pass **`status='draft'`** — let the human see what you proposed before it activates.
+
+```
+derive_subgoal({
+  parent_goal_id: '<launch-goal>',
+  title: 'First 3 paying customers',
+  rationale: 'Goal is at_risk — need a concrete intermediate target before broader push',
+  status: 'draft',
+})
+// Surfaces in dashboard pending. Human approves via update_goal({status: 'active'})
+// or in the UI. Plans auto-promote to active when first task moves to in_progress.
+```
+
+### Scenario C: You're uncertain and want explicit input
+
+Genuine ambiguity. Use `queue_decision`.
+
+```
+queue_decision({
+  title: 'Two conflicting facts about pricing',
+  context: 'Memory says $19/mo Pro tier; recent decision log says $29/mo. Which is current?',
+  smallest_input_needed: 'pick one',
+  options: [{ label: '$19' }, { label: '$29' }],
+  urgency: 'normal',
+})
+```
+
+The decision queue is for genuine uncertainty, not as a default gate on everything you do.
+
+## Editing structure (v1.0)
+
+These are routine — call them whenever needed. No decision-queue ceremony.
+
+| Want to... | Call |
+|---|---|
+| Rename a plan | `update_plan({plan_id, title})` |
+| Rename a task | `update_node({node_id, title})` |
+| Edit task instructions | `update_node({node_id, agent_instructions})` |
+| Move a task under a different phase | `move_node({node_id, new_parent_id})` |
+| Express B blocks A | `link_intentions({from_task_id: A, to_task_id: B, relation: 'blocks', rationale: '...'})` |
+| Remove a stale dep | `unlink_intentions({dependency_id, plan_id})` |
+| Archive a plan | `delete_plan({plan_id, reason})` |
+| Archive a task | `delete_node({node_id})` |
+| Restore an archived plan | `update_plan({plan_id, status: 'active', restore: true})` |
+
+`delete_*` is soft delete (sets `status='archived'`) — fully recoverable. Hard delete stays REST + admin-only on purpose; agents shouldn't be able to permanently destroy data.
+
+## Sharing and collaboration (v1.0)
+
+| Want to... | Call |
+|---|---|
+| Make a plan public | `share_plan({plan_id, visibility: 'public'})` |
+| Add a collaborator (by user_id) | `share_plan({plan_id, add_collaborators: [{user_id, role: 'editor'}]})` |
+| Remove a collaborator | `share_plan({plan_id, remove_collaborators: [user_id]})` |
+| Invite someone to the org | `invite_member({organization_id, email})` (or by `user_id`) |
+| Promote member to admin | `update_member_role({organization_id, membership_id, new_role: 'admin'})` |
+| Remove a member | `remove_member({organization_id, membership_id, reason})` |
+
+Email-based collaborator invites stay UI-only; `share_plan` accepts user_ids only. The dedicated `invite_member` call accepts email for org-level invites.
+
 ## Goal coaching
 
 When a user expresses intent — "I want to launch a feature", "we need better testing" — coach them into a structured goal before creating it.
@@ -190,18 +306,10 @@ recall_knowledge({
 
 `result_kind` options: `'facts'`, `'entities'`, `'episodes'`, `'all'`. Default is `'all'` — narrow it to control payload size.
 
-## Migrating from v0.8.x
-
-v0.9.0 is a breaking release. The old 63-tool surface is gone. See [MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping. Highlights:
-
-- `check_goals_health` + `get_my_tasks` + `get_recent_episodes` + `check_coherence_pending` → `briefing`
-- `quick_status` + `add_log` + `release_task` → `update_task`
-- `suggest_next_tasks` + `claim_task` + `get_task_context` → `claim_next_task`
-- `add_learning(entry_type='decision')` → `queue_decision` (real decision queue, not knowledge graph)
-- `get_goal` + `goal_path` + `goal_progress` + `assess_goal_quality` → `goal_state`
-- `recall_knowledge` + `find_entities` + `get_recent_episodes` + `check_contradictions` → `recall_knowledge`
+## Migration history
 
-CRUD-shaped admin tools (`create_node`, `update_plan`, `delete_*`) are removed in v0.9.0. They return as `ap_admin_*` namespace in v1.0.0. Use the AgentPlanner REST API directly if you need them now.
+- **v0.8.x → v0.9.0** — clean break. 63 legacy CRUD tools collapsed into 15 BDI-aligned tools. See [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping.
+- **v0.9.x → v1.0.0** — additive. v0.9 read/update tools unchanged. Adds the full mutation surface (creation, structural edits, sharing, collaboration) so humans can steer entirely through agent conversation. The previously planned `ap_admin_*` namespace is no longer needed — those operations are now first-class BDI tools, with the draft-status seam keeping autonomous agent creation reviewable. See [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
 ## Principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.9.1",
+  "version": "1.1.0",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {
@@ -12,6 +12,7 @@
     "dev": "nodemon src/index.js",
     "dev:http": "MCP_TRANSPORT=http nodemon src/index.js",
     "test": "jest",
+    "validate:mcp-loop": "jest __tests__/agent-loop-facade.test.js --runInBand",
     "test:tools": "node test-tools.js",
     "setup": "node src/setup.js",
     "setup-claude-code": "node src/setup-claude-code.js",

package/src/api-client.js

@@ -17,12 +17,29 @@ const getAuthScheme = (token) => {
 
 const authScheme = getAuthScheme(userApiToken);
 
+// Identify this caller in the API server's tool_calls telemetry.
+// Setup wizards (per client) should set MCP_CLIENT_LABEL to one of
+// "Claude Desktop" | "Claude Code" | "Cursor" | "ChatGPT" | "OpenClaw"
+// so the Settings → Integrations dashboard can group calls per client.
+let pkgVersion;
+try { pkgVersion = require('../package.json').version; } catch { pkgVersion = '0.0.0'; }
+const clientLabel = process.env.MCP_CLIENT_LABEL || null;
+const userAgent = clientLabel
+  ? `agent-planner-mcp/${pkgVersion} (${clientLabel})`
+  : `agent-planner-mcp/${pkgVersion}`;
+
 // Create API client instance
 const apiClient = axios.create({
   baseURL: process.env.API_URL || 'http://localhost:3000',
   headers: {
     'Content-Type': 'application/json',
-    'Authorization': userApiToken ? `${authScheme} ${userApiToken}` : undefined
+    'Authorization': userApiToken ? `${authScheme} ${userApiToken}` : undefined,
+    'User-Agent': userAgent,
+    // X-Client-Label takes precedence on the API side (see
+    // toolCallTelemetry.middleware) so MCP setup wizards can label
+    // calls precisely without polluting the User-Agent string.
+    ...(clientLabel ? { 'X-Client-Label': clientLabel } : {}),
+    'X-MCP-Client': clientLabel || 'unknown',
   }
 });
 
@@ -738,6 +755,15 @@ const users = {
   },
 };
 
+// ─── Agent Loop facade ────────────────────────────────────────
+const agentLoop = {
+  briefing: async (params = {}) => (await apiClient.get('/agent/briefing', { params })).data,
+  startWorkSession: async (data = {}) => (await apiClient.post('/agent/work-sessions', data)).data,
+  completeWorkSession: async (sessionId, data = {}) => (await apiClient.post(`/agent/work-sessions/${sessionId}/complete`, data)).data,
+  blockWorkSession: async (sessionId, data = {}) => (await apiClient.post(`/agent/work-sessions/${sessionId}/block`, data)).data,
+  createIntention: async (data = {}) => (await apiClient.post('/agent/intentions', data)).data,
+};
+
 // ─── Dependencies (cross-plan & external) ─────────────────────
 const dependencies = {
   /**
@@ -778,11 +804,21 @@ const dependencies = {
  */
 function createApiClient(token, options = {}) {
   const scheme = getAuthScheme(token);
+  // Telemetry headers — same shape as the default client. options.clientLabel
+  // wins over the global env var so HTTP-mode sessions can label themselves
+  // per connection (e.g. when the SSE handshake reveals the client).
+  const sessionLabel = options.clientLabel || process.env.MCP_CLIENT_LABEL || null;
+  const sessionUserAgent = sessionLabel
+    ? `agent-planner-mcp/${pkgVersion} (${sessionLabel})`
+    : `agent-planner-mcp/${pkgVersion}`;
   const client = axios.create({
     baseURL: options.apiUrl || process.env.API_URL || 'http://localhost:3000',
     headers: {
       'Content-Type': 'application/json',
-      'Authorization': token ? `${scheme} ${token}` : undefined
+      'Authorization': token ? `${scheme} ${token}` : undefined,
+      'User-Agent': sessionUserAgent,
+      ...(sessionLabel ? { 'X-Client-Label': sessionLabel } : {}),
+      'X-MCP-Client': sessionLabel || 'unknown',
     }
   });
 
@@ -945,6 +981,13 @@ function createApiClient(token, options = {}) {
         return (await client.get(`/users/my-tasks${qs}`)).data;
       },
     },
+    agentLoop: {
+      briefing: async (params = {}) => (await client.get('/agent/briefing', { params })).data,
+      startWorkSession: async (data = {}) => (await client.post('/agent/work-sessions', data)).data,
+      completeWorkSession: async (sessionId, data = {}) => (await client.post(`/agent/work-sessions/${sessionId}/complete`, data)).data,
+      blockWorkSession: async (sessionId, data = {}) => (await client.post(`/agent/work-sessions/${sessionId}/block`, data)).data,
+      createIntention: async (data = {}) => (await client.post('/agent/intentions', data)).data,
+    },
     axiosInstance: client,
   };
 }
@@ -975,6 +1018,7 @@ module.exports = {
   dependencies,
   coherence,
   users,
+  agentLoop,
   axiosInstance,  // Export for direct API calls
   createApiClient  // Factory for per-session clients (HTTP mode)
 };

package/src/setup.js

@@ -158,13 +158,16 @@ function updateClaudeConfig(configPath, mcpServerPath, apiUrl, token) {
     config.mcpServers = {};
   }
 
-  // Add or update planning-system server
+  // Add or update planning-system server.
+  // MCP_CLIENT_LABEL identifies this install in the Settings →
+  // Integrations dashboard's tool_calls telemetry stream.
   config.mcpServers['planning-system'] = {
     command: 'node',
     args: [path.join(mcpServerPath, 'src', 'index.js')],
     env: {
       API_URL: apiUrl,
-      USER_API_TOKEN: token
+      USER_API_TOKEN: token,
+      MCP_CLIENT_LABEL: 'Claude Desktop'
     }
   };