@kammcs/buildit-mcp 0.2.0 → 0.8.0

package/dist/tools/reply.js

@@ -0,0 +1,138 @@
+/**
+ * reply: answers the session's owner in buildIt.Social (channel mode only).
+ *
+ * The answer is posted as the agent, labelled with the session, in the
+ * agent's direct conversation with its owner, or in a work item's thread
+ * (in the item's project channel) when the session works on that item: in
+ * the thread named (or the item's, by key), else in the thread of the
+ * latest message, mention or assignment that arrived, else as a new
+ * message of the direct conversation. It is safe to retry: the
+ * idempotency key is the new message's id.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { postSessionMessage } from '../channel/api.js';
+import { NOT_THE_CHANNEL } from '../channel/lock.js';
+import { isUuid, resolveThread } from '../channel/threads.js';
+import { ToolInputError } from '../errors.js';
+import { defineTool } from '../toolsets/registry.js';
+import { IdempotencyKeyInput, itemRef, ItemRefInput } from './shared.js';
+export const REPLY_MAX_CHARS = 4000;
+export const ReplyInputSchema = z.object({
+    text: z
+        .string()
+        .min(1)
+        .max(REPLY_MAX_CHARS)
+        .refine((s) => s.trim().length > 0, 'A reply cannot be blank.')
+        .describe(`The answer, in Markdown, at most ${REPLY_MAX_CHARS} characters. No images. Item keys such as DEMO-12 show as live cards.`),
+    thread_id: z
+        .uuid()
+        .optional()
+        .describe('The thread_id of the <channel> message you answer. Left out: the thread of the latest message, while only one thread is active; with several, give it (or item).'),
+    item: ItemRefInput.optional().describe("A work item's key (DEMO-12), to answer in its thread: one you work on (the <channel> tag's item). Instead of thread_id."),
+    reply_to_id: z
+        .uuid()
+        .optional()
+        .describe('A message_id to quote as the one you answer, inside the thread.'),
+    idempotency_key: IdempotencyKeyInput.optional(),
+});
+const ReplyOutputSchema = z.object({
+    created: z.boolean().describe('false: an earlier call with this idempotency_key posted it.'),
+    message: z.object({
+        id: z.string(),
+        conversation_id: z.string(),
+        thread_id: z.string().nullable(),
+        reply_to_id: z.string().nullable(),
+        created_at: z.string(),
+    }),
+    idempotency_key: z.string(),
+});
+/** The reply tool for one channel session. */
+export function createReplyTool(state) {
+    return defineTool({
+        name: 'reply',
+        // Not in the catalog: listed only in channel mode, whatever the toolsets.
+        toolset: 'chat',
+        title: 'Reply in buildIt.Social',
+        description: `Answers the person who directs this session, in buildIt.Social: posts your text as the agent (labelled with this session) in its conversation with them, or in a work item's thread when the message came from one (meta item), where they read it on their computer or phone. Use it for every answer to a message that arrived as a <channel> tag: pass that tag's thread_id so the answer lands in the same thread (left out, it goes to the thread of the latest message, mention or assignment; with none yet, it starts a new message in your conversation with them). For an item assigned to you, post progress, questions and the result in its thread: pass its thread_id, or item with its key. You can post only in the threads of items you work on; everyone in the project's channel reads them. Markdown, at most ${REPLY_MAX_CHARS} characters; split longer answers. idempotency_key makes a retry return the first message instead of posting twice; one is generated and returned if you leave it out.`,
+        scopes: [],
+        annotations: {
+            title: 'Reply in buildIt.Social',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: ReplyInputSchema,
+        outputSchema: ReplyOutputSchema,
+        async run(args, ctx) {
+            if (!state.isChannel)
+                throw new ToolInputError(NOT_THE_CHANNEL);
+            const key = args.idempotency_key ?? randomUUID();
+            const threadId = await resolveThread(state, ctx, args, 'reply');
+            const r = await postSessionMessage(ctx.api, {
+                id: key,
+                text: args.text,
+                ...(threadId === undefined ? {} : { thread_id: threadId }),
+                ...(args.reply_to_id === undefined ? {} : { reply_to_id: args.reply_to_id }),
+            }, ctx.apiOptions);
+            state.typing?.stop(threadId);
+            const m = r.message;
+            const item = args.item === undefined ? undefined : itemRef(args.item).toUpperCase();
+            const where = m.thread_id
+                ? item !== undefined && !isUuid(item)
+                    ? `in the thread of ${item} (${m.thread_id})`
+                    : `in thread ${m.thread_id}`
+                : 'as a new message';
+            return {
+                structured: {
+                    created: r.created,
+                    message: {
+                        id: m.id,
+                        conversation_id: m.conversation_id,
+                        thread_id: m.thread_id ?? null,
+                        reply_to_id: m.reply_to_id ?? null,
+                        created_at: m.created_at,
+                    },
+                    idempotency_key: key,
+                },
+                text: r.created
+                    ? `Sent ${where} (message ${m.id}).`
+                    : `Nothing new: this reply was already sent ${where} with this idempotency_key (message ${m.id}).`,
+            };
+        },
+    });
+}
+/**
+ * turn_ended: called by the plugin's Stop hook when Claude's turn ends, so
+ * buildIt.Social stops showing that the agent is writing, and the main
+ * agent's tool approvals still open (the person answered "No" in the
+ * terminal, so the turn went on) close as no longer needed. Not for Claude.
+ */
+export function createTurnEndedTool(state) {
+    return defineTool({
+        name: 'turn_ended',
+        toolset: 'chat',
+        title: 'Turn ended (plugin hook)',
+        description: "Called by the buildit plugin's Stop hook when your turn ends; it tells buildIt.Social that the agent is no longer writing, and closes your tool approvals that no longer need an answer. Not for you to call: it does nothing you need.",
+        scopes: [],
+        runsAfterSessionEnd: true,
+        annotations: {
+            title: 'Turn ended (plugin hook)',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: z.object({}),
+        outputSchema: z.object({ stopped: z.number().describe('Threads that were working.') }),
+        async run() {
+            const working = state.typing?.working.length ?? 0;
+            // The main agent's open tool approvals are no longer needed.
+            state.approvals?.agentDone('');
+            await state.typing?.stopAll();
+            // The Stop hook reads the text as its output: an empty object lets the turn end.
+            return { structured: { stopped: working }, text: '{}' };
+        },
+    });
+}

package/dist/tools/shared.js

@@ -66,6 +66,17 @@ export const ItemRefInput = z
     .string()
     .regex(ITEM_REF_RE, 'An item key such as DEMO-12, or an item uuid.')
     .describe('An item key such as DEMO-12 (any case, a leading # is fine) or the item uuid.');
+/** The agent API version that gives items Needs. */
+export const NEEDS_API = '1.9.0';
+/** An item's Needs: capability tags (the server lower-cases, sorts and folds duplicates). */
+export const NeedsInput = z
+    .array(z
+    .string()
+    .trim()
+    .toLowerCase()
+    .regex(/^[a-z0-9][a-z0-9+._-]{0,31}$/, 'A capability tag such as macos (a-z 0-9 + . _ -).'))
+    .max(10)
+    .describe('Capability tags (windows, macos, linux, ios, android, xcode, flutter, docker, rust, web, gpu, or your own).');
 export const ProjectKeyInput = z
     .string()
     .regex(/^[A-Za-z][A-Za-z0-9]{1,5}$/, 'A project key such as DEMO.')
@@ -134,8 +145,10 @@ export const ItemOutSchema = z.object({
     status_category: z.string().describe('not_started, started, done or canceled.'),
     priority: z.string(),
     assignee: PersonSchema.nullable(),
+    assignee_agent: z.string().nullable().describe("The assignee's agent working on it."),
     parent: z.string().nullable().describe("The parent's key."),
     labels: z.array(z.string()),
+    needs: z.array(z.string()),
     estimate: z.number().nullable(),
     sprint: z.string().nullable(),
     fix_release: z.string().nullable(),
@@ -157,8 +170,10 @@ export function itemOut(i) {
         status_category: i.status.category,
         priority: i.priority,
         assignee: i.assignee ? person(i.assignee) : null,
+        assignee_agent: i.assignee_agent ? label(i.assignee_agent.name, PERSON_NAME_CHARS) : null,
         parent: i.parent?.key ?? null,
         labels: i.labels.map((l) => label(l.name, 40)),
+        needs: (i.needs ?? []).map((n) => label(n, 32)),
         estimate: i.estimate,
         sprint: nameLabel(i.sprint?.name),
         fix_release: nameLabel(i.fix_release?.name),
@@ -427,6 +442,13 @@ export function historyOut(h) {
 // ---------------------------------------------------------------------------
 // Text
 // ---------------------------------------------------------------------------
+/** Who an item is assigned to, in lines: "@Sam", "assignee Claude · for Sam", or "unassigned". */
+export function assigneeText(i) {
+    if (i.assignee_agent && i.assignee) {
+        return `assignee ${i.assignee_agent} · for ${i.assignee.name}`;
+    }
+    return i.assignee ? `@${i.assignee.name}` : 'unassigned';
+}
 /** One line about an item, for lists (it carries the title, so lists are wrapped). */
 export function itemLine(i) {
     const parts = [
@@ -434,12 +456,13 @@ export function itemLine(i) {
         i.type,
         `${i.status} (${i.status_category})`,
         ...(i.priority !== 'none' ? [i.priority] : []),
-        i.assignee ? `@${i.assignee.name}` : 'unassigned',
+        assigneeText(i),
         ...(i.estimate !== null ? [`est ${i.estimate}`] : []),
         ...(i.parent ? [`parent ${i.parent}`] : []),
         ...(i.sprint ? [i.sprint] : []),
         ...(i.due_date ? [`due ${i.due_date}`] : []),
         ...(i.labels.length > 0 ? [`labels ${i.labels.join(', ')}`] : []),
+        ...(i.needs.length > 0 ? [`needs ${i.needs.join(', ')}`] : []),
     ];
     return `${parts.join(' · ')} — ${i.title}`;
 }

package/dist/tools/threads.js

@@ -0,0 +1,149 @@
+/**
+ * list_threads: the threads this session works in (channel mode only):
+ * its direct-message threads and the work items' threads bound to it,
+ * newest activity first, at most 50 (GET /v1/session/threads).
+ *
+ * It also refreshes which item threads are active (the set the explicit
+ * thread rule counts), since the server's list is the one that knows.
+ */
+import { z } from 'zod';
+import { listSessionThreads } from '../channel/api.js';
+import { NOT_THE_CHANNEL } from '../channel/lock.js';
+import { ToolInputError } from '../errors.js';
+import { defineTool } from '../toolsets/registry.js';
+import { sanitizeLabel, wrapUntrusted } from '../untrusted.js';
+/** Built-in statuses whose name doesn't follow from the key. */
+const BUILT_IN_NAMES = { todo: 'To do', canceled: 'Cancelled' };
+/** "in_review" as people read it: "In review". */
+const humanize = (key) => {
+    const words = key.replace(/[_-]+/g, ' ').trim();
+    return words === '' ? '' : words.charAt(0).toUpperCase() + words.slice(1);
+};
+/**
+ * A status's name. Built-in statuses come with a key and no name (the app
+ * names them in the person's language), so the name follows from the key,
+ * else from the category.
+ */
+export function statusName(status) {
+    if (status === null)
+        return null;
+    if (status.name !== null && status.name.trim() !== '')
+        return sanitizeLabel(status.name, 60);
+    const key = status.key?.trim().toLowerCase() ?? '';
+    const named = key === '' ? undefined : (BUILT_IN_NAMES[key] ?? humanize(key));
+    const name = named !== undefined && named !== '' ? named : humanize(status.category);
+    return name === '' ? null : sanitizeLabel(name, 60);
+}
+const ThreadOutSchema = z.object({
+    thread_id: z.string(),
+    conversation_id: z.string(),
+    kind: z.string().describe('dm: your direct message with the person; item: a work item.'),
+    item: z
+        .object({
+        key: z.string(),
+        title: z.string().describe('People-written; flattened to one defused line.'),
+        status: z.string().nullable(),
+    })
+        .nullable(),
+    open_cards: z.number(),
+    last_owner_message_at: z.string().nullable(),
+    handoff: z
+        .object({
+        id: z.string().describe('The handoff id (withdraw_handoff and decline_handoff take it).'),
+        role: z
+            .string()
+            .describe('target: this item is a subtask handed to this session; asked: this session proposed handing on a subtask of this item.'),
+        status: z.string(),
+    })
+        .nullable()
+        .describe("The item thread's handoff, if it has one (null for a server older than agent API 1.9.0)."),
+});
+/** A thread's handoff in words, for its line. */
+function handoffFact(h) {
+    return h.role === 'target'
+        ? `a subtask handed to this session (handoff ${h.id}, ${h.status}); if you can't do it, decline_handoff`
+        : h.role === 'asked'
+            ? `you proposed handing on a subtask of it (handoff ${h.id}, ${h.status})`
+            : `handoff ${h.id} (${h.role}, ${h.status})`;
+}
+/** The list_threads tool for one channel session. */
+export function createListThreadsTool(state) {
+    return defineTool({
+        name: 'list_threads',
+        // Not in the catalog: listed only in channel mode, whatever the toolsets.
+        toolset: 'chat',
+        title: 'List the threads this session works in',
+        description: "Lists the threads this session works in: your direct message with the person, and the work items' threads (key, title, status, open cards, when the person last wrote). Use it to name the thread for reply, ask or an approval card (thread_id, or the item's key) while you work in several, and after a restart.",
+        scopes: [],
+        annotations: {
+            title: 'List the threads this session works in',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: z.object({}),
+        outputSchema: z.object({ threads: z.array(ThreadOutSchema) }),
+        async run(_args, ctx) {
+            if (!state.isChannel)
+                throw new ToolInputError(NOT_THE_CHANNEL);
+            const r = await listSessionThreads(ctx.api, ctx.apiOptions);
+            const threads = r.threads.map((t) => ({
+                thread_id: t.thread_id,
+                conversation_id: t.conversation_id,
+                kind: sanitizeLabel(t.kind, 20),
+                item: t.item === null
+                    ? null
+                    : {
+                        key: sanitizeLabel(t.item.key, 40),
+                        title: sanitizeLabel(t.item.title, 300),
+                        status: statusName(t.item.status),
+                    },
+                open_cards: t.open_cards,
+                last_owner_message_at: t.last_owner_message_at,
+                handoff: t.handoff === null || t.handoff === undefined
+                    ? null
+                    : {
+                        id: t.handoff.id,
+                        role: sanitizeLabel(t.handoff.role, 20),
+                        status: sanitizeLabel(t.handoff.status, 20),
+                    },
+            }));
+            // The server's list is the one that knows which item threads are bound.
+            state.activeItems.clear();
+            for (const t of r.threads) {
+                if (t.kind === 'item' && t.item !== null)
+                    state.activateItem(t.item.key, t.item.id);
+            }
+            const newestDm = r.threads.find((t) => t.kind === 'dm');
+            if (state.lastDmThread === undefined && newestDm !== undefined) {
+                state.lastDmThread = newestDm.thread_id;
+            }
+            if (threads.length === 0) {
+                return {
+                    structured: { threads },
+                    text: 'This session works in no thread yet.',
+                };
+            }
+            const lines = threads.map((t) => {
+                const facts = [
+                    `thread_id ${t.thread_id}`,
+                    `${t.open_cards} open ${t.open_cards === 1 ? 'card' : 'cards'}`,
+                    `the person last wrote ${t.last_owner_message_at ?? 'never'}`,
+                    ...(t.handoff === null ? [] : [handoffFact(t.handoff)]),
+                ].join(' · ');
+                return t.item === null
+                    ? `your direct message · ${facts}`
+                    : `${t.item.key} · ${t.item.status ?? 'no status'} · ${facts} — ${t.item.title}`;
+            });
+            return {
+                structured: { threads },
+                text: [
+                    `This session works in ${threads.length} ${threads.length === 1 ? 'thread' : 'threads'}, newest activity first:`,
+                    // The titles and statuses are people-written: the lines are one block.
+                    wrapUntrusted(lines.join('\n'), { source: 'threads', maxChars: 40_000 }),
+                ].join('\n'),
+            };
+        },
+    });
+}

package/dist/tools/whoami.js

@@ -2,6 +2,8 @@
  * whoami: who the token acts as, where, and with what reach.
  */
 import { z } from 'zod';
+import { getSession } from '../channel/api.js';
+import { NOT_THE_CHANNEL } from '../channel/lock.js';
 import { OPERATIONS } from '../api/generated/operations.js';
 import { defineTool } from '../toolsets/registry.js';
 import { expandScopes } from '../toolsets/toolsets.js';
@@ -24,7 +26,14 @@ const OutputSchema = z.object({
             .describe('A test org (true); null when the API is older than 1.2.0.'),
     }),
     token: z.object({
-        name: z.string().nullable(),
+        name: z
+            .string()
+            .nullable()
+            .describe("The token's name; for an agent session, the session's label."),
+        kind: z
+            .string()
+            .nullable()
+            .describe('pat: a personal access token; session: an agent session (channel mode); null when the API is older.'),
         expires_at: z.string().nullable(),
     }),
     scopes: z.array(z.string()).describe('As granted; a write scope also allows reading.'),
@@ -58,6 +67,17 @@ const OutputSchema = z.object({
             .number()
             .describe("The org's requests a minute, across all its tokens."),
     }),
+    capabilities: z
+        .object({
+        confirmed: z
+            .array(z.string())
+            .describe('The tags the person confirmed: what work with Needs can be handed to this session for.'),
+        suggested: z
+            .array(z.string())
+            .describe('What this computer detected and suggests, not confirmed yet (they never count).'),
+    })
+        .nullable()
+        .describe("An agent session's capability tags; null for a personal token or an API older than 1.9.0."),
     server: z.object({
         name: z.string(),
         version: z.string(),
@@ -122,6 +142,25 @@ export const whoamiTool = defineTool({
                 return undefined;
             }),
         ]);
+        // An agent session's capability tags, read fresh (the person may have confirmed some since).
+        const session = ctx.channel !== undefined && me.token.kind === 'session'
+            ? await getSession(ctx.api, options).then((info) => {
+                const channel = ctx.channel;
+                if (channel?.session?.session.id === info.session.id)
+                    channel.session = info;
+                return info;
+            }, () => ctx.channel?.session)
+            : undefined;
+        const confirmed = session?.session.capabilities;
+        const detected = session?.session.capabilities_detected;
+        const capabilities = confirmed === undefined && detected === undefined
+            ? null
+            : {
+                confirmed: (confirmed ?? []).map((t) => sanitizeLabel(t, 32)),
+                suggested: (detected ?? [])
+                    .map((t) => sanitizeLabel(t, 32))
+                    .filter((t) => !(confirmed ?? []).includes(t)),
+            };
         const minVersion = meta?.min_mcp_version;
         const updateRequired = minVersion !== undefined && compareVersions(SERVER_VERSION, minVersion) < 0;
         const structured = {
@@ -137,6 +176,7 @@ export const whoamiTool = defineTool({
             },
             token: {
                 name: nullableLabel(me.token.name, NAME_CHARS),
+                kind: me.token.kind === undefined ? null : sanitizeLabel(me.token.kind, 20),
                 expires_at: me.token.expires_at,
             },
             scopes: [...me.token.scopes].sort(),
@@ -151,6 +191,7 @@ export const whoamiTool = defineTool({
                 id: p.id,
             })),
             features: { projects: me.features.projects },
+            capabilities,
             rate_limits: {
                 requests_per_minute: me.rate_limits.requests_per_minute,
                 user_requests_per_minute: me.rate_limits.user_requests_per_minute,
@@ -176,7 +217,9 @@ export const whoamiTool = defineTool({
         const names = [
             `User: ${s.user.name ?? s.user.id}${s.user.email ? ` (${s.user.email})` : ''}`,
             `Org: ${s.org.name ?? s.org.id}`,
-            ...(s.token.name ? [`Token: ${s.token.name}`] : []),
+            ...(s.token.name
+                ? [`${s.token.kind === 'session' ? 'Session' : 'Token'}: ${s.token.name}`]
+                : []),
         ];
         if (s.projects.length > 0) {
             const shown = s.projects
@@ -188,7 +231,7 @@ export const whoamiTool = defineTool({
             names.push(`Channels the token is limited to: ${s.limits.channels.join(', ')}`);
         }
         const lines = [
-            `Signed in to buildIt.Social with a personal access token${s.token.expires_at ? ` (expires ${s.token.expires_at})` : ''}. Who and where, as people named them:`,
+            `Signed in to buildIt.Social with ${s.token.kind === 'session' ? "an agent session's token (it acts as the session's owner)" : 'a personal access token'}${s.token.expires_at ? ` (expires ${s.token.expires_at})` : ''}. Who and where, as people named them:`,
             wrapLines(names, 'names'),
             `Scopes: ${s.scopes.length > 0 ? s.scopes.join(', ') : 'none'}.`,
             `Limits: ${s.limits.projects === null
@@ -199,6 +242,10 @@ export const whoamiTool = defineTool({
                     ? 'no channels'
                     : `only the ${s.limits.channels.length} channel(s) listed above, among those the user can see`}.`,
         ];
+        if (s.capabilities !== null) {
+            const { confirmed: mine, suggested } = s.capabilities;
+            lines.push(`Capabilities of this session: ${mine.length > 0 ? mine.join(', ') : 'none confirmed'}${suggested.length > 0 ? `; suggested, not confirmed: ${suggested.join(', ')}` : ''}. Only confirmed ones count: work that needs others goes to another of the person's sessions (propose_handoff), or the person confirms them in buildIt.Social (Settings → Agents).`);
+        }
         if (s.org.test === true) {
             lines.push('This org is a test org: its data may be wiped and seeded by test tools.');
         }
@@ -222,6 +269,9 @@ export const whoamiTool = defineTool({
         if (s.server.not_served !== null && s.server.not_served.length > 0) {
             lines.push(`This buildIt.Social server (API ${s.server.api_version ?? 'unknown'}) doesn't serve these operations yet, so calls that need them are refused until it is updated: ${s.server.not_served.join(', ')}.`);
         }
+        if (ctx.channel !== undefined && !ctx.channel.isChannel) {
+            lines.push(NOT_THE_CHANNEL);
+        }
         if (updateRequired) {
             lines.push(`This buildit-mcp (${SERVER_VERSION}) is older than the API supports (${minVersion} or newer). Ask the person to update it.`);
         }

package/dist/toolsets/catalog.js

@@ -5,7 +5,7 @@
  */
 import { PROMPTS } from '../prompts.js';
 import { RESOURCES } from '../resources.js';
-import { listChannelsTool, readChannelTool, readThreadTool } from '../tools/chat.js';
+import { listChannelsTool, listEmojiTool, listPinsTool, readChannelTool, readThreadTool, } from '../tools/chat.js';
 import { addCommentTool, listCommentsTool } from '../tools/comments.js';
 import { getItemTool, searchItemsTool } from '../tools/items-read.js';
 import { assignItemTool, createItemTool, linkItemsTool, rankItemTool, transitionItemTool, unlinkItemsTool, updateItemTool, } from '../tools/items-write.js';
@@ -49,6 +49,8 @@ export const CATALOG = [
     listChannelsTool,
     readChannelTool,
     readThreadTool,
+    listPinsTool,
+    listEmojiTool,
     // admin
     createChannelTool,
     createProjectTool,

package/dist/toolsets/registry.js

@@ -13,6 +13,8 @@ export function createToolContext(init) {
         ...(init.signal ? { signal: init.signal } : {}),
         apiOptions,
         call: (id, args = {}) => callOperation(init.api, id, args, apiOptions),
+        ...(init.channel ? { channel: init.channel } : {}),
+        ...(init.progress ? { progress: init.progress } : {}),
     };
 }
 /** Identity helper that keeps the argument and output types tied to the schemas. */