@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/tools/dismiss.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDismissAllTool = exports.registerDismissTool = void 0;
+const zod_1 = require("zod");
+const error_format_js_1 = require("../error-format.js");
+const registerDismissTool = (server, client) => {
+    server.registerTool('hwip_dismiss', {
+        description: 'Dismiss (mark as read) a specific push notification by ID. Use after processing a notification to clear it from the user\'s feed.',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            pushId: zod_1.z.string().describe('Push ID to dismiss (e.g., "push_01HX...")'),
+        },
+    }, async ({ pushId }) => {
+        try {
+            await client.dismissPush(pushId);
+            return (0, error_format_js_1.textResult)({ dismissed: true, pushId });
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    });
+};
+exports.registerDismissTool = registerDismissTool;
+const registerDismissAllTool = (server, client) => {
+    server.registerTool('hwip_dismiss_all', {
+        description: 'Dismiss all push notifications at once. Clears the entire notification feed.',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {},
+    }, async () => {
+        try {
+            const result = await client.dismissAllPushes();
+            return (0, error_format_js_1.textResult)({ dismissed: result.data.dismissed, badge: result.data.badge ?? 0 });
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    });
+};
+exports.registerDismissAllTool = registerDismissAllTool;

package/dist/tools/file.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type HwipApiClient } from '../api-client.js';
+import { type McpServerConfig } from '../config.js';
+export declare const registerFileTool: (server: McpServer, client: HwipApiClient, config: McpServerConfig) => void;
+//# sourceMappingURL=file.d.ts.map

package/dist/tools/file.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFileTool = void 0;
+const zod_1 = require("zod");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const api_client_js_1 = require("../api-client.js");
+const config_js_1 = require("../config.js");
+const error_format_js_1 = require("../error-format.js");
+const key_changes_js_1 = require("../key-changes.js");
+const crypto_js_1 = require("../crypto.js");
+const push_audience_js_1 = require("../push-audience.js");
+const mime_js_1 = require("../mime.js");
+class FileTooLargeError extends Error {
+    size;
+    constructor(size) {
+        super(`File is ${size} bytes; the most hwip carries is ${api_client_js_1.MAX_FILE_BYTES}`);
+        this.size = size;
+    }
+}
+/**
+ * Collapse the two accepted input shapes into one payload.
+ *
+ * A `filePath` stays a Buffer end to end — images and PDFs only survive the
+ * trip as raw bytes, and reading from disk keeps a several-hundred-KB
+ * attachment out of the tool call itself (base64 in the arguments would
+ * inflate it by a third and burn the agent's context).
+ */
+const resolvePayload = async (args) => {
+    if (args.filePath) {
+        // Look before reading: the file lands in memory whole, so a directory or an
+        // oversize path must be turned away while it is still just a path.
+        const info = await (0, promises_1.stat)(args.filePath);
+        if (!info.isFile())
+            throw new Error(`${args.filePath} is not a regular file`);
+        if (info.size > api_client_js_1.MAX_FILE_BYTES)
+            throw new FileTooLargeError(info.size);
+        const body = await (0, promises_1.readFile)(args.filePath);
+        return { fileName: args.fileName ?? (0, node_path_1.basename)(args.filePath), body, size: body.byteLength };
+    }
+    return {
+        fileName: args.fileName,
+        body: args.content,
+        size: new TextEncoder().encode(args.content).byteLength,
+    };
+};
+const registerFileTool = (server, client, config) => {
+    server.registerTool('hwip_file', {
+        description: 'Send a file to the user\'s device. Pass `filePath` to send a file that already exists on disk — images (png/jpg/gif/webp/heic), PDFs, logs, anything. Pass `content` instead to send text you generated. Images render inline on the device.',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            filePath: zod_1.z
+                .string()
+                .optional()
+                .describe('Absolute path to a local file to send. Required for images, PDFs, and any other binary — never base64 a file into `content`.'),
+            content: zod_1.z.string().optional().describe('Text content of the file. Use only for text you generated; requires `fileName`.'),
+            fileName: zod_1.z
+                .string()
+                .optional()
+                .describe('File name with extension (e.g., "report.txt"). Required with `content`; defaults to the basename of `filePath`.'),
+            title: zod_1.z.string().optional().describe('Notification title (defaults to fileName)'),
+            targetDeviceId: zod_1.z.string().optional().describe('Target device ID. Omit to use configured default or send to all devices.'),
+        },
+    }, (0, key_changes_js_1.notingKeyChanges)(async ({ filePath, fileName: fileNameArg, content, title, targetDeviceId }, extra) => {
+        if (!filePath && content === undefined) {
+            return (0, error_format_js_1.errorResult)({
+                error: 'INVALID_INPUT',
+                message: 'Either filePath or content is required',
+                suggestion: 'Pass filePath for a file on disk (images, PDFs), or content + fileName for generated text',
+            });
+        }
+        if (!filePath && !fileNameArg) {
+            return (0, error_format_js_1.errorResult)({
+                error: 'INVALID_INPUT',
+                message: 'fileName is required when sending content',
+                suggestion: 'Add fileName with an extension, e.g. "report.md"',
+            });
+        }
+        let payload;
+        try {
+            payload = await resolvePayload({ filePath, content, fileName: fileNameArg });
+        }
+        catch (err) {
+            if (err instanceof FileTooLargeError) {
+                return (0, error_format_js_1.errorResult)({
+                    error: 'FILE_TOO_LARGE',
+                    message: err.message,
+                    suggestion: 'Send a smaller file, or an archive of the part the user needs. Free accounts send up to 25 MiB, Pro up to 1 GiB',
+                });
+            }
+            return (0, error_format_js_1.errorResult)({
+                error: 'FILE_READ_FAILED',
+                message: err instanceof Error ? err.message : String(err),
+                suggestion: 'Check that filePath is an absolute path to a readable file',
+            });
+        }
+        const { fileName, body, size: originalSize } = payload;
+        // The whole upload-then-send sequence sits in this closure so the file is
+        // sealed for the same audience as the push that carries it.
+        const send = async (recipients) => {
+            const pushTitle = (0, config_js_1.formatPushTitle)(config.projectName, title ?? fileName);
+            const target = targetDeviceId ?? config.deviceId;
+            const fileType = (0, mime_js_1.inferMimeType)(fileName);
+            // An agent that abandoned the call abandoned the send.
+            if (extra?.signal?.aborted) {
+                return (0, error_format_js_1.errorResult)({ error: 'CANCELLED', message: 'The send was cancelled before the file went out' });
+            }
+            // Step 1: Seal the attachment and the push body together, before
+            // anything is uploaded: a failure in between would leave ciphertext
+            // under no push.
+            let sealed;
+            try {
+                sealed = {
+                    file: await (0, crypto_js_1.encryptFileForDevices)(body, recipients),
+                    push: await (0, crypto_js_1.encryptPushBodyForDevices)({ title: pushTitle }, recipients),
+                };
+            }
+            catch (err) {
+                console.error('[Crypto] Sealing the file failed:', err);
+                return (0, error_format_js_1.errorResult)({ error: push_audience_js_1.E2E_REQUIRED, message: (0, push_audience_js_1.sealFailed)('sealing the file failed') });
+            }
+            const uploadType = 'application/octet-stream';
+            // Step 2: Request upload URL
+            const upload = await client.requestUpload({ fileName, fileType: uploadType, fileSize: sealed.file.ciphertext.length });
+            // Step 3: Upload content to S3
+            await client.uploadToS3(upload.data.uploadUrl, sealed.file.ciphertext, uploadType);
+            // Step 4: Send the push. `fileType` on the descriptor stays the real
+            // type — it drives how the client renders the decrypted bytes.
+            const result = await client.sendPush({
+                type: 'file',
+                targetDeviceId: target,
+                sessionId: config.sessionId,
+                body: sealed.push.body,
+                isEncrypted: sealed.push.isEncrypted,
+                deviceKeyMap: sealed.push.deviceKeyMap,
+                senderPublicKey: sealed.push.senderPublicKey,
+                files: [{
+                        fileKey: upload.data.fileKey,
+                        fileName,
+                        fileSize: originalSize,
+                        fileType,
+                        iv: sealed.file.iv,
+                        deviceKeyMap: sealed.file.deviceKeyMap,
+                    }],
+            });
+            return (0, error_format_js_1.textResult)({
+                pushId: result.data.pushId,
+                fileKey: upload.data.fileKey,
+                fileSize: originalSize,
+                encrypted: true,
+                delivery: 'Sent via cloud',
+            });
+        };
+        try {
+            const audience = await (0, push_audience_js_1.resolveAudience)(client);
+            if ('refused' in audience)
+                return (0, error_format_js_1.errorResult)({ error: audience.code, message: audience.refused });
+            return await send(audience.recipients);
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    }));
+};
+exports.registerFileTool = registerFileTool;

package/dist/tools/list.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HwipApiClient } from '../api-client.js';
+export declare const registerListTool: (server: McpServer, client: HwipApiClient) => void;
+//# sourceMappingURL=list.d.ts.map

package/dist/tools/list.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerListTool = void 0;
+const zod_1 = require("zod");
+const error_format_js_1 = require("../error-format.js");
+const registerListTool = (server, client) => {
+    server.registerTool('hwip_list', {
+        description: 'List recent push notifications. Use this to check notification history, avoid duplicates, or reference previous messages. An end-to-end encrypted push shows `encrypted: true` with no title or body.',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            limit: zod_1.z
+                .number()
+                .min(1)
+                .max(20)
+                .default(5)
+                .describe('Number of pushes to return (default: 5, max: 20)'),
+            type: zod_1.z
+                .enum(['note', 'link', 'file', 'clipboard', 'hook'])
+                .optional()
+                .describe('Filter by push type'),
+        },
+    }, async ({ limit, type }) => {
+        try {
+            const result = await client.listPushes({ limit, type });
+            // An encrypted push's body is ciphertext only the user's devices open: say so instead.
+            const summary = result.data.map((p) => ({
+                pushId: p.pushId,
+                type: p.type,
+                ...(p.isEncrypted ? { encrypted: true } : { title: p.title, body: p.body?.slice(0, 100) }),
+                createdAt: p.createdAt,
+            }));
+            return (0, error_format_js_1.textResult)({ pushes: summary, total: summary.length, hasMore: result.pagination.hasMore });
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    });
+};
+exports.registerListTool = registerListTool;

package/dist/tools/lookup.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HwipApiClient } from '../api-client.js';
+/**
+ * Read-only lookups for the ids `hwip_notify` takes (`targetDeviceId`,
+ * `channelId`). The same lists are MCP resources, but an agent that only
+ * calls tools never reads a resource, so without these it had no way to
+ * find an id to target.
+ */
+export declare const registerLookupTools: (server: McpServer, client: HwipApiClient) => void;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/tools/lookup.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLookupTools = void 0;
+const error_format_js_1 = require("../error-format.js");
+/**
+ * Read-only lookups for the ids `hwip_notify` takes (`targetDeviceId`,
+ * `channelId`). The same lists are MCP resources, but an agent that only
+ * calls tools never reads a resource, so without these it had no way to
+ * find an id to target.
+ */
+const registerLookupTools = (server, client) => {
+    const readOnly = {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    };
+    server.registerTool('hwip_devices', {
+        description: "List the user's devices with their online status. Use a `deviceId` as hwip_notify's `targetDeviceId` to reach one device.",
+        annotations: readOnly,
+        inputSchema: {},
+    }, async () => {
+        try {
+            const result = await client.listDevices();
+            return (0, error_format_js_1.textResult)({ devices: result.data });
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    });
+    server.registerTool('hwip_channels', {
+        description: "List the user's channels. Use a `channelId` with hwip_broadcast to reach a channel's subscribers.",
+        annotations: readOnly,
+        inputSchema: {},
+    }, async () => {
+        try {
+            const result = await client.listChannels();
+            return (0, error_format_js_1.textResult)({ channels: result.data });
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    });
+};
+exports.registerLookupTools = registerLookupTools;

package/dist/tools/notify.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HwipApiClient } from '../api-client.js';
+import { type McpServerConfig } from '../config.js';
+export declare const registerNotifyTool: (server: McpServer, client: HwipApiClient, config: McpServerConfig) => void;
+//# sourceMappingURL=notify.d.ts.map

package/dist/tools/notify.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerNotifyTool = void 0;
+const zod_1 = require("zod");
+const error_format_js_1 = require("../error-format.js");
+const key_changes_js_1 = require("../key-changes.js");
+const config_js_1 = require("../config.js");
+const crypto_js_1 = require("../crypto.js");
+const push_audience_js_1 = require("../push-audience.js");
+const mime_js_1 = require("../mime.js");
+const sanitize_js_1 = require("../sanitize.js");
+// The device feed shows a short preview of the body. Anything longer gets
+// truncated there, so we attach the full text as a file for full viewing.
+const PREVIEW_LENGTH = 200;
+const registerNotifyTool = (server, client, config) => {
+    server.registerTool('hwip_notify', {
+        description: 'Send a one-way push notification to the user\'s devices. Use this to inform the user about task completion, errors, or status updates. Long bodies are automatically uploaded as a file for full viewing.',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            title: zod_1.z.string().describe('Notification title'),
+            body: zod_1.z.string().optional().describe('Notification body text'),
+            url: zod_1.z.string().url().optional().describe('Optional URL to open on the device.'),
+            priority: zod_1.z
+                .enum(['low', 'normal', 'high', 'urgent'])
+                .default('normal')
+                .describe('Notification priority. Use "urgent" for critical alerts, "low" for background info.'),
+            targetDeviceId: zod_1.z.string().optional().describe('Target device ID. Omit to use configured default or send to all devices.'),
+        },
+    }, (0, key_changes_js_1.notingKeyChanges)(async ({ title, body, url, priority, targetDeviceId }) => {
+        const send = async (recipients) => {
+            const deviceId = targetDeviceId ?? config.deviceId;
+            const pushTitle = (0, config_js_1.formatPushTitle)(config.projectName, title);
+            // Strip any tool-call markup that leaked into the body argument.
+            const cleanBody = (0, sanitize_js_1.sanitizeText)(body);
+            // Attach a file whenever the body would be clipped in the feed preview.
+            const isLongBody = !!cleanBody && cleanBody.length > PREVIEW_LENGTH;
+            if (isLongBody && cleanBody) {
+                const fileName = 'response.md';
+                const fileType = (0, mime_js_1.inferMimeType)(fileName);
+                // Self-contained Markdown so the file alone carries the full text.
+                const fileMarkdown = `# ${title}\n\n${cleanBody}`;
+                const fileBytes = new TextEncoder().encode(fileMarkdown).byteLength;
+                const preview = cleanBody.slice(0, PREVIEW_LENGTH) + '...';
+                // Seal the attachment and the push body together, before anything is
+                // uploaded: a failure in between would leave ciphertext under no push.
+                let sealed;
+                try {
+                    sealed = {
+                        file: await (0, crypto_js_1.encryptFileForDevices)(fileMarkdown, recipients),
+                        push: await (0, crypto_js_1.encryptPushBodyForDevices)({ title: pushTitle, body: preview, url }, recipients),
+                    };
+                }
+                catch (err) {
+                    console.error('[Crypto] Sealing the notification failed:', err);
+                    return (0, error_format_js_1.errorResult)({ error: push_audience_js_1.E2E_REQUIRED, message: (0, push_audience_js_1.sealFailed)('sealing the notification failed') });
+                }
+                const uploadContentType = 'application/octet-stream';
+                const upload = await client.requestUpload({ fileName, fileType: uploadContentType, fileSize: sealed.file.ciphertext.length });
+                await client.uploadToS3(upload.data.uploadUrl, sealed.file.ciphertext, uploadContentType);
+                // No title or url beside the envelope: `isEncrypted` promises the server sees neither.
+                const pushPayload = {
+                    body: sealed.push.body,
+                    type: 'file',
+                    priority,
+                    files: [{
+                            fileKey: upload.data.fileKey,
+                            fileName,
+                            fileSize: fileBytes,
+                            fileType,
+                            iv: sealed.file.iv,
+                            deviceKeyMap: sealed.file.deviceKeyMap,
+                        }],
+                    targetDeviceId: deviceId,
+                    sessionId: config.sessionId,
+                    isEncrypted: sealed.push.isEncrypted,
+                    deviceKeyMap: sealed.push.deviceKeyMap,
+                    senderPublicKey: sealed.push.senderPublicKey,
+                };
+                const result = await client.sendPush(pushPayload);
+                return (0, error_format_js_1.textResult)({ pushId: result.data.pushId, fileKey: upload.data.fileKey, autoFile: true, encrypted: true });
+            }
+            let enc;
+            try {
+                enc = await (0, crypto_js_1.encryptPushBodyForDevices)({ title: pushTitle, body: cleanBody, url }, recipients);
+            }
+            catch (err) {
+                console.error('[Crypto] Sealing the notification failed:', err);
+                return (0, error_format_js_1.errorResult)({ error: push_audience_js_1.E2E_REQUIRED, message: (0, push_audience_js_1.sealFailed)('sealing the notification failed') });
+            }
+            const pushPayload = {
+                body: enc.body,
+                type: 'hook',
+                priority,
+                targetDeviceId: deviceId,
+                sessionId: config.sessionId,
+                isEncrypted: enc.isEncrypted,
+                deviceKeyMap: enc.deviceKeyMap,
+                senderPublicKey: enc.senderPublicKey,
+            };
+            const result = await client.sendPush(pushPayload);
+            return (0, error_format_js_1.textResult)({ pushId: result.data.pushId, encrypted: true });
+        };
+        try {
+            const audience = await (0, push_audience_js_1.resolveAudience)(client);
+            if ('refused' in audience)
+                return (0, error_format_js_1.errorResult)({ error: audience.code, message: audience.refused });
+            return await send(audience.recipients);
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    }));
+};
+exports.registerNotifyTool = registerNotifyTool;

package/dist/tools/rename.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HwipApiClient } from '../api-client.js';
+import type { McpServerConfig } from '../config.js';
+export declare const registerRenameTool: (server: McpServer, client: HwipApiClient, config: McpServerConfig) => void;
+//# sourceMappingURL=rename.d.ts.map

package/dist/tools/rename.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRenameTool = void 0;
+const zod_1 = require("zod");
+const error_format_js_1 = require("../error-format.js");
+// Mirrors the server cap (hwip apps/server/src/functions/devices.ts).
+const MAX_ALIAS_LENGTH = 60;
+const registerRenameTool = (server, client, config) => {
+    server.registerTool('hwip_session_rename', {
+        description: "Set a custom display name for THIS agent session in the user's Hwip app (the Streams › Agents list). " +
+            'Label what this session is working on — e.g. "Prod deploy" or "Auth refactor" — so the user can tell ' +
+            'parallel sessions apart on their phone. Renames the current session; the name persists until changed.',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            alias: zod_1.z
+                .string()
+                .trim()
+                .min(1)
+                .max(MAX_ALIAS_LENGTH)
+                .describe(`Display name for this session (max ${MAX_ALIAS_LENGTH} characters).`),
+        },
+    }, async ({ alias }) => {
+        try {
+            const { agentDeviceId, agentSessionName } = config;
+            // The session key is resolved once at startup from the listener device
+            // id + tmux session name. Absent it, there is nothing to rename.
+            if (!agentDeviceId || !agentSessionName) {
+                return (0, error_format_js_1.textResult)({
+                    renamed: false,
+                    reason: 'No active agent session detected — this tool renames the tmux session it runs in, which requires `hwip listener` and a tmux session.',
+                });
+            }
+            await client.renameAgentSession(agentDeviceId, agentSessionName, alias);
+            return (0, error_format_js_1.textResult)({ renamed: true, session: agentSessionName, alias });
+        }
+        catch (err) {
+            return (0, error_format_js_1.formatToolError)(err);
+        }
+    });
+};
+exports.registerRenameTool = registerRenameTool;

package/dist/trust-pins.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pinning the account's devices as a sender sees them (twin of the cli's `src/trust-pins.ts` and `src/trust-lock.ts`).
+ *
+ * `hwip_notify`, `hwip_file`, `hwip_ask` and `hwip_agent_send` read `GET /devices` before they seal. Every device that
+ * lists a key is pinned the first time it is seen, and a pin whose device now lists another key is replaced — with one
+ * warning, because a key that changed is also what a relay swapping the list looks like, and a record (`key-changes.ts`)
+ * the next tool result shows, since this server's stderr reaches nobody. Nothing here decides who is
+ * sealed for: the list does. The pins are what the cli listener holds a request against and what a person compares
+ * with `hwip trust`; trust never stops a send.
+ *
+ * The file is shared with the cli, which also keeps the listener's sealed-command numbers in it (`commands`,
+ * `commandKeys`). Every writer re-reads it under `trusted-devices.lock` and rewrites only its own part: here that is
+ * `devices` (and, for a replaced pin, the old key's command number carried into `commandKeys`, as the cli does), with
+ * every other field kept as it was. `sealedOnce` is read past and not written back.
+ */
+/** The cli listener's state file. */
+export declare const TRUST_PATH: string;
+/** A device id as the app, the cli and the server mint them. */
+export declare const DEVICE_ID: RegExp;
+/** Devices pinned at most: a list padded with made-up devices must not grow the file one rewrite at a time. */
+export declare const MAX_PINNED_DEVICES = 64;
+type Pin = {
+    publicKey: string;
+    pinnedAt: string;
+};
+/** The file as read: `devices` checked, every other field kept for the rewrite. */
+type TrustFile = Record<string, unknown> & {
+    devices: Record<string, Pin>;
+};
+/** The trust file: a missing one is empty, one that will not read or parse is `null`, never a guess. */
+export declare const readTrustFile: (path: string) => TrustFile | null;
+/**
+ * Run `fn` holding `trusted-devices.lock` beside the trust file, created with `wx` as the cli creates it. `locked: false`:
+ * the lock was held past `waitMs` or cannot be made, and `fn` did not run.
+ */
+export declare const withTrustLock: <T>(trustPath: string, fn: () => T, { waitMs }?: {
+    waitMs?: number;
+}) => {
+    locked: true;
+    value: T;
+} | {
+    locked: false;
+};
+export interface ObservedDevice {
+    deviceId: string;
+    publicKey?: string;
+    /** The name the account lists it under, for the key-change record. */
+    nickname?: string;
+}
+export interface Observed {
+    /** Devices pinned for the first time. */
+    pinned: string[];
+    /** Devices whose pin was replaced by the key they list now — or would have been, when the status is not `ok`. */
+    replaced: string[];
+    /** Devices not pinned: their key is pinned for another id, or the cap is reached. */
+    skipped: string[];
+    /** `unreadable`: nothing was checked or written. `unlocked`: nothing was written. A send goes on in both cases. */
+    status: 'ok' | 'unreadable' | 'unlocked';
+}
+/**
+ * Pin what `devices` lists: a new device is pinned, a changed key replaces its pin with one warning. Never refuses and
+ * never throws — a file that cannot be read or written leaves the pins as they were and the send goes on.
+ */
+export declare const observeDevices: (path: string, devices: ObservedDevice[], { selfId, now, warn }?: {
+    selfId?: string;
+    now?: () => Date;
+    warn?: (line: string) => void;
+}) => Observed;
+export {};
+//# sourceMappingURL=trust-pins.d.ts.map