@kammcs/buildit-mcp 0.2.0 → 0.8.0

package/dist/config.js

@@ -5,25 +5,46 @@
  * environment (a flag would be visible to other processes), and no message
  * produced here ever contains it.
  */
+import { basename, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
+import { parseCapabilitiesOption } from './capabilities.js';
 import { LOG_LEVELS, scrubString } from './log.js';
 import { DEFAULT_TOOLSETS, isToolsetName, TOOLSET_NAMES, } from './toolsets/toolsets.js';
 export const DEFAULT_API_URL = 'https://api.buildit.social/functions/v1/agent-api';
 export const DEFAULT_HTTP_HOST = '127.0.0.1';
 export const DEFAULT_HTTP_PORT = 8765;
+export const DEFAULT_ASK_TIMEOUT_MINUTES = 60;
+export const DEFAULT_APPROVAL_TIMEOUT_MINUTES = 60;
+export const DEFAULT_MAX_PARALLEL_ITEMS = 3;
 export class ConfigError extends Error {
     name = 'ConfigError';
 }
 export const USAGE = `Usage: buildit-mcp [options]
+       buildit-mcp connect --project <KEY> [--label <name>] [--folder <path>] [--api-url <url>]
+       buildit-mcp disconnect [--folder <path>] [--api-url <url>]
+       buildit-mcp status [--folder <path>] [--api-url <url>]
 
 An MCP server for buildIt.Social. By default it serves one person over stdio,
 with the personal access token in the BUILDIT_TOKEN environment variable.
+With --channel it is also a Claude Code channel: the messages its owner sends
+to the agent in buildIt.Social arrive in the Claude Code session, which
+answers with the reply tool. Its token is the session token that
+"buildit-mcp connect" saved for the folder (or BUILDIT_TOKEN).
+
+Commands (run them in a terminal, in the folder where Claude Code runs):
+  connect                   Connect this folder to buildIt.Social as an agent
+                            session: shows a code to approve in the app, then
+                            saves the session token in the OS keychain
+  disconnect                Forget this folder's saved session
+  status                    Show this folder's session
+  Run "buildit-mcp <command> --help" for a command's options.
 
 Options (each also has an environment variable):
   --api-url <url>           BUILDIT_API_URL           Agent API base URL
                                                       (default ${DEFAULT_API_URL})
   --toolsets <list>         BUILDIT_TOOLSETS          Comma-separated toolsets, or "all"
-                                                      (default ${DEFAULT_TOOLSETS.join(',')};
+                                                      (default ${DEFAULT_TOOLSETS.join(',')}, or all
+                                                      with --channel;
                                                       known: ${TOOLSET_NAMES.join(', ')})
   --read-only               BUILDIT_READ_ONLY=true    Only list tools that change nothing
   --exclude-tools <list>    BUILDIT_EXCLUDE_TOOLS     Comma-separated tool names to hide
@@ -33,6 +54,29 @@ Options (each also has an environment variable):
   --port <port>             BUILDIT_PORT              HTTP port (default ${DEFAULT_HTTP_PORT})
   --allowed-hosts <list>    BUILDIT_ALLOWED_HOSTS     Hostnames accepted in the Host header
   --allowed-origins <list>  BUILDIT_ALLOWED_ORIGINS   Hostnames accepted in the Origin header
+  --channel                 BUILDIT_CHANNEL=true      Claude Code channel mode (stdio only)
+  --folder <path>           BUILDIT_FOLDER            The folder whose saved session --channel uses
+                                                      (default: the working directory)
+  --from-plugin                                       --channel: started by the buildit plugin, which
+                                                      Claude Code registers as the channel (the
+                                                      plugin passes it)
+                            BUILDIT_QUESTIONS_IN_APP  --channel: the plugin's question hook asks in
+                                                      buildIt.Social (default true)
+                            BUILDIT_ASK_TIMEOUT_MINUTES
+                                                      --channel: how long a question card waits,
+                                                      1 to 60 (default 60)
+                            BUILDIT_MAX_PARALLEL_ITEMS
+                                                      --channel with the plugin: how many work items
+                                                      are worked on at once, 1 to 10 (default 3)
+                            BUILDIT_APPROVALS_IN_APP  --channel: the plugin's permission hook asks to
+                                                      approve tool calls in buildIt.Social too
+                                                      (default true)
+                            BUILDIT_APPROVAL_TIMEOUT_MINUTES
+                                                      --channel: how long a tool approval card waits,
+                                                      1 to 60 (default 60)
+                            BUILDIT_CAPABILITIES      --channel: the capability tags the session
+                                                      suggests when it starts (macos,ios, or none),
+                                                      instead of detecting them
   --allow-any-host          BUILDIT_ALLOW_ANY_HOST=true
                                                       Off loopback, serve without checking the
                                                       Host header (otherwise BUILDIT_ALLOWED_HOSTS
@@ -43,6 +87,60 @@ Options (each also has an environment variable):
 The token is never accepted as a flag. In stdio mode set BUILDIT_TOKEN; in HTTP
 mode every request carries its own "Authorization: Bearer <token>" header.
 `;
+export const COMMAND_USAGE = {
+    connect: `Usage: buildit-mcp connect --project <KEY> [options]
+
+Connects this folder to buildIt.Social as a session of your personal agent,
+for Claude Code's channel mode (buildit-mcp --channel). It shows a code and a
+link: open the link, check the code, and approve in buildIt.Social. The
+session token is then saved in the OS keychain for this folder and API.
+
+Options:
+  --project <KEY>           A project the session may reach (repeat it, or
+                            separate keys with commas; 1 to 10)
+  --label <name>            The session's name in buildIt.Social, 1 to 40
+                            characters (default: the folder's name)
+  --folder <path>           The folder (default: the working directory)
+  --api-url <url>           BUILDIT_API_URL  Agent API base URL
+                            (default ${DEFAULT_API_URL})
+  --capabilities <tags>     The capability tags to suggest (macos,ios), or
+                            none, instead of detecting them. Detection looks
+                            at the operating system and for known programs
+                            (flutter, docker, cargo, adb, Xcode) without
+                            running them, and sends only the tag names
+  --yes                     Save without asking "Is this you?" once it is
+                            approved. For scripts only: unsafe if anyone else
+                            could have seen the code, since whoever approves
+                            it gets the session
+  -h, --help                Show this help
+
+Once approved, it says who approved it (the agent, its owner, the org, the
+projects) and asks "Is this you?"; only "y" saves the token, and any other
+answer cancels the session.
+`,
+    disconnect: `Usage: buildit-mcp disconnect [options]
+
+Cancels this folder's session in buildIt.Social and forgets its saved token.
+If buildIt.Social can't be reached, the token is forgotten anyway: revoke
+the session in the app then.
+
+Options:
+  --folder <path>           The folder (default: the working directory)
+  --api-url <url>           BUILDIT_API_URL  Agent API base URL
+  -h, --help                Show this help
+`,
+    status: `Usage: buildit-mcp status [options]
+
+Shows the session saved for this folder: its agent, name, org and reach, and
+whether buildIt.Social still accepts it.
+
+Options:
+  --folder <path>           The folder (default: the working directory)
+  --api-url <url>           BUILDIT_API_URL  Agent API base URL
+  -h, --help                Show this help
+`,
+};
+const SESSION_COMMANDS = ['connect', 'disconnect', 'status'];
 const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
 const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
 export function parseBoolean(name, raw, fallback) {
@@ -55,6 +153,73 @@ export function parseBoolean(name, raw, fallback) {
         return false;
     throw new ConfigError(`${name} must be true or false (got "${raw}").`);
 }
+/**
+ * The plugin's settings arrive as environment variables it fills in, so a
+ * value that is empty or doesn't parse keeps the default, with a warning,
+ * instead of stopping the server.
+ */
+function parseAsk(env, warnings) {
+    let questionsInApp = true;
+    const rawIn = env.BUILDIT_QUESTIONS_IN_APP?.trim() ?? '';
+    if (rawIn !== '') {
+        const value = rawIn.toLowerCase();
+        if (TRUE_VALUES.has(value))
+            questionsInApp = true;
+        else if (FALSE_VALUES.has(value))
+            questionsInApp = false;
+        else
+            warnings.push('BUILDIT_QUESTIONS_IN_APP is not true or false; questions go to buildIt.Social.');
+    }
+    let timeoutMinutes = DEFAULT_ASK_TIMEOUT_MINUTES;
+    const rawMinutes = env.BUILDIT_ASK_TIMEOUT_MINUTES?.trim() ?? '';
+    if (rawMinutes !== '') {
+        const n = Number(rawMinutes);
+        if (Number.isFinite(n) && n >= 1 && n <= 60) {
+            timeoutMinutes = Math.floor(n);
+        }
+        else {
+            warnings.push(`BUILDIT_ASK_TIMEOUT_MINUTES must be 1 to 60; using ${DEFAULT_ASK_TIMEOUT_MINUTES}.`);
+        }
+    }
+    let maxParallelItems = DEFAULT_MAX_PARALLEL_ITEMS;
+    const rawParallel = env.BUILDIT_MAX_PARALLEL_ITEMS?.trim() ?? '';
+    if (rawParallel !== '') {
+        const n = Number(rawParallel);
+        if (Number.isFinite(n) && n >= 1 && n <= 10) {
+            maxParallelItems = Math.floor(n);
+        }
+        else {
+            warnings.push(`BUILDIT_MAX_PARALLEL_ITEMS must be 1 to 10; using ${DEFAULT_MAX_PARALLEL_ITEMS}.`);
+        }
+    }
+    return { questionsInApp, timeoutMinutes, maxParallelItems };
+}
+/** The tool approval settings, read as the question settings are (a bad value keeps the default). */
+function parseApprovals(env, warnings) {
+    let inApp = true;
+    const rawIn = env.BUILDIT_APPROVALS_IN_APP?.trim() ?? '';
+    if (rawIn !== '') {
+        const value = rawIn.toLowerCase();
+        if (TRUE_VALUES.has(value))
+            inApp = true;
+        else if (FALSE_VALUES.has(value))
+            inApp = false;
+        else
+            warnings.push('BUILDIT_APPROVALS_IN_APP is not true or false; tool approvals go to buildIt.Social.');
+    }
+    let timeoutMinutes = DEFAULT_APPROVAL_TIMEOUT_MINUTES;
+    const rawMinutes = env.BUILDIT_APPROVAL_TIMEOUT_MINUTES?.trim() ?? '';
+    if (rawMinutes !== '') {
+        const n = Number(rawMinutes);
+        if (Number.isFinite(n) && n >= 1 && n <= 60) {
+            timeoutMinutes = Math.floor(n);
+        }
+        else {
+            warnings.push(`BUILDIT_APPROVAL_TIMEOUT_MINUTES must be 1 to 60; using ${DEFAULT_APPROVAL_TIMEOUT_MINUTES}.`);
+        }
+    }
+    return { inApp, timeoutMinutes };
+}
 function splitList(raw) {
     return [
         ...new Set(raw
@@ -90,6 +255,24 @@ const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 export function isLoopbackHost(host) {
     return LOOPBACK_HOSTS.has(host.toLowerCase());
 }
+/** The agent API's path on a buildIt.Social host. */
+export const AGENT_API_PATH = '/functions/v1/agent-api';
+/**
+ * The note shown once when an API address is a bare host (no path), which
+ * parseApiUrl completes with the agent API's path; undefined otherwise.
+ */
+export function apiUrlNote(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        if (new URL(raw.trim()).pathname !== '/')
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return `The API address ${raw.trim()} has no path, so buildit-mcp uses ${parseApiUrl(raw)}, the agent API on that host.`;
+}
 export function parseApiUrl(raw) {
     let url;
     try {
@@ -108,6 +291,9 @@ export function parseApiUrl(raw) {
     if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
         throw new ConfigError('BUILDIT_API_URL must use https:// (plain http:// is only allowed for localhost).');
     }
+    // A bare host means its agent API.
+    if (url.pathname === '/')
+        url.pathname = AGENT_API_PATH;
     return url.toString().replace(/\/+$/, '');
 }
 const HOSTNAME = /^(\[[0-9a-f:.]+\]|[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)$/;
@@ -166,15 +352,134 @@ function parseLogLevel(raw) {
 function nonEmpty(value) {
     return value === undefined || value.trim() === '' ? undefined : value;
 }
+const PROJECT_KEY = /^[A-Za-z][A-Za-z0-9]{1,5}$/;
+export const LABEL_MAX_CHARS = 40;
+/** Control, direction and zero-width characters (a RegExp character class), which a session label may not hold. */
+export const FORBIDDEN_CHARS = '[\\u0000-\\u001F\\u007F-\\u009F\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2069\\uFEFF]';
+/** Project keys from --project flags (each may list several, comma-separated). */
+export function parseProjects(values) {
+    const keys = [...new Set(values.flatMap((v) => splitList(v)).map((k) => k.toUpperCase()))];
+    if (keys.length === 0) {
+        throw new ConfigError('Name the project the session may reach with --project <KEY>, for example --project DEMO.');
+    }
+    const bad = keys.filter((k) => !PROJECT_KEY.test(k));
+    if (bad.length > 0) {
+        throw new ConfigError(`Not a project key: ${bad.join(', ')}. Keys are 2 to 6 letters and digits, starting with a letter (for example DEMO).`);
+    }
+    if (keys.length > 10)
+        throw new ConfigError('A session may reach at most 10 projects.');
+    return keys;
+}
+/** --capabilities or BUILDIT_CAPABILITIES, checked (ConfigError names what is wrong). */
+function capabilitiesOption(raw, what) {
+    try {
+        return parseCapabilitiesOption(raw);
+    }
+    catch (err) {
+        throw new ConfigError(`${what}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** The --label given, checked; or the folder's name, made to fit. */
+export function sessionLabel(raw, folder) {
+    if (raw !== undefined) {
+        const label = raw.trim();
+        if (label.length === 0 || Array.from(label).length > LABEL_MAX_CHARS) {
+            throw new ConfigError(`The label must be 1 to ${LABEL_MAX_CHARS} characters.`);
+        }
+        if (new RegExp(FORBIDDEN_CHARS, 'u').test(label)) {
+            throw new ConfigError('The label may not hold control, direction or invisible characters.');
+        }
+        return label;
+    }
+    const name = Array.from(basename(folder).replace(new RegExp(FORBIDDEN_CHARS, 'gu'), '').trim())
+        .slice(0, LABEL_MAX_CHARS)
+        .join('')
+        .trim();
+    return name.length > 0 ? name : 'session';
+}
+/** The folder a session belongs to: --folder, else BUILDIT_FOLDER, else the working directory. */
+function folderOf(flag, env, cwd) {
+    const raw = typeof flag === 'string' ? flag : nonEmpty(env.BUILDIT_FOLDER);
+    if (raw !== undefined && raw.trim() === '')
+        throw new ConfigError('--folder must not be empty.');
+    return resolve(cwd, raw?.trim() ?? '.');
+}
+function parseSessionCommand(command, argv, env, cwd, secrets) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: [...argv],
+            strict: true,
+            allowPositionals: false,
+            options: {
+                'api-url': { type: 'string' },
+                folder: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+                ...(command === 'connect'
+                    ? {
+                        project: { type: 'string', multiple: true },
+                        label: { type: 'string' },
+                        capabilities: { type: 'string' },
+                        yes: { type: 'boolean' },
+                    }
+                    : {}),
+            },
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ConfigError(`${scrubString(message, secrets)} Run "buildit-mcp ${command} --help" for the options.`);
+    }
+    if (values.help === true)
+        return { kind: 'help', command };
+    const apiFlag = values['api-url'];
+    const apiRaw = (typeof apiFlag === 'string' ? apiFlag : nonEmpty(env.BUILDIT_API_URL)) ?? DEFAULT_API_URL;
+    const apiUrl = parseApiUrl(apiRaw);
+    const note = apiUrlNote(apiRaw);
+    const folder = folderOf(values.folder, env, cwd);
+    if (command !== 'connect') {
+        return {
+            kind: command,
+            options: {
+                apiUrl,
+                folder,
+                apiUrlFlag: typeof apiFlag === 'string',
+                ...(note === undefined ? {} : { apiUrlNote: note }),
+            },
+        };
+    }
+    const projectFlags = values.project;
+    const projects = parseProjects(Array.isArray(projectFlags) ? projectFlags : []);
+    const label = sessionLabel(typeof values.label === 'string' ? values.label : undefined, folder);
+    const capabilities = typeof values.capabilities === 'string'
+        ? capabilitiesOption(values.capabilities, '--capabilities')
+        : undefined;
+    return {
+        kind: 'connect',
+        options: {
+            apiUrl,
+            folder,
+            projects,
+            label,
+            yes: values.yes === true,
+            ...(capabilities === undefined ? {} : { capabilities }),
+            ...(note === undefined ? {} : { apiUrlNote: note }),
+        },
+    };
+}
 /**
  * Parses flags and environment variables. Throws ConfigError with a message
  * that is safe to print (it never contains the token).
  */
-export function parseCli(argv, env) {
+export function parseCli(argv, env, cwd = process.cwd()) {
     const secrets = env.BUILDIT_TOKEN ? [env.BUILDIT_TOKEN] : [];
     if (argv.some((a) => a === '--token' || a.startsWith('--token='))) {
         throw new ConfigError('The token is never accepted as a flag (other processes can read flags). Set the BUILDIT_TOKEN environment variable instead.');
     }
+    const command = SESSION_COMMANDS.find((c) => c === argv[0]);
+    if (command !== undefined) {
+        return parseSessionCommand(command, argv.slice(1), env, cwd, secrets);
+    }
     let values;
     try {
         ({ values } = parseArgs({
@@ -193,6 +498,9 @@ export function parseCli(argv, env) {
                 'allowed-hosts': { type: 'string' },
                 'allowed-origins': { type: 'string' },
                 'allow-any-host': { type: 'boolean' },
+                channel: { type: 'boolean' },
+                folder: { type: 'string' },
+                'from-plugin': { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'v' },
             },
@@ -213,9 +521,23 @@ export function parseCli(argv, env) {
     const warnings = [];
     const http = values.http === true || parseBoolean('BUILDIT_HTTP', env.BUILDIT_HTTP, false);
     const mode = http ? 'http' : 'stdio';
-    const apiUrl = parseApiUrl(str('api-url', 'BUILDIT_API_URL') ?? DEFAULT_API_URL);
+    const channelMode = values.channel === true || parseBoolean('BUILDIT_CHANNEL', env.BUILDIT_CHANNEL, false);
+    if (channelMode && mode === 'http') {
+        throw new ConfigError('Channel mode (--channel) runs over stdio only: Claude Code starts it as a local server.');
+    }
+    const apiRaw = str('api-url', 'BUILDIT_API_URL') ?? DEFAULT_API_URL;
+    const apiUrl = parseApiUrl(apiRaw);
+    const apiNote = apiUrlNote(apiRaw);
+    if (apiNote !== undefined)
+        warnings.push(apiNote);
     const toolsetsRaw = str('toolsets', 'BUILDIT_TOOLSETS');
-    const toolsets = toolsetsRaw === undefined ? [...DEFAULT_TOOLSETS] : parseToolsets(toolsetsRaw);
+    // Channel mode turns every toolset on by default: approvals need destructive and admin (the
+    // session's own scopes still limit what works).
+    const toolsets = toolsetsRaw === undefined
+        ? channelMode
+            ? [...TOOLSET_NAMES]
+            : [...DEFAULT_TOOLSETS]
+        : parseToolsets(toolsetsRaw);
     const readOnly = values['read-only'] === true || parseBoolean('BUILDIT_READ_ONLY', env.BUILDIT_READ_ONLY, false);
     const excludeRaw = str('exclude-tools', 'BUILDIT_EXCLUDE_TOOLS');
     const excludeTools = excludeRaw === undefined ? [] : parseToolNames(excludeRaw, 'BUILDIT_EXCLUDE_TOOLS');
@@ -236,8 +558,33 @@ export function parseCli(argv, env) {
         httpConfig.allowedOrigins = parseHostList(originsRaw, 'BUILDIT_ALLOWED_ORIGINS', true);
     }
     let token;
+    let channel;
     const rawToken = env.BUILDIT_TOKEN;
-    if (mode === 'stdio') {
+    if (channelMode) {
+        channel = {
+            folder: folderOf(values.folder, env, cwd),
+            tokenSource: 'store',
+            apiUrlFlag: typeof values['api-url'] === 'string',
+            fromPlugin: values['from-plugin'] === true || nonEmpty(env.CLAUDE_PLUGIN_ROOT) !== undefined,
+        };
+        const rawCapabilities = nonEmpty(env.BUILDIT_CAPABILITIES);
+        if (rawCapabilities !== undefined) {
+            channel.capabilities = capabilitiesOption(rawCapabilities, 'BUILDIT_CAPABILITIES');
+        }
+        const envToken = rawToken?.trim() ?? '';
+        if (envToken.startsWith('buildit_ags_')) {
+            if (/\s/.test(envToken)) {
+                throw new ConfigError('BUILDIT_TOKEN contains whitespace; check that it was copied whole.');
+            }
+            token = envToken;
+            channel.tokenSource = 'env';
+        }
+        else if (envToken !== '') {
+            // A user-level personal access token from the usual setup: the folder's session wins.
+            warnings.push('BUILDIT_TOKEN is not a session token, so channel mode ignores it and uses the session that "buildit-mcp connect" saved for the folder.');
+        }
+    }
+    else if (mode === 'stdio') {
         if (rawToken === undefined || rawToken.trim() === '') {
             throw new ConfigError('BUILDIT_TOKEN is not set. Create a personal access token in buildIt.Social and put it in the BUILDIT_TOKEN environment variable (never in a file you commit).');
         }
@@ -245,7 +592,7 @@ export function parseCli(argv, env) {
         if (/\s/.test(token)) {
             throw new ConfigError('BUILDIT_TOKEN contains whitespace; check that it was copied whole.');
         }
-        if (!token.startsWith('buildit_pat_')) {
+        if (!token.startsWith('buildit_pat_') && !token.startsWith('buildit_ags_')) {
             warnings.push('BUILDIT_TOKEN does not start with "buildit_pat_"; buildIt.Social personal access tokens do.');
         }
     }
@@ -269,6 +616,9 @@ export function parseCli(argv, env) {
             mode,
             apiUrl,
             ...(token === undefined ? {} : { token }),
+            ...(channel === undefined ? {} : { channel }),
+            ask: parseAsk(env, warnings),
+            approvals: parseApprovals(env, warnings),
             toolsets,
             readOnly,
             excludeTools,

package/dist/errors.js

@@ -73,6 +73,15 @@ const NOT_FOUND_HINTS = {
     plan: 'Use a handle a propose_* tool returned in this conversation, or propose the change again.',
     route: 'The API does not serve this call: it may be older than this buildit-mcp. Check BUILDIT_API_URL, or use another tool.',
 };
+/**
+ * The next step for codes whose contract hint names an API operation this
+ * server has no tool for (get_session_handoff): said in this server's terms
+ * instead of the API's hint.
+ */
+const SERVER_HINTS = {
+    handoff_exists: "Don't propose it again: the subtask already has a live handoff (details.handoff_id), whose outcome arrives as event=handoff_resolved.",
+    handoff_closed: 'Nothing more to do with this handoff: its card has already ended.',
+};
 /**
  * Each of the contract's rate-limit buckets, in plain words. A bucket the
  * contract adds later is shown by retry_after alone, as the contract asks.
@@ -83,6 +92,13 @@ const RATE_BUCKETS = {
     token_writes_per_day: 'writes per day for this token',
     org_requests_per_minute: 'requests per minute for the whole org, across all its tokens',
     user_requests_per_minute: 'requests per minute for your account, across all your tokens',
+    session_polls_per_minute: 'polls per minute for this session',
+    session_typing_per_minute: 'typing notices per minute for this session',
+    session_approvals_per_minute: 'tool approval calls per minute for this session',
+    session_handoffs_per_minute: 'handoff calls per minute for this session',
+    connect_starts_per_hour: 'connections started per hour from this address',
+    connect_pending_grants: 'connections waiting for approval on this server',
+    connect_pending_per_address: 'connections waiting for approval from this network',
 };
 /** The release operations, as plan_release's actions. */
 const RELEASE_ACTIONS = {
@@ -284,7 +300,7 @@ export function describeApiError(err) {
     const kindHint = err.code === 'not_found' && typeof details.kind === 'string'
         ? NOT_FOUND_HINTS[details.kind]
         : undefined;
-    const hint = kindHint ?? hintFor(err.code, err.hint);
+    const hint = kindHint ?? SERVER_HINTS[err.code] ?? hintFor(err.code, err.hint);
     if (hint && !(waitShown && RETRY_ADVICE.test(hint))) {
         const text = clean(inServerTerms(hint));
         if (!alreadySaid(text, said)) {
@@ -316,6 +332,38 @@ export function describeApiError(err) {
     return lines.join('\n');
 }
 /** A tool result for any failure inside a tool handler. */
+/** The codes that mean an agent session is over: its token is no longer accepted. */
+export const SESSION_OVER_CODES = new Set([
+    'token_revoked',
+    'token_expired',
+    'token_invalid',
+]);
+const SESSION_OVER_WHY = {
+    token_revoked: 'it was revoked',
+    token_expired: 'it expired after 30 days unused',
+    token_invalid: 'buildIt.Social no longer recognises its token',
+};
+/**
+ * What to tell the agent once a session token is refused for good: a
+ * session is reconnected with `connect`, never with a new personal access
+ * token.
+ */
+export function sessionEndedText(code) {
+    const why = SESSION_OVER_WHY[code] ?? code;
+    return `This buildIt.Social session has ended (${why}). In this folder run \`buildit-mcp connect --project <KEY>\`, approve it, then restart Claude Code. Tell the person; retrying won't help.`;
+}
+/** A tool result for a call made after (or refused because) the session ended. */
+export function sessionEndedResult(code) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `buildit-mcp error: session_ended (${code})\n${sessionEndedText(code)}`,
+            },
+        ],
+    };
+}
 export function toolErrorResult(err, requestId) {
     if (err instanceof ApiError) {
         return { isError: true, content: [{ type: 'text', text: describeApiError(err) }] };