@clawscarf/cli 0.1.0-alpha.1

package/scripts/installation/options.js

@@ -0,0 +1,360 @@
+import { Option } from "commander";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { installationSchema } from "./configuration.js";
+import { cloudUrlSchema } from "../cloud/url.js";
+import { recipeConfiguration, recipeModelFile, } from "./setup.js";
+import { readInputFile } from "./files.js";
+import { InstallationError } from "./errors.js";
+import { configurationSchema, gatewayRoutesSchema, } from "../models/configuration.js";
+import { selectModel } from "./models.js";
+import { openPack } from "../packs/source.js";
+const file = z
+    .string()
+    .min(1)
+    .transform((value) => resolve(value));
+const port = z.coerce.number().int().min(1024).max(65535);
+const text = z.string().min(1);
+/** Public selections only; internal paths and bootstrap state are never CLI overrides. */
+export const selectionSchema = z.object({
+    name: installationSchema.shape.name.optional(),
+    administratorName: text.optional(),
+    port: port.optional(),
+    widgetPort: port.optional(),
+    origin: cloudUrlSchema.optional(),
+    widgetOrigin: cloudUrlSchema.optional(),
+    tlsCertificate: file.optional(),
+    tlsKeyFile: file.optional(),
+    access: z.enum(["hosted", "oidc"]).optional(),
+    oidcIssuer: z.url().optional(),
+    oidcClientId: text.optional(),
+    oidcSecretFile: file.optional(),
+    administratorSubject: text.optional(),
+    administratorEmail: z.email().optional(),
+    cpu: installationSchema.shape.resources.shape.runtime.shape.cpu.optional(),
+    memory: installationSchema.shape.resources.shape.runtime.shape.memory.optional(),
+    connections: z.boolean().optional(),
+    connectionsCloudUrl: cloudUrlSchema.optional(),
+    browser: z.boolean().optional(),
+    model: text.optional(),
+    provider: text.optional(),
+    reasoning: z.enum(["low", "medium", "high"]).optional(),
+    llmKeyFile: file.optional(),
+    providerEnvFile: file.optional(),
+    modelCatalog: file.optional(),
+    modelGatewayUrl: z.url().optional(),
+    modelGatewayKeyFile: file.optional(),
+    modelGatewayCaFile: file.optional(),
+    pack: z.array(text).optional(),
+    packs: z
+        .literal(false)
+        .nullish()
+        .transform((value) => value ?? undefined),
+    packBindings: z.array(text).optional(),
+    packPython: file.optional(),
+});
+export function installationOptions(command) {
+    return command
+        .option("--name <name>", "Installation name")
+        .option("--administrator-name <name>", "First administrator display name")
+        .option("--port <number>", "Local application port (default: 18800)")
+        .option("--widget-port <number>", "Local widgets port (default: 18802)")
+        .option("--origin <url>", "Public HTTPS application origin")
+        .option("--widget-origin <url>", "Public HTTPS widgets origin")
+        .option("--tls-certificate <file>", "HTTPS certificate")
+        .option("--tls-key-file <file>", "Private HTTPS key file")
+        .addOption(new Option("--access <mode>", "Login provider").choices([
+        "hosted",
+        "oidc",
+    ]))
+        .option("--oidc-issuer <url>", "Company OIDC issuer")
+        .option("--oidc-client-id <id>", "Company OIDC client ID")
+        .option("--oidc-secret-file <file>", "Private company OIDC client secret")
+        .option("--administrator-subject <subject>", "First administrator OIDC subject (for unattended setup)")
+        .option("--administrator-email <email>", "First administrator email (with --administrator-subject)")
+        .option("--cpu <count>", "Runtime CPU allocation")
+        .option("--memory <size>", "Runtime memory, for example 4Gi")
+        .option("--connections", "Enable Connections")
+        .option("--no-connections", "Disable Connections")
+        .option("--connections-cloud-url <url>", "Use a separate Connections service")
+        .option("--browser", "Enable experimental browser capability")
+        .option("--no-browser", "Disable browser capability")
+        .option("--model <id>", "Default model from the model catalog")
+        .option("--provider <id>", "Model provider, for example openai or openrouter")
+        .addOption(new Option("--reasoning <level>", "Model reasoning level").choices([
+        "low",
+        "medium",
+        "high",
+    ]))
+        .option("--llm-key-file <file>", "Private file containing the selected provider's API key")
+        .option("--provider-env-file <file>", "Private provider credentials file for multiple model routes")
+        .option("--model-catalog <file>", "Advanced: import a model catalog")
+        .option("--model-gateway-url <url>", "Advanced: existing LiteLLM endpoint ending in /v1")
+        .option("--model-gateway-key-file <file>", "Private key for an existing LiteLLM gateway")
+        .option("--model-gateway-ca-file <file>", "Private CA for an existing LiteLLM gateway")
+        .option("--pack <id:members>", "Select bundled pack members; repeat for multiple packs", append)
+        .addOption(new Option("--no-packs", "Remove all recipe pack selections").default(null))
+        .option("--pack-bindings <id=file>", "Account bindings for a selected pack; repeat as needed", append)
+        .option("--pack-python <file>", "Python with the pinned OpenShell SDK for experimental packs");
+}
+function append(value, previous = []) {
+    return [...previous, value];
+}
+function invalid(message) {
+    throw new InstallationError("invalid_configuration", message);
+}
+export async function selectedDraft(context, recipe, selections, inputs, retained) {
+    const o = selectionSchema.parse(selections);
+    if (retained) {
+        const mutable = new Set([
+            "model",
+            "provider",
+            "reasoning",
+            "llmKeyFile",
+            "providerEnvFile",
+            "modelCatalog",
+            "modelGatewayKeyFile",
+            "modelGatewayCaFile",
+            "connections",
+            "connectionsCloudUrl",
+            "pack",
+            "packs",
+            "packBindings",
+            "packPython",
+        ]);
+        if (Object.entries(o).some(([key, value]) => value !== undefined && !mutable.has(key)))
+            invalid("Existing installations support changes to models, keys, Connections and packs only.");
+    }
+    const config = structuredClone(retained ?? recipeConfiguration(context, recipe));
+    if (o.name !== undefined)
+        config.name = o.name;
+    if (o.administratorName !== undefined)
+        config.access.administratorName = o.administratorName;
+    if (o.cpu !== undefined)
+        config.resources.runtime.cpu = o.cpu;
+    if (o.memory !== undefined)
+        config.resources.runtime.memory = o.memory;
+    if (o.browser !== undefined)
+        config.browser.enabled = o.browser;
+    if (o.connections !== undefined)
+        config.connections.mode = o.connections ? "hosted" : "disabled";
+    if (o.connectionsCloudUrl)
+        config.connections.cloudUrl = o.connectionsCloudUrl;
+    const https = o.origin || o.widgetOrigin || o.tlsCertificate || o.tlsKeyFile;
+    if (https) {
+        if (o.port !== undefined || o.widgetPort !== undefined)
+            invalid("Use local ports or HTTPS origins, not both.");
+        if (!o.origin || !o.widgetOrigin || !o.tlsCertificate)
+            invalid("HTTPS requires --origin, --widget-origin and --tls-certificate.");
+        if (!o.origin.startsWith("https:") || !o.widgetOrigin.startsWith("https:"))
+            invalid("Public origins must use HTTPS.");
+        config.exposure = {
+            mode: "https",
+            applicationOrigin: o.origin,
+            widgetOrigin: o.widgetOrigin,
+            certificateFile: o.tlsCertificate,
+            keyFile: o.tlsKeyFile ?? "",
+        };
+    }
+    else if (config.exposure.mode === "local") {
+        config.exposure.applicationPort = o.port ?? config.exposure.applicationPort;
+        config.exposure.widgetPort = o.widgetPort ?? config.exposure.widgetPort;
+        if (config.exposure.applicationPort === config.exposure.widgetPort)
+            invalid("Application and widgets must use different ports.");
+    }
+    const oidc = o.oidcIssuer || o.oidcClientId || o.oidcSecretFile;
+    if (oidc || o.access === "oidc") {
+        if (o.access === "hosted")
+            invalid("Company OIDC options conflict with --access hosted.");
+        if (!o.oidcIssuer || !o.oidcClientId)
+            invalid("Company login requires --oidc-issuer and --oidc-client-id.");
+        config.access = {
+            mode: "oidc",
+            administratorName: config.access.administratorName,
+            issuer: o.oidcIssuer,
+            clientId: o.oidcClientId,
+            clientSecretFile: o.oidcSecretFile ?? "",
+        };
+    }
+    if (Boolean(o.administratorSubject) !== Boolean(o.administratorEmail))
+        invalid("Supply both --administrator-subject and --administrator-email.");
+    if (o.administratorSubject && o.administratorEmail) {
+        config.access.administratorSubject = o.administratorSubject;
+        config.access.administratorEmail = o.administratorEmail;
+    }
+    if (o.pack && o.packs === false)
+        invalid("Use --pack or --no-packs, not both.");
+    if (o.packs === false)
+        config.packs = [];
+    if (o.pack) {
+        config.packs = [];
+        for (const choice of o.pack) {
+            const [id, members, extra] = choice.split(":");
+            if (!id ||
+                !members ||
+                extra !== undefined ||
+                !context.packs.some((pack) => pack.id === id))
+                invalid("Use --pack <pack-id:member,member>; list available packs with clawscarf recipes.");
+            const directory = context.packs.find((pack) => pack.id === id)?.directory;
+            if (!directory)
+                invalid(`Unknown pack: ${id}`);
+            const pack = await openPack(directory);
+            const selected = members.split(",");
+            if (config.packs.some((item) => item.directory === directory) ||
+                new Set(selected).size !== selected.length ||
+                selected.some((member) => !pack.manifest.members.some((item) => item.id === member)))
+                invalid("Select each pack once and use its declared member IDs.");
+            config.packs.push({ directory, members: selected });
+        }
+    }
+    for (const binding of o.packBindings ?? []) {
+        const separator = binding.indexOf("=");
+        const id = binding.slice(0, separator), path = binding.slice(separator + 1);
+        const selected = config.packs.find((pack) => pack.directory ===
+            context.packs.find((pack) => pack.id === id)?.directory);
+        if (separator < 1 || !path || !selected)
+            invalid("Use --pack-bindings <selected-pack-id=file>.");
+        selected.bindingsFile = resolve(path);
+    }
+    if (o.packPython && !config.packs.length)
+        invalid("--pack-python requires a selected pack.");
+    if (!config.packs.length)
+        delete config.packOperator;
+    else if (o.packPython)
+        config.packOperator = {
+            pythonExecutable: o.packPython,
+            experimentalClaws: true,
+        };
+    const preset = context.recipes.find((item) => item.id === recipe)?.models;
+    if (!config.models && preset)
+        config.models = {
+            mode: "litellm",
+            configurationFile: recipeModelFile(preset, inputs, context.modelCatalog),
+            upstreamEnvironmentFile: "",
+        };
+    if (o.modelCatalog)
+        config.models =
+            config.models?.mode === "external"
+                ? { ...config.models, configurationFile: o.modelCatalog }
+                : {
+                    mode: "litellm",
+                    configurationFile: o.modelCatalog,
+                    upstreamEnvironmentFile: "",
+                };
+    const current = config.models;
+    const catalog = current
+        ? await inputs.readJson(current.configurationFile)
+        : undefined;
+    if (o.modelGatewayUrl) {
+        if (!catalog)
+            invalid("An existing gateway requires a recipe model or --model-catalog.");
+        const parsed = z
+            .union([gatewayRoutesSchema, configurationSchema])
+            .parse(catalog);
+        if ("mode" in parsed && parsed.mode === "disabled")
+            invalid("The model gateway must be enabled.");
+        config.models = {
+            mode: "external",
+            configurationFile: inputs.set("external-models.json", JSON.stringify(configurationSchema.parse({
+                ...parsed,
+                mode: "external",
+                baseUrl: o.modelGatewayUrl,
+            }))),
+            credentialFile: o.modelGatewayKeyFile ?? "",
+            ...(o.modelGatewayCaFile ? { caFile: o.modelGatewayCaFile } : {}),
+        };
+    }
+    else if (o.modelGatewayKeyFile || o.modelGatewayCaFile) {
+        if (config.models?.mode !== "external")
+            invalid("Gateway credentials require --model-gateway-url.");
+        if (o.modelGatewayKeyFile)
+            config.models.credentialFile = o.modelGatewayKeyFile;
+        if (o.modelGatewayCaFile)
+            config.models.caFile = o.modelGatewayCaFile;
+    }
+    if (o.model || o.provider || o.reasoning) {
+        if (config.models?.mode === "external") {
+            if (o.provider)
+                invalid("Providers for an existing gateway are configured by its operator.");
+            const parsed = configurationSchema.parse(await inputs.readJson(config.models.configurationFile));
+            if (parsed.mode !== "external")
+                invalid("Expected an external model gateway.");
+            const id = o.model ?? parsed.defaultModel;
+            const model = parsed.models.find((item) => item.id === id && item.enabled);
+            if (!model)
+                invalid("Select an enabled model from the gateway catalog.");
+            if (o.reasoning && !model.reasoning)
+                invalid("This model does not support reasoning levels.");
+            const { thinkingDefault: previous, ...base } = parsed;
+            config.models.configurationFile = inputs.set("external-models.json", JSON.stringify({
+                ...base,
+                defaultModel: id,
+                ...(model.reasoning && (o.reasoning ?? previous)
+                    ? { thinkingDefault: o.reasoning ?? previous }
+                    : {}),
+            }));
+        }
+        else {
+            const routes = catalog ? gatewayRoutesSchema.parse(catalog) : undefined;
+            const id = o.model ?? routes?.defaultModel;
+            if (!id)
+                invalid("Select --model before choosing a provider or reasoning level.");
+            const existing = routes?.models.find((item) => item.id === id);
+            const offers = [...context.modelCatalog];
+            if (existing?.route &&
+                !offers.some((offer) => offer.model.id === id &&
+                    offer.model.route.model === existing.route?.model))
+                offers.unshift({
+                    provider: existing.route.model.split("/")[0] ?? "",
+                    model: { ...existing, route: existing.route },
+                    reasoningLevels: existing.reasoning ? ["low", "medium", "high"] : [],
+                });
+            const matching = offers.filter((offer) => offer.model.id === id &&
+                (!o.provider || offer.model.route.model.split("/")[0] === o.provider));
+            const offer = matching.find((item) => item.model.route.model === existing?.route?.model) ?? matching[0];
+            if (!offer)
+                invalid("Unknown model/provider selection. Use clawscarf recipes to see the model catalog.");
+            if (o.reasoning && !offer.reasoningLevels.includes(o.reasoning))
+                invalid("The selected model/provider does not support this reasoning level.");
+            const thinking = o.reasoning ??
+                (routes?.thinkingDefault &&
+                    offer.reasoningLevels.includes(routes.thinkingDefault)
+                    ? routes.thinkingDefault
+                    : offer.reasoningLevels.includes("medium")
+                        ? "medium"
+                        : offer.reasoningLevels[0]);
+            config.models = selectModel(current, routes, offer, thinking, inputs, Boolean(retained));
+        }
+    }
+    if (o.llmKeyFile && o.providerEnvFile)
+        invalid("Use --llm-key-file or --provider-env-file, not both.");
+    if (config.models?.mode === "external" && (o.llmKeyFile || o.providerEnvFile))
+        invalid("Use --model-gateway-key-file for an existing gateway.");
+    if (!config.models && (o.llmKeyFile || o.providerEnvFile))
+        invalid("Select a recipe model or --model before supplying credentials.");
+    if (config.models?.mode === "litellm") {
+        if (o.providerEnvFile)
+            config.models.upstreamEnvironmentFile = o.providerEnvFile;
+        if (o.llmKeyFile) {
+            const routes = gatewayRoutesSchema.parse(await inputs.readJson(config.models.configurationFile));
+            const variables = new Set(routes.models
+                .filter((model) => model.enabled)
+                .map((model) => model.route?.apiKeyEnv));
+            const [variable] = variables;
+            if (variables.size !== 1 || !variable)
+                invalid("Multiple provider keys require --provider-env-file.");
+            const key = (await readInputFile(o.llmKeyFile, true))
+                .toString("utf8")
+                .trim();
+            if (!key || /[\r\n'"`]/.test(key))
+                invalid("The LLM key file must contain one nonempty key without quotes.");
+            config.models.upstreamEnvironmentFile = inputs.set("models.env", `${variable}='${key}'\n`);
+        }
+    }
+    if (!retained) {
+        if (config.access.mode === "hosted")
+            config.access.registrationFile = resolve(inputs.directory, "secrets/hosted-login.json");
+        config.connections.registrationFile = resolve(inputs.directory, "secrets/connections-registration.json");
+    }
+    return config;
+}

package/scripts/installation/packs.js

@@ -0,0 +1,150 @@
+import { OperatorError } from "../errors.js";
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { openPack } from "../packs/source.js";
+import { planPack, applyPack } from "../packs/lifecycle.js";
+import { planSchema } from "../packs/model.js";
+import { OpenShellClaws } from "../packs/openshell.js";
+import { readState, resourceNames, writePrivate } from "../deployment/state.js";
+import { fingerprint, readJson } from "./files.js";
+export const selectionSchema = z.strictObject({
+    python: z.string().optional(),
+    packs: z.array(z.strictObject({
+        directory: z.string(),
+        digest: z.string(),
+        members: z.array(z.string()),
+        bindingsFile: z.string().optional(),
+        bindingsDigest: z.string().optional(),
+    })),
+});
+export const packOutcomeSchema = z.strictObject({
+    member: z.string(),
+    state: z.enum(["complete", "blocked", "unconfirmed"]),
+});
+/** Called within the installation's existing lifecycle lock, before readiness is announced. */
+export async function activatePacks(directory, report, target) {
+    const selection = selectionSchema.parse(await readJson(join(directory, "packs.json")));
+    const receipts = join(directory, "pack-operations");
+    await mkdir(receipts, { recursive: true, mode: 0o700 });
+    const files = (await readdir(receipts)).filter((file) => file.endsWith(".json") && !file.endsWith("-plan.json"));
+    if (!selection.packs.length && !files.length)
+        return [];
+    if (!selection.python)
+        throw new OperatorError("Pack operator is required while removing retained packs.");
+    const state = await readState(directory);
+    const controller = join(directory, "controller");
+    const gateway = resourceNames(state).sandbox;
+    const native = target ??
+        new OpenShellClaws({
+            executable: state.input.openshellCli,
+            python: selection.python,
+            sandbox: gateway,
+            gateway,
+            env: {
+                ...process.env,
+                OPENCLAW_EXPERIMENTAL_CLAWS: "1",
+                XDG_CONFIG_HOME: join(controller, "config"),
+                XDG_STATE_HOME: join(controller, "state"),
+                XDG_DATA_HOME: join(controller, "data"),
+            },
+        });
+    const operations = selection.packs.flatMap((pack) => pack.members.map((member) => ({ pack, member, remove: false })));
+    const selected = new Set(operations.map((item) => item.member));
+    for (const file of files) {
+        const member = file.slice(0, -5);
+        if (selected.has(member))
+            continue;
+        const previous = planSchema.parse(await readJson(join(receipts, member + "-plan.json")));
+        if (previous.member !== member)
+            throw new OperatorError("Pack receipt identity changed.");
+        operations.push({
+            member,
+            remove: true,
+            pack: {
+                directory: previous.pack,
+                digest: previous.packDigest,
+                members: [member],
+            },
+        });
+    }
+    const outcomes = [];
+    for (const { pack, member, remove } of operations) {
+        let operation = remove ? "remove" : "add";
+        let attempted = false;
+        try {
+            const path = join(receipts, member + ".json");
+            const selectionDigest = fingerprint(JSON.stringify({
+                digest: pack.digest,
+                bindingsDigest: pack.bindingsDigest,
+                member,
+            }));
+            try {
+                const retained = z
+                    .strictObject({
+                    ownerId: z.literal(state.ownerId),
+                    selectionDigest: z.string(),
+                    state: z.enum(["pending", "complete"]),
+                })
+                    .parse(await readJson(path));
+                if (retained.state === "complete" &&
+                    !remove &&
+                    retained.selectionDigest === selectionDigest) {
+                    outcomes.push({ member, state: "complete" });
+                    continue;
+                }
+                if (retained.state === "complete") {
+                    operation = remove ? "remove" : "update";
+                }
+                else {
+                    attempted = true;
+                    throw new OperatorError("A pack mutation has an unconfirmed outcome. Inspect native Claws before an explicit change; startup will not repeat it.");
+                }
+            }
+            catch (error) {
+                if (!(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT"))
+                    throw error;
+            }
+            if ((await openPack(pack.directory)).digest !== pack.digest ||
+                (pack.bindingsFile &&
+                    fingerprint(await readFile(pack.bindingsFile)) !==
+                        pack.bindingsDigest))
+                throw new OperatorError("Selected pack inputs changed. Review a new installation plan.");
+            report(`${operation === "remove" ? "Removing" : operation === "update" ? "Updating" : "Installing"} pack member ${member}…`);
+            const plan = await planPack({
+                directory: pack.directory,
+                member,
+                operation,
+                workspace: `/home/node/.openclaw/workspace-${member}`,
+                ...(pack.bindingsFile ? { bindingsFile: pack.bindingsFile } : {}),
+            }, native);
+            await writePrivate(join(receipts, member + "-plan.json"), JSON.stringify(plan));
+            attempted = true;
+            await writePrivate(path, JSON.stringify({
+                ownerId: state.ownerId,
+                selectionDigest,
+                state: "pending",
+            }));
+            await applyPack(plan, native, pack.bindingsFile);
+            await writePrivate(path, JSON.stringify({
+                ownerId: state.ownerId,
+                selectionDigest,
+                state: "complete",
+            }));
+            if (remove) {
+                await rm(path);
+                await rm(join(receipts, member + "-plan.json"));
+            }
+            outcomes.push({ member, state: "complete" });
+        }
+        catch {
+            const state = attempted ? "unconfirmed" : "blocked";
+            outcomes.push({ member, state });
+            report(`Pack member ${member}: ${state}. Inspect its native Claws plan and prerequisites; no mutation was replayed. The team server remains available.`);
+        }
+    }
+    await writePrivate(join(directory, "pack-status.json"), JSON.stringify(outcomes));
+    return outcomes;
+}

package/scripts/installation/plan.js

@@ -0,0 +1,121 @@
+import { dirname, join, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { prepareLocal } from "../deployment/prepare.js";
+import { readState, ensurePrivateFile, withInstallationLock, } from "../deployment/state.js";
+import { fingerprint, readJson } from "./files.js";
+import { InstallationError } from "./errors.js";
+import { allocatePorts, resolveInstallation } from "./resolve.js";
+import { resolveConfigurationInputs } from "./configure.js";
+import { installationSchema } from "./configuration.js";
+export const planSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    stateDirectory: z.string(),
+    fingerprint: z.string(),
+    observedState: z.string().nullable(),
+    internalPorts: z.array(z.number().int().min(1024).max(65535)).length(7),
+    action: z.enum(["prepare", "resume"]),
+    release: z.string(),
+    browser: z.boolean(),
+    capabilities: z.strictObject({
+        models: z.enum(["external", "litellm"]),
+        connections: z.enum(["disabled", "hosted"]),
+        packs: z.array(z.strictObject({ directory: z.string(), members: z.array(z.string()) })),
+    }),
+});
+async function observation(directory) {
+    try {
+        await readState(directory);
+        return fingerprint(await readFile(join(directory, "installation.json")));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function planInstallation(configFile) {
+    const config = installationSchema.parse(await readJson(configFile));
+    const directory = resolve(dirname(resolve(configFile)), config.stateDirectory);
+    const observed = await observation(directory);
+    const state = observed ? await readState(directory) : null;
+    const input = state?.input;
+    const internalPorts = input
+        ? [
+            input.ports.controller,
+            input.ports.management,
+            input.ports.native,
+            input.ports.nativeWidgets,
+            input.ports.database,
+            input.browser?.port ?? 65534,
+            input.modelGateway?.port ?? 65533,
+        ]
+        : await allocatePorts();
+    const resolved = await resolveInstallation(configFile, internalPorts);
+    if (state && !isDeepStrictEqual(state.input, resolved.input))
+        throw new InstallationError("change_unsupported", "This change requires an explicit configuration or upgrade operation. Prepare never replaces retained settings.");
+    await verifyRetainedInputs(directory, resolved.fingerprint);
+    return planSchema.parse({
+        schemaVersion: 1,
+        stateDirectory: directory,
+        fingerprint: resolved.fingerprint,
+        observedState: observed,
+        internalPorts,
+        action: state ? "resume" : "prepare",
+        release: resolved.release.version,
+        browser: config.browser.enabled,
+        capabilities: {
+            models: config.models.mode,
+            connections: config.connections.mode,
+            packs: resolved.packSelection.packs.map(({ directory, members }) => ({
+                directory,
+                members,
+            })),
+        },
+    });
+}
+export async function applyInstallation(configFile, planFile) {
+    const plan = planSchema.parse(await readJson(planFile));
+    const resolved = await resolveInstallation(configFile, plan.internalPorts);
+    if (resolved.fingerprint !== plan.fingerprint ||
+        resolved.stateDirectory !== plan.stateDirectory)
+        throw new InstallationError("stale_plan", "Configuration or release inputs changed. Create a new plan.");
+    return withInstallationLock(plan.stateDirectory, async () => {
+        if ((await observation(plan.stateDirectory)) !== plan.observedState)
+            throw new InstallationError("stale_plan", "Installation state changed. Create a new plan before resuming.");
+        await verifyRetainedInputs(resolved.stateDirectory, resolved.fingerprint);
+        // The existing operator records identity before effects and verifies retained resource ownership.
+        await prepareLocal(resolved.stateDirectory, resolved.input, {
+            inputFingerprint: resolved.fingerprint,
+            ...(resolved.config.connections.mode === "disabled"
+                ? {}
+                : {
+                    connections: resolved.connectorCredentialFile
+                        ? { credentialFile: resolved.connectorCredentialFile }
+                        : {},
+                }),
+        });
+        await ensurePrivateFile(join(resolved.stateDirectory, "release.json"), JSON.stringify(resolved.release, null, 2));
+        await ensurePrivateFile(join(resolved.stateDirectory, "packs.json"), JSON.stringify(resolved.packSelection));
+        await ensurePrivateFile(join(resolved.stateDirectory, "settings.json"), JSON.stringify({
+            ...resolveConfigurationInputs(resolved.config, dirname(resolve(configFile))),
+            stateDirectory: resolved.stateDirectory,
+        }, null, 2));
+        return {
+            state: "prepared",
+            directory: resolved.stateDirectory,
+            release: resolved.release.version,
+        };
+    });
+}
+async function verifyRetainedInputs(directory, expected) {
+    try {
+        if ((await readFile(join(directory, "inputs.sha256"), "utf8")) !== expected)
+            throw new InstallationError("change_unsupported", "Saved capability inputs changed. Run clawscarf configure --directory to review changes; startup does not reapply or rotate native settings.");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+}