@kammcs/buildit-mcp 0.10.0 → 0.11.0

package/dist/tools/reply.js

@@ -8,18 +8,27 @@
  * 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.
+ *
+ * With `request` (agent API 1.13.0) the post is the result of a request
+ * from buildIt.Social (a <channel> tag with event="request"). Without
+ * thread_id or item it starts a new message of the direct conversation,
+ * never "the latest thread" (which may be an item's): a catch-up's result
+ * is private. A request this session knows goes only where its `result`
+ * says; the server refuses anything else too (request_result_private).
  */
 import { randomUUID } from 'node:crypto';
 import { rm } from 'node:fs/promises';
 import { z } from 'zod';
 import { postSessionMessage } from '../channel/api.js';
+import { REQUESTS_API } from '../channel/requests.js';
 import { FILES_API, FILES_OPERATIONS, filesServed } from '../channel/attachments.js';
 import { checkFiles, prepareFiles, REPLY_MAX_FILES, shareFiles } from '../channel/upload.js';
 import { NOT_THE_CHANNEL } from '../channel/lock.js';
-import { isUuid, resolveThread } from '../channel/threads.js';
+import { DM_AND_THREAD, dmThread, isItemThread, isUuid, resolveThread, } from '../channel/threads.js';
 import { ToolInputError } from '../errors.js';
 import { defineTool } from '../toolsets/registry.js';
 import { sanitizeLabel } from '../untrusted.js';
+import { compareVersions } from '../version.js';
 import { IdempotencyKeyInput, itemRef, ItemRefInput } from './shared.js';
 export const REPLY_MAX_CHARS = 4000;
 const TextInput = z
@@ -36,6 +45,14 @@ const ReplyToInput = z
     .uuid()
     .optional()
     .describe('A message_id to quote as the one you answer, inside the thread.');
+const DmInput = z
+    .boolean()
+    .optional()
+    .describe('true: post in your direct message with the person (its latest thread, or a new message), never in an item thread. Use it for anything about a request (event="request") other than its result: a note, a queued notice.');
+const RequestInput = z
+    .uuid()
+    .optional()
+    .describe('The request_id of a <channel> tag with event="request", when this post is its result. A request whose result is "dm" (a catch-up) goes only to your direct message: leave thread_id and item out.');
 /**
  * reply on a server older than 1.11.0: loose, so a call that still passes
  * `files` (from a tool list read before the server's version was known)
@@ -46,6 +63,8 @@ export const ReplyInputSchema = z.looseObject({
     thread_id: ThreadInput,
     item: ItemInput,
     reply_to_id: ReplyToInput,
+    dm: DmInput,
+    request: RequestInput,
     idempotency_key: IdempotencyKeyInput.optional(),
 });
 /** reply on a server that serves files: `files`, and text optional with them. */
@@ -60,6 +79,8 @@ export const ReplyWithFilesInputSchema = z.object({
     thread_id: ThreadInput,
     item: ItemInput,
     reply_to_id: ReplyToInput,
+    dm: DmInput,
+    request: RequestInput,
     idempotency_key: IdempotencyKeyInput.optional(),
 });
 const MessageOutput = z.object({
@@ -90,6 +111,7 @@ const ReplyWithFilesOutputSchema = ReplyOutputSchema.extend({
         .describe('The files posted, as given, with the name readers see.'),
 });
 const BASE_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.`;
+const REQUEST_DESCRIPTION = ` For the result of a request (a <channel> tag with event="request"), pass its request_id as request, and post where the tag's result says: result="dm" means your direct message only, so leave thread_id and item out. Anything else about a request (a note, a queued notice) goes with dm: true, so it never lands in an item's thread.`;
 const FILES_DESCRIPTION = ` To share files (a render, a screenshot, a log, a document), pass their local paths in files: they are posted at once in the same thread, with the text, and everyone who reads the thread can open them. Before anything is uploaded, every file is checked: it must be inside the project folder or the temp folder, not a secret store (.env files, keys, certificates, .ssh and the like), not a program, within the size limit (250 MiB for a video, 100 MiB for anything else), and a text file must not hold anything that looks like a credential. Location is removed from photos and videos. One refused file sends nothing, and the error says why: fix it and send the reply again. Share only files the person asked for or that your work needs.`;
 /** The refusal of files on a server that doesn't take them: nothing is sent. */
 const TOO_OLD_FOR_FILES = `Not sent: this buildIt.Social server is older than agent API ${FILES_API}; files can't be sent. Nothing was posted. Send the text alone, and describe the file (or where it is) instead.`;
@@ -109,6 +131,48 @@ function whereOf(m, item) {
             : `in thread ${m.thread_id}`
         : 'as a new message';
 }
+/** The refusal of a private result posted outside the direct message, before any call. */
+const PRIVATE_RESULT = "Not sent (request_result_private): this request's result goes only to your direct message with the person; a catch-up is private. Send it again with reply, without thread_id or item, and with the same request.";
+/**
+ * Where reply posts. With `request` and no thread named: a new message of
+ * the direct conversation (never the latest thread, which may be an
+ * item's). A request this session knows with result "dm" is refused in an
+ * item's thread here, before any call (the server refuses it too).
+ */
+async function replyThread(state, ctx, args) {
+    if (args.dm === true) {
+        if (args.thread_id !== undefined || args.item !== undefined) {
+            throw new ToolInputError(DM_AND_THREAD);
+        }
+        return dmThread(state);
+    }
+    if (args.request === undefined)
+        return resolveThread(state, ctx, args, 'reply');
+    const known = state.requests.get(args.request.toLowerCase());
+    if (known?.place === 'dm') {
+        if (args.item !== undefined)
+            throw new ToolInputError(PRIVATE_RESULT);
+        if (args.thread_id !== undefined && isItemThread(state, args.thread_id)) {
+            throw new ToolInputError(PRIVATE_RESULT);
+        }
+    }
+    if (args.thread_id === undefined && args.item === undefined)
+        return undefined;
+    return resolveThread(state, ctx, args, 'reply');
+}
+/**
+ * The body's `request`, on a server that takes it (agent API 1.13.0 and
+ * newer, or one that hasn't said its version). An older server never sent
+ * a request, so a post there is an ordinary one.
+ */
+function requestField(ctx, request) {
+    if (request === undefined)
+        return {};
+    const version = ctx.api.served?.apiVersion;
+    if (version !== undefined && compareVersions(version, REQUESTS_API) < 0)
+        return {};
+    return { request };
+}
 /**
  * The reply tool for one channel session. With `files` (a server that
  * serves them, 1.11.0 and newer), it also posts local files; without, it
@@ -128,7 +192,7 @@ export function createReplyTool(state, options = { files: false }) {
             // Not in the catalog: listed only in channel mode, whatever the toolsets.
             toolset: 'chat',
             title: 'Reply in buildIt.Social',
-            description: BASE_DESCRIPTION,
+            description: BASE_DESCRIPTION + REQUEST_DESCRIPTION,
             scopes: [],
             // Listed only for a server known not to serve files (the other reply is the default).
             listedUnlessOperations: FILES_OPERATIONS,
@@ -142,12 +206,13 @@ export function createReplyTool(state, options = { files: false }) {
                     throw new ToolInputError(TOO_OLD_FOR_FILES);
                 }
                 const key = args.idempotency_key ?? randomUUID();
-                const threadId = await resolveThread(state, ctx, args, 'reply');
+                const threadId = await replyThread(state, ctx, args);
                 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 }),
+                    ...requestField(ctx, args.request),
                 }, ctx.apiOptions);
                 state.typing?.stop(threadId);
                 const m = r.message;
@@ -166,7 +231,7 @@ export function createReplyTool(state, options = { files: false }) {
         name: 'reply',
         toolset: 'chat',
         title: 'Reply in buildIt.Social',
-        description: BASE_DESCRIPTION + FILES_DESCRIPTION,
+        description: BASE_DESCRIPTION + REQUEST_DESCRIPTION + FILES_DESCRIPTION,
         scopes: [],
         requiresOperations: FILES_OPERATIONS,
         annotations,
@@ -183,11 +248,12 @@ export function createReplyTool(state, options = { files: false }) {
                 throw new ToolInputError(TOO_OLD_FOR_FILES);
             }
             const key = args.idempotency_key ?? randomUUID();
-            const threadId = await resolveThread(state, ctx, args, 'reply');
+            const threadId = await replyThread(state, ctx, args);
             const item = args.item === undefined ? undefined : itemRef(args.item).toUpperCase();
             const base = {
                 ...(args.text === undefined ? {} : { text: args.text }),
                 ...(args.reply_to_id === undefined ? {} : { reply_to_id: args.reply_to_id }),
+                ...requestField(ctx, args.request),
             };
             if (files.length === 0) {
                 const r = await postSessionMessage(ctx.api, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kammcs/buildit-mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "MCP server for buildIt.Social: lets AI agents work with an org's projects, pages and channels through the buildIt.Social agent API, with a personal access token.",
   "license": "MIT",
   "author": "Kamm Creative Solutions",