@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/cmos-message.js

@@ -0,0 +1,729 @@
+"use strict";
+// ABOUTME: cmos_message tool — cross-project messaging via cmos-dashboard REST API.
+// ABOUTME: Supports backlog_request, question, status_update, info_push, intel_request, intel_alert.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmosMessageToolDefinition = exports.cmosMessageSchema = exports.MESSAGE_TYPE_MAP = exports.VALID_MESSAGE_TABS = exports.VALID_RESPOND_STATUSES = exports.VALID_MESSAGE_STATUSES = exports.VALID_MESSAGE_TYPES = exports.CMOS_MESSAGE_ACTIONS = void 0;
+exports.getWhoamiDiagnostics = getWhoamiDiagnostics;
+exports.cmosMessage = cmosMessage;
+exports.formatMessageForLLM = formatMessageForLLM;
+/**
+ * cmos_message Tool
+ *
+ * Consolidated messaging tool with action parameter support.
+ * Actions: send, list, respond.
+ * Calls the cmos-dashboard REST API via DashboardClient.
+ *
+ * @module tools/cmos/cmos-message
+ */
+const zod_1 = require("zod");
+const path_1 = __importDefault(require("path"));
+const errors_1 = require("./errors");
+const auth_state_1 = require("../../auth/auth-state");
+const dashboard_client_1 = require("./dashboard-client");
+const client_1 = require("./client");
+const sender_identity_1 = require("./sender-identity");
+const sender_context_1 = require("../../intelligence/sender-context");
+// ─── Constants ───────────────────────────────────────────────────────────────
+exports.CMOS_MESSAGE_ACTIONS = ['send', 'list', 'respond', 'directory', 'whoami'];
+exports.VALID_MESSAGE_TYPES = [
+    'backlog_request',
+    'question',
+    'status_update',
+    'info_push',
+    'intel_request',
+    'intel_alert',
+];
+exports.VALID_MESSAGE_STATUSES = ['pending', 'accepted', 'declined', 'replied'];
+exports.VALID_RESPOND_STATUSES = ['accepted', 'declined', 'replied'];
+exports.VALID_MESSAGE_TABS = ['inbox', 'sent'];
+/**
+ * Message type to ActivityPub verb/object mapping.
+ */
+exports.MESSAGE_TYPE_MAP = {
+    backlog_request: { verb: 'create', object: 'mission' },
+    question: { verb: 'ask', object: 'note' },
+    status_update: { verb: 'update', object: 'mission' },
+    info_push: { verb: 'add', object: 'reference' },
+    intel_request: { verb: 'request', object: 'intelligence' },
+    intel_alert: { verb: 'notify', object: 'intelligence' },
+};
+/** Regex for validating cmos:// addresses. */
+const CMOS_ADDRESS_REGEX = /^cmos:\/\/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+(\/[a-zA-Z0-9_-]+)?$/;
+/** Regex for validating UUID format. */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// ─── Zod Schema ──────────────────────────────────────────────────────────────
+exports.cmosMessageSchema = zod_1.z
+    .object({
+    action: zod_1.z
+        .enum(exports.CMOS_MESSAGE_ACTIONS)
+        .describe('Message action: send | list | respond | directory | whoami'),
+    // send params
+    targetAddress: zod_1.z
+        .string()
+        .optional()
+        .describe('cmos:// address of the recipient (required for send)'),
+    type: zod_1.z
+        .enum(exports.VALID_MESSAGE_TYPES)
+        .optional()
+        .describe('Message type: backlog_request | question | status_update | info_push | intel_request | intel_alert (required for send)'),
+    summary: zod_1.z
+        .string()
+        .optional()
+        .describe('Short description displayed in inbox list (required for send)'),
+    body: zod_1.z.string().optional().describe('Full message content'),
+    senderProjectId: zod_1.z
+        .string()
+        .optional()
+        .describe("Sender's project UUID. Resolved from local metadata.dashboard_project_id when omitted; falls back to matching local cmos_address against /api/projects/me. Agents should leave this unset — it is authoritatively resolved from the cwd's project identity."),
+    evidence: zod_1.z
+        .array(zod_1.z.object({ type: zod_1.z.string(), id: zod_1.z.string() }))
+        .optional()
+        .describe('TraceLab evidence references [{type, id}]'),
+    // list params
+    tab: zod_1.z.enum(exports.VALID_MESSAGE_TABS).optional().describe('inbox (default) or sent'),
+    status: zod_1.z
+        .enum(exports.VALID_MESSAGE_STATUSES)
+        .optional()
+        .describe('Filter by message status for list action'),
+    limit: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe('Max messages to return (default 20)'),
+    // respond params
+    messageId: zod_1.z
+        .string()
+        .optional()
+        .describe('UUID of the message to respond to (required for respond)'),
+    respondStatus: zod_1.z
+        .enum(exports.VALID_RESPOND_STATUSES)
+        .optional()
+        .describe('Response status: accepted | declined | replied (required for respond)'),
+    notes: zod_1.z.string().optional().describe('Response notes'),
+    projectRoot: zod_1.z
+        .string()
+        .optional()
+        .describe('Project root directory to search for CMOS database (defaults to cwd)'),
+})
+    .strict();
+// ─── Tool Definition ─────────────────────────────────────────────────────────
+exports.cmosMessageToolDefinition = {
+    name: 'cmos_message',
+    description: 'Agent messaging tool for cross-project communication via cmos-dashboard. ' +
+        'Actions: send (send message to another project), list (check inbox/sent), ' +
+        'respond (accept/decline/reply to a message), directory (discover addressable projects), ' +
+        'whoami (diagnose sender attribution). ' +
+        'Send auto-detects senderProjectId, normalizes addresses (spaces→hyphens, lowercase), ' +
+        'and validates target against the project directory before sending. ' +
+        'Requires CMOS_DASHBOARD_URL, CMOS_DASHBOARD_USER, and CMOS_DASHBOARD_PASSWORD environment variables.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: [...exports.CMOS_MESSAGE_ACTIONS],
+                description: 'Message action: send | list | respond | directory | whoami',
+            },
+            targetAddress: {
+                type: 'string',
+                description: 'cmos:// address of the recipient. Format: cmos://username/project-name[/mission-id]',
+            },
+            type: {
+                type: 'string',
+                enum: [...exports.VALID_MESSAGE_TYPES],
+                description: 'Message type: backlog_request | question | status_update | info_push | intel_request | intel_alert',
+            },
+            summary: {
+                type: 'string',
+                description: 'Short description displayed in inbox list',
+            },
+            body: { type: 'string', description: 'Full message content' },
+            senderProjectId: {
+                type: 'string',
+                description: "Sender's project UUID. Resolved from local metadata.dashboard_project_id when omitted; falls back to matching local cmos_address against /api/projects/me. Agents typically do not need to pass this.",
+            },
+            evidence: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        type: { type: 'string', description: 'Evidence type' },
+                        id: { type: 'string', description: 'Evidence identifier' },
+                    },
+                    required: ['type', 'id'],
+                },
+                description: 'TraceLab evidence references [{type, id}]',
+            },
+            tab: {
+                type: 'string',
+                enum: [...exports.VALID_MESSAGE_TABS],
+                description: 'inbox (default) or sent',
+            },
+            status: {
+                type: 'string',
+                enum: [...exports.VALID_MESSAGE_STATUSES],
+                description: 'Filter by message status for list action',
+            },
+            limit: {
+                type: 'number',
+                minimum: 1,
+                maximum: 100,
+                description: 'Max messages to return (default 20)',
+            },
+            messageId: {
+                type: 'string',
+                description: 'UUID of the message to respond to',
+            },
+            respondStatus: {
+                type: 'string',
+                enum: [...exports.VALID_RESPOND_STATUSES],
+                description: 'Response status: accepted | declined | replied',
+            },
+            notes: { type: 'string', description: 'Response notes' },
+            projectRoot: {
+                type: 'string',
+                description: 'Project root directory to search for CMOS database (defaults to cwd)',
+            },
+        },
+        required: ['action'],
+        additionalProperties: false,
+    },
+};
+// ─── Action Type Guard ───────────────────────────────────────────────────────
+function isMessageAction(value) {
+    return exports.CMOS_MESSAGE_ACTIONS.includes(value);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Normalize a cmos:// address: lowercase, replace spaces with hyphens,
+ * collapse multiple hyphens, trim whitespace from segments.
+ * Handles input like "cmos://Derek/CMOS Dashboard" → "cmos://derek/cmos-dashboard".
+ */
+function normalizeAddress(address) {
+    if (!address.startsWith('cmos://'))
+        return address;
+    const body = address.slice('cmos://'.length);
+    const normalized = body.toLowerCase().replace(/\s+/g, '-').replace(/-{2,}/g, '-');
+    return `cmos://${normalized}`;
+}
+function normalizeOptionalEnvPath(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return trimmed;
+}
+function formatCandidateLine(candidate) {
+    const status = candidate.accepted ? '✓' : '✗';
+    const location = candidate.projectRoot ? ` ${candidate.projectRoot}` : '';
+    const rejectReason = !candidate.accepted && candidate.rejectReason ? ` — ${candidate.rejectReason}` : '';
+    return `  ${status} ${candidate.source}${location}${rejectReason}`;
+}
+function resolvedFromContext(context) {
+    if (!context) {
+        return {
+            projectRoot: null,
+            source: null,
+            dashboardProjectId: null,
+            cmosAddress: null,
+        };
+    }
+    return {
+        projectRoot: context.projectRoot,
+        source: context.source,
+        dashboardProjectId: context.dashboardProjectId,
+        cmosAddress: context.cmosAddress,
+        ...(context.healed ? { healed: context.healed } : {}),
+    };
+}
+function buildWhoamiWarnings(strictError, relaxedContext, cwd, serverInstallRoot, envCmosProjectRoot, mcpRoots) {
+    const warnings = [];
+    if (envCmosProjectRoot) {
+        warnings.push(`${client_1.CMOS_PROJECT_ROOT_ENV} is set to ${envCmosProjectRoot}. Sprint 53 removed it from tool-call resolution; it now exists only for .env bootstrap.`);
+    }
+    if (cwd === serverInstallRoot) {
+        warnings.push('cwd equals server install root; this path must never be the implicit sender for another project.');
+    }
+    if ((!mcpRoots || mcpRoots.length === 0) && !relaxedContext?.projectRoot) {
+        warnings.push('No MCP roots were advertised and no local CMOS database was resolved; diagnosis is limited to cwd/registry inspection.');
+    }
+    if (relaxedContext?.healed) {
+        warnings.push(`Healed stale cmos_address from ${relaxedContext.healed.previous} to ${relaxedContext.healed.next}.`);
+    }
+    if (strictError) {
+        warnings.push('Next outbound send would fail-closed until sender identity resolves authoritatively.');
+    }
+    return warnings;
+}
+async function getWhoamiDiagnostics(options = {}) {
+    const cwd = path_1.default.resolve(options.cwdOverride ?? process.cwd());
+    const serverInstallRoot = path_1.default.resolve(options.serverInstallRootOverride ?? sender_context_1.SERVER_INSTALL_ROOT);
+    const envCmosProjectRoot = normalizeOptionalEnvPath(process.env[client_1.CMOS_PROJECT_ROOT_ENV]);
+    const serverInstall = {
+        root: serverInstallRoot,
+        wouldHaveBeenUsed: cwd === serverInstallRoot ||
+            (envCmosProjectRoot !== null && path_1.default.resolve(envCmosProjectRoot) === serverInstallRoot),
+        envCmosProjectRoot,
+    };
+    let strictContext;
+    let strictError;
+    try {
+        strictContext = await (0, sender_context_1.resolveSenderContext)({
+            explicitProjectRoot: options.explicitProjectRoot,
+            mcpRoots: options.mcpRoots,
+            requireSenderIdentity: true,
+            cwdOverride: options.cwdOverride,
+            serverInstallRootOverride: options.serverInstallRootOverride,
+        });
+    }
+    catch (err) {
+        if (err instanceof sender_context_1.SenderResolutionError) {
+            strictError = err;
+        }
+        else {
+            throw err;
+        }
+    }
+    let relaxedContext;
+    let relaxedError;
+    if (!strictContext) {
+        try {
+            relaxedContext = await (0, sender_context_1.resolveSenderContext)({
+                explicitProjectRoot: options.explicitProjectRoot,
+                mcpRoots: options.mcpRoots,
+                requireSenderIdentity: false,
+                cwdOverride: options.cwdOverride,
+                serverInstallRootOverride: options.serverInstallRootOverride,
+            });
+        }
+        catch (err) {
+            if (err instanceof sender_context_1.SenderResolutionError) {
+                relaxedError = err;
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    const resolvedContext = strictContext ?? relaxedContext;
+    const candidates = strictContext?.candidates ??
+        strictError?.candidates ??
+        relaxedContext?.candidates ??
+        relaxedError?.candidates ??
+        [];
+    // Sprint 57 m04: attach the local credential store + last deliveryAck snapshot
+    // so agents see auth state without a separate cmos_auth(action=list) call.
+    // Best-effort — never fail whoami because credential-store I/O hiccupped.
+    let authState;
+    try {
+        const authProjectRoot = resolvedContext?.projectRoot ?? options.explicitProjectRoot ?? undefined;
+        authState = await (0, auth_state_1.computeAuthState)(authProjectRoot ? { projectRoot: authProjectRoot } : {});
+    }
+    catch {
+        authState = undefined;
+    }
+    const data = {
+        resolved: resolvedFromContext(resolvedContext),
+        candidates: [...candidates],
+        serverInstall,
+        wouldAttributeAs: {
+            senderProjectId: strictContext?.dashboardProjectId ?? null,
+            senderAddress: strictContext?.cmosAddress ?? null,
+        },
+        ...(authState ? { authState } : {}),
+    };
+    const warnings = buildWhoamiWarnings(strictError, relaxedContext, cwd, serverInstallRoot, envCmosProjectRoot, options.mcpRoots);
+    if (authState?.warning) {
+        warnings.push(authState.warning);
+    }
+    if (strictContext) {
+        return (0, errors_1.createSuccess)(data, warnings);
+    }
+    return {
+        success: false,
+        data,
+        error: {
+            code: strictError?.code ?? 'SENDER_UNRESOLVABLE',
+            message: strictError?.message ??
+                'Could not authoritatively resolve sender context for the next outbound send.',
+            suggestion: 'Pass projectRoot explicitly, run from a directory with cmos/db/cmos.sqlite, or ensure the local CMOS DB has a UUID metadata.dashboard_project_id and canonical project_identity.cmos_address.',
+        },
+        warnings,
+    };
+}
+/**
+ * Fetch the project directory and return addresses that are close matches
+ * to the given target. Uses simple substring matching on address components.
+ */
+async function getSuggestedAddresses(client, targetAddress) {
+    const dirResult = await client.listDirectory();
+    if (!dirResult.success || !dirResult.data?.projects) {
+        return [];
+    }
+    // Extract the project slug from the target (e.g. "cmos-dashboard" from "cmos://derek/cmos-dashboard")
+    const parts = targetAddress.replace('cmos://', '').split('/');
+    const targetSlug = parts[1] ?? '';
+    const targetOwner = parts[0] ?? '';
+    return dirResult.data.projects
+        .filter((p) => {
+        const addr = p.address;
+        const addrParts = addr.replace('cmos://', '').split('/');
+        const slug = addrParts[1] ?? '';
+        const owner = addrParts[0] ?? '';
+        // Match on same owner, or slug contains/is-contained-by target slug
+        return owner === targetOwner || slug.includes(targetSlug) || targetSlug.includes(slug);
+    })
+        .slice(0, 5)
+        .map((p) => p.address);
+}
+// ─── Action Handlers ─────────────────────────────────────────────────────────
+async function handleSend(params, client) {
+    // Validate required params
+    if (!params.targetAddress) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.missingParameter('targetAddress'));
+    }
+    if (!params.type) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.missingParameter('type'));
+    }
+    if (!params.summary) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.missingParameter('summary'));
+    }
+    // Normalize address: lowercase, spaces → hyphens
+    const targetAddress = normalizeAddress(params.targetAddress);
+    // Validate cmos:// address format (after normalization)
+    if (!CMOS_ADDRESS_REGEX.test(targetAddress)) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.invalidParameter('targetAddress', params.targetAddress, [
+            'cmos://username/project-name',
+            'cmos://username/project-name/mission-id',
+        ]));
+    }
+    // Pre-send address resolution — validate target exists
+    const resolveResult = await client.resolveAddress({ address: targetAddress });
+    if (!resolveResult.success) {
+        // On 404, try to suggest close matches from directory
+        if (resolveResult.error?.code === 'DASHBOARD_NOT_FOUND') {
+            const suggestions = await getSuggestedAddresses(client, targetAddress);
+            const hint = suggestions.length > 0
+                ? `Did you mean: ${suggestions.join(', ')}?`
+                : 'Use cmos_message action="directory" to see all addressable projects.';
+            return (0, errors_1.createError)(errors_1.CmosErrors.dashboardNotFound(targetAddress, `Address '${targetAddress}' not found in project directory`, hint));
+        }
+        // For other errors (auth, network), pass through
+        return (0, errors_1.createError)(resolveResult.error);
+    }
+    // Sprint 53 m02: the dispatcher already ran `resolveSenderContext` with
+    // `requireSenderIdentity=true` and passed the resolved projectRoot through in
+    // `params.projectRoot`, so `readLocalSenderIdentity` opens the right DB. The
+    // `assertSenderIdentityValid` call below is defense-in-depth — if any future
+    // caller bypasses the dispatcher boundary and invokes `handleSend` directly
+    // with an unresolvable project, we fail-closed here with
+    // `SENDER_ATTRIBUTION_INCOMPLETE` rather than silently publishing a null sender.
+    // (The dispatcher's `SENDER_UNRESOLVABLE` and this layer's
+    // `SENDER_ATTRIBUTION_INCOMPLETE` are distinct so operators can tell which
+    // gate rejected the send.)
+    const localIdentity = await (0, sender_identity_1.readLocalSenderIdentity)(params.projectRoot);
+    const senderProjectId = params.senderProjectId ?? (await (0, sender_identity_1.resolveLocalSenderProjectId)(client, localIdentity));
+    const senderAddress = localIdentity.cmosAddress ?? undefined;
+    try {
+        (0, sender_identity_1.assertSenderIdentityValid)(localIdentity, senderProjectId);
+    }
+    catch (err) {
+        if (err instanceof sender_identity_1.SenderAttributionIncompleteError) {
+            return (0, errors_1.createError)({
+                code: err.code,
+                message: err.message,
+                suggestion: 'The dispatcher should have caught this via resolveSenderContext — report the call site so ' +
+                    'it can be routed through the audited boundary. Verify CMOS DB has a UUID ' +
+                    'metadata.dashboard_project_id and a canonical project_identity.cmos_address.',
+            });
+        }
+        throw err;
+    }
+    if (senderAddress && params.advertisedRoots && params.advertisedRoots.length > 0) {
+        let matchedAdvertisedRoot = false;
+        for (const root of params.advertisedRoots) {
+            const validation = await (0, sender_context_1.validateProject)(root, { heal: false });
+            if (validation.cmosAddress === senderAddress) {
+                matchedAdvertisedRoot = true;
+                break;
+            }
+        }
+        if (!matchedAdvertisedRoot) {
+            return (0, errors_1.createError)({
+                code: 'SENDER_ATTRIBUTION_MISMATCH',
+                message: `Resolved sender address '${senderAddress}' does not match any advertised MCP root.`,
+                suggestion: 'Verify the MCP client is advertising the intended workspace roots and that the local sender identity belongs to one of them before retrying the send.',
+            });
+        }
+    }
+    // Map type to verb/object
+    const mapping = exports.MESSAGE_TYPE_MAP[params.type];
+    const result = await client.sendMessage({
+        targetAddress,
+        type: params.type,
+        summary: params.summary,
+        body: params.body,
+        evidence: params.evidence,
+        senderProjectId,
+        senderAddress,
+    });
+    if (!result.success) {
+        return (0, errors_1.createError)(result.error);
+    }
+    const response = result.data;
+    const out = {
+        messageId: response.id,
+        targetAddress,
+        status: response.status ?? 'pending',
+        summary: params.summary,
+        verb: mapping.verb,
+        object: mapping.object,
+    };
+    // Echo the address we sent — useful for callers that want to verify attribution
+    // without opening the DB themselves. Only included when we actually sent one.
+    if (senderAddress)
+        out.senderAddress = senderAddress;
+    // Forward dashboard-reported routing/delivery status when present. Absence here
+    // is expected today and does not imply failure; see DashboardMessage.deliveryStatus.
+    if (response.deliveryStatus)
+        out.deliveryStatus = response.deliveryStatus;
+    return (0, errors_1.createSuccess)(out);
+}
+async function handleList(params, client) {
+    const tab = params.tab ?? 'inbox';
+    const limit = params.limit ?? 20;
+    const result = await client.listMessages({
+        tab,
+        status: params.status,
+        limit,
+    });
+    if (!result.success) {
+        return (0, errors_1.createError)(result.error);
+    }
+    return (0, errors_1.createSuccess)({
+        messages: result.data.messages,
+        unreadCount: result.data.unreadCount,
+        totalCount: result.data.totalCount,
+        tab,
+        statusFilter: params.status ?? null,
+    });
+}
+async function handleRespond(params, client) {
+    // Validate required params
+    if (!params.messageId) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.missingParameter('messageId'));
+    }
+    if (!params.respondStatus) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.missingParameter('respondStatus'));
+    }
+    // Validate UUID format
+    if (!UUID_REGEX.test(params.messageId)) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.invalidParameter('messageId', params.messageId, [
+            'UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+        ]));
+    }
+    const result = await client.respondToMessage({
+        messageId: params.messageId,
+        status: params.respondStatus,
+        notes: params.notes,
+    });
+    if (!result.success) {
+        return (0, errors_1.createError)(result.error);
+    }
+    return (0, errors_1.createSuccess)({
+        messageId: params.messageId,
+        previousStatus: 'pending',
+        currentStatus: params.respondStatus,
+        respondedAt: result.data.updatedAt ?? new Date().toISOString(),
+    });
+}
+async function handleDirectory(_params, client) {
+    const result = await client.listDirectory();
+    if (!result.success) {
+        return (0, errors_1.createError)(result.error);
+    }
+    return (0, errors_1.createSuccess)({
+        projects: result.data.projects,
+        totalCount: result.data.totalCount,
+    });
+}
+async function handleWhoami(params) {
+    return getWhoamiDiagnostics({ explicitProjectRoot: params.projectRoot });
+}
+// ─── Main Dispatcher ─────────────────────────────────────────────────────────
+/**
+ * Consolidated cmos_message tool.
+ * Creates a DashboardClient from env and dispatches to action handlers.
+ */
+async function cmosMessage(params) {
+    const actionValue = typeof params.action === 'string' ? params.action : '';
+    if (!isMessageAction(actionValue)) {
+        return (0, errors_1.createError)(errors_1.CmosErrors.invalidAction('cmos_message', actionValue, exports.CMOS_MESSAGE_ACTIONS));
+    }
+    if (actionValue === 'whoami') {
+        return handleWhoami(params);
+    }
+    // Create client via the credential-store-aware factory so device-code-minted
+    // user-scoped keys (Sprint 57) reach the messaging surface. The legacy fromEnv()
+    // factory only consults env-var auth and silently 401s when only a user-scoped
+    // key in the credential store is available.
+    const clientResult = await dashboard_client_1.DashboardClient.fromEnvForProject(params.projectRoot);
+    if (!clientResult.success) {
+        return (0, errors_1.createError)(clientResult.error);
+    }
+    const client = clientResult.data.client;
+    switch (actionValue) {
+        case 'send':
+            return handleSend(params, client);
+        case 'list':
+            return handleList(params, client);
+        case 'respond':
+            return handleRespond(params, client);
+        case 'directory':
+            return handleDirectory(params, client);
+    }
+}
+// ─── LLM Formatter ───────────────────────────────────────────────────────────
+function formatSendForLLM(result) {
+    if (!result.success) {
+        return `Failed to send message: ${result.error?.message ?? 'Unknown error'}\n${result.error?.suggestion ?? ''}`;
+    }
+    const d = result.data;
+    const lines = [
+        `Message sent successfully`,
+        `  ID: ${d.messageId}`,
+        `  To: ${d.targetAddress}`,
+        `  Summary: ${d.summary}`,
+        `  Type: ${d.verb}/${d.object}`,
+        `  Status: ${d.status}`,
+    ];
+    return lines.join('\n');
+}
+function formatListForLLM(result) {
+    if (!result.success) {
+        return `Failed to list messages: ${result.error?.message ?? 'Unknown error'}\n${result.error?.suggestion ?? ''}`;
+    }
+    const d = result.data;
+    const lines = [`Messages (${d.tab}) — ${d.totalCount} total, ${d.unreadCount} unread`];
+    if (d.statusFilter) {
+        lines[0] += ` (filtered: ${d.statusFilter})`;
+    }
+    if (d.messages.length === 0) {
+        lines.push('  No messages');
+    }
+    else {
+        for (const msg of d.messages) {
+            const from = msg.from ? ` from ${msg.from}` : '';
+            lines.push(`  [${msg.status}] ${msg.summary}${from} (${msg.id})`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatRespondForLLM(result) {
+    if (!result.success) {
+        return `Failed to respond to message: ${result.error?.message ?? 'Unknown error'}\n${result.error?.suggestion ?? ''}`;
+    }
+    const d = result.data;
+    return [
+        `Response recorded`,
+        `  Message: ${d.messageId}`,
+        `  Status: ${d.previousStatus} → ${d.currentStatus}`,
+        `  Responded at: ${d.respondedAt}`,
+    ].join('\n');
+}
+function formatDirectoryForLLM(result) {
+    if (!result.success) {
+        return `Failed to list project directory: ${result.error?.message ?? 'Unknown error'}\n${result.error?.suggestion ?? ''}`;
+    }
+    const d = result.data;
+    const lines = [`Project Directory — ${d.totalCount} addressable project(s)`];
+    if (d.projects.length === 0) {
+        lines.push('  No projects found');
+    }
+    else {
+        for (const p of d.projects) {
+            const desc = p.description ? ` — ${p.description}` : '';
+            lines.push(`  ${p.address} (${p.id})${desc}`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatWhoamiForLLM(result) {
+    const d = result.data;
+    const lines = ['Attribution diagnosis'];
+    if (result.success) {
+        const sender = d?.wouldAttributeAs.senderAddress ?? 'unknown sender';
+        const senderId = d?.wouldAttributeAs.senderProjectId
+            ? ` (${d.wouldAttributeAs.senderProjectId})`
+            : '';
+        lines.push(`  Next outbound send would attribute as: ${sender}${senderId}`);
+    }
+    else {
+        lines.push('  Next outbound send would fail closed');
+        if (result.error?.message) {
+            lines.push(`  Error: ${result.error.message}`);
+        }
+    }
+    lines.push(`  Resolved root: ${d?.resolved.projectRoot ?? 'none'}`);
+    lines.push(`  Source: ${d?.resolved.source ?? 'none'}`);
+    lines.push(`  Dashboard project ID: ${d?.resolved.dashboardProjectId ?? 'none'}`);
+    lines.push(`  CMOS address: ${d?.resolved.cmosAddress ?? 'none'}`);
+    if (d?.resolved.healed) {
+        lines.push(`  Healed address: ${d.resolved.healed.previous} -> ${d.resolved.healed.next}`);
+    }
+    lines.push(`  Server install root: ${d?.serverInstall.root ?? sender_context_1.SERVER_INSTALL_ROOT}`);
+    lines.push(`  Legacy server-install fallback risk: ${d?.serverInstall.wouldHaveBeenUsed ? 'yes' : 'no'}`);
+    lines.push(`  ${client_1.CMOS_PROJECT_ROOT_ENV}: ${d?.serverInstall.envCmosProjectRoot ?? 'unset'}`);
+    if (result.warnings && result.warnings.length > 0) {
+        lines.push('Warnings:');
+        for (const warning of result.warnings) {
+            lines.push(`  - ${warning}`);
+        }
+    }
+    lines.push('Candidate trace:');
+    if (!d || d.candidates.length === 0) {
+        lines.push('  No candidates recorded');
+    }
+    else {
+        for (const candidate of d.candidates) {
+            lines.push(formatCandidateLine(candidate));
+        }
+    }
+    return lines.join('\n');
+}
+function formatMessageForLLM(action, result) {
+    if (!result.success && result.error?.code === 'INVALID_ACTION') {
+        const availableActions = result.error.availableActions ??
+            result.error.available_actions ??
+            result.error.validValues ??
+            [];
+        const lines = ['Failed to execute cmos_message', '', `Error: ${result.error.message}`];
+        if (availableActions.length > 0) {
+            lines.push('', `Available actions: ${availableActions.join(', ')}`);
+        }
+        if (result.error.suggestion) {
+            lines.push('', `Suggestion: ${result.error.suggestion}`);
+        }
+        return lines.join('\n');
+    }
+    switch (action) {
+        case 'send':
+            return formatSendForLLM(result);
+        case 'list':
+            return formatListForLLM(result);
+        case 'respond':
+            return formatRespondForLLM(result);
+        case 'directory':
+            return formatDirectoryForLLM(result);
+        case 'whoami':
+            return formatWhoamiForLLM(result);
+        default:
+            return result.success ? 'Message action completed' : 'Failed to execute cmos_message';
+    }
+}
+//# sourceMappingURL=cmos-message.js.map