agent-relay 13.2.0 → 13.4.0

package/dist/cli/lib/spawn-liveness.js

@@ -0,0 +1,184 @@
+import { RelayPlacementError, safeRelayErrorMessage } from '@agent-relay/sdk';
+import { shellQuote, withDeadline } from './agent-registration.js';
+import { isNotFoundError } from './agent-removal.js';
+import { heartbeatAgeMs, isAvailableFleetNode, MAX_LIVE_HEARTBEAT_AGE_MS, readRemoteLiveAgents, } from './fleet-live-agents.js';
+export class FleetSpawnError extends Error {
+    code;
+    liveness;
+    diagnostic;
+    state;
+    exitCode;
+    invocationId;
+    node;
+    dispatchState;
+    receipt;
+    constructor(
+    // `spawn_unconfirmed` is the established public code for an accepted spawn
+    // whose outcome is unknown (relay#1563); keep it so callers keyed on it keep
+    // working, and carry the pending outcome in `state` and the exit code.
+    code, message, context, liveness, diagnostic) {
+        super(message);
+        this.code = code;
+        this.liveness = liveness;
+        this.diagnostic = diagnostic;
+        this.state = code === 'spawn_unconfirmed' ? 'pending' : 'failed';
+        this.exitCode = code === 'spawn_unconfirmed' ? 8 : 1;
+        this.invocationId = context.invocationId;
+        this.node = context.node;
+        this.dispatchState = context.dispatchState;
+        this.receipt = context.receipt;
+    }
+}
+export function mayStillBeRunning(error) {
+    return ((error instanceof RelayPlacementError && error.state === 'unconfirmed_may_be_running') ||
+        (error instanceof FleetSpawnError && error.code === 'spawn_unconfirmed'));
+}
+export function pendingSpawnError(name, context, liveness, diagnostic) {
+    // A worker found elsewhere is invisible to a node-scoped check.
+    const nodeOption = context.node && liveness.evidence !== 'live_elsewhere' ? ` --node ${shellQuote(context.node)}` : '';
+    // Heartbeats carry worker names, not invocation IDs, so presence cannot be
+    // attributed to this spawn: it may be a worker that was already running.
+    const attribution = liveness.evidence === 'live' || liveness.evidence === 'live_elsewhere' || liveness.evidence === 'stale'
+        ? `A worker with this name is listed by a node heartbeat, but heartbeats do not identify the invocation that started it, so it may be an earlier worker rather than this spawn. `
+        : '';
+    return new FleetSpawnError('spawn_unconfirmed', `Spawn of ${JSON.stringify(name)} was accepted; its outcome is pending. ` +
+        `Evidence: ${liveness.evidence}${liveness.node ? ` on ${JSON.stringify(liveness.node)}` : ''}. ` +
+        attribution +
+        `Invocation: ${context.invocationId ?? 'unavailable'}; dispatch: ${context.dispatchState ?? 'unknown'}. ` +
+        `Do not retry blindly: check \`agent-relay fleet agent list${nodeOption}\` first. ` +
+        `Only if no worker is running and you intend to reclaim the name, run \`agent-relay agent remove ${shellQuote(name)} --wait\` and wait for clearance before respawning.`, context, liveness, diagnostic);
+}
+export function classifySpawnFailure(message) {
+    // Anchored to the broker formatter; unrelated "already exists" failures are not registration collisions.
+    return /(?:^|:\s)failed to pre-register worker '[^\n]+': agent '[^\n]+' already exists and registration is create-only(?:;|$)/i.test(message)
+        ? 'spawn_name_taken'
+        : undefined;
+}
+export function nameTakenSpawnError(name, error) {
+    return new FleetSpawnError('spawn_name_taken', `${safeRelayErrorMessage(error)} A removal or cleanup from a previous unsuccessful spawn may still be in flight. Re-check \`agent-relay agent list\`; if the name is present with no worker running, run \`agent-relay agent remove ${shellQuote(name)} --wait\`, wait for clearance, then retry.`, error);
+}
+/** Reads are bounded and client construction is fallible (agent-token-only callers are supported). */
+export async function probeSpawnLiveness(options) {
+    let readError;
+    let rosterUnread = false;
+    let rosterIncomplete = false;
+    const read = (fn) => withDeadline(fn, () => new Error('Spawn evidence read timed out.'), 2_000);
+    if (options.getInvocation) {
+        try {
+            const value = await read(options.getInvocation);
+            if (value && typeof value === 'object') {
+                const invocation = value;
+                if (/^(completed|succeeded|success|failed|error|cancelled|canceled|denied)$/i.test(String(invocation.status))) {
+                    return { evidence: 'invocation_terminal', invocation };
+                }
+            }
+        }
+        catch (error) {
+            readError = safeRelayErrorMessage(error);
+        }
+    }
+    try {
+        const client = options.createClient();
+        try {
+            // Read the clock when a heartbeat is judged, after the reads: sampling it
+            // first would let read latency make an old heartbeat look fresh.
+            const clock = () => options.now?.() ?? Date.now();
+            const target = options.targetNode ? await read(() => client.nodes.get(options.targetNode)) : undefined;
+            const nodes = options.targetNode && target ? [target] : await read(() => client.nodes.list());
+            // Prefer the targeted read; consult the fleet unless the target is an
+            // available node whose fresh heartbeat claims this name.
+            const targetAge = target ? heartbeatAgeMs(target, clock()) : null;
+            if (options.targetNode &&
+                target &&
+                !(isAvailableFleetNode(target) &&
+                    targetAge !== null &&
+                    targetAge <= MAX_LIVE_HEARTBEAT_AGE_MS &&
+                    readRemoteLiveAgents(target).agents.some((a) => a.name === options.name))) {
+                nodes.push(...(await read(() => client.nodes.list())));
+            }
+            let weaker;
+            const now = clock();
+            for (const node of nodes) {
+                if (!isAvailableFleetNode(node))
+                    continue;
+                const live = readRemoteLiveAgents(node);
+                // A node whose heartbeat roster is missing or undecodable may still be
+                // running the worker, so a later missing registration cannot prove absence.
+                if (!live.complete)
+                    rosterIncomplete = true;
+                if (!live.agents.some((agent) => agent.name === options.name))
+                    continue;
+                const age = heartbeatAgeMs(node, now);
+                const evidence = age === null || age > MAX_LIVE_HEARTBEAT_AGE_MS
+                    ? 'stale'
+                    : options.targetNode && node.name !== options.targetNode
+                        ? 'live_elsewhere'
+                        : 'live';
+                // Keep a failed invocation read visible next to roster evidence.
+                const result = {
+                    evidence,
+                    node: node.name,
+                    heartbeatAgeMs: age,
+                    ...(readError ? { readError } : {}),
+                };
+                if (evidence === 'live')
+                    return result;
+                // Fresh evidence elsewhere outranks a stale entry.
+                if (!weaker || (weaker.evidence === 'stale' && evidence === 'live_elsewhere'))
+                    weaker = result;
+            }
+            if (weaker)
+                return weaker;
+        }
+        catch (error) {
+            readError = safeRelayErrorMessage(error);
+            rosterUnread = true;
+        }
+        try {
+            await read(() => client.agents.get(options.name));
+            return { evidence: 'registered', ...(readError ? { readError } : {}) };
+        }
+        catch (error) {
+            // `absent` claims no worker was observed. A missing registration only
+            // proves that when the node roster was actually read.
+            if (isNotFoundError(error) && !rosterUnread && !rosterIncomplete)
+                return { evidence: 'absent', ...(readError ? { readError } : {}) };
+            if (!isNotFoundError(error))
+                readError = safeRelayErrorMessage(error);
+        }
+    }
+    catch (error) {
+        readError = safeRelayErrorMessage(error);
+    }
+    return { evidence: 'unknown', readError };
+}
+/** Preserve the original request's launch/readiness contract on the final invocation read. */
+export function terminalSpawnOutcome(invocation, context, requireReady) {
+    const output = invocation.output;
+    if (!/^(completed|succeeded|success)$/i.test(String(invocation.status)) ||
+        output?.spawned !== true ||
+        typeof output.ready !== 'boolean' ||
+        (requireReady && output.ready !== true)) {
+        throw new RelayPlacementError('spawn_failed', typeof invocation.error === 'string'
+            ? invocation.error
+            : 'Spawn completed without the requested launch/readiness proof.', {
+            capability: 'spawn',
+            attempts: 1,
+            state: 'failed',
+            invocationId: context.invocationId,
+            node: context.node,
+            dispatchState: context.dispatchState,
+            receipt: invocation,
+        });
+    }
+    return {
+        ...invocation,
+        placement: {
+            state: output.ready ? 'ready' : 'accepted',
+            confirmed: true,
+            invocationId: context.invocationId,
+            dispatchState: context.dispatchState,
+        },
+    };
+}
+//# sourceMappingURL=spawn-liveness.js.map

package/dist/cli/lib/spawn-liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-liveness.js","sourceRoot":"","sources":["../../../src/cli/lib/spawn-liveness.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/task-input.d.ts

@@ -0,0 +1,26 @@
+/** Broker-wide PTY ceiling for the formatted envelope; a harness may reject a lower effective wire limit. */
+export declare const MAX_INJECTION_BODY_BYTES: number;
+/** Room the broker keeps for attribution and its MCP reminder around a body. */
+export declare const ENVELOPE_RESERVE_BYTES: number;
+/** Largest body that still fits {@link MAX_INJECTION_BODY_BYTES} once formatted. */
+export declare const MAX_TASK_BODY_BYTES: number;
+/**
+ * The broker's portable ceiling for a prompt passed as one process argument
+ * (Muse's startup task, a headless provider's message).
+ */
+export declare const MAX_ARGV_TASK_BYTES: number;
+/**
+ * A native runtime receives its task as a delivery frame, so no wire limit
+ * applies; this only bounds how much of a `--task-file` the CLI will read.
+ */
+export declare const MAX_NATIVE_TASK_BYTES: number;
+/** Who receives a task: the CLI, and the runtime once it is resolved. */
+export interface TaskTarget {
+    cli: string;
+    /** `native` delivers the task as a frame, without the PTY envelope; omitted means PTY. */
+    runtime?: 'native' | 'pty';
+}
+export declare function readTaskInput(task: unknown, taskFile: unknown, required?: boolean, target?: TaskTarget): Promise<string | undefined>;
+/** Validate a task as its target receives it; recheck after anything is appended to it. */
+export declare function validateTaskSize(text: string, target?: TaskTarget): void;
+//# sourceMappingURL=task-input.d.ts.map

package/dist/cli/lib/task-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-input.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/task-input.ts"],"names":[],"mappings":"AAEA,6GAA6G;AAC7G,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAClD,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,QAAW,CAAC;AAC/C,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,QAAoD,CAAC;AACrF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAY,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,0FAA0F;IAC1F,OAAO,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;CAC5B;AAiBD,wBAAsB,aAAa,CACjC,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,OAAO,EACjB,QAAQ,UAAQ,EAChB,MAAM,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAY7B;AAOD,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAExE"}

package/dist/cli/lib/task-input.js

@@ -0,0 +1,102 @@
+import { open } from 'node:fs/promises';
+/** Broker-wide PTY ceiling for the formatted envelope; a harness may reject a lower effective wire limit. */
+export const MAX_INJECTION_BODY_BYTES = 16 * 1024;
+/** Room the broker keeps for attribution and its MCP reminder around a body. */
+export const ENVELOPE_RESERVE_BYTES = 2 * 1024;
+/** Largest body that still fits {@link MAX_INJECTION_BODY_BYTES} once formatted. */
+export const MAX_TASK_BODY_BYTES = MAX_INJECTION_BODY_BYTES - ENVELOPE_RESERVE_BYTES;
+/**
+ * The broker's portable ceiling for a prompt passed as one process argument
+ * (Muse's startup task, a headless provider's message).
+ */
+export const MAX_ARGV_TASK_BYTES = 16 * 1024;
+/**
+ * A native runtime receives its task as a delivery frame, so no wire limit
+ * applies; this only bounds how much of a `--task-file` the CLI will read.
+ */
+export const MAX_NATIVE_TASK_BYTES = 1024 * 1024;
+/** Mirrors the broker's `is_muse_executable`: the basename, case-insensitive, minus a Windows launcher suffix. */
+function isMuseExecutable(cli) {
+    const basename = cli.split(/[\\/]/).pop() || cli;
+    return basename.toLowerCase().replace(/\.(exe|cmd|bat)$/, '') === 'muse';
+}
+/** Muse takes its task as one argument; a native runtime as a frame; everything else through the PTY envelope. */
+function taskLimitKind(target) {
+    if (target?.runtime === 'native')
+        return 'native';
+    if (target && isMuseExecutable(target.cli))
+        return 'argv';
+    return 'pty';
+}
+export async function readTaskInput(task, taskFile, required = false, target) {
+    if (task !== undefined && taskFile !== undefined)
+        throw new Error('Specify exactly one of --task or --task-file');
+    if (task === undefined && taskFile === undefined) {
+        if (required)
+            throw new Error('Specify exactly one of --task or --task-file');
+        return undefined;
+    }
+    const text = taskFile === undefined ? task : await readTaskFile(String(taskFile), taskByteLimit(target), target);
+    if (typeof text !== 'string' || !text.trim())
+        throw new Error('Task must not be empty');
+    validateTaskSize(text, target);
+    return text;
+}
+function taskByteLimit(target) {
+    const kind = taskLimitKind(target);
+    return kind === 'pty' ? MAX_TASK_BODY_BYTES : kind === 'argv' ? MAX_ARGV_TASK_BYTES : MAX_NATIVE_TASK_BYTES;
+}
+/** Validate a task as its target receives it; recheck after anything is appended to it. */
+export function validateTaskSize(text, target) {
+    validateTaskBytes(Buffer.byteLength(text, 'utf8'), target);
+}
+function validateTaskBytes(bytes, target) {
+    const kind = taskLimitKind(target);
+    if (kind === 'pty' && bytes > MAX_TASK_BODY_BYTES)
+        throwInjectionTooLarge();
+    if (kind === 'argv')
+        validateArgvTaskSize(bytes);
+    if (kind === 'native' && bytes > MAX_NATIVE_TASK_BYTES) {
+        throw new Error(`Task exceeds ${MAX_NATIVE_TASK_BYTES} UTF-8 bytes; use a brief file on the node and send a short pointer`);
+    }
+}
+/**
+ * Read a UTF-8 task file, never more than one byte past `limit`: that is enough
+ * to reject an oversized file without materializing all of it. Size is checked
+ * before decoding, since the cut can split a character, and malformed UTF-8 is
+ * rejected rather than replaced, so the agent never gets different text.
+ */
+async function readTaskFile(path, limit, target) {
+    const handle = await open(path, 'r');
+    try {
+        const maxBytes = limit + 1;
+        const buffer = Buffer.alloc(maxBytes);
+        let length = 0;
+        while (length < maxBytes) {
+            const { bytesRead } = await handle.read(buffer, length, maxBytes - length, null);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+        }
+        if (length > limit)
+            validateTaskBytes(length, target);
+        try {
+            return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, length));
+        }
+        catch {
+            throw new Error(`Task file ${path} is not valid UTF-8`);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validateArgvTaskSize(bytes) {
+    if (bytes > MAX_ARGV_TASK_BYTES) {
+        throw new Error(`Task exceeds the ${MAX_ARGV_TASK_BYTES}-byte portable argv limit for a single process argument; use a brief file on the node and send a short pointer`);
+    }
+}
+function throwInjectionTooLarge() {
+    throw new Error(`Task exceeds ${MAX_TASK_BODY_BYTES} UTF-8 bytes (the ${MAX_INJECTION_BODY_BYTES}-byte PTY limit less room for the message envelope); use a brief file on the node and send a short pointer`);
+}
+//# sourceMappingURL=task-input.js.map

package/dist/cli/lib/task-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-input.js","sourceRoot":"","sources":["../../../src/cli/lib/task-input.ts"],"names":[],"mappings":"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"}

package/dist/cli/mcp/messaging-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messaging-tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/messaging-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAapE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAkDlD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,cAAc,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,eAAe,EACxD,gCAAgC,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,EACvE,aAAa,CAAC,EAAE,gBAAgB,GAC/B,IAAI,CAueN"}
+{"version":3,"file":"messaging-tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/messaging-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyBpE,OAAO,EAAE,gBAAgB,EAAiB,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAsElD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,cAAc,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,eAAe,EACxD,gCAAgC,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,EACvE,aAAa,CAAC,EAAE,gBAAgB,GAC/B,IAAI,CAylBN"}

package/dist/cli/mcp/messaging-tools.js

@@ -1,9 +1,10 @@
-import { replayMessageMetadata } from '@agent-relay/sdk';
+import { downloadRelayFile, replayMessageMetadata, uploadRelayFile, } from '@agent-relay/sdk';
 import { z } from 'zod';
 import { compactDirectMessageReceipt, directMessageDeliveryFailure, directMessageReceipt, messageReadersReceipt, resolveExactAgentName, } from '../lib/message-delivery-receipts.js';
+import { MAX_ATTACHMENT_BYTES, contentTypeFor, decodeBase64Strict, readAttachment, saveAttachment, } from '../lib/attachments.js';
 import { jsonContent, jsonResult, textContent } from './tool-results.js';
 import { identityOverrideInputShape, messageResult } from './tool-shapes.js';
-import { McpRequestReplay } from './request-replay.js';
+import { McpRequestReplay, replayScopeOf } from './request-replay.js';
 const directMessageResult = z.looseObject({
     id: z.string().optional().describe('Message ID, for "get_message_readers"'),
     conversationId: z.string().optional().describe('DM conversation ID, addressing relay://dm/{id}'),
@@ -49,6 +50,22 @@ function resolveEmoji(input) {
     };
     return aliases[normalized] ?? input;
 }
+const idempotencyKeyInput = z
+    .string()
+    // Relaycast trims this key upstream, so trim before both the local replay
+    // cache and the forwarded call to keep one logical send on one key; a
+    // whitespace-only key would otherwise become an unkeyed send.
+    .trim()
+    .min(1)
+    .max(255)
+    .optional()
+    .describe('Stable key for retrying this same message after a lost response; use a new key for a new message. Surrounding whitespace is trimmed and a whitespace-only key is rejected.');
+function requireFiles(client) {
+    if (!client.files) {
+        throw new Error('This Relay client cannot store files.');
+    }
+    return client.files;
+}
 /**
  * Register the channel, message, thread, DM, reaction, search, and inbox MCP
  * tools. These all act through a single agent client resolved per-call from the
@@ -165,11 +182,12 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
         inputSchema: {
             channel: z.string().describe('Channel name'),
             text: z.string().describe('Message text'),
-            attachments: z.array(z.string()).optional().describe('File attachment IDs'),
+            attachments: z.array(z.string()).optional().describe('File IDs from "upload_file"'),
             mode: z
                 .enum(['wait', 'steer'])
                 .optional()
                 .describe('wait (default): queue delivery until each recipient reaches a safe idle boundary; steer: request immediate injection, which may interrupt active work.'),
+            idempotency_key: idempotencyKeyInput,
             ...identityOverrideInputShape,
         },
         outputSchema: jsonResult,
@@ -179,11 +197,17 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ channel, text, attachments, mode, as }) => jsonContent(await getAgentClient(as).send(channel, text, {
-        attachments,
-        data: replayMessageMetadata(),
-        mode,
-    })));
+    }, async ({ channel, text, attachments, mode, idempotency_key, as }, extra) => {
+        // Bind the acting identity now: a register_agent that moves the session
+        // default must not reroute a write that is already in flight.
+        const client = getAgentClient(as);
+        return replay.run('post_message', extra, idempotency_key, async () => jsonContent(await client.send(channel, text, {
+            attachments,
+            data: replayMessageMetadata(),
+            mode,
+            idempotencyKey: idempotency_key,
+        })), replayScopeOf(client));
+    });
     server.registerTool('list_messages', {
         title: 'Get Messages',
         description: 'Retrieve message history from a channel. ' +
@@ -210,6 +234,7 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
         inputSchema: {
             message_id: z.string().describe('Parent message ID'),
             text: z.string().describe('Reply text'),
+            idempotency_key: idempotencyKeyInput,
             ...identityOverrideInputShape,
         },
         outputSchema: jsonResult,
@@ -219,7 +244,13 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ message_id, text, as }) => jsonContent(await getAgentClient(as).reply(message_id, text, { data: replayMessageMetadata() })));
+    }, async ({ message_id, text, idempotency_key, as }, extra) => {
+        const client = getAgentClient(as);
+        return replay.run('reply_to_thread', extra, idempotency_key, async () => jsonContent(await client.reply(message_id, text, {
+            data: replayMessageMetadata(),
+            idempotencyKey: idempotency_key,
+        })), replayScopeOf(client));
+    });
     server.registerTool('get_message_thread', {
         title: 'Get Thread',
         description: 'Retrieve a message thread. ' +
@@ -249,17 +280,8 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
                 .enum(['wait', 'steer'])
                 .optional()
                 .describe('wait (default): queue until the recipient reaches a safe idle boundary; steer: request immediate injection, which may interrupt active work. Both modes return before reading is confirmed.'),
-            attachments: z.array(z.string()).optional().describe('File attachment IDs'),
-            idempotency_key: z
-                .string()
-                // Relaycast trims this key upstream, so trim before both the local
-                // replay cache and the forwarded call to keep one logical send on one
-                // key; a whitespace-only key would otherwise become an unkeyed send.
-                .trim()
-                .min(1)
-                .max(255)
-                .optional()
-                .describe('Stable key for retrying this same message after a lost response; use a new key for a new message. Surrounding whitespace is trimmed and a whitespace-only key is rejected.'),
+            attachments: z.array(z.string()).optional().describe('File IDs from "upload_file"'),
+            idempotency_key: idempotencyKeyInput,
             ...identityOverrideInputShape,
         },
         outputSchema: directMessageResult,
@@ -269,19 +291,22 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ to, text, mode, attachments, idempotency_key, as }, extra) => replay.run('send_dm', extra, idempotency_key, async () => {
-        const agents = await listAgentsForRecipientResolution?.();
-        const resolvedRecipient = agents ? resolveExactAgentName(agents, to) : undefined;
-        const message = await getAgentClient(as).dm(to, text, {
-            idempotencyKey: idempotency_key,
-            mode,
-            attachments,
-            data: replayMessageMetadata(),
-        });
-        const receipt = compactDirectMessageReceipt(directMessageReceipt(message, to, mode, resolvedRecipient));
-        const result = jsonContent(receipt);
-        return directMessageDeliveryFailure(receipt) ? { ...result, isError: true } : result;
-    }));
+    }, async ({ to, text, mode, attachments, idempotency_key, as }, extra) => {
+        const client = getAgentClient(as);
+        return replay.run('send_dm', extra, idempotency_key, async () => {
+            const agents = await listAgentsForRecipientResolution?.();
+            const resolvedRecipient = agents ? resolveExactAgentName(agents, to) : undefined;
+            const message = await client.dm(to, text, {
+                idempotencyKey: idempotency_key,
+                mode,
+                attachments,
+                data: replayMessageMetadata(),
+            });
+            const receipt = compactDirectMessageReceipt(directMessageReceipt(message, to, mode, resolvedRecipient));
+            const result = jsonContent(receipt);
+            return directMessageDeliveryFailure(receipt) ? { ...result, isError: true } : result;
+        }, replayScopeOf(client));
+    });
     server.registerTool('list_dms', {
         title: 'List DM Conversations',
         description: 'List direct message conversations for the current agent. ' +
@@ -302,6 +327,7 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
             participants: z.array(z.string()).describe('Participant agent names'),
             name: z.string().optional().describe('Optional group name'),
             text: z.string().describe('Initial message'),
+            attachments: z.array(z.string()).optional().describe('File IDs from "upload_file"'),
             ...identityOverrideInputShape,
         },
         outputSchema: jsonResult,
@@ -311,14 +337,90 @@ export function registerMessagingTools(server, getAgentClient, listAgentsForReci
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ participants, name, text, as }) => {
+    }, async ({ participants, name, text, attachments, as }) => {
         const client = getAgentClient(as);
         const conversation = await client.dms.createGroup({ participants, name });
         const message = await client.dms.sendMessage(conversation.id, text, {
+            attachments,
             data: replayMessageMetadata(),
         });
         return jsonContent({ conversation, message });
     });
+    server.registerTool('upload_file', {
+        title: 'Upload File',
+        description: 'Upload a file (for example a screenshot) so it can be attached to a message. ' +
+            'Pass a local `path`, or `content_base64` with `filename`. The bytes are stored before this returns, so the returned `id` is ready to pass in `attachments` to "send_dm", "post_message" or "send_group_dm". ' +
+            `Files are limited to ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MiB.`,
+        inputSchema: {
+            path: z.string().optional().describe('Local file path to upload'),
+            content_base64: z.string().optional().describe('File bytes, base64-encoded (instead of path)'),
+            filename: z.string().optional().describe('File name; defaults to the basename of path'),
+            content_type: z.string().optional().describe('MIME type; guessed from the file name when omitted'),
+            ...identityOverrideInputShape,
+        },
+        outputSchema: jsonResult,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ path: filePath, content_base64, filename, content_type, as }) => {
+        if (filePath && content_base64 !== undefined) {
+            throw new Error('Pass either a local `path` or `content_base64`, not both.');
+        }
+        let file;
+        if (filePath) {
+            const read = await readAttachment(filePath);
+            file = {
+                ...read,
+                filename: filename ?? read.filename,
+                contentType: content_type ?? read.contentType,
+            };
+        }
+        else if (content_base64 !== undefined && filename) {
+            const data = decodeBase64Strict(content_base64);
+            if (data.byteLength > MAX_ATTACHMENT_BYTES) {
+                throw new Error(`Cannot attach ${filename}: ${data.byteLength} bytes exceeds the ${MAX_ATTACHMENT_BYTES}-byte limit.`);
+            }
+            file = { filename, contentType: content_type ?? contentTypeFor(filename), data };
+        }
+        else {
+            throw new Error('Pass a local `path`, or `content_base64` with `filename`.');
+        }
+        const uploaded = await uploadRelayFile(requireFiles(getAgentClient(as)), file);
+        // Signed download URLs are bearer credentials. MCP callers need only
+        // the stable metadata and id used to attach the completed upload.
+        return jsonContent({
+            id: uploaded.id,
+            filename: uploaded.filename,
+            contentType: uploaded.contentType,
+            sizeBytes: uploaded.sizeBytes,
+            status: uploaded.status,
+        });
+    });
+    server.registerTool('download_file', {
+        title: 'Download File',
+        description: 'Download a message attachment to a local file and return its `path`, so you can open it (for example, read an attached screenshot). ' +
+            "Use the `file_id` (or `id`) from a message's attachments. By default the file is saved under .agent-relay/attachments/<file_id>/ in the working directory.",
+        inputSchema: {
+            file_id: z.string().describe('Attachment file ID'),
+            path: z.string().optional().describe('Output file or existing directory'),
+            ...identityOverrideInputShape,
+        },
+        outputSchema: jsonResult,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ file_id, path: out, as }) => {
+        const { file, data } = await downloadRelayFile(requireFiles(getAgentClient(as)), file_id);
+        const saved = await saveAttachment(file_id, file.filename, data, out);
+        return jsonContent({
+            id: file.id,
+            filename: file.filename,
+            contentType: file.contentType,
+            sizeBytes: data.byteLength,
+            path: saved,
+        });
+    });
     server.registerTool('add_reaction', {
         title: 'Add Reaction',
         description: 'Add an emoji reaction to a message. ' +