@kammcs/buildit-mcp 0.2.0 → 0.7.0

package/dist/channel/typing.js

@@ -0,0 +1,150 @@
+/**
+ * "<agent> is writing…" in buildIt.Social while Claude works on a message.
+ *
+ * When the loop hands one of the owner's messages to Claude, the thread it
+ * came in starts "working": the server says the agent is typing there at
+ * once (POST /v1/session/typing), and again every 15 seconds (the app shows
+ * it for 30). It stops, with one `typing: false`, when for that thread:
+ * reply posts, ask posts a question card (the card shows the agent waits),
+ * a plan card is posted; for every thread, when the plugin's Stop hook says
+ * Claude's turn ended (the turn_ended tool), after 10 minutes without a
+ * tool call for it, and on shutdown. When the session ends, the timers
+ * just stop (the token no longer works).
+ *
+ * The 10 minutes count per thread: a tool call that names a thread (its
+ * thread_id, or an item's key) is that thread's activity, and a call that
+ * names none counts for the working thread only while there is one. Item
+ * workers run in parallel through this one server, so each item's thread
+ * shows "is writing" while its own worker calls tools, and `work` starts it
+ * again when a worker goes on after a reply.
+ *
+ * It is only a hint: failures are logged, never shown to Claude, and a 429
+ * pauses the beats until its Retry-After has passed.
+ */
+import { ApiError } from '../api/client.js';
+import { sessionTyping } from './api.js';
+/** How often a working thread says so again. */
+export const TYPING_EVERY_MS = 15_000;
+/** A thread stops working after this long without a tool call. */
+export const TYPING_IDLE_MS = 10 * 60_000;
+export class TypingIndicator {
+    options;
+    threads = new Map();
+    /** Each working thread's latest activity. */
+    lastActivity = new Map();
+    everyMs;
+    idleMs;
+    now;
+    /** No beats before this time (after a 429). */
+    quietUntil = 0;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.everyMs = options.everyMs ?? TYPING_EVERY_MS;
+        this.idleMs = options.idleMs ?? TYPING_IDLE_MS;
+        this.now = options.now ?? Date.now;
+    }
+    /** The threads working now (tests). */
+    get working() {
+        return [...this.threads.keys()];
+    }
+    /** A message for Claude arrived in this thread: it is working on it. */
+    start(threadId) {
+        if (this.closed)
+            return;
+        this.lastActivity.set(threadId, this.now());
+        const old = this.threads.get(threadId);
+        if (old !== undefined)
+            clearInterval(old);
+        const timer = setInterval(() => {
+            this.beat(threadId);
+        }, this.everyMs);
+        timer.unref();
+        this.threads.set(threadId, timer);
+        void this.send(threadId, true);
+    }
+    /**
+     * A tool call to this server: Claude is still at work, on that thread
+     * when the call names one, else on the only working thread (with
+     * several, a call that names none keeps none of them going).
+     */
+    activity(threadId) {
+        const now = this.now();
+        if (threadId !== undefined) {
+            if (this.threads.has(threadId))
+                this.lastActivity.set(threadId, now);
+            return;
+        }
+        if (this.threads.size !== 1)
+            return;
+        for (const id of this.threads.keys())
+            this.lastActivity.set(id, now);
+    }
+    /** A worker is at work on this thread: it shows "is writing" again if it had stopped. */
+    work(threadId) {
+        if (this.closed)
+            return;
+        if (this.threads.has(threadId)) {
+            this.lastActivity.set(threadId, this.now());
+            return;
+        }
+        this.start(threadId);
+    }
+    /** Stops one thread (reply, a card posted); nothing when it isn't working. */
+    stop(threadId) {
+        if (threadId === undefined)
+            return;
+        const timer = this.threads.get(threadId);
+        if (timer === undefined)
+            return;
+        clearInterval(timer);
+        this.threads.delete(threadId);
+        this.lastActivity.delete(threadId);
+        void this.send(threadId, false);
+    }
+    /** Stops every thread (the turn ended, or shutdown); the promise settles once they are told. */
+    async stopAll() {
+        const ids = [...this.threads.keys()];
+        for (const timer of this.threads.values())
+            clearInterval(timer);
+        this.threads.clear();
+        this.lastActivity.clear();
+        await Promise.all(ids.map((id) => this.send(id, false)));
+    }
+    /** The session ended: stop every timer, and send nothing more. */
+    close() {
+        this.closed = true;
+        for (const timer of this.threads.values())
+            clearInterval(timer);
+        this.threads.clear();
+    }
+    beat(threadId) {
+        if (this.now() - (this.lastActivity.get(threadId) ?? 0) >= this.idleMs) {
+            this.options.logger.debug('typing stopped: no activity', { thread_id: threadId });
+            this.stop(threadId);
+            return;
+        }
+        if (this.now() < this.quietUntil)
+            return;
+        void this.send(threadId, true);
+    }
+    async send(threadId, typing) {
+        if (this.closed)
+            return;
+        // A stop is sent even while quiet: the app would otherwise show it until its time runs out.
+        if (typing && this.now() < this.quietUntil)
+            return;
+        try {
+            await sessionTyping(this.options.api, { thread_id: threadId, typing }, { tool: 'typing', signal: AbortSignal.timeout(15_000) });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 429) {
+                this.quietUntil = this.now() + Math.max(this.everyMs, (err.retryAfterSeconds ?? 60) * 1000);
+                return;
+            }
+            this.options.logger.debug('typing not sent', {
+                code: err instanceof ApiError ? err.code : 'error',
+            });
+        }
+    }
+}

package/dist/channel/waiters.js

@@ -0,0 +1,229 @@
+/** The longest the loop waits for a waiter to handle one event. */
+export const WAITER_STEP_MS = 10_000;
+/** The card message's id that an event is about, if it names one. */
+export function eventMessageId(event) {
+    const message = event.data.message;
+    if (message === null || typeof message !== 'object')
+        return undefined;
+    const id = message.id;
+    return typeof id === 'string' ? id : undefined;
+}
+/** How many cards' outcomes are remembered for a repeated ask. */
+const REMEMBERED = 500;
+/** A map that forgets its oldest entries past a size. */
+class Bounded {
+    map = new Map();
+    get(key) {
+        return this.map.get(key);
+    }
+    set(key, value) {
+        this.map.delete(key);
+        this.map.set(key, value);
+        if (this.map.size > REMEMBERED) {
+            const oldest = this.map.keys().next().value;
+            if (oldest !== undefined)
+                this.map.delete(oldest);
+        }
+    }
+}
+/**
+ * The waiters of one session, by card message id (several may wait for one
+ * card: the hook can run twice for one question), and what the session's
+ * cards became: the answers accepted, and how each card closed. A repeated
+ * ask for a card that was already answered returns those answers instead
+ * of waiting for events that were handed on (and acknowledged) before.
+ */
+export class CardWaiters {
+    stepMs;
+    waiters = new Map();
+    /** The thread of each card waited on (by message id), as registered. */
+    threads = new Map();
+    answers = new Bounded();
+    closings = new Bounded();
+    verdicts = new Bounded();
+    ended = false;
+    constructor(stepMs = WAITER_STEP_MS) {
+        this.stepMs = stepMs;
+    }
+    /** Whether the session has ended (a new waiter is ended at once). */
+    get isEnded() {
+        return this.ended;
+    }
+    /**
+     * Registers a waiter for a card, in its thread (undefined: a top-level
+     * card); the returned function unregisters it.
+     */
+    register(messageId, waiter, threadId) {
+        let set = this.waiters.get(messageId);
+        if (set === undefined) {
+            set = new Set();
+            this.waiters.set(messageId, set);
+        }
+        set.add(waiter);
+        if (threadId !== undefined)
+            this.threads.set(messageId, threadId);
+        if (this.ended)
+            waiter.end();
+        return () => {
+            const current = this.waiters.get(messageId);
+            if (current === undefined)
+                return;
+            current.delete(waiter);
+            if (current.size === 0) {
+                this.waiters.delete(messageId);
+                this.threads.delete(messageId);
+            }
+        };
+    }
+    has(messageId) {
+        return this.waiters.has(messageId);
+    }
+    /** How many cards are waited on (tests). */
+    get size() {
+        return this.waiters.size;
+    }
+    /** Remembers the answers accepted for a card. */
+    rememberAnswers(messageId, answers) {
+        this.answers.set(messageId, answers);
+    }
+    /** The answers accepted for a card, if this process saw them. */
+    answersOf(messageId) {
+        return this.answers.get(messageId);
+    }
+    /** Remembers how a tool approval ended (the hook's answer for it). */
+    rememberApproval(messageId, verdict) {
+        this.verdicts.set(messageId, verdict);
+    }
+    /**
+     * How a tool approval ended, if this process saw it and it was for this
+     * tool and input: a repeated hook call for the same call gets the same
+     * answer; anything else is unknown.
+     */
+    approvalOf(messageId, toolName, hash) {
+        const verdict = this.verdicts.get(messageId);
+        return verdict !== undefined && verdict.toolName === toolName && verdict.hash === hash
+            ? verdict
+            : undefined;
+    }
+    /** How a card closed (its closed_by), if this process saw it. */
+    closedBy(messageId) {
+        return this.closings.get(messageId);
+    }
+    /**
+     * Hands the event to its card's waiters and waits until they have handled
+     * it, or for at most stepMs. A card.closed is remembered first. False when
+     * no waiter waits for that card.
+     */
+    async deliver(event) {
+        const id = eventMessageId(event);
+        if (id === undefined)
+            return false;
+        if (event.type === 'card.closed') {
+            const by = event.data.closed_by;
+            this.closings.set(id, typeof by === 'string' ? by : 'app');
+        }
+        const set = this.waiters.get(id);
+        if (set === undefined || set.size === 0)
+            return false;
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.stepMs);
+        });
+        try {
+            await Promise.race([
+                Promise.all([...set].map((w) => w.handle(event).catch(() => undefined))),
+                late,
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return true;
+    }
+    /**
+     * The session no longer works in this thread (it was unassigned from the
+     * item): every card waited on there is remembered as closed, and its
+     * waiters stop with `closed`. The server closes the cards itself.
+     */
+    closeThread(threadId) {
+        let closed = 0;
+        for (const [messageId, thread] of [...this.threads]) {
+            if (thread !== threadId)
+                continue;
+            this.closings.set(messageId, 'unassigned');
+            for (const waiter of [...(this.waiters.get(messageId) ?? [])]) {
+                waiter.close();
+                closed++;
+            }
+        }
+        return closed;
+    }
+    /** The session ended for good: every waiter is told, and later ones at once. */
+    endAll() {
+        this.ended = true;
+        for (const set of [...this.waiters.values()])
+            for (const waiter of [...set])
+                waiter.end();
+    }
+}
+/**
+ * A waiter that queues its events, for a loop that takes them one at a
+ * time (`next`) and says when each is handled.
+ */
+export class CardInbox {
+    queue = [];
+    wake;
+    ended = false;
+    closed = false;
+    handle(event) {
+        return new Promise((resolve) => {
+            this.queue.push({ event, done: resolve });
+            this.wake?.();
+        });
+    }
+    end() {
+        this.ended = true;
+        this.wake?.();
+    }
+    close() {
+        this.closed = true;
+        this.wake?.();
+    }
+    /**
+     * The next event, or why there is none: the deadline passed (`timeout`),
+     * the signal aborted, the session ended, or the card's thread closed to
+     * the session (`closed`). Events already queued come first.
+     */
+    async next(deadline, signal, now = Date.now) {
+        for (;;) {
+            const queued = this.queue.shift();
+            if (queued !== undefined)
+                return queued;
+            if (signal?.aborted)
+                return 'aborted';
+            if (this.ended)
+                return 'session_ended';
+            if (this.closed)
+                return 'closed';
+            const left = deadline - now();
+            if (left <= 0)
+                return 'timeout';
+            await new Promise((resolve) => {
+                const timer = setTimeout(done, left);
+                function done() {
+                    clearTimeout(timer);
+                    signal?.removeEventListener('abort', done);
+                    resolve();
+                }
+                this.wake = done;
+                signal?.addEventListener('abort', done, { once: true });
+            });
+            this.wake = undefined;
+        }
+    }
+    /** Says every queued event was handled (when the waiter stops). */
+    drain() {
+        for (const d of this.queue.splice(0))
+            d.done();
+    }
+}

package/dist/channel/workers.js

@@ -0,0 +1,66 @@
+/**
+ * Where the plugin's AskUserQuestion hook posts a question.
+ *
+ * The hook can't name a thread, but Claude Code tells it who is asking:
+ * its input carries `agent_id` and `agent_type` when the tool call comes
+ * from a subagent (both empty for the main agent; checked with Claude Code
+ * 2.1.312, where `agent_type` is the plugin-scoped name, such as
+ * `buildit:buildit-item-worker`, and `agent_id` the id the Agent tool gave
+ * the lead). So:
+ *
+ * - the main agent (the lead) asks in the direct message: its latest
+ *   thread there, else a new message;
+ * - an item worker asks in its item's thread, found in the lead's table of
+ *   workers (`.claude/buildit-workers.json` in the folder, which the lead
+ *   keeps: `{"workers": [{"agent_id", "item", "thread_id"}]}`);
+ * - anything else (another subagent, a worker the table doesn't name) is
+ *   not placed, and the hook lets the terminal ask.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** The lead's table of item workers, relative to the folder. */
+export const WORKERS_FILE = join('.claude', 'buildit-workers.json');
+/** The item worker's agent name (the plugin's agents/buildit-item-worker.md). */
+export const ITEM_WORKER_NAME = 'buildit-item-worker';
+/** The largest table read. */
+const WORKERS_FILE_MAX_BYTES = 256 * 1024;
+/**
+ * Whether the hook's agent_type is the plugin's item worker: exactly its
+ * name, or the name under this plugin (never another plugin's agent of the
+ * same name).
+ */
+export function isItemWorker(agentType) {
+    return agentType === ITEM_WORKER_NAME || agentType === `buildit:${ITEM_WORKER_NAME}`;
+}
+/** The lead's entry for the worker with this agent id, if the table names it. */
+export function workerEntry(folder, agentId) {
+    const path = join(folder, WORKERS_FILE);
+    let parsed;
+    try {
+        if (statSync(path).size > WORKERS_FILE_MAX_BYTES)
+            return undefined;
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const list = Array.isArray(parsed)
+        ? parsed
+        : parsed !== null && typeof parsed === 'object'
+            ? parsed.workers
+            : undefined;
+    if (!Array.isArray(list))
+        return undefined;
+    const str = (v) => typeof v === 'string' && v.trim() !== '' && v.length <= 200 ? v.trim() : undefined;
+    for (const entry of list) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        if (str(e.agent_id) !== agentId)
+            continue;
+        const found = { thread_id: str(e.thread_id), item: str(e.item) };
+        if (found.thread_id !== undefined || found.item !== undefined)
+            return found;
+    }
+    return undefined;
+}

package/dist/cli/claude-config.js

@@ -0,0 +1,100 @@
+/**
+ * What Claude Code is configured to start for a folder, as far as its
+ * files show it: for `buildit-mcp status`, which warns when both a channel
+ * server added with `claude mcp add` (or in the folder's .mcp.json) and the
+ * buildit plugin are set up, since only one of them may be the folder's
+ * channel.
+ *
+ * It only reads: `~/.claude.json` (user and per-project servers), the
+ * folder's `.mcp.json`, and the plugin lists (`~/.claude/plugins/
+ * installed_plugins.json`, `enabledPlugins` in the user's and the folder's
+ * settings). A plugin loaded with --plugin-dir can't be seen. Nothing from
+ * these files is printed but the places a server was found.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { folderIdentity } from '../secrets/keychain.js';
+/** The plugin's name, as its manifest names it. */
+export const PLUGIN_NAME = 'buildit';
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function recordOf(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v)
+        ? v
+        : {};
+}
+/** Whether an mcpServers entry runs buildit-mcp in channel mode. */
+export function isChannelServer(entry) {
+    const e = recordOf(entry);
+    const args = Array.isArray(e.args)
+        ? e.args.filter((a) => typeof a === 'string')
+        : [];
+    const line = [typeof e.command === 'string' ? e.command : '', ...args].join(' ');
+    if (!/buildit-mcp/.test(line))
+        return false;
+    const env = recordOf(e.env);
+    return (args.includes('--channel') ||
+        /^(1|true|yes|on)$/i.test(typeof env.BUILDIT_CHANNEL === 'string' ? env.BUILDIT_CHANNEL : ''));
+}
+/** The buildit-mcp channel servers configured for the folder outside the plugin. */
+export function channelServers(folder, home = homedir()) {
+    const found = [];
+    const add = (servers, place) => {
+        for (const [name, entry] of Object.entries(recordOf(servers))) {
+            if (isChannelServer(entry) && !found.some((f) => f.name === name && f.place === place)) {
+                found.push({ name, place });
+            }
+        }
+    };
+    const user = readJson(join(home, '.claude.json'));
+    if (user !== undefined) {
+        add(user.mcpServers, '~/.claude.json');
+        const id = folderIdentity(folder);
+        const project = Object.entries(recordOf(user.projects)).find(([path]) => folderIdentity(path) === id)?.[1];
+        add(recordOf(project).mcpServers, '~/.claude.json');
+    }
+    const local = readJson(join(folder, '.mcp.json'));
+    if (local !== undefined)
+        add(local.mcpServers, '.mcp.json');
+    return found;
+}
+/** Where a buildit-mcp channel server is configured for the folder ("~/.claude.json", ".mcp.json"). */
+export function channelServerPlaces(folder, home = homedir()) {
+    return [...new Set(channelServers(folder, home).map((s) => s.place))];
+}
+const isPluginKey = (key) => key === PLUGIN_NAME || key.startsWith(`${PLUGIN_NAME}@`);
+/** Whether the buildit plugin is installed or enabled (by the files Claude Code keeps). */
+export function pluginConfigured(folder, home = homedir()) {
+    const installed = readJson(join(home, '.claude', 'plugins', 'installed_plugins.json'));
+    if (Object.keys(recordOf(installed?.plugins)).some(isPluginKey))
+        return true;
+    for (const path of [
+        join(home, '.claude', 'settings.json'),
+        join(folder, '.claude', 'settings.json'),
+        join(folder, '.claude', 'settings.local.json'),
+    ]) {
+        const enabled = recordOf(readJson(path)?.enabledPlugins);
+        if (Object.entries(enabled).some(([key, on]) => isPluginKey(key) && on === true))
+            return true;
+    }
+    return false;
+}
+/** The warning `status` prints when both are set up, or undefined. */
+export function duplicateChannelWarning(folder, home = homedir()) {
+    const servers = channelServers(folder, home);
+    if (servers.length === 0 || !pluginConfigured(folder, home))
+        return undefined;
+    const places = [...new Set(servers.map((s) => s.place))];
+    const names = servers.map((s) => `"${s.name}"`).join(', ');
+    return `Warning:  the buildit plugin is installed, and ${places.join(' and ')} also starts "buildit-mcp --channel" for this folder (${names}). Only one of them can be the channel, and the plugin's wins: remove the other server (claude mcp remove ${servers[0]?.name ?? '<name>'}), then restart Claude Code.`;
+}