mandala-computer-mcp 0.5.0 → 0.7.0

package/dist/tools/operations.d.ts

@@ -0,0 +1,44 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import type { Registrar } from './types.js';
+/**
+ * The key on a step a read of the computer shows: start, stop, suspend,
+ * delete, move, update_computer (not restart: see
+ * {@link restartIdempotencyKeyArg}). See {@link resendAfterSpentKey}.
+ */
+export declare const idempotencyKeyArg: z.ZodOptional<z.ZodString>;
+/**
+ * The key on restart_computer, whose step no read of the computer shows: it
+ * reads running before and after a reset. So the route never conditions a
+ * resend on get_computer; see {@link resendAfterSpentKey}.
+ */
+export declare const restartIdempotencyKeyArg: z.ZodOptional<z.ZodString>;
+/**
+ * The key on a call that makes a new computer or overwrites a disk: create,
+ * clone, clone_snapshot, restore_snapshot. A resend after a spent key waits for
+ * the operation to be final. See {@link resendAfterSpentKey}.
+ */
+export declare const buildIdempotencyKeyArg: z.ZodOptional<z.ZodString>;
+/**
+ * The answer to a lifecycle tool call that failed, with what its key means.
+ *
+ * The platform's own `idempotency_*` refusals get their sentence instead of the
+ * generic `reason` advice. A failure whose outcome is unknown ENDS with the
+ * retry that cannot do the step twice, and which one depends on who answered:
+ *
+ * - The answer never arrived, the keyed call is still running, or a proxy in
+ *   front of the platform answered: the same tool, with the same key.
+ * - The platform itself answered a `5xx`: it has settled that key as lost
+ *   (OPL-5304), so the same key can only be answered
+ *   `idempotency_outcome_unknown`. The next step is a read, then a resend
+ *   with a new key or none if the step did not happen. Which read depends on
+ *   the tool (see {@link resendAfterSpentKey}): a create, clone or restore
+ *   waits for its operation to be final, since a read of the computer made
+ *   at once cannot see one still landing; a restart, which no read of the
+ *   computer shows, is read off its operation and otherwise left to the user;
+ *   every other step is read off the computer, since its operation stays
+ *   `pending` for an hour regardless.
+ */
+export declare function keyedFailure(err: unknown, tool: string, what: string, key: string): CallToolResult;
+export declare const registerOperations: Registrar;
+//# sourceMappingURL=operations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/tools/operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA8C5C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,4BAE7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,4BAEpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,4BAElC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,cAAc,CAiBhB;AAuBD,eAAO,MAAM,kBAAkB,EAAE,SAmJhC,CAAC"}

package/dist/tools/operations.js

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { IDEMPOTENCY_KEY_PATTERN } from '../api.js';
+import { CancelledError, idempotencyAdvice, isTransientForPoll, keyedOutcomeUnknown, platformAnsweredFailure, resendAfterSpentKey, resendUnseenByRead, } from '../errors.js';
+import { failed, guarded, operationIdOf, refused, said } from '../format.js';
+import * as P from '../paths.js';
+import { heartbeat, POLL_MS, pollDelay, sleep } from '../poll.js';
+import { label, metadata, metadataCall } from './directory.js';
+import { readAnnotations } from './results.js';
+/**
+ * One lifecycle operation (platform OPL-5055), projected to its public fields.
+ *
+ * `kind` and `state` are open strings: the platform adds kinds, and one this
+ * server does not know is a kind, not a malformed answer. Strict on the error's
+ * shape, because a `failed` operation relayed without its reason is a failure
+ * with nothing to say about why.
+ */
+const operation = z.object({
+    id: label,
+    kind: label,
+    computer_id: z.string().nullable(),
+    state: label,
+    error: z.object({ code: z.string(), message: z.string() }).nullable(),
+    // The key the call that started it was sent with (OPL-5127): null for one
+    // sent without, and absent from a platform that predates the field.
+    idempotency_key: z.string().nullable().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    finished_at: z.string().nullable(),
+});
+const page = z.object({
+    operations: z.array(operation),
+    next_cursor: z.string().min(1).nullable(),
+});
+/**
+ * The `idempotency_key` a lifecycle tool takes (platform OPL-5127), checked
+ * against the platform's rule here so a key it would refuse never leaves.
+ */
+const keyArg = z
+    .string()
+    .regex(IDEMPOTENCY_KEY_PATTERN, 'idempotency_key must be 1 to 255 characters, each printable ASCII other than a space')
+    .optional();
+const KEY_FIRST = "Optional. Omit it on a first attempt: a fresh key is sent for you, and an answer that is lost names it. Pass the key such an answer named to send the SAME call again without it being done twice — the platform answers with the first call's result, or says it is still running. After a 5xx the platform answered, or idempotency_outcome_unknown, the key is spent (resending with it answers idempotency_outcome_unknown)";
+const KEY_LAST = ' Keys last 24 hours; the same key with different arguments is refused.';
+/**
+ * The key on a step a read of the computer shows: start, stop, suspend,
+ * delete, move, update_computer (not restart: see
+ * {@link restartIdempotencyKeyArg}). See {@link resendAfterSpentKey}.
+ */
+export const idempotencyKeyArg = keyArg.describe(`${KEY_FIRST}: read get_computer (and get_operation when the error named an operation_id: succeeded means it happened, running means wait on it, pending alone is no reason to wait), and if the step did not take effect, send the call again with a new key, or none.${KEY_LAST}`);
+/**
+ * The key on restart_computer, whose step no read of the computer shows: it
+ * reads running before and after a reset. So the route never conditions a
+ * resend on get_computer; see {@link resendAfterSpentKey}.
+ */
+export const restartIdempotencyKeyArg = keyArg.describe(`${KEY_FIRST}. A restart cannot be seen in get_computer (it reads running before and after one), so do not read the computer to decide: read get_operation with the operation_id the error named, or list_operations with the key. Succeeded means the restart happened; running means wait on it. Anything else leaves it possibly done, so ask the user before sending it again with a new key, or none — a second restart resets the guest again.${KEY_LAST}`);
+/**
+ * The key on a call that makes a new computer or overwrites a disk: create,
+ * clone, clone_snapshot, restore_snapshot. A resend after a spent key waits for
+ * the operation to be final. See {@link resendAfterSpentKey}.
+ */
+export const buildIdempotencyKeyArg = keyArg.describe(`${KEY_FIRST} and the call may still be under way: read its operation first (get_operation with the operation_id the error named, or list_operations with the key), wait while it is pending or running and do not resend meanwhile, and send the call with a new key (or none) only once the operation is final as failed or not found AND get_computer shows the step did not happen.${KEY_LAST}`);
+/**
+ * The answer to a lifecycle tool call that failed, with what its key means.
+ *
+ * The platform's own `idempotency_*` refusals get their sentence instead of the
+ * generic `reason` advice. A failure whose outcome is unknown ENDS with the
+ * retry that cannot do the step twice, and which one depends on who answered:
+ *
+ * - The answer never arrived, the keyed call is still running, or a proxy in
+ *   front of the platform answered: the same tool, with the same key.
+ * - The platform itself answered a `5xx`: it has settled that key as lost
+ *   (OPL-5304), so the same key can only be answered
+ *   `idempotency_outcome_unknown`. The next step is a read, then a resend
+ *   with a new key or none if the step did not happen. Which read depends on
+ *   the tool (see {@link resendAfterSpentKey}): a create, clone or restore
+ *   waits for its operation to be final, since a read of the computer made
+ *   at once cannot see one still landing; a restart, which no read of the
+ *   computer shows, is read off its operation and otherwise left to the user;
+ *   every other step is read off the computer, since its operation stays
+ *   `pending` for an hour regardless.
+ */
+export function keyedFailure(err, tool, what, key) {
+    const advice = idempotencyAdvice(err, tool);
+    const result = failed(err, advice === undefined);
+    const [first, ...rest] = result.content;
+    if (first?.type !== 'text')
+        return result;
+    let text = first.text;
+    if (advice)
+        text += `\n\nAbout its idempotency_key: ${advice}.`;
+    if (keyedOutcomeUnknown(err)) {
+        text += `\n\nTo retry without risking a second ${what}, call ${tool} again with idempotency_key "${key}".`;
+    }
+    else if (platformAnsweredFailure(err)) {
+        const op = operationIdOf(err.body);
+        text +=
+            `\n\nThe platform answered this itself, so whether it took effect is unknown — its host may still be carrying out the ${what} — and it has settled idempotency_key "${key}": resending with that key will answer idempotency_outcome_unknown, not do it. ` +
+                `${resendAfterSpentKey(tool, op, key, `call ${tool} again`)}.` +
+                (resendUnseenByRead(tool) ? '' : ` That way there is no second ${what}.`);
+    }
+    return { ...result, content: [{ ...first, text }, ...rest] };
+}
+const operationIdArg = z
+    .string()
+    .min(1)
+    .describe('The operation_id a lifecycle tool answered: a create, a clone, a start, stop, suspend or restart, a resize, a snapshot restore, or a move.');
+/** The sentence every answer about an operation starts with. */
+const line = (op) => `${op.id}: ${op.kind}${op.computer_id ? ` of ${op.computer_id}` : ''} — ${op.state}` +
+    (op.error ? ` (${op.error.code}: ${op.error.message})` : '') +
+    (op.idempotency_key ? ` [idempotency_key ${JSON.stringify(op.idempotency_key)}]` : '');
+/**
+ * Said beside every `succeeded`, because it is the misreading that costs the
+ * most: a model that reads a succeeded start as a desktop that answers drives
+ * a guest that is still booting.
+ */
+const NOT_BOOTED = 'succeeded means the platform finished its step, not that the desktop has booted: wait_for_computer is still the wait for a desktop that answers.';
+export const registerOperations = (server, session) => {
+    server.registerTool('get_operation', {
+        title: 'Read a lifecycle operation',
+        description: `One lifecycle operation: what an accepted create, clone, start, stop, suspend, restart, snapshot restore, resize, move or delete started, and where it got to. A call made with an idempotency_key is recorded pending before it is carried out, so it can be found even when its answer was lost; one the platform never heard end is failed with error.code lost. state is pending or running while live, and succeeded or failed once final; a failed one carries error.code (start_failed, build_failed, computer_gone, move_failed, resize_not_applied, lost, and more may be added) and a sentence. Most are already succeeded when the call that started them answered; a clone is running until its disk is copied, and a move until it lands. ${NOT_BOOTED} An id this key cannot see, or one that has expired, is not found.`,
+        inputSchema: { operation_id: operationIdArg },
+        annotations: readAnnotations,
+    }, ({ operation_id }, extra) => metadataCall(async () => {
+        const op = metadata(operation, await session.api.json('GET', P.operation(operation_id), { signal: extra.signal }));
+        return said(line(op), op);
+    }));
+    server.registerTool('list_operations', {
+        title: 'List lifecycle operations',
+        description: "The lifecycle operations this account's API calls started, newest first, a page at a time: kind, computer_id, state, error and timestamps. computer_id keeps one computer's (for a clone, the new computer's) — omitted, it is the whole account's, not the selected computer's. Pass next_cursor back as cursor for the next page; it is null on the last. Calls made from the dashboard record none.",
+        inputSchema: {
+            computer_id: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Only this computer's operations. Not defaulted to the selected computer."),
+            limit: z.number().int().min(1).max(100).optional().describe('Page size; default 20.'),
+            cursor: z.string().min(1).optional().describe('The next_cursor of the page before.'),
+            idempotency_key: z
+                .string()
+                .regex(IDEMPOTENCY_KEY_PATTERN, 'idempotency_key must be 1 to 255 characters, each printable ASCII other than a space')
+                .optional()
+                .describe("Only the operation the lifecycle call sent with this idempotency_key recorded — found even when that call's answer was lost — within the key's 24 hours."),
+        },
+        annotations: readAnnotations,
+    }, ({ computer_id, limit, cursor, idempotency_key }, extra) => metadataCall(async () => {
+        const data = metadata(page, await session.api.json('GET', P.OPERATIONS, {
+            query: { computer_id, limit, cursor, idempotency_key },
+            signal: extra.signal,
+        }));
+        if (!data.operations.length)
+            return said('No operations.', data);
+        return said(data.operations.map(line).join('\n') +
+            (data.next_cursor
+                ? `\n\nMore: pass cursor=${data.next_cursor} for the next page.`
+                : ''), data);
+    }));
+    server.registerTool('wait_for_operation', {
+        title: 'Wait for a lifecycle operation to finish',
+        description: `Poll a lifecycle operation until it is final. Answers once it has succeeded; a failed one is an error carrying error.code and the platform's sentence (resize_not_applied is a move that landed at the old size: the computer has moved, and update_computer finishes the resize). ${NOT_BOOTED} Most operations are already final when their call answers, so this is for a clone (running until its disk is copied) or a move. Reports progress while it waits, so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; get_operation reads it if the wait runs out.`,
+        inputSchema: {
+            operation_id: operationIdArg,
+            timeout_s: z
+                .number()
+                .int()
+                .min(1)
+                .max(900)
+                .default(300)
+                .describe('How long to wait before handing back and letting you poll.'),
+        },
+        annotations: readAnnotations,
+    }, ({ operation_id, timeout_s }, extra) => guarded(async () => {
+        const path = P.operation(operation_id);
+        const untilDeadline = AbortSignal.timeout(timeout_s * 1000);
+        const signal = extra.signal
+            ? AbortSignal.any([extra.signal, untilDeadline])
+            : untilDeadline;
+        const api = session.api.with(signal);
+        const beat = heartbeat(extra, server.server);
+        let last;
+        let blocked;
+        try {
+            while (!untilDeadline.aborted) {
+                if (extra.signal?.aborted) {
+                    return refused(`Cancelled while waiting for ${operation_id}. The operation is not stopped by that; get_operation says where it got to.`, last);
+                }
+                let raw;
+                try {
+                    raw = await api.json('GET', path);
+                }
+                catch (err) {
+                    if (extra.signal?.aborted)
+                        continue;
+                    if (err instanceof CancelledError) {
+                        if (untilDeadline.aborted)
+                            break;
+                        blocked = err.message;
+                        await sleep(POLL_MS, signal);
+                        continue;
+                    }
+                    if (!isTransientForPoll(err))
+                        throw err;
+                    blocked = err instanceof Error ? err.message : String(err);
+                    await beat(`${operation_id} — the platform could not be asked: ${blocked}`);
+                    await sleep(pollDelay(err), signal);
+                    continue;
+                }
+                const op = metadata(operation, raw);
+                last = op;
+                blocked = undefined;
+                if (op.state === 'succeeded')
+                    return said(`${line(op)}.\n\n${NOT_BOOTED}`, op);
+                if (op.state === 'failed')
+                    return refused(`${line(op)}.`, op);
+                // A state this server does not know, on an operation the platform
+                // says has FINISHED, is a final state added after it was written.
+                // Polling it would run to the deadline and then call it live.
+                if (op.finished_at !== null && op.state !== 'pending' && op.state !== 'running') {
+                    return refused(`${line(op)}. It has finished in a state this server does not know; read it with get_operation.`, op);
+                }
+                await beat(line(op));
+                await sleep(POLL_MS, signal);
+            }
+            return refused(blocked
+                ? `Gave up after ${timeout_s}s; the platform could not be asked — the last attempt said: ${blocked}. The operation is not stopped by that; get_operation says where it got to.`
+                : `Still ${last?.state ?? 'live'} after ${timeout_s}s. The operation is not stopped by that; wait again, or read it with get_operation.`, last);
+        }
+        finally {
+            await beat.stop();
+        }
+    }));
+};
+//# sourceMappingURL=operations.js.map

package/dist/tools/operations.js.map

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

package/dist/tools/secrets.d.ts

@@ -1,21 +1,26 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { type Secret } from '../secret-store.js';
 import type { Registrar } from './types.js';
 /**
- * A computer's secret bindings: which of the account's secrets it receives, at
- * which revision, and where — as an environment variable (`env`) or as a file
- * under FILES_DIR (`file`).
+ * Secrets: the account's store of named values, and which of them each
+ * computer is bound to.
  *
- * No value ever crosses these routes, in either direction — only secret ids,
- * revision ids, env names and file names — so nothing here can show one, and
- * nothing a model sends can set one. Secrets themselves are created and rotated
- * elsewhere.
+ * The BINDINGS (get/set_computer_secrets) carry only ids, revision ids, env
+ * names and file names — no value crosses those routes in either direction.
+ *
+ * The STORE (list/get/create/set/replace/delete_secret) is where a value goes in,
+ * and only in: the platform never answers one, the decoded answers here carry
+ * none, and a tool that took a value never repeats it — not in a success, not
+ * in a refusal. See {@link withoutValue}.
  *
  * A change of bindings takes effect at the computer's NEXT START OR RESTART. A
  * running computer keeps what it booted with until then, and a suspended one
  * resumes with its old values; the sentences below say so every time, because a
  * model that reads "saved" as "delivered" goes on to use a credential the guest
- * does not have yet. The one thing that reaches a running computer sooner is a
- * replaced VALUE of a secret bound as a file: that file is rewritten in place.
+ * does not have yet. What reaches a running computer sooner is a replaced VALUE:
+ * a file binding's file is rewritten in place, and on an image that supports it
+ * an env binding's new value reaches new shells and desktop-session commands.
  */
 /** Where a file binding is published in the guest. */
 export declare const FILES_DIR = "/run/mandala-secrets/user/files";
@@ -35,24 +40,48 @@ export declare function secretBindingsSchema(revision: boolean): z.ZodEffects<z.
     file: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     secret_id: string;
-    file?: string | undefined;
     env?: string | undefined;
     revision_id?: unknown;
+    file?: string | undefined;
 }, {
     secret_id: string;
-    file?: string | undefined;
     env?: string | undefined;
     revision_id?: unknown;
+    file?: string | undefined;
 }>, "many">, {
     secret_id: string;
-    file?: string | undefined;
     env?: string | undefined;
     revision_id?: unknown;
+    file?: string | undefined;
 }[], {
     secret_id: string;
-    file?: string | undefined;
     env?: string | undefined;
     revision_id?: unknown;
+    file?: string | undefined;
 }[]>;
+/** The published ceiling on a value, in bytes of UTF-8. */
+export declare const SECRET_VALUE_MAX_BYTES = 4096;
+/** The published ceiling on a name, in characters. */
+export declare const SECRET_NAME_MAX_CHARS = 60;
+/** How many times set_secret reads the scope again after a conflict. */
+export declare const SECRET_SET_RETRIES = 3;
+/**
+ * The secret called `name` in a listing of one scope, or `undefined`: trimmed
+ * as the platform trims names, and ignoring ASCII case and nothing else, which
+ * is how it keeps them unique — `openai_api_key` is taken when `OPENAI_API_KEY` is.
+ */
+export declare function namedSecret(secrets: readonly Secret[], name: string): Secret | undefined;
+/**
+ * A tool result with every occurrence of a value taken out.
+ *
+ * The SECOND layer. The first is that no secret-store tool puts response text
+ * in its answer at all — see {@link storeGuarded} — and the Api keeps none for
+ * those routes. This catches what the first could still let through: a value
+ * that happens to equal a decoded field, or a message this server did not
+ * write. No length exemption: a one-character value is searched for too,
+ * which can mangle the sentence and is the price of never showing it. The
+ * JSON-escaped spelling is searched for as well, since data is shown as JSON.
+ */
+export declare function withoutValue(result: CallToolResult, value: string): CallToolResult;
 export declare const registerSecrets: Registrar;
 //# sourceMappingURL=secrets.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/tools/secrets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AAEH,sDAAsD;AACtD,eAAO,MAAM,SAAS,oCAAoC,CAAC;AAE3D,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAiBlC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;KA0DrD;AAyED,eAAO,MAAM,eAAe,EAAE,SA+E7B,CAAC"}
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/tools/secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAIL,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,sDAAsD;AACtD,eAAO,MAAM,SAAS,oCAAoC,CAAC;AAE3D,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAiBlC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;KA0DrD;AA0FD,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAiDxC,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIxF;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAclF;AAsED,eAAO,MAAM,eAAe,EAAE,SAqR7B,CAAC"}