@loicngr/kobo 2.1.15 → 2.1.16

package/dist/server/services/workspace-group-message-service.js

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto';
+import { parseGroupMessageInput, } from '../../shared/workspace-group-messages.js';
+import { getDb } from '../db/index.js';
+import { isShuttingDown } from './agent/orchestrator.js';
+import { broadcastPersistedEvent, persistWorkspaceEvent } from './websocket-service.js';
+import { deliverWorkspaceMessage } from './workspace-message-service.js';
+import { getWorkspace } from './workspace-service.js';
+export class GroupMessageError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+const jobs = [];
+const active = new Set();
+let stopping = false;
+export function getGroupMessageBatch(id) {
+    const row = getDb().prepare('SELECT receipt_json FROM workspace_message_batches WHERE id=?').get(id);
+    return row ? JSON.parse(row.receipt_json) : undefined;
+}
+function updateRecipient(id, workspaceId, state, error) {
+    const batch = getGroupMessageBatch(id);
+    if (!batch)
+        throw new Error('Group message receipt is unavailable');
+    const recipient = batch.recipients.find((item) => item.workspaceId === workspaceId);
+    recipient.state = state;
+    if (error)
+        recipient.error = error.slice(0, 1000);
+    else
+        delete recipient.error;
+    batch.complete = batch.recipients.every((item) => item.state !== 'pending' && item.state !== 'sending');
+    getDb().prepare('UPDATE workspace_message_batches SET receipt_json=? WHERE id=?').run(JSON.stringify(batch), id);
+}
+/** Persist before scheduling. Repeating an ID only observes its existing immutable request. */
+export function startGroupMessageBatch(value, source) {
+    let input;
+    try {
+        input = parseGroupMessageInput(value);
+    }
+    catch (error) {
+        throw new GroupMessageError(error instanceof Error ? error.message : String(error), 400);
+    }
+    const fingerprint = createHash('sha256')
+        .update(JSON.stringify([input.content, [...input.workspaceIds].sort(), source ?? null]))
+        .digest('hex');
+    const db = getDb();
+    const result = db
+        .transaction(() => {
+        const row = db
+            .prepare('SELECT fingerprint,receipt_json FROM workspace_message_batches WHERE id=?')
+            .get(input.requestId);
+        if (row) {
+            if (row.fingerprint !== fingerprint)
+                throw new GroupMessageError('This requestId was already used for different content, recipients or source', 409);
+            return { fresh: false, batch: JSON.parse(row.receipt_json) };
+        }
+        if (stopping || isShuttingDown())
+            throw new GroupMessageError('Kōbō is shutting down', 503);
+        const batch = {
+            id: input.requestId,
+            createdAt: new Date().toISOString(),
+            complete: false,
+            recipients: input.workspaceIds.map((workspaceId) => {
+                const workspace = getWorkspace(workspaceId);
+                const error = !workspace
+                    ? 'Workspace not found'
+                    : workspace.archivedAt || workspace.worktreePurgedAt
+                        ? 'Restore the workspace before sending a message'
+                        : undefined;
+                return {
+                    workspaceId,
+                    name: workspace?.name ?? workspaceId,
+                    delivery: workspace?.autoLoop ? 'next_iteration' : 'immediate',
+                    state: error ? 'rejected' : 'pending',
+                    ...(error ? { error } : {}),
+                };
+            }),
+        };
+        batch.complete = batch.recipients.every((item) => item.state === 'rejected');
+        db.prepare('INSERT INTO workspace_message_batches(id,fingerprint,receipt_json,created_at) VALUES (?,?,?,?)').run(batch.id, fingerprint, JSON.stringify(batch), batch.createdAt);
+        return { fresh: true, batch };
+    })
+        .immediate();
+    if (result.fresh) {
+        for (const recipient of result.batch.recipients)
+            if (recipient.state === 'pending')
+                jobs.push({ batchId: result.batch.id, recipient, content: input.content, source });
+        queueMicrotask(pump);
+    }
+    return result.batch;
+}
+async function deliver(job) {
+    const { batchId, recipient } = job;
+    let dispatched = false;
+    let accepted = false;
+    try {
+        updateRecipient(batchId, recipient.workspaceId, 'sending');
+        await deliverWorkspaceMessage(recipient.workspaceId, {
+            content: job.content,
+            source: job.source,
+            delivery: recipient.delivery,
+            clientMessageId: `group-${createHash('sha256')
+                .update(JSON.stringify([batchId, recipient.workspaceId]))
+                .digest('hex')}`,
+        }, {
+            beforeDispatch() {
+                const workspace = getWorkspace(recipient.workspaceId);
+                if (!workspace || !!workspace.autoLoop !== (recipient.delivery === 'next_iteration'))
+                    throw new Error('Auto-loop mode changed since submission; review the recipient before sending again');
+                dispatched = true;
+            },
+            persist(payload, sessionId) {
+                const event = getDb().transaction(() => {
+                    const persisted = persistWorkspaceEvent(recipient.workspaceId, 'user:message', payload, sessionId);
+                    updateRecipient(batchId, recipient.workspaceId, recipient.delivery === 'next_iteration' ? 'queued' : 'sent');
+                    return persisted;
+                })();
+                accepted = true;
+                broadcastPersistedEvent(event);
+            },
+        });
+        if (!accepted)
+            throw new Error('Delivery completed without a durable receipt');
+    }
+    catch (error) {
+        if (accepted)
+            return;
+        updateRecipient(batchId, recipient.workspaceId, dispatched ? 'unknown' : 'rejected', error instanceof Error ? error.message : String(error));
+    }
+}
+function pump() {
+    if (stopping)
+        return;
+    while (active.size < 3 && jobs.length) {
+        const job = jobs.shift();
+        const task = deliver(job)
+            .catch((error) => console.error('[group-message] Receipt persistence failed:', error))
+            .finally(() => {
+            active.delete(task);
+            pump();
+        });
+        active.add(task);
+    }
+}
+/** Startup only: persisted uncertain work is never automatically dispatched again. */
+export function reconcileGroupMessageBatches(db) {
+    stopping = false;
+    db.transaction(() => {
+        const rows = db.prepare('SELECT id,receipt_json FROM workspace_message_batches').all();
+        for (const row of rows) {
+            const batch = JSON.parse(row.receipt_json);
+            if (batch.complete)
+                continue;
+            for (const recipient of batch.recipients) {
+                if (recipient.state === 'pending') {
+                    recipient.state = 'not_sent';
+                    recipient.error = 'Server stopped before delivery';
+                }
+                else if (recipient.state === 'sending') {
+                    recipient.state = 'unknown';
+                    recipient.error = 'Server stopped during delivery; inspect workspace history before sending again';
+                }
+            }
+            batch.complete = true;
+            db.prepare('UPDATE workspace_message_batches SET receipt_json=? WHERE id=?').run(JSON.stringify(batch), row.id);
+        }
+    })();
+}
+export async function stopGroupMessageBatches() {
+    stopping = true;
+    for (const job of jobs.splice(0)) {
+        try {
+            updateRecipient(job.batchId, job.recipient.workspaceId, 'not_sent', 'Server stopped before delivery');
+        }
+        catch (error) {
+            // Startup will reconcile the durable pending row; still drain active jobs before closing SQLite.
+            console.error('[group-message] Could not persist shutdown receipt:', error);
+        }
+    }
+    await Promise.allSettled([...active]);
+}

package/dist/server/services/workspace-lifecycle-mcp-service.js

@@ -0,0 +1,72 @@
+import { validateWorkspaceLifecycleArguments } from '../../shared/workspace-lifecycle-tools.js';
+export class WorkspaceLifecycleMcpError extends Error {
+    status;
+    stage;
+    details;
+    constructor(message, status, stage, details = null) {
+        super(message);
+        this.status = status;
+        this.stage = stage;
+        this.details = details;
+        this.name = 'WorkspaceLifecycleMcpError';
+    }
+}
+async function request(dispatch, path, stage, method, body) {
+    const response = await dispatch(path, {
+        method,
+        ...(body === undefined ? {} : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
+    });
+    const payload = response.status === 204 ? null : await response.json().catch(() => null);
+    if (!response.ok)
+        throw new WorkspaceLifecycleMcpError(payload?.error ?? `Workspace lifecycle request failed (${response.status})`, response.status, stage, payload);
+    return payload;
+}
+/** The HTTP lifecycle remains the sole owner of stopping, locks and cleanup. */
+export async function executeWorkspaceLifecycleTool(name, raw, dispatch) {
+    let input;
+    try {
+        input = validateWorkspaceLifecycleArguments(name, raw);
+    }
+    catch (error) {
+        throw new WorkspaceLifecycleMcpError(error instanceof Error ? error.message : 'Invalid arguments', 400, 'validate');
+    }
+    const workspaceId = input.workspace_id;
+    const path = `/api/workspaces/${encodeURIComponent(workspaceId)}`;
+    if (name === 'archive_workspace')
+        return request(dispatch, `${path}/archive`, 'archive', 'POST');
+    if (name === 'purge_workspace_worktree')
+        return request(dispatch, `${path}/purge-worktree`, 'purge', 'POST');
+    if (name === 'unarchive_workspace')
+        return request(dispatch, `${path}/unarchive`, 'unarchive', 'POST');
+    if (name === 'restore_workspace') {
+        let workspace = (await request(dispatch, path, 'lookup', 'GET'));
+        if (!workspace.archivedAt && !workspace.worktreePurgedAt)
+            return { workspace, outcome: 'unchanged' };
+        let restoration = {
+            workspace,
+            outcome: 'unarchived',
+        };
+        if (workspace.worktreePurgedAt || workspace.worktreeOwned !== false) {
+            // Even without a purge flag, check an owned archived checkout on disk.
+            // The existing restore endpoint rejects missing manual deletions rather
+            // than silently announcing successful restoration of an absent folder.
+            restoration = (await request(dispatch, `${path}/restore-worktree`, 'restore', 'POST'));
+            workspace = restoration.workspace;
+        }
+        if (workspace.archivedAt)
+            workspace = (await request(dispatch, `${path}/unarchive`, 'unarchive', 'POST'));
+        return { ...restoration, workspace };
+    }
+    const workspace = (await request(dispatch, path, 'lookup', 'GET'));
+    const confirmationBranch = input.confirmation_branch.trim();
+    if (workspace?.workingBranch !== confirmationBranch)
+        throw new WorkspaceLifecycleMcpError('confirmation_branch must match the current workspace working branch', 409, 'confirm-delete');
+    const result = await request(dispatch, path, 'delete', 'DELETE', {
+        deleteLocalBranch: input.delete_local_branch ?? false,
+        deleteRemoteBranch: input.delete_remote_branch ?? false,
+        // Rechecked by the existing route under its lifecycle guard, so a changed
+        // branch between GET and DELETE cannot authorize a different deletion.
+        confirmationBranch,
+    });
+    return result ?? { ok: true, workspaceId, warnings: [] };
+}

package/dist/server/services/workspace-message-service.js

@@ -24,6 +24,11 @@ export async function deliverWorkspaceMessage(workspaceId, message, hooks) {
             if (!message.clientMessageId)
                 throw new Error('clientMessageId is required for queued delivery');
             const acceptedBefore = hasLoopMessage(workspaceId, message.clientMessageId);
+            if (!acceptedBefore) {
+                if (!workspace.autoLoop)
+                    throw new Error('Auto-loop is not enabled');
+                hooks?.beforeDispatch?.();
+            }
             if (!autoLoop.queueInstruction(workspaceId, message.content, message.clientMessageId, message.source))
                 throw new Error('Auto-loop is not enabled');
             if (!acceptedBefore)

package/dist/shared/pr-checkout-steps.js

@@ -0,0 +1,86 @@
+/** Blockers the user CAN resolve, by picking another worktree path. Everything
+ *  else (missing CLI, fork PR, deleted remote branch, index.lock, unrelated
+ *  history) leaves nothing to choose and ends the flow. */
+const RESOLVABLE_BLOCKERS = new Set(['path-occupied', 'worktree-other-branch']);
+/**
+ * Derive the ordered steps for a report. A blocker short-circuits everything:
+ * there is no point asking about a stash when the forge CLI is missing.
+ * `operation` precedes `changes` because aborting a rebase changes what is dirty.
+ */
+export function deriveSteps(report) {
+    const fatal = report.blockers.filter((b) => !RESOLVABLE_BLOCKERS.has(b.kind));
+    if (fatal.length > 0) {
+        return [{ id: 'blocked', blocking: true, titleKey: 'prCheckout.step.blocked' }];
+    }
+    const steps = [];
+    if (report.blockers.some((b) => RESOLVABLE_BLOCKERS.has(b.kind))) {
+        steps.push({ id: 'path', blocking: false, titleKey: 'prCheckout.step.path' });
+    }
+    if (report.workspace.state !== 'none') {
+        steps.push({ id: 'workspace', blocking: false, titleKey: 'prCheckout.step.workspace' });
+    }
+    // A purged workspace's worktree can reappear as an 'orphan' on disk during the
+    // pr-watcher's restore window (see AGENTS.md § Worktree purge) — restoring the
+    // workspace (via the 'workspace' step above) already handles reattaching it, so
+    // this must not also surface as a separate worktree step.
+    if (report.workspace.state !== 'purged' &&
+        (report.worktree.state === 'orphan' || report.worktree.state === 'attached')) {
+        steps.push({ id: 'worktree', blocking: false, titleKey: 'prCheckout.step.worktree' });
+    }
+    if (report.ongoingOperation) {
+        steps.push({ id: 'operation', blocking: false, titleKey: 'prCheckout.step.operation' });
+    }
+    if (report.localChanges.present) {
+        steps.push({ id: 'changes', blocking: false, titleKey: 'prCheckout.step.changes' });
+    }
+    if (report.branch.state === 'behind' || report.branch.state === 'ahead' || report.branch.state === 'diverged') {
+        steps.push({ id: 'divergence', blocking: false, titleKey: 'prCheckout.step.divergence' });
+    }
+    return steps;
+}
+/**
+ * The pre-selected choice for each step. The rule that matters: wherever local
+ * commits or local edits exist, the default is the one that loses nothing.
+ */
+export function defaultDecisions(report) {
+    const decisions = {};
+    if (report.workspace.state === 'active')
+        decisions.existingWorkspace = 'open';
+    if (report.workspace.state === 'archived')
+        decisions.archivedWorkspace = 'unarchive';
+    if (report.workspace.state === 'purged')
+        decisions.purgedWorktree = 'restore';
+    // A purged workspace's worktree can reappear as an 'orphan' on disk during the
+    // pr-watcher's restore window (see AGENTS.md § Worktree purge) — restoring the
+    // workspace already handles reattaching it, so this must not also surface as a
+    // separate 'attach' decision.
+    if (report.workspace.state !== 'purged' && report.worktree.state === 'orphan')
+        decisions.orphanWorktree = 'attach';
+    // 'cancel' — not 'abort' — is the loses-nothing default: aborting a rebase
+    // or merge discards any conflict-resolution work already staged, exactly
+    // the kind of destructive default this function otherwise avoids.
+    if (report.ongoingOperation)
+        decisions.ongoingOperation = 'cancel';
+    if (report.localChanges.present)
+        decisions.localChanges = 'keep';
+    if (report.branch.state === 'behind')
+        decisions.divergence = 'fast-forward';
+    else if (report.branch.state === 'ahead' || report.branch.state === 'diverged')
+        decisions.divergence = 'keep';
+    return decisions;
+}
+/** Return an i18n key for choices that cannot preserve the requested work. */
+export function checkoutDecisionError(report, decisions) {
+    if (decisions.divergence === 'fast-forward' &&
+        (report.branch.state === 'ahead' || report.branch.state === 'diverged'))
+        return 'prCheckout.divergence.notFastForward';
+    if ((report.worktree.state === 'orphan' || report.worktree.state === 'attached') &&
+        decisions.orphanWorktree === 'create-elsewhere')
+        return 'prCheckout.worktree.branchInUse';
+    if (report.localChanges.present &&
+        (decisions.localChanges ?? 'keep') === 'keep' &&
+        decisions.divergence === 'reset-hard') {
+        return 'prCheckout.changes.keepResetConflict';
+    }
+    return null;
+}

package/dist/shared/workspace-creation-tools.js

@@ -0,0 +1,182 @@
+import { MAX_ATTACHMENTS, MAX_ATTACHMENTS_BYTES, validateAttachments } from './attachments.js';
+/** Base64 expansion of the shared upload limit, plus bounded JSON metadata. */
+export const MAX_MCP_CREATION_REQUEST_BYTES = Math.ceil(MAX_ATTACHMENTS_BYTES / 3) * 4 + 1024 * 1024;
+const string = (maxLength = 200, minLength = 1) => ({ type: 'string', minLength, maxLength });
+const choice = (...values) => ({ type: 'string', enum: values });
+const object = (properties, required = []) => ({
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+});
+const effort = choice('auto', 'none', 'low', 'medium', 'high', 'xhigh', 'max');
+const engine = choice('claude-code', 'codex');
+const path = string(4096);
+const url = string(4096);
+const titles = { type: 'array', items: string(20_000), maxItems: 500 };
+const properties = {
+    name: string(1000),
+    project_path: path,
+    source_branch: string(1024),
+    working_branch: string(1024),
+    engine,
+    model: string(),
+    reasoning_effort: effort,
+    brainstorm_model: string(),
+    brainstorm_reasoning_effort: effort,
+    description: string(200_000, 0),
+    tags: { type: 'array', items: string(200), maxItems: 100 },
+    tasks: titles,
+    acceptance_criteria: titles,
+    agent_permission_mode: choice('plan', 'bypass', 'strict', 'interactive'),
+    auto_loop: { type: 'boolean' },
+    auto_loop_session_mode: choice('per_task', 'continuous'),
+    skip_setup_script: { type: 'boolean' },
+    auto_loop_final_review: {
+        ...object({ engine, model: string(), reasoning_effort: effort, additional_instructions: string(20_000, 0) }, [
+            'engine',
+            'model',
+            'reasoning_effort',
+        ]),
+        type: ['object', 'null'],
+    },
+    workflow_policy: object({
+        commit: choice('manual', 'automatic'),
+        push: choice('manual', 'automatic'),
+        publish: choice('manual', 'automatic'),
+    }),
+    notion_url: {
+        ...url,
+        description: 'Import this Notion ticket before launching the agent. Requires an enabled, configured Notion integration.',
+    },
+    notion_page_id: {
+        ...string(),
+        description: 'Optional stored Notion page identifier. Does not import content on its own; provide notion_url to import the ticket.',
+    },
+    sentry_url: url,
+    pr_url: url,
+    worktree_path: path,
+    comparison_id: string(),
+    creation_id: string(),
+    attachments: {
+        type: 'array',
+        maxItems: MAX_ATTACHMENTS,
+        items: object({ name: string(255), mime_type: string(200, 0), data_base64: string(Math.ceil(MAX_ATTACHMENTS_BYTES / 3) * 4) }, ['name', 'mime_type', 'data_base64']),
+    },
+    pr_checkout: object({
+        fingerprint: string(),
+        decisions: object({
+            existingWorkspace: choice('open', 'continue'),
+            archivedWorkspace: choice('unarchive', 'continue'),
+            purgedWorktree: choice('restore'),
+            orphanWorktree: choice('attach', 'create-elsewhere'),
+            pathCollision: object({ worktreePath: path }, ['worktreePath']),
+            localChanges: choice('stash', 'commit', 'discard', 'keep'),
+            ongoingOperation: choice('abort', 'cancel'),
+            divergence: choice('fast-forward', 'rebase', 'reset-hard', 'keep'),
+        }),
+    }, ['fingerprint', 'decisions']),
+};
+const schemas = {
+    create_workspace: object(properties, ['name', 'project_path']),
+    diagnose_workspace_pr: object({ project_path: path, pr_url: url }, ['project_path', 'pr_url']),
+};
+export const WORKSPACE_CREATION_TOOLS = [
+    {
+        name: 'create_workspace',
+        description: 'Create a Kōbō workspace with the same configuration as the create form, including final review, workflow policy, imports and inline base64 attachments (10 files, 50 MiB total). Plain creation requires source_branch and working_branch; worktree_path requires source_branch. A pr_url derives canonical branches and diagnoses checkout first. Unsafe or ambiguous checkout returns requiresAction and a fingerprint: repeat with explicit pr_checkout decisions. Never silently discards local work. Existing workspaces can be opened or explicitly unarchived; no duplicate is created. skip_setup_script defaults to true for PR checkout. Project must be configured in Kōbō.',
+        inputSchema: schemas.create_workspace,
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    {
+        name: 'diagnose_workspace_pr',
+        description: 'Read the canonical PR and local checkout state for a configured project. Returns report, pr and fingerprint for explicit create_workspace pr_checkout decisions; creates no workspace and applies no checkout changes.',
+        inputSchema: schemas.diagnose_workspace_pr,
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+];
+export function isWorkspaceCreationTool(name) {
+    return Object.hasOwn(schemas, name);
+}
+function validate(schema, value, label) {
+    if (value === null && Array.isArray(schema.type))
+        return;
+    if (schema.type === 'object' || Array.isArray(schema.type)) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(`${label} must be an object`);
+        const input = value;
+        for (const key of Object.keys(input)) {
+            if (!Object.hasOwn(schema.properties, key))
+                throw new Error(`Unknown field ${label}.${key}`);
+            validate(schema.properties[key], input[key], `${label}.${key}`);
+        }
+        for (const key of schema.required ?? [])
+            if (!Object.hasOwn(input, key))
+                throw new Error(`${label}.${key} is required`);
+    }
+    else if (schema.type === 'array') {
+        if (!Array.isArray(value) || value.length > schema.maxItems)
+            throw new Error(`${label} must be an array with at most ${schema.maxItems} entries`);
+        for (const item of value)
+            validate(schema.items, item, label);
+    }
+    else if (schema.type === 'boolean') {
+        if (typeof value !== 'boolean')
+            throw new Error(`${label} must be a boolean`);
+    }
+    else {
+        if (typeof value !== 'string' ||
+            value.includes('\0') ||
+            value.length < (schema.minLength ?? 0) ||
+            value.length > (schema.maxLength ?? Infinity) ||
+            (schema.minLength && !value.trim()) ||
+            (schema.enum && !schema.enum.includes(value)))
+            throw new Error(`Invalid ${label}`);
+    }
+}
+/** Validates before dispatch, including uploads before a PR checkout can mutate Git. */
+export function validateWorkspaceCreationArguments(name, input) {
+    if (!isWorkspaceCreationTool(name))
+        throw new Error(`Unknown workspace creation tool: ${name}`);
+    validate(schemas[name], input, name);
+    const value = input;
+    for (const key of ['notion_url', 'sentry_url', 'pr_url']) {
+        if (value[key] !== undefined) {
+            const parsed = new URL(value[key]);
+            if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password)
+                throw new Error(`Invalid ${key}`);
+        }
+    }
+    if (name === 'create_workspace') {
+        const { attachments: _attachments, ...metadataFields } = value;
+        // Keep room for multipart file headers within the downstream 1 MiB allowance.
+        if (new TextEncoder().encode(JSON.stringify(metadataFields)).byteLength > 960 * 1024)
+            throw new Error('Workspace creation metadata exceeds 960 KiB');
+        if (!value.pr_url && (!value.source_branch || (!value.worktree_path && !value.working_branch)))
+            throw new Error('source_branch and working_branch are required unless using a PR or existing worktree');
+        if (value.pr_checkout && !value.pr_url)
+            throw new Error('pr_checkout requires pr_url');
+        const files = (value.attachments ?? []);
+        const metadata = files.map((file) => {
+            if (/[/\\]/.test(file.name) || file.name === '.' || file.name === '..')
+                throw new Error('Attachment name must be a filename, not a path');
+            const data = file.data_base64;
+            if (data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data))
+                throw new Error('Attachment data_base64 must be canonical base64');
+            // Reject non-zero pad bits too, before the server allocates decoded buffers.
+            const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+            if ((data.endsWith('==') && (alphabet.indexOf(data.at(-3)) & 15) !== 0) ||
+                (!data.endsWith('==') && data.endsWith('=') && (alphabet.indexOf(data.at(-2)) & 3) !== 0))
+                throw new Error('Attachment data_base64 must be canonical base64');
+            return {
+                name: file.name,
+                type: file.mime_type,
+                size: (data.length / 4) * 3 - (data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0),
+            };
+        });
+        const error = validateAttachments(metadata);
+        if (error)
+            throw new Error(`Invalid attachments: ${error}`);
+    }
+    return value;
+}

package/dist/shared/workspace-group-message-tools.js

@@ -0,0 +1,134 @@
+import { MAX_GROUP_MESSAGE_LENGTH, MAX_GROUP_MESSAGE_RECIPIENTS, parseGroupMessageInput, } from './workspace-group-messages.js';
+const identifier = { type: 'string', pattern: '^[A-Za-z0-9_-]{1,200}$', minLength: 1, maxLength: 200 };
+const statuses = [
+    'created',
+    'extracting',
+    'brainstorming',
+    'executing',
+    'compacting',
+    'awaiting-user',
+    'completed',
+    'idle',
+    'error',
+    'quota',
+];
+export const WORKSPACE_GROUP_MESSAGE_TOOLS = [
+    {
+        name: 'preview_workspace_group_message',
+        description: 'Preview eligible non-archived, non-purged workspaces before sending a group message. Tags match ANY selected tag, statuses match ANY selected status, and all enabled filters intersect. Set dev_server_running to true to include only workspaces with a running development server. Empty filters select all eligible workspaces. Paginate with offset and limit (maximum 200); results sort by workspace ID. Delivery is immediate for manual workspaces and next_iteration for auto-loop. This is a live preview, not a reservation; explicitly select recipient IDs for send_workspace_group_message.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tags: {
+                    type: 'array',
+                    maxItems: 200,
+                    uniqueItems: true,
+                    items: { type: 'string', minLength: 1, maxLength: 200 },
+                },
+                statuses: {
+                    type: 'array',
+                    uniqueItems: true,
+                    maxItems: statuses.length,
+                    items: { type: 'string', enum: statuses },
+                },
+                dev_server_running: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Only include workspaces whose development server status is running. Intersects other filters.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: MAX_GROUP_MESSAGE_RECIPIENTS,
+                    default: MAX_GROUP_MESSAGE_RECIPIENTS,
+                },
+                offset: { type: 'integer', minimum: 0, default: 0 },
+            },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'send_workspace_group_message',
+        description: 'Send one message to an explicit selection of 1–200 unique workspace IDs after previewing recipients. A workspace-bound agent cannot target its own workspace. Supply a unique request_id; retrying the same ID and identical payload observes the existing batch without resending. Different payloads with that ID fail. Returns a durable asynchronous batch receipt: use get_workspace_group_message to inspect per-recipient outcomes. Manual workspaces receive immediately; auto-loop workspaces queue for their next iteration. Ineligible targets are rejected individually. After interruption, not_sent and unknown outcomes are never automatically retried; inspect history before submitting a new request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: identifier,
+                workspace_ids: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: MAX_GROUP_MESSAGE_RECIPIENTS,
+                    uniqueItems: true,
+                    items: identifier,
+                },
+                content: { type: 'string', minLength: 1, maxLength: MAX_GROUP_MESSAGE_LENGTH },
+            },
+            required: ['request_id', 'workspace_ids', 'content'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    {
+        name: 'get_workspace_group_message',
+        description: 'Read a persisted group-message receipt by request_id, including complete and each recipient state: pending, sending, sent, queued, rejected, unknown, or not_sent. This read never sends or retries messages. Queued means accepted for a future auto-loop iteration, not executed.',
+        inputSchema: {
+            type: 'object',
+            properties: { request_id: identifier },
+            required: ['request_id'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export function isWorkspaceGroupMessageTool(name) {
+    return WORKSPACE_GROUP_MESSAGE_TOOLS.some((tool) => tool.name === name);
+}
+export function validateWorkspaceGroupMessageArguments(name, raw) {
+    const tool = WORKSPACE_GROUP_MESSAGE_TOOLS.find((item) => item.name === name);
+    if (!tool)
+        throw new Error(`Unknown group message tool: ${name}`);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('Arguments must be an object');
+    const input = raw;
+    for (const key of Object.keys(input))
+        if (!Object.hasOwn(tool.inputSchema.properties, key))
+            throw new Error(`Unknown field: ${key}`);
+    for (const key of tool.inputSchema.required ?? [])
+        if (!Object.hasOwn(input, key))
+            throw new Error(`${key} is required`);
+    if (name === 'send_workspace_group_message') {
+        parseGroupMessageInput({ requestId: input.request_id, workspaceIds: input.workspace_ids, content: input.content });
+    }
+    else if (name === 'get_workspace_group_message') {
+        if (typeof input.request_id !== 'string' || !/^[A-Za-z0-9_-]{1,200}$/.test(input.request_id))
+            throw new Error('Invalid request_id');
+    }
+    else {
+        if (input.dev_server_running !== undefined && typeof input.dev_server_running !== 'boolean')
+            throw new Error('Invalid dev_server_running');
+        for (const key of ['tags', 'statuses']) {
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) ||
+                value.length > (key === 'tags' ? 200 : statuses.length) ||
+                new Set(value).size !== value.length ||
+                value.some((item) => typeof item !== 'string' ||
+                    !item.trim() ||
+                    item.length > 200 ||
+                    (key === 'statuses' && !statuses.includes(item))))
+                throw new Error(`Invalid ${key}`);
+        }
+        if (input.limit !== undefined &&
+            (typeof input.limit !== 'number' ||
+                !Number.isSafeInteger(input.limit) ||
+                input.limit < 1 ||
+                input.limit > MAX_GROUP_MESSAGE_RECIPIENTS))
+            throw new Error('Invalid limit');
+        if (input.offset !== undefined &&
+            (typeof input.offset !== 'number' || !Number.isSafeInteger(input.offset) || input.offset < 0))
+            throw new Error('Invalid offset');
+    }
+    return input;
+}