@todoist/comms-mcp 0.0.0-stage → 11.0.0

package/dist/tools/update-user-info.js

@@ -0,0 +1,270 @@
+import { CommsRequestError, getCommsErrorString, } from '@doist/comms-sdk';
+import { z } from 'zod';
+import { UserInfoOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+import { normaliseActiveUntil } from '../utils/user-status.js';
+import { buildUserInfoResult } from './user-output.js';
+const MAX_MESSAGE_LENGTH = 80;
+const StatusArgsSchema = z.object({
+    message: z.string().trim().min(1).max(MAX_MESSAGE_LENGTH),
+    emoji: z.string().trim().min(1).optional().describe('A Unicode emoji, such as 🏝️.'),
+    activeUntil: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe('When it ends: a future ISO 8601 timestamp with Z or an offset, e.g. 2026-11-10T00:00:00+00:00. Omit for no end.'),
+    pauseNotifications: z
+        .boolean()
+        .optional()
+        .describe('Hold back Comms notifications while active. They are not sent later.'),
+    pauseActivity: z.boolean().optional().describe('Pause Karma and streaks while active.'),
+});
+// The password is left out on purpose: it is never changed through this server.
+const ArgsSchema = {
+    name: z.string().trim().min(1).optional().describe('Full name.'),
+    timezone: z.string().trim().min(1).optional().describe('IANA timezone, e.g. Europe/London.'),
+    lang: z.string().trim().min(1).optional().describe('Language code, e.g. en.'),
+    status: StatusArgsSchema.nullable()
+        .optional()
+        .describe('Replaces the whole status: an omitted emoji, end or pause is removed. null removes the status.'),
+};
+// An ISO 8601 timestamp that carries its own zone, so it never depends on the server's.
+const ZONED_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(?:Z|([+-])(\d{2}):(\d{2}))$/i;
+// The offsets in use worldwide run from UTC-12:00 to UTC+14:00.
+const MIN_OFFSET_MINUTES = -12 * 60;
+const MAX_OFFSET_MINUTES = 14 * 60;
+function invalidActiveUntil(value) {
+    return new Error(`activeUntil must be an ISO 8601 timestamp with Z or an offset, such as "2026-11-10T00:00:00+00:00". Got "${value}".`);
+}
+function parseActiveUntil(value, now) {
+    const match = ZONED_TIMESTAMP.exec(value);
+    if (!match) {
+        throw invalidActiveUntil(value);
+    }
+    const [, year, month, day, hour, minute, second = '0', sign, offsetHours, offsetMinutes] = match;
+    const [y, mo, d, h, mi, s] = [year, month, day, hour, minute, second].map(Number);
+    // `Date` rolls an impossible day or time over (31 November becomes 1 December), so build the
+    // wall-clock instant and require every part to survive the round trip. `setUTCFullYear` keeps
+    // the years 0 to 99, which `Date.UTC` would read as 1900 to 1999.
+    const wallClock = new Date(0);
+    wallClock.setUTCFullYear(y, mo - 1, d);
+    wallClock.setUTCHours(h, mi, s);
+    const partsSurvive = wallClock.getUTCFullYear() === y &&
+        wallClock.getUTCMonth() === mo - 1 &&
+        wallClock.getUTCDate() === d &&
+        wallClock.getUTCHours() === h &&
+        wallClock.getUTCMinutes() === mi &&
+        wallClock.getUTCSeconds() === s;
+    const offset = sign
+        ? (sign === '-' ? -1 : 1) * (Number(offsetHours) * 60 + Number(offsetMinutes))
+        : 0;
+    if (!partsSurvive || offset < MIN_OFFSET_MINUTES || offset > MAX_OFFSET_MINUTES) {
+        throw invalidActiveUntil(value);
+    }
+    // Sub-second precision and offset minutes are checked by `Date` itself, now that the date and
+    // time are known to be real.
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw invalidActiveUntil(value);
+    }
+    if (parsed.getTime() <= now.getTime()) {
+        throw new Error(`activeUntil must be in the future. Got "${value}".`);
+    }
+    return parsed.toISOString();
+}
+// An explicit scope, because `{}` keeps whatever scope another client stored for the effect.
+const ALL_SCOPE = { scope: { mode: 'all' } };
+/** The whole status to store. Omitted fields are cleared, not kept. */
+function buildStatus(status, now) {
+    const { message, emoji, activeUntil, pauseNotifications, pauseActivity } = status;
+    // The schema checks these, but a caller that skips it can send anything. A message or emoji
+    // Comms accepts but the comparison below cannot read would fail only after the write applied,
+    // and a pause flag of "false" would read as true.
+    if (typeof message !== 'string' || !message.trim()) {
+        throw new Error('status.message is required to set a status. Pass status: null to remove it.');
+    }
+    if (emoji != null && typeof emoji !== 'string') {
+        throw new Error('status.emoji must be text, such as "🏝️".');
+    }
+    if (activeUntil != null && typeof activeUntil !== 'string') {
+        throw invalidActiveUntil(String(activeUntil));
+    }
+    for (const [flag, value] of Object.entries({ pauseNotifications, pauseActivity })) {
+        if (value != null && typeof value !== 'boolean') {
+            throw new Error(`status.${flag} must be true or false.`);
+        }
+    }
+    return {
+        // Trimmed as the schema would, so a caller that skips it sends the same values.
+        message: message.trim(),
+        emoji: emoji?.trim() || null,
+        activeUntil: activeUntil != null ? parseActiveUntil(activeUntil, now) : null,
+        effects: {
+            pauseNotifications: pauseNotifications ? ALL_SCOPE : null,
+            pauseActivity: pauseActivity ? ALL_SCOPE : null,
+        },
+    };
+}
+// Each profile field and where Comms reports it back.
+const PROFILE_FIELDS = { name: 'fullName', timezone: 'timezone', lang: 'lang' };
+function buildProfile(args) {
+    const profile = {};
+    for (const field of Object.keys(PROFILE_FIELDS)) {
+        const value = args[field];
+        if (value === undefined) {
+            continue;
+        }
+        // The schema checks this too, for a caller that skips it.
+        if (typeof value !== 'string' || !value.trim()) {
+            throw new Error(`${field} must be text that is not blank.`);
+        }
+        profile[field] = value.trim();
+    }
+    return Object.keys(profile).length > 0 ? profile : null;
+}
+// Comms may store a value in another form than it was sent, or report one it has not caught up
+// with yet, so a difference is reported beside the result rather than failing a write that applied.
+function profileDifferences(held, sent) {
+    return Object.keys(PROFILE_FIELDS)
+        .filter((field) => sent[field] !== undefined && held[PROFILE_FIELDS[field]] !== sent[field])
+        .map((field) => `Comms reports ${field} as "${held[PROFILE_FIELDS[field]]}", not "${sent[field]}"; use ${ToolNames.USER_INFO} to check it.`);
+}
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const SCOPE_HINTS = {
+    401: ' Comms rejected the token, so the connection may need reconnecting.',
+    403: ' Changing it needs the user:write scope, so the connection may need reconnecting to grant it.',
+};
+/**
+ * The SDK's message for a refusal is only the status code, and a connection may not hold
+ * `user:write`, which covers updating the user's settings, so a refusal says what it needs. No
+ * failure claims the change did not apply: the SDK retries a POST after a network error, so an
+ * earlier attempt may have.
+ */
+function explainWriteFailure(error, subject) {
+    const checkIt = `Use ${ToolNames.USER_INFO} to check it.`;
+    const status = error instanceof CommsRequestError ? error.httpStatusCode : undefined;
+    if (status === undefined || status >= 500) {
+        return new Error(`The ${subject} change is unconfirmed: ${errorDetail(error)}. ${checkIt}`);
+    }
+    const reason = getCommsErrorString(error);
+    return new Error(`Comms refused to change the ${subject} (HTTP ${status})${reason ? `: ${reason}` : ''}.${SCOPE_HINTS[status] ?? ''} ${checkIt}`);
+}
+// Whether an emoji carries U+FE0F (🏝️ or 🏝) changes nothing on screen, so a server that adds or
+// drops it has not stored a different status. Nor has one that normalises a message's Unicode form
+// or runs of whitespace, or trims what a caller skipping the schema left padded.
+function normaliseEmoji(emoji) {
+    return emoji?.replace(/\uFE0F/g, '').trim() || null;
+}
+function normaliseMessage(message) {
+    return message?.normalize('NFC').replace(/\s+/g, ' ').trim();
+}
+// A pause Comms holds with another scope is not the one asked for, so presence alone is not enough.
+function samePause(held, sent) {
+    return Boolean(held) === Boolean(sent) && held?.scope?.mode === sent?.scope?.mode;
+}
+function sameStatus(held, sent) {
+    // An end Comms sends that cannot be read stays as sent, so it never matches the one asked for.
+    const heldUntil = held.activeUntil ? normaliseActiveUntil(held.activeUntil) : null;
+    // What was sent was built from a parsed end, so it always reads.
+    const sentUntil = sent.activeUntil ? new Date(sent.activeUntil).toISOString() : null;
+    return (normaliseMessage(held.message) === normaliseMessage(sent.message) &&
+        normaliseEmoji(held.emoji) === normaliseEmoji(sent.emoji) &&
+        heldUntil === sentUntil &&
+        samePause(held.effects?.pauseNotifications, sent.effects?.pauseNotifications) &&
+        samePause(held.effects?.pauseActivity, sent.effects?.pauseActivity));
+}
+/** Updates the profile, and lists any field Comms reports differently from the one sent. */
+async function writeProfile(client, profile, statusPending) {
+    // The status is only sent once Comms has accepted the profile change.
+    const notSent = statusPending ? ' The status change was not sent.' : '';
+    const user = await client.users.update(profile).catch((error) => {
+        throw new Error(`${explainWriteFailure(error, 'profile').message}${notSent}`);
+    });
+    return { user, differences: profileDifferences(user, profile) };
+}
+/** Sets or clears the status, then checks the user Comms returns holds what was asked for. */
+async function writeStatus(client, status) {
+    const checkIt = `use ${ToolNames.USER_INFO} to see it.`;
+    if (status === null) {
+        const user = await client.users.clearStatus().catch((error) => {
+            throw explainWriteFailure(error, 'status');
+        });
+        if (user.status) {
+            throw new Error(`Comms accepted the clear but still reports a status; ${checkIt}`);
+        }
+        return user;
+    }
+    const user = await client.users.setStatus(status).catch((error) => {
+        throw explainWriteFailure(error, 'status');
+    });
+    if (!user.status) {
+        throw new Error(`Comms accepted the status but reports no active status; ${checkIt}`);
+    }
+    if (!sameStatus(user.status, status)) {
+        throw new Error(`Comms accepted the status but reports a different one; ${checkIt}`);
+    }
+    return user;
+}
+/**
+ * The user to report: the profile from its own write and the status from the status write, which
+ * is the one that checked it. After a profile-only update the status is read back when the
+ * response leaves it out, because a missing status is not the same as none.
+ */
+async function reportedUser(client, profileUser, statusUser) {
+    if (profileUser && statusUser) {
+        return { ...profileUser, status: statusUser.status };
+    }
+    if (statusUser) {
+        return statusUser;
+    }
+    if (!profileUser) {
+        throw new Error('Neither the profile nor the status was written, so there is no user to report.');
+    }
+    if (profileUser.status !== undefined) {
+        return profileUser;
+    }
+    const current = await client.users.getSessionUser().catch((error) => {
+        throw new Error(`Comms accepted the profile change, but reading the status back failed: ${errorDetail(error)}. Use ${ToolNames.USER_INFO} to check it.`);
+    });
+    return { ...profileUser, status: current.status };
+}
+const updateUserInfo = {
+    name: ToolNames.UPDATE_USER_INFO,
+    description: "Change the user's name, timezone, language or status; fields left out are kept. A status given replaces the whole status. The status is shown next to their name in Comms and Todoist. Returns the user as user-info does.",
+    parameters: ArgsSchema,
+    outputSchema: UserInfoOutputSchema.shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    async execute(args, client) {
+        const profile = buildProfile(args);
+        // undefined leaves the status alone, and null removes it.
+        const status = args.status === undefined || args.status === null
+            ? args.status
+            : buildStatus(args.status, new Date());
+        if (!profile && status === undefined) {
+            throw new Error('At least one of `name`, `timezone`, `lang`, or `status` must be provided.');
+        }
+        const profileWrite = profile
+            ? await writeProfile(client, profile, status !== undefined)
+            : undefined;
+        const statusUser = status === undefined
+            ? undefined
+            : await writeStatus(client, status).catch((error) => {
+                if (!profile) {
+                    throw error;
+                }
+                // The status failure may itself be unconfirmed, so this claims nothing about it.
+                throw new Error(`Comms accepted the profile change. ${errorDetail(error)}`);
+            });
+        const result = buildUserInfoResult(await reportedUser(client, profileWrite?.user, statusUser));
+        const changed = [...Object.keys(profile ?? {}), ...(status !== undefined ? ['status'] : [])];
+        const summary = [`Updated: ${changed.join(', ')}`, ...(profileWrite?.differences ?? [])];
+        return {
+            textContent: `${summary.join('\n')}\n\n${result.textContent}`,
+            structuredContent: result.structuredContent,
+        };
+    },
+};
+export { updateUserInfo };

package/dist/tools/user-info.d.ts

@@ -0,0 +1,32 @@
+import { type UserInfoStructured } from './user-output.js';
+declare const userInfo: {
+    name: "user-info";
+    description: string;
+    parameters: {};
+    outputSchema: {
+        type: import("zod").ZodLiteral<"user_info">;
+        userId: import("zod").ZodNumber;
+        name: import("zod").ZodString;
+        shortName: import("zod").ZodString;
+        email: import("zod").ZodString;
+        timezone: import("zod").ZodString;
+        lang: import("zod").ZodString;
+        status: import("zod").ZodOptional<import("zod").ZodObject<{
+            message: import("zod").ZodString;
+            emoji: import("zod").ZodOptional<import("zod").ZodString>;
+            activeUntil: import("zod").ZodOptional<import("zod").ZodString>;
+            pauseNotifications: import("zod").ZodBoolean;
+            pauseActivity: import("zod").ZodBoolean;
+        }, import("zod/v4/core").$strip>>;
+    };
+    annotations: {
+        readOnlyHint: true;
+        destructiveHint: false;
+        idempotentHint: true;
+    };
+    execute(_args: Record<string, never>, client: import("@doist/comms-sdk").CommsApi): Promise<{
+        textContent: string;
+        structuredContent: UserInfoStructured;
+    }>;
+};
+export { userInfo, type UserInfoStructured };

package/dist/tools/user-info.js

@@ -0,0 +1,16 @@
+import { UserInfoOutputSchema } from '../utils/output-schemas.js';
+import { ToolNames } from '../utils/tool-names.js';
+import { buildUserInfoResult } from './user-output.js';
+const ArgsSchema = {};
+const userInfo = {
+    name: ToolNames.USER_INFO,
+    description: 'Get information about the authenticated Comms user: user ID, full name, short name, email, timezone, language, and the status shown next to their name in Comms and Todoist.',
+    parameters: ArgsSchema,
+    outputSchema: UserInfoOutputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    async execute(_args, client) {
+        const user = await client.users.getSessionUser();
+        return buildUserInfoResult(user);
+    },
+};
+export { userInfo };

package/dist/tools/user-output.d.ts

@@ -0,0 +1,9 @@
+import type { User } from '@doist/comms-sdk';
+import type { UserInfoOutput } from '../utils/output-schemas.js';
+type UserInfoStructured = Record<string, unknown> & UserInfoOutput;
+/** The user-info result for a user, shared with update-user-info so both report the same way. */
+declare function buildUserInfoResult(user: User): {
+    textContent: string;
+    structuredContent: UserInfoStructured;
+};
+export { buildUserInfoResult, type UserInfoStructured };

package/dist/tools/user-output.js

@@ -0,0 +1,28 @@
+import { describeStatus, toStatusOutput } from '../utils/user-status.js';
+/** The user-info result for a user, shared with update-user-info so both report the same way. */
+function buildUserInfoResult(user) {
+    const status = user.status ? toStatusOutput(user.status) : undefined;
+    const lines = [
+        '# User Information',
+        '',
+        `**User ID:** ${user.id}`,
+        `**Name:** ${user.fullName}`,
+        `**Short Name:** ${user.shortName}`,
+        `**Email:** ${user.email}`,
+        `**Timezone:** ${user.timezone}`,
+        `**Language:** ${user.lang}`,
+        ...describeStatus(status),
+    ];
+    const structuredContent = {
+        type: 'user_info',
+        userId: user.id,
+        name: user.fullName,
+        shortName: user.shortName,
+        email: user.email,
+        timezone: user.timezone,
+        lang: user.lang,
+        ...(status ? { status } : {}),
+    };
+    return { textContent: lines.join('\n'), structuredContent };
+}
+export { buildUserInfoResult };

package/dist/usage-tracking.d.ts

@@ -0,0 +1,23 @@
+import { CommsApi } from '@doist/comms-sdk';
+import type { McpServerOptions } from '@todoist/mcp-core/host';
+declare const COMMS_MCP_VERSION: string;
+/**
+ * Runs `run` as a call of the tool named `tool`: every Comms API request it makes, however
+ * deep and however late, is tagged with that name. Concurrent calls each keep their own.
+ */
+declare function runAsTool<T>(tool: string, run: () => T): T;
+/**
+ * The headers the Comms API reads to attribute a request to this server and to the tool that
+ * made it. `tool` defaults to the tool whose call is running, or `unknown` outside one.
+ */
+declare function buildUsageTrackingHeaders(tool?: string): Record<string, string>;
+/**
+ * A Comms API client that tags every request with the usage-tracking headers.
+ *
+ * The SDK calls `headers` once per request (its retries reuse the result), from inside the
+ * request's own async context, so the tool name is whichever call made the request. This keeps
+ * the SDK's own transport, with its proxy support and timeouts, rather than replacing it with a
+ * `customFetch`.
+ */
+declare function createCommsClient({ token, baseUrl }: McpServerOptions): CommsApi;
+export { COMMS_MCP_VERSION, buildUsageTrackingHeaders, createCommsClient, runAsTool };

package/dist/usage-tracking.js

@@ -0,0 +1,41 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createRequire } from 'node:module';
+import { CommsApi } from '@doist/comms-sdk';
+// Read at runtime: `tsc` compiles only `src/`, so the manifest can't be imported. From `src/`
+// in tests and from `dist/` once installed, it is one directory up either way.
+const { version: COMMS_MCP_VERSION } = createRequire(import.meta.url)('../package.json');
+/** What `mcp-tool` says for a request made outside any tool call. */
+const UNKNOWN_TOOL = 'unknown';
+/** The tool whose call is running, for every request made while it runs. */
+const currentTool = new AsyncLocalStorage();
+/**
+ * Runs `run` as a call of the tool named `tool`: every Comms API request it makes, however
+ * deep and however late, is tagged with that name. Concurrent calls each keep their own.
+ */
+function runAsTool(tool, run) {
+    return currentTool.run(tool, run);
+}
+/**
+ * The headers the Comms API reads to attribute a request to this server and to the tool that
+ * made it. `tool` defaults to the tool whose call is running, or `unknown` outside one.
+ */
+function buildUsageTrackingHeaders(tool = currentTool.getStore() ?? UNKNOWN_TOOL) {
+    return {
+        'User-Agent': `comms-mcp/${COMMS_MCP_VERSION}`,
+        'Doist-Platform': 'mcp',
+        'Doist-Version': COMMS_MCP_VERSION,
+        'mcp-tool': tool,
+    };
+}
+/**
+ * A Comms API client that tags every request with the usage-tracking headers.
+ *
+ * The SDK calls `headers` once per request (its retries reuse the result), from inside the
+ * request's own async context, so the tool name is whichever call made the request. This keeps
+ * the SDK's own transport, with its proxy support and timeouts, rather than replacing it with a
+ * `customFetch`.
+ */
+function createCommsClient({ token, baseUrl }) {
+    return new CommsApi(token, { baseUrl, headers: () => buildUsageTrackingHeaders() });
+}
+export { COMMS_MCP_VERSION, buildUsageTrackingHeaders, createCommsClient, runAsTool };

package/dist/utils/attachments.d.ts

@@ -0,0 +1,24 @@
+import { type Attachment } from '@doist/comms-sdk';
+import type { OutputAttachment } from './output-schemas.js';
+export type { Attachment };
+/**
+ * Coerce a raw `attachments` value from the Comms API into a list of attachment
+ * objects, dropping anything that doesn't carry the two fields every attachment
+ * is guaranteed to have (`attachmentId` and `urlType`). Returns `undefined` when
+ * nothing valid remains so callers can omit the field entirely rather than
+ * emitting an empty array or a malformed entry that fails the output schema.
+ *
+ * The API sends `null` for fields an attachment lacks. Those are dropped here,
+ * since the output schema declares them optional rather than nullable.
+ *
+ * Note: an attachment's `url` points at the Comms file store and currently
+ * requires a browser session cookie to download — there is no OAuth-authenticated
+ * attachment download endpoint on the public Comms REST API today.
+ */
+export declare function normalizeAttachments(value: unknown): OutputAttachment[] | undefined;
+/**
+ * Render a one-line `**Attachments (n):** ...` summary, or `undefined` when there
+ * are none. Each attachment shows its name (falling back to title), an optional
+ * byte size, and its URL.
+ */
+export declare function formatAttachmentsLine(attachments: Attachment[] | undefined): string | undefined;

package/dist/utils/attachments.js

@@ -0,0 +1,57 @@
+import { removeNullFields } from '@todoist/mcp-core';
+/**
+ * Separator between an attachment's label and its URL in the formatted text line.
+ * Kept in one place so the rendering logic below stays in sync with itself.
+ */
+const URL_SEPARATOR = ' — ';
+/**
+ * Coerce a raw `attachments` value from the Comms API into a list of attachment
+ * objects, dropping anything that doesn't carry the two fields every attachment
+ * is guaranteed to have (`attachmentId` and `urlType`). Returns `undefined` when
+ * nothing valid remains so callers can omit the field entirely rather than
+ * emitting an empty array or a malformed entry that fails the output schema.
+ *
+ * The API sends `null` for fields an attachment lacks. Those are dropped here,
+ * since the output schema declares them optional rather than nullable.
+ *
+ * Note: an attachment's `url` points at the Comms file store and currently
+ * requires a browser session cookie to download — there is no OAuth-authenticated
+ * attachment download endpoint on the public Comms REST API today.
+ */
+export function normalizeAttachments(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const attachments = value.filter((item) => {
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            return false;
+        }
+        const candidate = item;
+        return typeof candidate.attachmentId === 'string' && typeof candidate.urlType === 'string';
+    });
+    return attachments.length > 0
+        ? attachments.map((attachment) => removeNullFields(attachment))
+        : undefined;
+}
+/**
+ * Render a one-line `**Attachments (n):** ...` summary, or `undefined` when there
+ * are none. Each attachment shows its name (falling back to title), an optional
+ * byte size, and its URL.
+ */
+export function formatAttachmentsLine(attachments) {
+    if (!attachments || attachments.length === 0) {
+        return undefined;
+    }
+    const items = attachments
+        .map((a) => {
+        const name = a.fileName ?? a.title ?? undefined;
+        const size = typeof a.fileSize === 'number' ? ` (${a.fileSize} bytes)` : '';
+        const url = a.url ?? undefined;
+        if (name) {
+            return url ? `${name}${size}${URL_SEPARATOR}${url}` : `${name}${size}`;
+        }
+        return url ?? '(unnamed attachment)';
+    })
+        .join('; ');
+    return `**Attachments (${attachments.length}):** ${items}`;
+}

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Concurrency budget for fan-out call sites that hydrate auxiliary data
+ * (channel metadata, creator names, individual mark-done operations).
+ *
+ * Today these scale with workspace size and are invisible; the day someone
+ * runs against a 200-thread workspace they otherwise blow through the
+ * undici socket pool / API rate limiter. A small ceiling caps the burst
+ * without slowing the common small case.
+ */
+export declare const FANOUT_CONCURRENCY = 8;
+/**
+ * `Promise.all` with a bounded concurrency budget. Use at every fan-out
+ * site so the choice stays consistent and a single tweak (limit, retry,
+ * tracing) lands in one place instead of three.
+ *
+ * Each item runs `worker(item)` through a fresh `p-limit` instance — the
+ * limit is per-call, not shared across sites, so unrelated tools can't
+ * starve each other.
+ */
+export declare function limitedAll<T, R>(items: readonly T[], worker: (item: T) => Promise<R>, concurrency?: number): Promise<R[]>;

package/dist/utils/concurrency.js

@@ -0,0 +1,24 @@
+import pLimit from 'p-limit';
+/**
+ * Concurrency budget for fan-out call sites that hydrate auxiliary data
+ * (channel metadata, creator names, individual mark-done operations).
+ *
+ * Today these scale with workspace size and are invisible; the day someone
+ * runs against a 200-thread workspace they otherwise blow through the
+ * undici socket pool / API rate limiter. A small ceiling caps the burst
+ * without slowing the common small case.
+ */
+export const FANOUT_CONCURRENCY = 8;
+/**
+ * `Promise.all` with a bounded concurrency budget. Use at every fan-out
+ * site so the choice stays consistent and a single tweak (limit, retry,
+ * tracing) lands in one place instead of three.
+ *
+ * Each item runs `worker(item)` through a fresh `p-limit` instance — the
+ * limit is per-call, not shared across sites, so unrelated tools can't
+ * starve each other.
+ */
+export async function limitedAll(items, worker, concurrency = FANOUT_CONCURRENCY) {
+    const limit = pLimit(concurrency);
+    return Promise.all(items.map((item) => limit(() => worker(item))));
+}

package/dist/utils/constants.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shown in place of a name when a user ID can't be resolved — the user has been
+ * removed, or the viewer may not see them.
+ */
+export declare const UNKNOWN_USER = "Unknown user";

package/dist/utils/constants.js

@@ -0,0 +1,5 @@
+/**
+ * Shown in place of a name when a user ID can't be resolved — the user has been
+ * removed, or the viewer may not see them.
+ */
+export const UNKNOWN_USER = 'Unknown user';

package/dist/utils/degrade.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Several tools deliberately degrade past a lookup they can live without — a name
+ * they only needed for a label, a channel they can identify by ID. Swallowing the
+ * rejection silently leaves a user who has left the workspace looking exactly like
+ * an expired token, so record what was dropped and why.
+ */
+import type { CommsApi, VisibleWorkspaceUser } from '@doist/comms-sdk';
+/** Failed identifiers reported per batch before the rest are counted only. */
+export declare const SAMPLE_LIMIT = 5;
+type Runner = <T, R>(items: readonly T[], worker: (item: T) => Promise<R>) => Promise<R[]>;
+/**
+ * Resolves every id, degrading past individual failures to `null` and reporting
+ * them as one log line per batch.
+ *
+ * A batch is as large as the caller's input, so one expired token must not
+ * become one log event per id.
+ *
+ * @param toolName - The tool doing the lookups, for the log prefix.
+ * @param message - What could not be resolved, e.g. 'failed to resolve channel creator'.
+ * @param ids - The identifiers to resolve.
+ * @param resolve - Performs one lookup.
+ * @param options.runner - How to run the batch. Defaults to `Promise.all`; pass
+ * `limitedAll` at fan-out sites that need a concurrency ceiling.
+ * @returns Each result in input order, with `null` where the lookup failed.
+ */
+export declare function degradeAllWithLog<Id, T>(toolName: string, message: string, ids: readonly Id[], resolve: (id: Id) => Promise<T>, options?: {
+    runner?: Runner;
+}): Promise<(T | null)[]>;
+/**
+ * Resolves workspace users in one batched lookup, degrading the way
+ * {@link degradeAllWithLog} does: a user the workspace has no record of, or a
+ * failed request, is left out of the result and reported in one log line.
+ *
+ * @param client - The Comms API client.
+ * @param toolName - The tool doing the lookups, for the log prefix.
+ * @param message - What could not be resolved, e.g. 'failed to resolve thread participant'.
+ * @param workspaceId - The workspace the users belong to.
+ * @param userIds - The users to resolve.
+ * @returns The resolved users keyed by id.
+ */
+export declare function resolveUsersWithLog(client: CommsApi, toolName: string, message: string, workspaceId: number, userIds: readonly number[]): Promise<Map<number, VisibleWorkspaceUser>>;
+/**
+ * Builds a `.catch` handler that logs the failure and resolves to `fallback`.
+ * For one-off lookups; use {@link degradeAllWithLog} for a batch, so a batch of
+ * failures reports once rather than per id.
+ *
+ * @param toolName - The tool doing the lookup, for the log prefix.
+ * @param message - What could not be resolved.
+ * @param context - Identifiers worth having in the log, e.g. `{ workspaceId }`.
+ * @param fallback - The value to resolve to instead.
+ */
+export declare function degradeWithLog<T>(toolName: string, message: string, context: Record<string, unknown>, fallback: T): (error: unknown) => T;
+/**
+ * Reports the items a batch tool could not act on, as one log line per call.
+ *
+ * Tools like mark-done and mark-read fold per-item errors into the tool result
+ * instead of throwing, so without this the server answers 200 and logs nothing
+ * while a caller's items stayed untouched — a whole batch can fail on an expired
+ * token or a dropped connection with no trace on this side. Stays quiet when
+ * there is nothing to report.
+ *
+ * Sample entries are logged as given, so pass only the fields worth having in
+ * a log line.
+ *
+ * @param toolName - The tool that ran the batch, for the log prefix.
+ * @param failed - Items the tool could not complete.
+ * @param options.warnings - Items that completed but with a secondary op failing.
+ * @param options.context - Extra attributes for the log line, e.g. `{ itemType }`.
+ */
+export declare function logOperationFailures(toolName: string, failed: ReadonlyArray<{
+    item: string;
+    error: string;
+}>, options?: {
+    warnings?: ReadonlyArray<{
+        item: string;
+        op: string;
+        error: string;
+    }>;
+    context?: Record<string, unknown>;
+}): void;
+export {};