mandala-computer-mcp 0.4.0 → 0.6.0

package/dist/tools/directory.d.ts

@@ -0,0 +1,13 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import type { Registrar } from './types.js';
+export declare const count: z.ZodNumber;
+export declare const label: z.ZodString;
+export declare const exitCode: z.ZodNumber;
+export declare const executionId: z.ZodString;
+/** Strip unknown fields and never print a schema exception containing response values. */
+export declare function metadata<T>(schema: z.ZodType<T>, value: unknown): T;
+/** Shared only by the passive metadata tools. No retry or readiness side effects. */
+export declare function metadataCall(work: () => Promise<CallToolResult>): Promise<CallToolResult>;
+export declare const registerDirectory: Registrar;
+//# sourceMappingURL=directory.d.ts.map

package/dist/tools/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/tools/directory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,KAAK,aAAwC,CAAC;AAC3D,eAAO,MAAM,KAAK,aAAoB,CAAC;AACvC,eAAO,MAAM,QAAQ,aAAoD,CAAC;AAC1E,eAAO,MAAM,WAAW,aAA0C,CAAC;AAEnE,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAKnE;AAED,qFAAqF;AACrF,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAqC/F;AAsBD,eAAO,MAAM,iBAAiB,EAAE,SAwC/B,CAAC"}

package/dist/tools/directory.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { APIError } from '../errors.js';
+import { apiErrorMessage, failed, said } from '../format.js';
+import * as P from '../paths.js';
+import { computerSchema, readAnnotations } from './results.js';
+export const count = z.number().int().nonnegative().safe();
+export const label = z.string().min(1);
+export const exitCode = z.number().int().min(-2147483648).max(2147483647);
+export const executionId = z.string().regex(/^exec_[a-f0-9]{32}$/);
+/** Strip unknown fields and never print a schema exception containing response values. */
+export function metadata(schema, value) {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success)
+        throw new Error('Malformed metadata response; no complete result was established.');
+    return parsed.data;
+}
+/** Shared only by the passive metadata tools. No retry or readiness side effects. */
+export async function metadataCall(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (!(error instanceof APIError))
+            return failed(error);
+        const fields = z
+            .object({
+            code: z.string().optional(),
+            reason: z.string().optional(),
+            incomplete: z.boolean().optional(),
+        })
+            .safeParse(error.body);
+        const detail = fields.success ? fields.data : {};
+        const nested = error.body?.error;
+        const message = apiErrorMessage(error);
+        const refusal = failed(new APIError(message, error.status, { ...detail, error: message, reason: error.reason }, error.retryAfterMs, error), nested === null || typeof nested !== 'object' || Array.isArray(nested));
+        return {
+            ...refusal,
+            content: [
+                ...refusal.content,
+                ...said('Refusal metadata:', {
+                    code: detail.code,
+                    incomplete: detail.incomplete,
+                    ...(error.retryAfterMs === undefined ? {} : { retry_after_ms: error.retryAfterMs }),
+                }).content,
+            ],
+        };
+    }
+}
+const directorySchema = z.object({
+    path: label,
+    entries: z
+        .array(z
+        .object({
+        name: label,
+        type: z.enum(['file', 'directory', 'symlink', 'special', 'unavailable']),
+        size_bytes: count.optional(),
+    })
+        .refine((entry) => entry.type === 'file' || entry.size_bytes === undefined, 'Only regular files may report size_bytes'))
+        .max(512),
+    truncated: z.boolean(),
+    skipped: count,
+});
+export const registerDirectory = (server, session) => {
+    server.registerTool('list_directory', {
+        title: 'List a guest directory without waking it',
+        description: 'Read one passive, unordered directory listing from an already running computer. No resume or idle extension; ordinary API rate/capacity admission still applies. At most 512 examined entries/128 KiB, with no continuation token. Narrow the path when partial. Symlinks are not followed; a final symlink directory is refused. No file content is read.',
+        inputSchema: {
+            computer_id: computerSchema,
+            path: z
+                .string()
+                .startsWith('/')
+                .refine((path) => ![...path].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127) &&
+                !P.hasUnpairedSurrogate(path), 'path must be an exact usable absolute guest path'),
+        },
+        annotations: readAnnotations,
+    }, ({ computer_id, path }, extra) => metadataCall(async () => {
+        const data = metadata(directorySchema, await session.api.json('GET', P.directory(session.resolve(computer_id)), {
+            query: { path },
+            signal: extra.signal,
+        }));
+        if (data.path !== path)
+            throw new Error('Directory response did not match the requested path.');
+        return said(data.truncated || data.skipped > 0
+            ? 'PARTIAL directory listing: entries or names were omitted. This is an unordered subset with no continuation token; use a narrower path.'
+            : 'Directory metadata only. An unavailable entry has no inferred type or size; symlinks are not followed.', data);
+    }));
+};
+//# sourceMappingURL=directory.js.map

package/dist/tools/directory.js.map

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

package/dist/tools/executions.d.ts

@@ -0,0 +1,3 @@
+import type { Registrar } from './types.js';
+export declare const registerExecutions: Registrar;
+//# sourceMappingURL=executions.d.ts.map

package/dist/tools/executions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executions.d.ts","sourceRoot":"","sources":["../../src/tools/executions.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4D5C,eAAO,MAAM,kBAAkB,EAAE,SAkDhC,CAAC"}

package/dist/tools/executions.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { APIError, CancelledError } from '../errors.js';
+import { EXECUTION_OUTPUT_DEFAULT, EXECUTION_OUTPUT_MAX, EXECUTION_RESULT_MAX, ExecutionValueError, executionComputerId, executionMetadata, executionOutput, executionReadQuery, } from '../executions.js';
+import { refused, said, withErrorMetadata } from '../format.js';
+import * as P from '../paths.js';
+const identity = {
+    computer_id: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe('Computer to read; defaults to use_computer selection.'),
+    execution_id: z
+        .string()
+        .length(37)
+        .regex(/^exec_[0-9a-f]{32}$/)
+        .describe('Stable execution_id returned by an accepted background exec; never a PID.'),
+};
+const offset = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+async function readResult(fn, signal) {
+    try {
+        if (signal.aborted)
+            return refused('Execution read cancelled. No command was replayed.');
+        const result = await fn();
+        if (signal.aborted)
+            return refused('Execution read cancelled. No command was replayed.');
+        if (Buffer.byteLength(JSON.stringify(result)) > EXECUTION_RESULT_MAX) {
+            return refused('Execution response cannot fit the bounded tool result. No output was presented and no command was replayed.');
+        }
+        return result;
+    }
+    catch (err) {
+        if (signal.aborted || err instanceof CancelledError)
+            return refused('Execution read cancelled. No command was replayed.');
+        if (err instanceof ExecutionValueError)
+            return refused(err.message);
+        if (err instanceof APIError) {
+            const status = err.status;
+            const advice = status === 404
+                ? 'This execution is unavailable; do not substitute a PID or start the command again.'
+                : status === 409
+                    ? 'The output is unavailable in the current state; no resume was requested.'
+                    : status === 401
+                        ? 'A credential was refused; inspect the supplied classification before another read.'
+                        : status === 403
+                            ? 'The current credential does not have permission for this read.'
+                            : 'The platform refused this read; no fallback was attempted.';
+            return withErrorMetadata(refused(`Execution read failed (HTTP ${status}). ${advice} No command was replayed.`), err);
+        }
+        // Network/JSON errors and redirect locations can contain untrusted text or private URLs.
+        return refused('Execution read could not be completed. Check the selected computer and connection; no fallback or command replay was attempted.');
+    }
+}
+export const registerExecutions = (server, session) => {
+    server.registerTool('get_execution', {
+        title: 'Read a stable execution observation',
+        description: 'Read one background execution by stable execution_id. Last-observed running, exited or lost; running is not proof the computer is awake, and lost establishes no success or failure. Metadata only: no guest I/O, activity refresh, resume, polling loop, PID fallback or command replay. Handles are volatile and can become unavailable after restart, replacement, expiry or cleanup.',
+        inputSchema: identity,
+        annotations,
+    }, ({ computer_id, execution_id }, extra) => readResult(async () => {
+        const id = executionComputerId(session.resolve(computer_id));
+        const data = await session.api
+            .with(extra.signal)
+            .json('GET', P.execution(id, execution_id));
+        return said('Last observed execution state; running does not prove the computer is awake, and lost is not an exit result.', executionMetadata(data, id, execution_id));
+    }, extra.signal));
+    server.registerTool('read_execution_output', {
+        title: 'Read an independent execution output chunk',
+        description: 'Read volatile, mutable guest output once at explicit independent stdout_offset and stderr_offset byte positions. Performs guest I/O but does not refresh activity, resume, change shared PID cursors, retry, tail, capture or replay a command. Unsuitable for passive Activities/history. Each stream is limited to 4096 bytes by default, at most 16384. Text is lossless UTF-8 (BOM preserved); NUL, binary and split UTF-8 remain exact base64. False more flags mean current EOF, not completion. Diagnostics repeat independently; only the first 4096 diagnostic bytes are displayed, with distinct available/displayed counts and display/daemon truncation flags.',
+        inputSchema: {
+            ...identity,
+            stdout_offset: offset,
+            stderr_offset: offset,
+            limit: z.number().int().min(1).max(EXECUTION_OUTPUT_MAX).default(EXECUTION_OUTPUT_DEFAULT),
+        },
+        annotations,
+    }, ({ computer_id, execution_id, stdout_offset, stderr_offset, limit }, extra) => readResult(async () => {
+        const query = executionReadQuery(stdout_offset, stderr_offset, limit);
+        const id = executionComputerId(session.resolve(computer_id));
+        const data = await session.api
+            .with(extra.signal)
+            .json('GET', P.executionOutput(id, execution_id), { query });
+        return said('Volatile guest output, not retained artifacts. False more flags mean current EOF only. Diagnostics repeat; a truncated display is only a prefix of the available diagnostic. No shared cursor was consumed.', executionOutput(data, execution_id, query));
+    }, extra.signal));
+};
+//# sourceMappingURL=executions.js.map

package/dist/tools/executions.js.map

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

package/dist/tools/guest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../../src/tools/guest.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAyK5C,eAAO,MAAM,aAAa,EAAE,SAgjB3B,CAAC"}
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../../src/tools/guest.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgN5C,eAAO,MAAM,aAAa,EAAE,SAyrB3B,CAAC"}

package/dist/tools/guest.js

@@ -1,7 +1,9 @@
 import { z } from 'zod';
-import { ConflictError, GatewayTimeoutError, platformSaid, RangeNotSatisfiableError, } from '../errors.js';
-import { guarded, image, isInlineImage, json, MAX_INLINE_IMAGE_BYTES, refused, said, text, } from '../format.js';
+import { ConflictError, CreateOnlyConflictError, FileExistsError, GatewayTimeoutError, platformSaid, RangeNotSatisfiableError, } from '../errors.js';
+import { apiErrorMessage, guarded, image, isInlineImage, json, MAX_INLINE_IMAGE_BYTES, refused, said, text, withErrorMetadata, } from '../format.js';
 import * as P from '../paths.js';
+import { retainIntent, synchronousResultId } from '../results.js';
+import { retentionSchema } from './results.js';
 const idArg = {
     computer_id: z
         .string()
@@ -34,6 +36,33 @@ const MAX_INLINE_BYTES = 256 * 1024;
  * body is cancelled rather than read.
  */
 const MAX_WINDOW_BYTES = MAX_INLINE_IMAGE_BYTES;
+/**
+ * `no_wake` on a file transfer (OPL-5026): refuse rather than resume a
+ * computer that is not running. Sent as the one value the platform takes.
+ */
+const noWakeArg = z
+    .boolean()
+    .default(false)
+    .describe('true: do not resume a computer that is not running — refuse instead (409), so nothing is resumed and nothing is charged for a resume. Use it to look at a suspended computer’s files only if it is already awake. false (the default) resumes a suspended computer to answer, which is charged.');
+/**
+ * A 409 on a transfer sent with `no_wake`, read as the refusal it most likely is.
+ *
+ * The platform refuses a computer that is not running with a 409 that has, so
+ * far, carried no `reason` — a change under way gives it `unavailable`. Either
+ * way it means the same thing here, so both are answered alike; any other word
+ * is left to the ordinary refusal, which says what it means.
+ */
+function noWakeRefusal(err, id, what) {
+    if (!(err instanceof ConflictError))
+        return undefined;
+    if (err instanceof FileExistsError)
+        return undefined;
+    if (err.reason !== undefined && err.reason !== 'unavailable')
+        return undefined;
+    return withErrorMetadata(refused(`${apiErrorMessage(err)} (HTTP ${err.status})\n\n${id} was not resumed, because no_wake was set: ` +
+        `most likely it is not running, and ${what}. start_computer wakes it (a resume is charged), ` +
+        'or call again without no_wake to let this resume it.'), err);
+}
 const absolutePath = (what) => z
     .string()
     .startsWith('/', `${what} must be an absolute path starting with /`)
@@ -72,7 +101,7 @@ const BACKGROUND_SLOTS_FULL = /already has (\d+) background commands? running/i;
 function backgroundSlotsFull(err) {
     if (!(err instanceof ConflictError) || err.reason !== undefined)
         return undefined;
-    const held = Number(BACKGROUND_SLOTS_FULL.exec(err.message)?.[1]);
+    const held = Number(BACKGROUND_SLOTS_FULL.exec(apiErrorMessage(err))?.[1]);
     return Number.isSafeInteger(held) && held > 0 ? held : undefined;
 }
 /**
@@ -93,13 +122,13 @@ function backgroundSlotsFull(err) {
  * the caller say which one it is in, which is the difference between a next step
  * and a guess.
  */
-const backgroundFull = (err, held) => refused(`${err.message}\n\nA slot is held for as long as its command runs, and all ${held} are held now. ` +
+const backgroundFull = (err, held) => withErrorMetadata(refused(`${apiErrorMessage(err)}\n\nA slot is held for as long as its command runs, and all ${held} are held now. ` +
     `Nothing on this side frees one: a command that has already finished is not counted, so there is ` +
     `nothing to reap, and a poll reads output rather than releasing anything. If any of the ${held} are ` +
     `servers, they do not exit on their own and another exec with background: true gets this same answer ` +
     `for as long as they run. The way out is to stop one you no longer need — exec_kill on a pid an ` +
     `earlier exec returned, with exec_poll to see which are still running. If they are builds or installs ` +
-    `rather than servers, one of them finishes by itself and its slot comes back a moment later.`);
+    `rather than servers, one of them finishes by itself and its slot comes back a moment later.`), err);
 /**
  * A window action that timed out on the way back, turned into the next step it
  * needs — which is a READ, and never this call again (OPL-3910).
@@ -140,7 +169,7 @@ const windowOutcomeMayBeUnknown = (err) => {
 };
 const windowOutcomeUnknown = (err, action, windowId) => {
     const named = platformSaid(err.body);
-    return refused(`${named ? `${named}\n\n` : ''}The ${action} on ${windowId} did not report a result before the ` +
+    return withErrorMetadata(refused(`${named ? `${named}\n\n` : ''}The ${action} on ${windowId} did not report a result before the ` +
         `deadline (HTTP ${err.status}). That is not a refusal and it is not a report that nothing ` +
         `happened: the guest may have taken the action and lost the race to say so, so the outcome is ` +
         `UNKNOWN and the ${action} may already have been applied. Do not send this call again to find ` +
@@ -150,7 +179,7 @@ const windowOutcomeUnknown = (err, action, windowId) => {
                 `window id is not reserved forever — the X server can hand the same id to something else — ` +
                 `so a second close is not safely a no-op on a window that has already gone.`
             : `A repeated ${action} is untidy rather than destructive, but it still answers with a guess ` +
-                `where a read answers with the window.`));
+                `where a read answers with the window.`)), err);
 };
 export const registerGuest = (server, session) => {
     server.registerTool('exec', {
@@ -159,6 +188,10 @@ export const registerGuest = (server, session) => {
         inputSchema: {
             ...idArg,
             command: z.string().describe('A shell command line.'),
+            retain_output: z
+                .union([z.boolean(), retentionSchema])
+                .optional()
+                .describe('Explicit synchronous output retention only. False/absent preserves default behavior. A valid result_id confirms a retained version; optional failure never replays the command.'),
             timeout_s: z
                 .number()
                 .int()
@@ -169,26 +202,35 @@ export const registerGuest = (server, session) => {
             desktop: z
                 .boolean()
                 .default(false)
-                .describe('Run inside the logged-in desktop session instead of as root with no display. Required for anything with a window: the guest agent has no DISPLAY, so a GUI app started without this cannot draw. Linux only.'),
+                .describe('Run inside the logged-in desktop session instead of as root with no display. Required for anything with a window: the guest agent has no DISPLAY, so a GUI app started without this cannot draw. Also the way to reach secrets bound to this computer as environment variables (set_computer_secrets): they live in the desktop session, and on an image that supports it a value replaced while the computer runs is seen by new desktop-session commands within seconds. Whether a plain root exec sees bound secrets depends on the platform version, so a command that needs one should use this. Linux only.'),
             background: z
                 .boolean()
                 .default(false)
                 .describe('Return a handle immediately instead of waiting. Use for builds, installs, test suites and servers, then read output with exec_poll. To learn that it finished, wait_for_event with types ["process.exited"] and the pid this returns — the computer reports the exit, so waiting for it costs one call rather than an exec_poll loop. Strictly better than backgrounding with "&", which throws away the exit code and the output. A computer runs at most sixteen of these at once, and past that this is refused with a 409 saying how many are already running rather than queued. A slot is held until its command exits, which for a server is never, so the way out of that refusal is exec_kill on a pid an earlier exec returned — not another attempt.'),
-            cwd: absolutePath('cwd').optional(),
+            cwd: absolutePath('cwd')
+                .optional()
+                .describe('Absolute path to run in. If it does not exist the command does not run, and exit_code is 127.'),
             env: z
                 .record(z.string(), z.string())
                 .optional()
                 .describe('Environment for this command, as {NAME: "value"}. Use it instead of writing FOO=bar in front of the command: a prefix assignment is shell syntax, so a value holding a space, a quote, a newline or a $ has to be quoted correctly by you and is silently truncated or re-parsed when it is not, while this reaches the process whole and unquoted. It also keeps a secret out of the command line, which is world-readable in the guest\'s ps and, for a background command, comes back to you inside every exec_poll answer. The variables are added on top of the guest\'s login profile rather than replacing it, so PATH and the rest are still there, and they apply to this command only — including with desktop: true. Names must not be empty or contain "=".'),
         },
-    }, ({ computer_id, command, timeout_s, desktop, background, cwd, env }, extra) => guarded(async () => {
+    }, ({ computer_id, command, timeout_s, desktop, background, cwd, env, retain_output }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
+        const retain = retainIntent(retain_output, background);
+        let status;
         let res;
         try {
-            res = await session.api
-                .with(extra.signal)
-                .json('POST', P.computerAction(id, 'exec'), {
-                body: P.execBody({ command, timeout_s, desktop, background, cwd, env }),
-            });
+            const api = session.api.with(extra.signal), body = P.execBody({ command, timeout_s, desktop, background, cwd, env, retain_output });
+            if (retain !== undefined) {
+                const observed = await api.jsonWithStatus('POST', P.computerAction(id, 'exec'), { body });
+                res = observed.value;
+                status = observed.status;
+            }
+            else
+                res = await api.json('POST', P.computerAction(id, 'exec'), {
+                    body,
+                });
         }
         catch (err) {
             // The one refusal on this route whose next step is a different tool
@@ -216,10 +258,28 @@ export const registerGuest = (server, session) => {
             if (!Number.isSafeInteger(res.pid) || res.pid <= 0) {
                 return refused(`The command was accepted but the guest reported no pid that is a usable positive safe integer, so there is no safe handle to poll or kill it with. It may still be running inside the computer — check with exec "ps aux".${note}`, body);
             }
-            return said(`Started as pid ${res.pid}. Read its output with exec_poll, stop it with exec_kill.${note}`, body);
+            const stable = P.isExecutionId(res.execution_id);
+            const acceptedBody = stable && body && typeof body === 'object' && !Array.isArray(body)
+                ? { ...body, execution_id: res.execution_id }
+                : body;
+            const identityNote = stable
+                ? ' Use get_execution for its last observation and read_execution_output with explicit offsets for independent reads; these never consume the shared PID cursor.'
+                : 'execution_id' in res
+                    ? ' The command was accepted, but its stable identity is unavailable because the returned execution_id was malformed. Do not replay the command; the valid PID remains available for legacy inspection, subject to PID reuse.'
+                    : '';
+            return said(`Started as pid ${res.pid}. Read its output with exec_poll, stop it with exec_kill.${identityNote}${note}`, acceptedBody);
         }
         const { body, note } = decodeExec(res, false);
-        return said(`${execSummary(res)}${note}`, body);
+        const retained = retain !== undefined ? synchronousResultId(res, status) : undefined;
+        const presented = retained && body && typeof body === 'object' && !Array.isArray(body)
+            ? { ...body, result_id: retained }
+            : body;
+        const retentionNote = retain === undefined
+            ? ''
+            : retained
+                ? ' Retained result confirmed; use get_result or read_result_output for a separate explicit read.'
+                : ' No retrievable retained result ID was confirmed. Do not replay the command to recover it.';
+        return said(`${execSummary(res)}${note}${retentionNote}`, presented);
     }));
     server.registerTool('exec_poll', {
         title: 'Read a background command',
@@ -322,15 +382,39 @@ export const registerGuest = (server, session) => {
     }));
     server.registerTool('window_action', {
         title: 'Act on a window',
-        description: 'Focus, raise, minimize, maximize, unmaximize, close, move or resize one window. The reply is the window afterwards, not an acknowledgement — the window manager places the frame and applications snap to their own grid, so a move to 300,200 routinely lands at 305,229. Believe the response, not the request. Prefer focus over raise: raising without focusing gives a window that is visibly in front and silently not receiving keystrokes. A 504 is neither a refusal nor a report that nothing happened unless its structured response explicitly says the request was not dispatched: an absent or ambiguous explanation leaves the action possibly already applied. An uncertain outcome is not permission to repeat it — the next call is list_windows, which says what the desktop is now, not this one again. Least of all for close, which cannot be undone.',
+        description: 'Focus, raise, minimize, maximize, unmaximize, close, move or resize one window. The reply is the window afterwards, not an acknowledgement — the window manager places the frame and applications snap to their own grid, so a move to 300,200 routinely lands at 305,229. Believe the response, not the request. On a Wayland desktop a tiled window cannot be moved or resized — float it first — and an action the compositor refuses is a 400. Prefer focus over raise: raising without focusing gives a window that is visibly in front and silently not receiving keystrokes. A 504 is neither a refusal nor a report that nothing happened unless its structured response explicitly says the request was not dispatched: an absent or ambiguous explanation leaves the action possibly already applied. An uncertain outcome is not permission to repeat it — the next call is list_windows, which says what the desktop is now, not this one again. Least of all for close, which cannot be undone.',
         inputSchema: {
             ...idArg,
             window_id: z.string().describe('From list_windows, e.g. "0x2600003".'),
             action: z.enum(P.WINDOW_ACTIONS),
-            x: z.number().int().optional().describe('For move.'),
-            y: z.number().int().optional().describe('For move.'),
-            width: z.number().int().optional().describe('For resize.'),
-            height: z.number().int().optional().describe('For resize.'),
+            x: z
+                .number()
+                .int()
+                .min(-32768)
+                .max(32767)
+                .optional()
+                .describe('Required for move, with y: -32768 to 32767.'),
+            y: z
+                .number()
+                .int()
+                .min(-32768)
+                .max(32767)
+                .optional()
+                .describe('Required for move, with x: -32768 to 32767.'),
+            width: z
+                .number()
+                .int()
+                .min(1)
+                .max(32767)
+                .optional()
+                .describe('Required for resize, with height: 1 to 32767.'),
+            height: z
+                .number()
+                .int()
+                .min(1)
+                .max(32767)
+                .optional()
+                .describe('Required for resize, with width: 1 to 32767.'),
         },
     }, ({ computer_id, window_id, action, x, y, width, height }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
@@ -390,7 +474,7 @@ export const registerGuest = (server, session) => {
     }));
     server.registerTool('write_file', {
         title: 'Put a file into the guest',
-        description: 'Write a file inside the computer. Paths must be absolute — the guest agent inherits whatever working directory it was started in, so a relative path resolves somewhere you did not name.',
+        description: 'Write a file inside the computer. Paths must be absolute — the guest agent inherits whatever working directory it was started in, so a relative path resolves somewhere you did not name. By default a file already at the path is replaced. Pass overwrite: false to create the file only if nothing is there: a path that is taken is refused and that attempt writes nothing — retrying does not change that. Incomplete contents are never published at the path, but a failure while publishing or answering can leave the COMPLETE file there: after any error, read the path before retrying or overwriting, since what is there may be your own upload. A refusal saying this computer\u2019s host cannot do a create-only write, and a 503 on one, mean nothing was sent — but neither means the path is free. overwrite: false is for Linux computers; a Windows computer refuses it. A suspended computer is resumed to take the write, which is charged, unless no_wake is set.',
         inputSchema: {
             ...idArg,
             path: absolutePath('path').describe('Absolute path inside the guest, e.g. /home/user/Desktop/notes.txt.'),
@@ -399,8 +483,13 @@ export const registerGuest = (server, session) => {
                 .enum(['utf8', 'base64'])
                 .default('utf8')
                 .describe('base64 for anything that is not text.'),
+            overwrite: z
+                .boolean()
+                .default(true)
+                .describe('true (the default) replaces a file already at the path. false creates the file only if nothing is there, and refuses without writing anything when the path is taken.'),
+            no_wake: noWakeArg,
         },
-    }, ({ computer_id, path, content, encoding }, extra) => guarded(async () => {
+    }, ({ computer_id, path, content, encoding, overwrite, no_wake }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         // Node's base64 decoder is lenient: it drops characters outside the
         // alphabet and stops early on bad padding, without ever throwing. A
@@ -423,18 +512,68 @@ export const registerGuest = (server, session) => {
             return refused(`That content has an unpaired surrogate in it — half of a character, usually from a string cut through the middle of an emoji. It is not valid UTF-8, so ${path} would have been written with a replacement character where your text was, and reported as a success. Nothing was written. Send the whole character, cut the text on a character boundary, or send the exact bytes with encoding: "base64".`);
         }
         const bytes = new Uint8Array(Buffer.from(content, encoding === 'base64' ? 'base64' : 'utf8'));
-        const res = await session.api.with(extra.signal).json('PUT', P.computerAction(id, 'files'), 
-        // The path is a query parameter, and the URL builder encodes it. Doing
-        // that matters more than it looks: `+` decodes to a space and `&`
-        // ends the parameter, so an unencoded path with punctuation in it
-        // writes a DIFFERENT file and nothing reports that, because the
-        // platform never sees what was meant.
-        { query: { path }, raw: bytes });
+        let res;
+        try {
+            res = await session.api.with(extra.signal).json('PUT', P.computerAction(id, 'files'), 
+            // The path is a query parameter, and the URL builder encodes it. Doing
+            // that matters more than it looks: `+` decodes to a space and `&`
+            // ends the parameter, so an unencoded path with punctuation in it
+            // writes a DIFFERENT file and nothing reports that, because the
+            // platform never sees what was meant.
+            //
+            // `overwrite` is sent only to ask for create-only (OPL-4994). Absent
+            // means replace on every platform version, so the default request
+            // is the one this tool always sent.
+            {
+                query: {
+                    path,
+                    ...(overwrite ? {} : { overwrite: 'false' }),
+                    ...(no_wake ? { no_wake: '1' } : {}),
+                },
+                raw: bytes,
+            });
+        }
+        catch (err) {
+            // A create-only upload's reasonless 409 is CreateOnlyConflictError
+            // whether or not no_wake was sent, and claims nothing about the path
+            // or the computer's state — the same answer the Python SDK gives.
+            if (no_wake && !(err instanceof CreateOnlyConflictError)) {
+                const asleep = noWakeRefusal(err, id, `nothing was written to ${path}`);
+                if (asleep)
+                    return asleep;
+            }
+            // Only THIS attempt is known to have written nothing. A create-only
+            // write whose earlier attempt lost its answer may have written the
+            // file itself, and the retry then meets its own file here — so the
+            // sentence must not tell a model to go elsewhere or overwrite blind.
+            if (err instanceof FileExistsError) {
+                return withErrorMetadata(refused(`${apiErrorMessage(err)}\n\nSomething is already at ${path}, and this attempt wrote ` +
+                    'nothing: the file there is untouched by it. This does not clear by waiting, so do not ' +
+                    'send the same call again. If an earlier attempt\u2019s outcome was unknown, the file may ' +
+                    'be yours: read it and compare before choosing another path or overwriting. To replace ' +
+                    'it on purpose, call write_file again with overwrite: true (or without overwrite).'), err);
+            }
+            // A create-only 409 with no usable reason — the body lost, empty, not
+            // the platform's JSON, or JSON without a string `reason`. The Api
+            // raises it as CreateOnlyConflictError so no caller resends it; the
+            // words here claim nothing about the path, nor that this attempt
+            // wrote nothing \u2014 without the platform's word, the 409 may come from
+            // a hop that had already forwarded the write. Not apiErrorMessage:
+            // the body's own text could say "already exists" without the
+            // platform's `exists` reason.
+            if (err instanceof CreateOnlyConflictError) {
+                return withErrorMetadata(refused(`${err.message} (HTTP ${err.status})\n\nThis create-only write to ${path} was refused ` +
+                    'as a conflict, reason unknown, and whether this attempt wrote anything is ' +
+                    'unconfirmed. Do not send the same call again: it was not said to clear by waiting. ' +
+                    'Read the path to see what is there before choosing another path or overwriting.'), err);
+            }
+            throw err;
+        }
         return said(`Wrote ${res.bytes ?? bytes.length} bytes to ${res.path ?? path}.`, res);
     }));
     server.registerTool('read_file', {
         title: 'Get a file out of the guest',
-        description: 'Read a file from inside the computer. Text comes back as text and images come back as images; anything else comes back base64. A large file comes back a window at a time rather than filling the conversation: `offset` says where the window starts, and the note under a truncated read gives the exact offset to pass next. There is no size a file can be that makes it unreadable this way — a 2 GB log is pages, not a refusal — but a file you want whole is still better pushed out of the guest than carried through a conversation, and the note says how. This reaches the guest agent to do it, so a suspended computer is resumed to answer and that resume is charged — it can even come back 402. read_clipboard, by contrast, refuses a suspended computer rather than starting it.',
+        description: 'Read a file from inside the computer. Text comes back as text and images come back as images; anything else comes back base64. A large file comes back a window at a time rather than filling the conversation: `offset` says where the window starts, and the note under a truncated read gives the exact offset to pass next. There is no size a file can be that makes it unreadable this way — a 2 GB log is pages, not a refusal — but a file you want whole is still better pushed out of the guest than carried through a conversation, and the note says how. This reaches the guest agent to do it, so a suspended computer is resumed to answer and that resume is charged — it can even come back 402 — unless no_wake is set, which refuses instead. read_clipboard, by contrast, refuses a suspended computer rather than starting it.',
         inputSchema: {
             ...idArg,
             path: absolutePath('path'),
@@ -445,6 +584,7 @@ export const registerGuest = (server, session) => {
                 .max(Number.MAX_SAFE_INTEGER)
                 .default(0)
                 .describe('Byte offset to start at. 0 is the beginning of the file. Each call returns a window from here, and the truncation note names the offset of the byte after the last one it returned — pass that to read on. Never assume a window covers what you asked for: read the offset out of the note rather than adding a fixed number.'),
+            no_wake: noWakeArg,
         },
         // Not readOnlyHint, for the reason cursor_position is not: the platform
         // marks `GET computers/:id/files` as spending, because reaching the guest
@@ -457,12 +597,12 @@ export const registerGuest = (server, session) => {
         // reading it twice — a host that gates retry-of-a-timed-out-call on
         // idempotentHint would refuse to retry a plain file read.
         annotations: { destructiveHint: false, idempotentHint: true },
-    }, ({ computer_id, path, offset }, extra) => guarded(async () => {
+    }, ({ computer_id, path, offset, no_wake }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         let file;
         try {
             file = await session.api.with(extra.signal).bytes('GET', P.computerAction(id, 'files'), {
-                query: { path },
+                query: { path, ...(no_wake ? { no_wake: '1' } : {}) },
                 // The window this tool asks the platform for, which is not the
                 // same as the window it will return. It is the larger of the two
                 // caps below — the most this tool could ever hand back — because
@@ -482,7 +622,12 @@ export const registerGuest = (server, session) => {
         }
         catch (err) {
             if (err instanceof RangeNotSatisfiableError)
-                return pastEnd(path, offset, err.size);
+                return withErrorMetadata(pastEnd(path, offset, err.size), err);
+            if (no_wake) {
+                const asleep = noWakeRefusal(err, id, `nothing was read from ${path}`);
+                if (asleep)
+                    return asleep;
+            }
             throw err;
         }
         const served = file.window;
@@ -903,6 +1048,10 @@ function decodeExec(res, continued) {
     const body = {};
     const notes = [];
     for (const [key, value] of Object.entries(source)) {
+        // Only the accepted launch can bind stable identity to this command.
+        // A reusable PID poll (or kill) cannot reconstruct that association.
+        if (key === 'execution_id' || key === 'result_id')
+            continue;
         if (claimed.has(key))
             continue;
         const field = EXEC_STREAMS[key];