mandala-computer-mcp 0.4.0 → 0.5.0

package/dist/tools/results.js.map

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

package/dist/tools/secrets.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+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`).
+ *
+ * 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.
+ *
+ * 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.
+ */
+/** Where a file binding is published in the guest. */
+export declare const FILES_DIR = "/run/mandala-secrets/user/files";
+/** At most this many secrets per computer, and this many of them as files. */
+export declare const SECRET_BINDINGS_MAX = 32;
+export declare const SECRET_FILES_MAX = 8;
+/**
+ * A binding list as the platform takes it, checked here for what it would
+ * refuse anyway — so the mistake is named against the entry that made it
+ * rather than coming back as a 400. `revision` adds the optional `revision_id`
+ * a rebind may send; a create has nothing to keep and takes none.
+ */
+export declare function secretBindingsSchema(revision: boolean): z.ZodEffects<z.ZodArray<z.ZodObject<{
+    revision_id?: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>> | undefined;
+    secret_id: z.ZodEffects<z.ZodString, string, string>;
+    env: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    secret_id: string;
+    file?: string | undefined;
+    env?: string | undefined;
+    revision_id?: unknown;
+}, {
+    secret_id: string;
+    file?: string | undefined;
+    env?: string | undefined;
+    revision_id?: unknown;
+}>, "many">, {
+    secret_id: string;
+    file?: string | undefined;
+    env?: string | undefined;
+    revision_id?: unknown;
+}[], {
+    secret_id: string;
+    file?: string | undefined;
+    env?: string | undefined;
+    revision_id?: unknown;
+}[]>;
+export declare const registerSecrets: Registrar;
+//# sourceMappingURL=secrets.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/secrets.js

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+import { guarded, refused, said } from '../format.js';
+import * as P from '../paths.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`).
+ *
+ * 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.
+ *
+ * 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.
+ */
+/** Where a file binding is published in the guest. */
+export const FILES_DIR = '/run/mandala-secrets/user/files';
+/** At most this many secrets per computer, and this many of them as files. */
+export const SECRET_BINDINGS_MAX = 32;
+export const SECRET_FILES_MAX = 8;
+const SECRET_ENV = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const SECRET_FILE = /^[a-z][a-z0-9_-]{0,47}$/;
+const ENV_RULE = 'letters, digits and underscores, not starting with a digit, at most 64 characters';
+const FILE_RULE = 'lowercase letters, digits, - and _, starting with a letter, at most 48 characters';
+/** An id as the platform spells one: not empty, and nothing around it. */
+const isId = (v) => typeof v === 'string' && v !== '' && v.trim() === v;
+const idString = (what) => z.string().refine(isId, `${what} must not be empty or have spaces around it`);
+/**
+ * A binding list as the platform takes it, checked here for what it would
+ * refuse anyway — so the mistake is named against the entry that made it
+ * rather than coming back as a 400. `revision` adds the optional `revision_id`
+ * a rebind may send; a create has nothing to keep and takes none.
+ */
+export function secretBindingsSchema(revision) {
+    // Strict: a key this tool does not take is refused, not dropped. A create
+    // that carried a `revision_id` would otherwise validate, bind the latest, and
+    // leave the caller believing it had chosen a revision.
+    const entry = z.strictObject({
+        secret_id: idString('secret_id').describe('The secret to bind — `csec-` and sixteen hex.'),
+        env: z
+            .string()
+            .regex(SECRET_ENV, `env must be ${ENV_RULE}`)
+            .optional()
+            .describe(`Deliver it as this environment variable in the desktop session: ${ENV_RULE}. Exactly one of env and file.`),
+        file: z
+            .string()
+            .regex(SECRET_FILE, `file must be ${FILE_RULE}`)
+            .optional()
+            .describe(`Deliver it as the file ${FILES_DIR}/<file>, for a program that reads a path (a kubeconfig, a key): ${FILE_RULE}. May hold any bytes. Exactly one of env and file.`),
+        ...(revision
+            ? {
+                revision_id: idString('revision_id')
+                    .optional()
+                    .describe('Omit to record the latest revision. Name the one the computer holds now to keep it: a revision is what the computer last received, not a pin, and every start or restart delivers the latest value regardless.'),
+            }
+            : {}),
+    });
+    return z
+        .array(entry)
+        .max(SECRET_BINDINGS_MAX, `at most ${SECRET_BINDINGS_MAX} secrets per computer`)
+        .superRefine((list, ctx) => {
+        const ids = new Set();
+        const envs = new Set();
+        const files = new Set();
+        list.forEach((b, i) => {
+            const at = (message) => ctx.addIssue({ code: 'custom', path: [i], message });
+            if ((b.env === undefined) === (b.file === undefined)) {
+                at(`secrets[${i}] must name exactly one of env and file`);
+            }
+            if (ids.has(b.secret_id))
+                at(`secrets[${i}]: ${b.secret_id} is bound twice`);
+            ids.add(b.secret_id);
+            // Two namespaces: a variable and a file may share a spelling.
+            if (b.env !== undefined) {
+                if (envs.has(b.env))
+                    at(`secrets[${i}].env ${b.env} is bound twice`);
+                envs.add(b.env);
+            }
+            if (b.file !== undefined) {
+                if (files.has(b.file))
+                    at(`secrets[${i}].file ${b.file} is bound twice`);
+                files.add(b.file);
+            }
+        });
+        if (files.size > SECRET_FILES_MAX) {
+            ctx.addIssue({ code: 'custom', message: `at most ${SECRET_FILES_MAX} secrets as files` });
+        }
+    });
+}
+const idArg = {
+    computer_id: z
+        .string()
+        .optional()
+        .describe('Which computer. Defaults to the one selected with use_computer.'),
+};
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const shapeOf = (v) => v === undefined ? 'no body at all' : v === null ? 'null' : Array.isArray(v) ? 'a list' : typeof v;
+function bindingsOf(body) {
+    if (!isRecord(body))
+        return undefined;
+    const { secrets, version } = body;
+    if (!Array.isArray(secrets))
+        return undefined;
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 0)
+        return undefined;
+    const out = [];
+    for (const entry of secrets) {
+        if (!isRecord(entry))
+            return undefined;
+        const { secret_id, revision_id, env, file } = entry;
+        if (!isId(secret_id) || !isId(revision_id))
+            return undefined;
+        // Exactly one, spelled as the platform would accept it. Null reads as
+        // absent; anything else present — an empty string included — counts, so a
+        // row naming both or neither is refused rather than guessed at.
+        const hasEnv = env !== undefined && env !== null;
+        const hasFile = file !== undefined && file !== null;
+        if (hasEnv === hasFile)
+            return undefined;
+        if (hasEnv) {
+            if (typeof env !== 'string' || !SECRET_ENV.test(env))
+                return undefined;
+            out.push({ secret_id, revision_id, env });
+        }
+        else {
+            if (typeof file !== 'string' || !SECRET_FILE.test(file))
+                return undefined;
+            out.push({ secret_id, revision_id, file });
+        }
+    }
+    return { secrets: out, version };
+}
+/**
+ * One binding in a line: where the guest finds it — a variable name, or a file's
+ * full path — then what it is bound to.
+ */
+const bindingLine = (b) => `${b.env ?? `${FILES_DIR}/${b.file}`} = ${b.secret_id} @ ${b.revision_id}`;
+const LEGEND = 'variable or file = secret @ revision, values never shown';
+/** The bindings, one per line. Callers say "none" themselves for an empty list. */
+function listing(b) {
+    return `\n${b.secrets.map(bindingLine).join('\n')}`;
+}
+const TIMING = 'The new bindings reach the guest at its NEXT START OR RESTART: a running computer keeps what it booted with until then, and a suspended one resumes with its old values.';
+/** What reaches a running computer without a restart: a replaced value, as a file. */
+const LIVE_FILES = "Every start and restart delivers each secret's latest value. Separately, when a secret's value is replaced, a running computer bound to it as a file has that file rewritten within seconds; a variable waits for the next start or restart.";
+export const registerSecrets = (server, session) => {
+    server.registerTool('get_computer_secrets', {
+        title: "Read a computer's secret bindings",
+        description: `Which of the account's secrets a computer is bound to: for each, the secret id, the revision last delivered, and where the guest finds it — an environment variable name, or a file under ${FILES_DIR}. Values are NEVER shown — no value crosses this route. Also answers \`version\`, the number to send to set_computer_secrets so it changes only this list (0 for a computer never bound). Any role may read it. The list is what the computer receives at its next start or restart, which a running computer may not have yet. ${LIVE_FILES}`,
+        inputSchema: idArg,
+        annotations: { readOnlyHint: true },
+    }, ({ computer_id }, extra) => guarded(async () => {
+        const id = session.resolve(computer_id);
+        const body = await session.api
+            .with(extra.signal)
+            .json('GET', P.computerAction(id, 'secrets'));
+        const bindings = bindingsOf(body);
+        if (!bindings) {
+            return refused(`GET /computers/${id}/secrets answered with ${shapeOf(body)}, not a list of secret bindings. This does not mean the computer has none.`, body);
+        }
+        if (!bindings.secrets.length) {
+            return said(`${id} is bound to no secrets (version ${bindings.version}). set_computer_secrets binds some.`, body);
+        }
+        const n = bindings.secrets.length;
+        return said(`${id} is bound to ${n} secret${n === 1 ? '' : 's'} (version ${bindings.version}; ${LEGEND}):${listing(bindings)}`, body);
+    }));
+    server.registerTool('set_computer_secrets', {
+        title: "Replace a computer's secret bindings",
+        description: `Replace the WHOLE list of secrets a computer is bound to — not a merge: any binding left out is removed, and \`secrets: []\` removes every binding. Each entry names a secret id and exactly one of \`env\` (the environment variable it is delivered under) or \`file\` (delivered as ${FILES_DIR}/<file>) — at most ${SECRET_BINDINGS_MAX} secrets, ${SECRET_FILES_MAX} of them as files, none twice and no variable or file name twice — and is recorded at that secret's latest revision unless it names \`revision_id\`, which must be the revision the computer holds now (any other revision is refused). A binding's revision is what the computer last received, never a pin: naming it only says this change keeps the value the running computer already has, so the change does not stop it being suspended. Only ids, revisions and names are sent and answered — values are NEVER shown or set here. ${TIMING} ${LIVE_FILES} Binding a computer that has NO secrets yet requires it to be STOPPED: that first binding is refused with 409 while the computer is running or suspended, because a computer started without secrets cannot receive them until it starts again, and a restart does not do that. Start it afterwards to deliver them. Send \`version\` from get_computer_secrets to change only the list you read: if it changed since, this is refused with 409 and nothing changes. Also 409 while a delivery to the computer is in progress. After a change that drops a secret or moves one to another revision, a running computer cannot be suspended or memory-snapshotted until it restarts. Owners and members only; Linux computers only, and binding one for the first time needs a template whose image can receive secrets.`,
+        inputSchema: {
+            ...idArg,
+            secrets: secretBindingsSchema(true).describe('The complete new list. Every binding not in it is removed; [] removes them all.'),
+            version: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe('The `version` a read answered. Sent, the change is refused (409) if the list changed since; omitted, it replaces whatever is there.'),
+        },
+        annotations: { destructiveHint: true },
+    }, ({ computer_id, secrets, version }, extra) => guarded(async () => {
+        const id = session.resolve(computer_id);
+        const body = await session.api
+            .with(extra.signal)
+            .json('PUT', P.computerAction(id, 'secrets'), {
+            body: { secrets, ...(version === undefined ? {} : { version }) },
+        });
+        const bindings = bindingsOf(body);
+        if (!bindings) {
+            return refused(`PUT /computers/${id}/secrets answered with ${shapeOf(body)}, not a list of secret bindings. THE CHANGE MAY HAVE BEEN MADE — get_computer_secrets says what the computer is bound to now.`, body);
+        }
+        const n = bindings.secrets.length;
+        const what = n
+            ? `${id} is now bound to ${n} secret${n === 1 ? '' : 's'} (version ${bindings.version}; ${LEGEND}):${listing(bindings)}`
+            : `${id} is now bound to no secrets (version ${bindings.version}).`;
+        return said(`${what}\n${TIMING} ${LIVE_FILES}`, body);
+    }));
+};
+//# sourceMappingURL=secrets.js.map

package/dist/tools/secrets.js.map

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

package/dist/tools/signals.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/tools/signals.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA0E5C,eAAO,MAAM,eAAe,EAAE,SAqD7B,CAAC"}

package/dist/tools/signals.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { said } from '../format.js';
+import * as P from '../paths.js';
+import { count, executionId, exitCode, label, metadata, metadataCall } from './directory.js';
+import { computerSchema, readAnnotations } from './results.js';
+const position = {
+    seq: count,
+    cursor: label,
+    at: label,
+    computer: label,
+    source: z.literal('daemon'),
+};
+const status = z.enum([
+    'running',
+    'stopped',
+    'suspended',
+    'building',
+    'build-failed',
+    'half-removed',
+]);
+const processData = z.union([
+    z.object({
+        pid: count.min(1).max(2147483647),
+        execution_id: executionId.optional(),
+        exit_code: exitCode,
+        lost: z.never().optional(),
+    }),
+    z.object({
+        pid: count.min(1).max(2147483647),
+        execution_id: executionId.optional(),
+        lost: z.literal(true),
+        exit_code: z.never().optional(),
+    }),
+]);
+const event = z.discriminatedUnion('type', [
+    z.object({ ...position, type: z.literal('process.exited'), data: processData }),
+    z.object({
+        ...position,
+        type: z.literal('computer.started'),
+        data: z.object({ status: z.literal('running'), previous: status.optional() }),
+    }),
+    z.object({
+        ...position,
+        type: z.literal('computer.stopped'),
+        data: z.object({ status: z.literal('stopped'), previous: status.optional() }),
+    }),
+    z.object({
+        ...position,
+        type: z.literal('computer.suspended'),
+        data: z.object({ status: z.literal('suspended'), previous: status.optional() }),
+    }),
+    z.object({
+        ...position,
+        type: z.literal('computer.idle'),
+        data: z.object({ idle_seconds: count }),
+    }),
+]);
+const page = z.object({
+    computer: label,
+    from: z.string(),
+    cursor: label,
+    events: z.array(event).max(100),
+    more: z.boolean(),
+    baseline: z.boolean(),
+    gap: z
+        .object({
+        cursor: label,
+        at: label,
+        type: z.literal('gap'),
+        computer: label,
+        source: z.literal('daemon'),
+        data: z.object({ oldest_cursor: label.optional(), detail: label }),
+    })
+        .optional(),
+    supported: z.array(label),
+    retention: z.literal('ephemeral'),
+});
+export const registerSignals = (server, session) => {
+    server.registerTool('read_signals', {
+        title: 'Read one passive platform signal page',
+        description: 'Read finite daemon facts without waking the computer, guest contact, event socket, watcher, capture or polling loop. Omit since or send empty for a head-only baseline with no replay; neither a baseline nor gap proves no earlier activity or task success. Keep the returned cursor even on an empty page: filtered-out rows can advance it. Retention is ephemeral, and resets are explicit gaps.',
+        inputSchema: {
+            computer_id: computerSchema,
+            since: z.string().max(2048).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readAnnotations,
+    }, ({ computer_id, since, limit }, extra) => metadataCall(async () => {
+        const id = session.resolve(computer_id);
+        const data = metadata(page, await session.api.json('GET', P.signals(id), {
+            query: { since, limit },
+            signal: extra.signal,
+        }));
+        // Compare opaque checkpoints without parsing or deriving a next cursor.
+        // Baselines and explicit resets describe one head; replay starts at since.
+        // Events must advance; the next cursor may also pass filtered rows.
+        const checkpoints = new Set([data.from, ...data.events.map((e) => e.cursor)]);
+        if (data.computer !== id ||
+            data.events.some((e, i) => e.computer !== id || (i > 0 && e.seq <= data.events[i - 1].seq)) ||
+            checkpoints.size !== data.events.length + 1 ||
+            (data.events.length > 0 &&
+                data.cursor !== data.events.at(-1)?.cursor &&
+                checkpoints.has(data.cursor)) ||
+            data.baseline !== (since === undefined || since === '') ||
+            (data.baseline && data.gap) ||
+            (data.gap && (data.gap.computer !== id || data.gap.cursor !== data.cursor)) ||
+            ((data.baseline || data.gap) &&
+                (data.events.length || data.more || data.from !== data.cursor)) ||
+            (!data.baseline && !data.gap && data.from !== since) ||
+            (data.more && !data.events.length) ||
+            data.events.length > (limit ?? 50))
+            throw new Error('Inconsistent signal page; no checkpoint was established.');
+        return said(`${data.gap ? 'GAP: the checkpoint was reset. ' : ''}${data.baseline ? 'Head-only baseline; no historical replay. ' : ''}One ephemeral page; use the returned cursor, including after an empty page. These facts do not establish task success.`, data);
+    }));
+};
+//# sourceMappingURL=signals.js.map

package/dist/tools/signals.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../src/tools/snapshots.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4M5C,eAAO,MAAM,iBAAiB,EAAE,SAkyB/B,CAAC"}
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../src/tools/snapshots.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4M5C,eAAO,MAAM,iBAAiB,EAAE,SA40B/B,CAAC"}

package/dist/tools/snapshots.js

@@ -291,7 +291,7 @@ export const registerSnapshots = (server, session, opts) => {
             memory: z
                 .boolean()
                 .default(false)
-                .describe('Include the running session. A memory snapshot is a saved machine, so it only loads back into the shape it came off: resize the computer afterwards and the restore is refused, because the vCPU count and the memory size are part of the state rather than decoration around it. Clone it instead in that case, which restores the disk and boots fresh.'),
+                .describe('Include the running session. A memory snapshot is a saved machine, so it only loads back into the shape it came off: resize the computer afterwards and the restore is refused, because the vCPU count and the memory size are part of the state rather than decoration around it. Clone it with memory: false instead in that case, which restores the disk and boots fresh.'),
             wait: z
                 .boolean()
                 .default(true)
@@ -599,27 +599,63 @@ export const registerSnapshots = (server, session, opts) => {
         return;
     server.registerTool('clone_snapshot', {
         title: 'Fork a snapshot into a new computer',
-        description: 'Build a new computer from a snapshot, leaving the original untouched. This is the fork half of snapshot-and-fork, and the only thing that works on an orphaned snapshot.',
+        description: "Build a new computer from a snapshot, leaving the original untouched. This is the fork half of snapshot-and-fork, and the only thing that works on an orphaned snapshot. A MEMORY snapshot is resumed: the copy comes up running the captured session, sharing its source's network identity, so it cannot run on the same host while its source is running. Pass memory: false to build it from the disk alone instead, as a fresh boot with its own identity. A memory snapshot of a computer that held SECRETS is resumed only with inherit_secrets: true, and then the copy HOLDS THE SAME CREDENTIALS as the computer it came from; without it the clone is built from the disk and this tool says so.",
         inputSchema: {
             snapshot_id: z.string(),
             name: z.string().optional().describe('A name for the new computer.'),
+            memory: z
+                .boolean()
+                .optional()
+                .describe('Memory snapshots only. false builds the new computer from the disk alone and boots it fresh; omitted or true resumes the captured session.'),
+            inherit_secrets: z
+                .boolean()
+                .optional()
+                .describe('Consent to resuming a memory snapshot of a computer that held secrets. The new computer holds the same credentials, bound to the same secrets. Only set this when that is what the user asked for.'),
             select: z
                 .boolean()
                 .default(true)
                 .describe("Make the new computer this session's selected one."),
         },
-    }, ({ snapshot_id, name, select }, extra) => guarded(async () => {
-        const c = unwrapComputer(await session.api
+    }, ({ snapshot_id, name, select, memory, inherit_secrets }, extra) => guarded(async () => {
+        // Each option only when set, so an ordinary clone sends what it always
+        // did; consent is sent only when given, since its absence is the default.
+        const body = {};
+        if (name !== undefined)
+            body.name = name;
+        if (memory !== undefined)
+            body.memory = memory;
+        if (inherit_secrets === true)
+            body.inherit_secrets = true;
+        const answer = await session.api
             .with(extra.signal)
-            .json('POST', P.snapshotAction(snapshot_id, 'clone'), {
-            body: name === undefined ? {} : { name },
-        }));
+            .json('POST', P.snapshotAction(snapshot_id, 'clone'), { body });
+        const c = unwrapComputer(answer);
         if (!c.id) {
             return refused(`The platform accepted the clone of ${snapshot_id} but sent no computer id back, so the copy cannot be identified. It may exist and be billable — list_computers will say. The selected computer is unchanged.`, withoutCredentials(c));
         }
         if (select && c.id)
             session.bind(c.id, c.resolution);
-        return said(`Forked ${snapshot_id} into ${describe(c)}${select && c.id ? ', and selected it' : ''}.`, withoutCredentials(c));
+        // The platform built it from the disk when the session could not come
+        // across (platform OPL-4964). Said first and in words, because a model
+        // that asked for a live fork and got a fresh boot would otherwise go on
+        // as if the session — its open windows, its running programs — were
+        // there.
+        //
+        // Read off the ANSWER as well as the computer: the platform sends the
+        // two fields beside the computer's own, flat, and unwrapComputer keeps
+        // only start_error from an envelope — so a future envelope carrying
+        // them would otherwise report a live fork for a fresh boot.
+        const outer = (answer && typeof answer === 'object' ? answer : {});
+        const raw = { ...c, ...outer };
+        if (raw.memory_dropped === true) {
+            const why = raw.memory_dropped_reason === 'bindings unrecorded'
+                ? "it was taken before copies could be given its computer's secrets"
+                : raw.memory_dropped_reason === 'secrets'
+                    ? 'its computer held secrets and inherit_secrets was not set'
+                    : 'the platform did not resume it';
+            return said(`Built ${describe(c)} from ${snapshot_id}'s DISK, booting fresh — its saved session was NOT resumed, because ${why}. No secrets are bound to it${select && c.id ? '. It is selected' : ''}.`, withoutCredentials(c));
+        }
+        return said(`${memory === false ? 'Built' : 'Forked'} ${snapshot_id} into ${describe(c)}${memory === false ? ' from its disk' : ''}${select && c.id ? ', and selected it' : ''}.`, withoutCredentials(c));
     }));
     server.registerTool('delete_snapshot', {
         title: 'Delete a snapshot',