npm - agent-planner-mcp - Versions diffs - 1.5.0 → 1.5.3 - Mend

agent-planner-mcp 1.5.0 → 1.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/package.json CHANGED Viewed

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

package/src/oauth/consent.js ADDED Viewed

@@ -0,0 +1,99 @@
+/**
+ * Consent + login surface for the OAuth authorization step.
+ *
+ * provider.authorize() renders this page (GET /authorize handled by the SDK).
+ * The form POSTs to /oauth/consent, which authenticates against the existing
+ * AgentPlanner /auth/login endpoint and, on success, mints a one-time
+ * authorization code bound to the user's AP credential, then redirects back to
+ * the client's redirect_uri with code + state.
+ */
+const axios = require('axios');
+const esc = (s = '') => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+function renderConsentPage(params, { clientName = 'an application', error = null } = {}) {
+  const hidden = (name) => `<input type="hidden" name="${name}" value="${esc(params[name])}">`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect AgentPlanner</title>
+<style>
+  body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#0f1115;color:#e7e9ee;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+  .card{background:#171a21;border:1px solid #262b36;border-radius:14px;padding:32px;width:360px;box-shadow:0 10px 40px rgba(0,0,0,.4)}
+  h1{font-size:18px;margin:0 0 4px}p{color:#9aa3b2;font-size:13px;margin:0 0 20px;line-height:1.5}
+  label{display:block;font-size:12px;color:#9aa3b2;margin:14px 0 6px}
+  input[type=email],input[type=password]{width:100%;box-sizing:border-box;padding:10px 12px;background:#0f1115;border:1px solid #2b3140;border-radius:8px;color:#e7e9ee;font-size:14px}
+  button{margin-top:22px;width:100%;padding:11px;background:#e0a96d;color:#1a1205;border:0;border-radius:8px;font-weight:600;font-size:14px;cursor:pointer}
+  .err{background:#3a1d1d;border:1px solid #6b2b2b;color:#f3b6b6;padding:9px 12px;border-radius:8px;font-size:12px;margin-bottom:14px}
+  .grant{color:#cfd5e1;font-size:12px;margin-top:16px}.grant b{color:#e7e9ee}
+</style></head><body>
+<div class="card">
+  <h1>Connect AgentPlanner</h1>
+  <p><b>${esc(clientName)}</b> wants to access your AgentPlanner plans, goals, and knowledge on your behalf.</p>
+  ${error ? `<div class="err">${esc(error)}</div>` : ''}
+  <form method="POST" action="/oauth/consent">
+    ${hidden('client_id')}${hidden('redirect_uri')}${hidden('code_challenge')}${hidden('code_challenge_method')}${hidden('state')}${hidden('scope')}${hidden('resource')}
+    <label for="email">Email</label>
+    <input id="email" name="email" type="email" autocomplete="username" required>
+    <label for="password">Password</label>
+    <input id="password" name="password" type="password" autocomplete="current-password" required>
+    <button type="submit">Sign in &amp; authorize</button>
+  </form>
+  <div class="grant">Signing in authorizes this connection only. You can disconnect <b>${esc(clientName)}</b> anytime from its connector settings, or from AgentPlanner → Settings → Connections.</div>
+</div></body></html>`;
+}
+// Builds the POST /oauth/consent handler. `apiUrl` is the AgentPlanner REST base.
+function makeConsentHandler({ store, apiUrl }) {
+  return async (req, res) => {
+    const b = req.body || {};
+    const params = {
+      client_id: b.client_id,
+      redirect_uri: b.redirect_uri,
+      code_challenge: b.code_challenge,
+      code_challenge_method: b.code_challenge_method,
+      state: b.state,
+      scope: b.scope,
+      resource: b.resource,
+    };
+    const client = await store.getClient(b.client_id);
+    if (!client) {
+      return res.status(400).send('Unknown client.');
+    }
+    // Defense-in-depth: redirect_uri must be one the client registered.
+    if (!Array.isArray(client.redirect_uris) || !client.redirect_uris.includes(b.redirect_uri)) {
+      return res.status(400).send('Invalid redirect_uri.');
+    }
+    let session;
+    try {
+      const resp = await axios.post(`${apiUrl}/auth/login`, { email: b.email, password: b.password }, { timeout: 10000 });
+      session = resp.data?.session;
+      var userId = resp.data?.user?.id;
+    } catch (err) {
+      const msg = err.response?.status === 401 ? 'Invalid email or password.' : 'Sign-in failed. Please try again.';
+      return res.status(200).send(renderConsentPage(params, { clientName: client.client_name, error: msg }));
+    }
+    if (!session?.access_token) {
+      return res.status(200).send(renderConsentPage(params, { clientName: client.client_name, error: 'Sign-in failed. Please try again.' }));
+    }
+    const code = await store.createCode({
+      clientId: b.client_id,
+      codeChallenge: b.code_challenge,
+      redirectUri: b.redirect_uri,
+      scopes: (b.scope || '').split(' ').filter(Boolean),
+      userId,
+    });
+    const url = new URL(b.redirect_uri);
+    url.searchParams.set('code', code);
+    if (b.state) url.searchParams.set('state', b.state);
+    return res.redirect(302, url.toString());
+  };
+}
+module.exports = { renderConsentPage, makeConsentHandler, esc };

package/src/oauth/provider.js ADDED Viewed

@@ -0,0 +1,99 @@
+/**
+ * OAuthServerProvider for the hosted MCP authorization server.
+ *
+ * Plugs into the MCP SDK's mcpAuthRouter (discovery metadata, DCR, /authorize,
+ * /token, /revoke, PKCE validation). Persistence is delegated to the backend
+ * via BackendOAuthStore.
+ *
+ * Token model: the OAuth access_token is a short-lived (1h) AgentPlanner JWT
+ * minted from the consenting user (validated statelessly on /mcp). The refresh
+ * token is opaque, revocable, and bound to the client — backed by the backend's
+ * oauth_refresh_tokens table. Revoking it kills the connection within the
+ * access-token TTL. No AP credential is stored at rest.
+ */
+const { renderConsentPage } = require('./consent');
+class ApOAuthProvider {
+  constructor({ store }) {
+    this._store = store;
+    this.clientsStore = {
+      getClient: (clientId) => this._store.getClient(clientId),
+      registerClient: (client) => this._store.registerClient(client),
+    };
+  }
+  // Render the consent/login page. mcpAuthRouter's /authorize handler has
+  // already validated redirect_uri against the registered client.
+  async authorize(client, params, res) {
+    res.status(200).set('Content-Type', 'text/html').send(renderConsentPage({
+      client_id: client.client_id,
+      redirect_uri: params.redirectUri,
+      code_challenge: params.codeChallenge,
+      code_challenge_method: 'S256',
+      state: params.state,
+      scope: (params.scopes || []).join(' '),
+      resource: params.resource ? params.resource.toString() : '',
+    }, { clientName: client.client_name }));
+  }
+  async challengeForAuthorizationCode(client, authorizationCode) {
+    const rec = await this._store.getCode(authorizationCode);
+    if (!rec || rec.clientId !== client.client_id) {
+      throw new Error('invalid_grant: unknown authorization code');
+    }
+    return rec.codeChallenge;
+  }
+  // Backend consume validates client/redirect/PKCE-bound code, mints + returns
+  // the token set (short-lived access JWT + opaque, revocable refresh token).
+  async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri) {
+    const tokens = await this._store.consumeCode(authorizationCode, {
+      clientId: client.client_id,
+      redirectUri,
+    });
+    if (!tokens || !tokens.access_token) {
+      throw new Error('invalid_grant: authorization code is invalid or expired');
+    }
+    return tokens;
+  }
+  // Rotate the opaque refresh token (bound to client_id) for a fresh token set.
+  async exchangeRefreshToken(client, refreshToken, _scopes) {
+    const tokens = await this._store.refresh(refreshToken, client.client_id);
+    if (!tokens || !tokens.access_token) {
+      throw new Error('invalid_grant: refresh token is invalid or expired');
+    }
+    return tokens;
+  }
+  // RFC 7009 revocation — revoke the (opaque) refresh token, killing the
+  // connection. Enables /oauth/revoke so connectors can disconnect.
+  async revokeToken(_client, request) {
+    if (request?.token) await this._store.revoke(request.token);
+  }
+  // Access tokens are AP JWTs; the MCP doesn't hold JWT_SECRET, so this is a
+  // structural/expiry decode only — the AP API performs real validation when it
+  // receives the JWT. /mcp itself uses the server-http auth middleware, not this.
+  async verifyAccessToken(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3) throw new Error('invalid_token');
+    let payload;
+    try {
+      payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    } catch {
+      throw new Error('invalid_token');
+    }
+    if (payload.exp && payload.exp * 1000 < Date.now()) throw new Error('invalid_token: expired');
+    return {
+      token,
+      clientId: payload.client_id || 'agentplanner',
+      scopes: ['agentplanner'],
+      expiresAt: payload.exp,
+      extra: { apToken: token, userId: payload.sub || payload.userId },
+    };
+  }
+}
+module.exports = { ApOAuthProvider };

package/src/oauth/store.js ADDED Viewed

@@ -0,0 +1,111 @@
+/**
+ * OAuth state store — thin HTTP client over the AgentPlanner backend's
+ * secret-guarded /internal/oauth endpoints. The MCP server has no database of
+ * its own; DCR clients and one-time PKCE codes live in the backend's Postgres.
+ *
+ * There is no token storage: the OAuth access_token is the user's AP JWT, so a
+ * restart never drops authenticated connections.
+ */
+const axios = require('axios');
+// Map a backend (camelCase) client row → the SDK's OAuthClientInformationFull
+// (snake_case) shape that mcpAuthRouter / the provider expect.
+function toSdkClient(row) {
+  if (!row) return undefined;
+  return {
+    client_id: row.clientId,
+    ...(row.clientSecret ? { client_secret: row.clientSecret, client_secret_expires_at: 0 } : {}),
+    client_name: row.clientName || undefined,
+    redirect_uris: row.redirectUris || [],
+    grant_types: row.grantTypes || [],
+    response_types: row.responseTypes || [],
+    scope: row.scope || undefined,
+    token_endpoint_auth_method: row.tokenEndpointAuthMethod || 'client_secret_basic',
+    client_id_issued_at: row.clientIdIssuedAt ? Math.floor(new Date(row.clientIdIssuedAt).getTime() / 1000) : undefined,
+  };
+}
+class BackendOAuthStore {
+  constructor({ apiUrl, internalSecret }) {
+    this.base = `${(apiUrl || 'http://localhost:3000').replace(/\/$/, '')}/internal/oauth`;
+    this.http = axios.create({
+      timeout: 10000,
+      headers: { 'X-Internal-Token': internalSecret || '' },
+    });
+  }
+  async getClient(clientId) {
+    try {
+      const { data } = await this.http.get(`${this.base}/clients/${encodeURIComponent(clientId)}`);
+      return toSdkClient(data);
+    } catch (err) {
+      if (err.response?.status === 404) return undefined;
+      throw err;
+    }
+  }
+  // SDK passes the client minus client_id (snake_case). Backend mints id/secret.
+  async registerClient(client) {
+    const { data } = await this.http.post(`${this.base}/clients`, client);
+    return toSdkClient(data);
+  }
+  // Stores the code bound to the authenticated user (no AP credential at rest).
+  async createCode({ clientId, codeChallenge, redirectUri, scopes, userId }) {
+    const { data } = await this.http.post(`${this.base}/codes`, {
+      client_id: clientId,
+      code_challenge: codeChallenge,
+      redirect_uri: redirectUri,
+      scopes: scopes || [],
+      user_id: userId || null,
+    });
+    return data.code;
+  }
+  // Peek (no consume) for the PKCE challenge lookup.
+  async getCode(code) {
+    try {
+      const { data } = await this.http.get(`${this.base}/codes/${encodeURIComponent(code)}`);
+      return { clientId: data.client_id, codeChallenge: data.code_challenge, redirectUri: data.redirect_uri };
+    } catch (err) {
+      if (err.response?.status === 404) return null;
+      throw err;
+    }
+  }
+  // One-time consume → backend validates client/redirect, mints + returns the
+  // OAuth token set (access JWT + opaque refresh). Null if the code is invalid.
+  async consumeCode(code, { clientId, redirectUri } = {}) {
+    try {
+      const { data } = await this.http.post(`${this.base}/codes/${encodeURIComponent(code)}/consume`, {
+        client_id: clientId,
+        redirect_uri: redirectUri,
+      });
+      return data; // { access_token, token_type, expires_in, refresh_token, scope }
+    } catch (err) {
+      if (err.response?.status === 404 || err.response?.status === 400) return null;
+      throw err;
+    }
+  }
+  // Rotate a refresh token → new token set (bound to client_id).
+  async refresh(refreshToken, clientId) {
+    try {
+      const { data } = await this.http.post(`${this.base}/refresh`, {
+        refresh_token: refreshToken,
+        client_id: clientId,
+      });
+      return data;
+    } catch (err) {
+      if (err.response?.status === 400) return null;
+      throw err;
+    }
+  }
+  // Revoke a refresh token (RFC 7009) — kills the connection.
+  async revoke(token) {
+    await this.http.post(`${this.base}/revoke`, { token });
+  }
+}
+module.exports = { BackendOAuthStore, toSdkClient };

package/src/server-http.js CHANGED Viewed

@@ -17,7 +17,15 @@ const { SessionManager } = require('./session-manager');
 const { setupTools } = require('./tools');
 const { createApiClient } = require('./api-client');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { createOAuthMetadata, mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } = require('@modelcontextprotocol/sdk/server/auth/router.js');
+const { authorizationHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/authorize.js');
+const { tokenHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/token.js');
+const { clientRegistrationHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/register.js');
+const { revocationHandler } = require('@modelcontextprotocol/sdk/server/auth/handlers/revoke.js');
 const { version } = require('../package.json');
+const { BackendOAuthStore } = require('./oauth/store');
+const { ApOAuthProvider } = require('./oauth/provider');
+const { makeConsentHandler } = require('./oauth/consent');
 require('dotenv').config();
 // MCP Protocol Version
@@ -37,6 +45,15 @@ class MCPHTTPServer {
     // Store for pending SSE streams per session
     this.sseStreams = new Map(); // sessionId -> { res, req }
+    // OAuth authorization server (for claude.ai / Claude Design connectors,
+    // which require the MCP OAuth handshake — static ApiKey is rejected there).
+    // The issuer/public origin is where claude.ai reaches the AS endpoints.
+    this.publicBaseUrl = (options.publicBaseUrl || process.env.OAUTH_ISSUER_URL || process.env.PUBLIC_URL || 'https://agentplanner.io').replace(/\/$/, '');
+    this.apiUrl = options.apiUrl || process.env.API_URL || 'http://localhost:3000';
+    this.oauthStore = new BackendOAuthStore({ apiUrl: this.apiUrl, internalSecret: process.env.MCP_INTERNAL_SECRET });
+    this.oauthProvider = new ApOAuthProvider({ store: this.oauthStore, apiUrl: this.apiUrl });
+    this.resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(new URL(`${this.publicBaseUrl}/mcp`));
     // Create Express app
     this.app = express();
@@ -51,15 +68,70 @@ class MCPHTTPServer {
    * Setup Express middleware
    */
   setupMiddleware() {
-    // Parse JSON bodies
+    // Behind nginx: trust the proxy so express-rate-limit (on the OAuth
+    // endpoints) reads the real client IP from X-Forwarded-For instead of
+    // throwing ERR_ERL_UNEXPECTED_X_FORWARDED_FOR.
+    this.app.set('trust proxy', 1);
+    // Parse JSON + urlencoded bodies (OAuth /token uses form encoding; the
+    // consent form posts urlencoded; /register + MCP use JSON).
     this.app.use(express.json());
+    this.app.use(express.urlencoded({ extended: false }));
-    // Logging middleware
+    // Logging middleware — log the request and, on finish, the status (+ the
+    // redirect target for 3xx, which is critical for debugging the OAuth flow).
     this.app.use((req, res, next) => {
       console.error(`${req.method} ${req.path} - ${req.get('MCP-Protocol-Version') || 'no version'}`);
+      res.on('finish', () => {
+        const loc = res.getHeader('location');
+        console.error(`  ↳ ${req.method} ${req.path} → ${res.statusCode}${loc ? ` Location=${loc}` : ''}`);
+      });
       next();
     });
+    // ── OAuth authorization server ───────────────────────────────────────────
+    // Mounted BEFORE the MCP auth/version/origin middleware so the browser- and
+    // connector-facing OAuth endpoints bypass the MCP-protocol checks. Unmatched
+    // paths (e.g. /mcp) fall through to the middleware below.
+    //
+    // The endpoints live under /oauth/* — NOT the SDK's default root paths —
+    // because /register would otherwise collide with the web UI's signup route.
+    // The SDK's mcpAuthRouter hard-codes root-relative endpoint paths, so we
+    // compose it by hand: serve discovery metadata advertising the /oauth/* URLs,
+    // and mount the handlers under /oauth.
+    const issuerUrl = new URL(this.publicBaseUrl);
+    const oauthBase = `${this.publicBaseUrl}/oauth`;
+    const baseMetadata = createOAuthMetadata({ provider: this.oauthProvider, issuerUrl, scopesSupported: ['agentplanner'] });
+    const oauthMetadata = {
+      ...baseMetadata,
+      authorization_endpoint: `${oauthBase}/authorize`,
+      token_endpoint: `${oauthBase}/token`,
+      registration_endpoint: baseMetadata.registration_endpoint ? `${oauthBase}/register` : undefined,
+      revocation_endpoint: baseMetadata.revocation_endpoint ? `${oauthBase}/revoke` : undefined,
+    };
+    // Discovery metadata at the RFC well-known paths (AS metadata at root,
+    // protected-resource at /.well-known/oauth-protected-resource/mcp).
+    this.app.use(mcpAuthMetadataRouter({
+      oauthMetadata,
+      resourceServerUrl: new URL(`${this.publicBaseUrl}/mcp`),
+      scopesSupported: ['agentplanner'],
+      resourceName: 'AgentPlanner',
+    }));
+    // AS endpoints under /oauth/* (matches the advertised metadata URLs).
+    const oauthRouter = express.Router();
+    oauthRouter.use('/authorize', authorizationHandler({ provider: this.oauthProvider }));
+    oauthRouter.use('/token', tokenHandler({ provider: this.oauthProvider }));
+    oauthRouter.post('/consent', makeConsentHandler({ store: this.oauthStore, apiUrl: this.apiUrl }));
+    oauthRouter.use('/register', clientRegistrationHandler({ clientsStore: this.oauthProvider.clientsStore }));
+    // Revocation only if the provider supports it. Access tokens are stateless
+    // AP JWTs (no denylist), so we don't — and the metadata omits the endpoint.
+    if (typeof this.oauthProvider.revokeToken === 'function') {
+      oauthRouter.use('/revoke', revocationHandler({ provider: this.oauthProvider }));
+    }
+    this.app.use('/oauth', oauthRouter);
     // Protocol version validation
     this.app.use((req, res, next) => {
       // Skip version check for health and discovery endpoints
@@ -79,28 +151,39 @@ class MCPHTTPServer {
       next();
     });
-    // Authentication — require Authorization header on /mcp
+    // Authentication — require Authorization header on /mcp.
+    // Three credential types are accepted:
+    //   1. ApiKey <token>      — AP API token (legacy, Desktop/Code/CLI)
+    //   2. Bearer <ap-jwt>     — raw AP JWT (legacy)
+    //   3. Bearer <oauth-tok>  — opaque token issued by our OAuth AS; resolved
+    //                            to the user's AP JWT (claude.ai / Claude Design)
+    // On a missing/invalid token we emit WWW-Authenticate with the protected-
+    // resource metadata URL so OAuth clients can discover the auth server.
     this.app.use((req, res, next) => {
-      if (req.path === '/health' || req.path === '/.well-known/mcp.json') return next();
+      if (req.path === '/health' || req.path.startsWith('/.well-known/')) return next();
+      const unauthorized = (message) => {
+        res.set('WWW-Authenticate', `Bearer resource_metadata="${this.resourceMetadataUrl}"`);
+        return res.status(401).json({ jsonrpc: '2.0', error: { code: -32000, message } });
+      };
       const authHeader = req.get('Authorization');
       if (!authHeader) {
-        return res.status(401).json({
-          jsonrpc: '2.0',
-          error: { code: -32000, message: 'Authorization header required. Use "Authorization: Bearer <token>" or "Authorization: ApiKey <token>".' }
-        });
+        return unauthorized('Authorization required. Use OAuth (add AgentPlanner as a connector) or "Authorization: ApiKey <token>".');
       }
       const parts = authHeader.split(' ');
       if (parts.length !== 2 || !['Bearer', 'ApiKey'].includes(parts[0])) {
-        return res.status(401).json({
-          jsonrpc: '2.0',
-          error: { code: -32000, message: 'Invalid Authorization format. Use "Bearer <token>" or "ApiKey <token>".' }
-        });
+        return unauthorized('Invalid Authorization format. Use "Bearer <token>" or "ApiKey <token>".');
       }
-      // Store the raw token for per-session API client creation
-      req.userToken = parts[1];
+      const [, token] = parts;
+      // The token is an AP credential: an API key, a raw AP JWT, or an
+      // OAuth-issued access token (which IS an AP JWT — see oauth/provider.js).
+      // All three are passed straight to the per-session API client; the AP API
+      // validates JWTs/keys. No separate OAuth token store to consult.
+      req.userToken = token;
       next();
     });

package/src/tools/bdi/beliefs.js CHANGED Viewed

@@ -463,8 +463,10 @@ async function listPlansHandler(args, apiClient) {
       const q = filter.query.toLowerCase();
       plans = plans.filter((p) => (p.title || '').toLowerCase().includes(q));
     }
-    plans = plans.slice(0, filter.limit || 50);
+    // Summarize the FULL filtered set BEFORE paginating — otherwise `total` and
+    // the status counts only reflect the truncated page, making an agent think
+    // it has seen every plan when it hasn't.
     const summary = plans.reduce(
       (acc, p) => {
         acc[p.status] = (acc[p.status] || 0) + 1;
@@ -474,10 +476,15 @@ async function listPlansHandler(args, apiClient) {
       { total: 0 },
     );
+    const limit = filter.limit || 50;
+    const page = plans.slice(0, limit);
+    summary.returned = page.length;
+    summary.truncated = plans.length > page.length; // true → raise `filter.limit` to see the rest
     return formatResponse({
       as_of: asOf(),
       summary,
-      plans: plans.map((p) => ({
+      plans: page.map((p) => ({
         id: p.id,
         title: p.title,
         status: p.status,
@@ -537,7 +544,16 @@ async function searchHandler(args, apiClient) {
       result = await apiClient.search.searchPlan(scope_id, query);
     } else {
       const global = await apiClient.search.globalSearch(query);
-      const all = Array.isArray(global?.results) ? global.results : [];
+      // The backend returns `results` as a GROUPED object
+      // ({ plans, nodes, comments, logs }), not a flat array — so the old
+      // `Array.isArray(results) ? … : []` always fell to [] and global search
+      // returned nothing. Flatten both shapes.
+      const r = global?.results;
+      const all = Array.isArray(r)
+        ? r
+        : r && typeof r === 'object'
+          ? [...(r.plans || []), ...(r.nodes || []), ...(r.comments || []), ...(r.logs || [])]
+          : [];
       const matchScope = (r) => {
         if (scope === 'global') return true;
         if (scope === 'plans') return r.type === 'plan';

package/src/tools/bdi/utility.js CHANGED Viewed

@@ -29,11 +29,20 @@ async function getStartedHandler(args) {
       "Each tool answers one whole agentic question and returns an `as_of` timestamp.",
     tools_by_namespace: {
       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'],
+      desires: ['list_goals', 'create_goal', 'update_goal', 'derive_subgoal'],
+      intentions: ['form_intention', 'extend_intention', 'link_intentions', 'propose_research_chain', 'claim_next_task', 'update_task', 'update_node', 'release_task', 'queue_decision', 'resolve_decision', 'add_learning'],
       workspaces: ['list_workspaces', 'create_workspace', 'list_blueprints', 'fork_blueprint', 'save_as_blueprint'],
     },
     recommended_workflows: [
+      {
+        name: 'Set up new work a human asked for',
+        steps: [
+          'list_goals / recall_knowledge — check what already exists',
+          'create_goal(...) — create the goal directly (status active). Agents create goals; there is no UI step or approval gate when a human asked.',
+          'form_intention(goal_id, nodes with ref + depends_on) — create the plan + task tree atomically, with execution order declared inline',
+          'Then execute it: claim_next_task → update_task',
+        ],
+      },
       {
         name: 'Mission control loop (Cowork autopilot or scheduled task)',
         steps: [
@@ -62,6 +71,7 @@ async function getStartedHandler(args) {
       },
     ],
     key_principles: [
+      'Agents create goals AND plans, not just execute — when a human asks you to set something up, use create_goal / form_intention directly (no UI round-trip, no approval gate). The UI is for human oversight, not the only way to create work.',
       '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)',