@clawscarf/cli 0.1.0-alpha.1 → 0.1.0-alpha.11

package/scripts/installation/installer/run.js

@@ -7,7 +7,7 @@ import { savedSetup, prepareConfiguration, rejectNewSelections, } from "../confi
 import * as clack from "@clack/prompts";
 import { styleText } from "node:util";
 import { setTimeout as delay } from "node:timers/promises";
-import { writeFile, access } from "node:fs/promises";
+import { access } from "node:fs/promises";
 import { dirname, resolve, join } from "node:path";
 import { collectInstallation } from "./collect.js";
 import { InstallerCancelled, SectionCancelled, progress, requireTerminal, terminalPrompts, unattendedPrompts, terminalLink, } from "./prompts.js";
@@ -65,7 +65,6 @@ export async function installFromAnswers(options, ui, operator = operations, tas
         throw new InstallationError("invalid_configuration", "No installation settings were collected.");
     const { configFile, config } = setup;
     const directory = dirname(configFile);
-    const planFile = join(directory, "preview.json");
     const stateDirectory = resolve(directory, config.stateDirectory);
     try {
         await task("Preparing required software", (signal, report) => operator.prerequisites(configFile, { acquire: true, signal, report }));
@@ -74,10 +73,7 @@ export async function installFromAnswers(options, ui, operator = operations, tas
         else
             await registerWithBrowser(configFile, ui, task, operator.register);
         const plan = await task("Checking installation settings", () => operator.plan(configFile));
-        await writeFile(planFile, JSON.stringify(plan, null, 2) + "\n", {
-            mode: 0o600,
-        });
-        await task("Installing ClawScarf", () => operator.apply(configFile, planFile));
+        await task("Installing ClawScarf", () => operator.apply(configFile, plan));
         if (!(options.start ??
             (options.nonInteractive ? true : await ui.confirm("Start now?", true)))) {
             ui.note(`clawscarf start --directory ${quote(directory)}`, "Start later");
@@ -161,7 +157,7 @@ function quote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
 /** The command selects the workflow; users never manipulate preparation files. */
-export async function runConfiguration(options) {
+export async function runConfiguration(options, observeMode) {
     options = {
         ...options,
         directory: options.directory ?? defaultInstallationDirectory,
@@ -174,8 +170,6 @@ export async function runConfiguration(options) {
     }
     const ui = options.nonInteractive ? unattendedPrompts : terminalPrompts;
     try {
-        if (options.reapply)
-            throw new InstallationError("invalid_configuration", "--reapply requires an existing installation.");
         const saved = await savedSetup(options);
         const state = saved
             ? resolve(dirname(saved.configFile), saved.config.stateDirectory)
@@ -193,6 +187,19 @@ export async function runConfiguration(options) {
                     throw error;
             }
         }
+        if (existing && state) {
+            try {
+                await access(join(state, "prepared.json"));
+            }
+            catch (error) {
+                if (!(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT"))
+                    throw error;
+                throw new InstallationError("invalid_configuration", `This folder retains settings but the installation is no longer prepared. If deletion failed, finish it with clawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)} --delete. After successful deletion, move or remove the installation folder before configuring it again, or choose a new --directory.`);
+            }
+        }
+        observeMode?.(existing ? "edit" : "new");
         let result = existing && state
             ? await editInstallationSettings(state, ui, options)
             : await installFromAnswers(options, ui, operations, (message, work) => progress(message, work, options));
@@ -218,14 +225,17 @@ export async function runConfiguration(options) {
                     : undefined;
             if (result.state === "cancelled")
                 clack.cancel("Cancelled.");
-            else
+            else {
+                if ("ready" in result && result.ready)
+                    ui.note(`clawscarf status --directory ${quote(options.directory ?? defaultInstallationDirectory)}\nclawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)}`, "Manage this installation");
                 clack.outro("ready" in result
                     ? result.ready
-                        ? `ClawScarf is ready.${applicationUrl ? ` Visit ${terminalLink(applicationUrl)}` : ""}\n\nManage this installation:\n  clawscarf status --directory ${quote(options.directory ?? defaultInstallationDirectory)}\n  clawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)}`
+                        ? `ClawScarf is ready.${applicationUrl ? ` Visit ${terminalLink(applicationUrl)}` : ""}`
                         : "ClawScarf needs attention. Check status for details."
                     : result.state === "unchanged"
                         ? "No changes. Server left as it was."
                         : "Configuration saved. Server stopped.");
+            }
             if ("ready" in result && result.ready && applicationUrl)
                 await ui.openBrowser(applicationUrl);
         }

package/scripts/installation/installer/sections/models.js

@@ -1,7 +1,6 @@
 import { selectModel } from "../../models.js";
 import { gatewayRoutesSchema, configurationSchema, } from "../../../models/configuration.js";
 import { secretInput } from "../secrets.js";
-import { inputFile } from "../inputs.js";
 import { InstallationError } from "../../errors.js";
 export async function modelRoutes(file, inputs) {
     return gatewayRoutesSchema.parse(await inputs.readJson(file));
@@ -91,15 +90,6 @@ export async function collectModelCredentials(ui, current, inputs) {
     const routes = await modelRoutes(current.configurationFile, inputs);
     const selected = routes.models.find((model) => model.id === routes.defaultModel);
     ui.note(`${selected?.name ?? routes.defaultModel}${routes.thinkingDefault ? " · " + routes.thinkingDefault : ""}\nProvider: ${selected?.route ? providerLabel(selected.route) : "Custom"}`, "LLM credentials");
-    const mode = await ui.select("LLM API keys", [
-        { value: "paste", label: "Enter keys (hidden)" },
-        { value: "file", label: "Import private credentials file" },
-    ], "paste");
-    if (mode === "file")
-        return {
-            ...current,
-            upstreamEnvironmentFile: await inputFile(ui, "Provider credentials file (.env)", true),
-        };
     const values = new Map();
     for (const model of routes.models.filter((item) => item.enabled)) {
         const route = model.route;
@@ -107,9 +97,9 @@ export async function collectModelCredentials(ui, current, inputs) {
             throw new InstallationError("invalid_configuration", "An enabled model has no provider route.");
         if (values.has(route.apiKeyEnv))
             continue;
-        const key = await ui.password(`${providerLabel(route)} LLM API key`);
+        const key = await ui.password(`${providerLabel(route)} API key`);
         if (!key.trim() || /[\r\n'"`]/.test(key))
-            throw new InstallationError("invalid_configuration", "Use a single-line provider key without quote characters, or import its credentials file.");
+            throw new InstallationError("invalid_configuration", "Use a single-line provider key without quote characters.");
         values.set(route.apiKeyEnv, key);
     }
     return {

package/scripts/installation/installer/settings.js

@@ -1,5 +1,4 @@
 import { checkHost, checkInstallationPrerequisites } from "../prerequisites.js";
-import { z } from "zod";
 import { selectedDraft } from "../options.js";
 import { setupContext } from "../setup.js";
 import { configurationChanges, resolveConfigurationInputs, validateSelections, } from "../configure.js";
@@ -13,27 +12,22 @@ import { progress } from "./prompts.js";
 import { SetupInputs, saveConfiguration } from "../save.js";
 import { readJson } from "../files.js";
 import { installationSchema } from "../configuration.js";
-import { planSettingsChange, reconfigureInstallation } from "../reconfigure.js";
+import { planSettingsChange, reconfigureInstallation, retainSettingsAuthorization, discardSettingsCandidate, } from "../reconfigure.js";
 import { controlInstallation, startInstallation } from "../lifecycle.js";
 import { InstallationError } from "../errors.js";
-import { withInstallationLock, writePrivate } from "../../deployment/state.js";
+import { readPreparation } from "../../deployment/state.js";
 /** The menu only gathers answers; the same plan/apply operations serve unattended callers. */
 export async function editInstallationSettings(directory, ui, options = {}, prerequisites = { host: checkHost, check: checkInstallationPrerequisites }) {
     directory = resolve(directory);
     if (options.recipe || options.cloudUrl)
-        throw new InstallationError("change_unsupported", "Existing installations keep their recipe, software release and login service. Change models, keys, Connections or packs instead.");
+        throw new InstallationError("change_unsupported", "Existing installations keep their recipe, software release and login service. Change models, keys, Connections, public web or packs instead.");
     if (options.nonInteractive && !options.yes)
         throw new InstallationError("invalid_configuration", "Changing an existing installation noninteractively requires --yes. The server may restart and deselected packs may be removed.");
     const task = (message, work) => progress(message, work, options);
     const settingsFile = join(directory, "settings.json");
     const before = await readFile(settingsFile, "utf8");
     const config = installationSchema.parse(JSON.parse(before));
-    const record = z
-        .object({
-        settingsCandidate: z.string().optional(),
-        settingsReapply: z.enum(["models", "connections"]).optional(),
-    })
-        .parse(await readJson(join(directory, "prepared.json")));
+    const record = await readPreparation(directory);
     const pending = record.settingsCandidate;
     if (record.settingsReapply &&
         options.reapply &&
@@ -68,22 +62,7 @@ export async function editInstallationSettings(directory, ui, options = {}, prer
         if (pending &&
             !options.nonInteractive &&
             !(await ui.confirm("Resume this interrupted change?"))) {
-            await withInstallationLock(directory, async () => {
-                const prepared = z
-                    .object({
-                    ownerId: z.string(),
-                    settingsCandidate: z.string().optional(),
-                    settingsReapply: z.enum(["models", "connections"]).optional(),
-                    settingsPending: z.string().optional(),
-                })
-                    .parse(await readJson(join(directory, "prepared.json")));
-                if (prepared.settingsCandidate !== pending)
-                    throw new InstallationError("stale_plan", "The pending change has changed. Reopen configure.");
-                if (!prepared.settingsPending) {
-                    await writePrivate(join(directory, "prepared.json"), JSON.stringify({ ownerId: prepared.ownerId }));
-                    retained = false;
-                }
-            });
+            retained = !(await discardSettingsCandidate(directory, pending));
             return { state: "cancelled" };
         }
         if (!pending &&
@@ -114,6 +93,9 @@ export async function editInstallationSettings(directory, ui, options = {}, prer
                     `Connections: ${plan.changes.connections.to === "disabled" ? "Off" : "On"}`,
                 ]
                 : []),
+            ...(plan.scopes.publicWeb
+                ? [`Public web: ${plan.changes.publicWeb.to ? "On" : "Off"}`]
+                : []),
             ...(plan.scopes.packs
                 ? [`Packs: ${plan.changes.packs.selected.join(", ") || "None"}`]
                 : []),
@@ -159,27 +141,8 @@ export async function editInstallationSettings(directory, ui, options = {}, prer
     }
     catch (error) {
         if (authorizing && !pending) {
-            const candidate = authorizing;
-            await withInstallationLock(directory, async () => {
-                if ((await readFile(settingsFile, "utf8")) !== before)
-                    throw new InstallationError("stale_plan", "Settings changed during authorization. Reopen configure before applying.");
-                const prepared = z
-                    .object({
-                    ownerId: z.string(),
-                    settingsCandidate: z.string().optional(),
-                    settingsReapply: z.enum(["models", "connections"]).optional(),
-                    settingsPending: z.string().optional(),
-                })
-                    .parse(await readJson(join(directory, "prepared.json")));
-                if (prepared.settingsCandidate || prepared.settingsPending)
-                    throw new InstallationError("stale_plan", "Another configuration is pending. Resume it before applying these settings.");
-                await writePrivate(join(directory, "prepared.json"), JSON.stringify({
-                    ...prepared,
-                    settingsCandidate: candidate,
-                    ...(reapply ? { settingsReapply: reapply } : {}),
-                }));
-                retained = true;
-            });
+            await retainSettingsAuthorization(directory, authorizing, before, reapply);
+            retained = true;
         }
         if (attempted)
             ui.note("Check status, then run configure --directory again to review and resume the interrupted change.", "Retained settings");

package/scripts/installation/installer/summary.js

@@ -36,9 +36,11 @@ export async function installationSummary(config, inputs) {
         : config.exposure.applicationOrigin;
     return [
         `${config.name} — ${origin}`,
+        `Agent: ${config.agentName}`,
         `Administrator: ${config.access.administratorName} · ${config.access.mode === "hosted" ? "ClawScarf login" : "Custom OIDC"}`,
         `Models: ${model}`,
         `Connections: ${config.connections.mode === "disabled" ? "Off" : "On"}`,
+        `Public web: ${config.publicWeb ? "On" : "Off"} (private destinations blocked)`,
         `Browser: ${config.browser.enabled ? "Experimental" : "Off"} · Packs: ${config.packs.flatMap((pack) => pack.members).join(", ") || "None"}`,
     ].join("\n");
 }

package/scripts/installation/options.js

@@ -18,6 +18,7 @@ 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(),
+    agentName: installationSchema.shape.agentName.optional(),
     administratorName: text.optional(),
     port: port.optional(),
     widgetPort: port.optional(),
@@ -36,6 +37,7 @@ export const selectionSchema = z.object({
     connections: z.boolean().optional(),
     connectionsCloudUrl: cloudUrlSchema.optional(),
     browser: z.boolean().optional(),
+    publicWeb: z.boolean().optional(),
     model: text.optional(),
     provider: text.optional(),
     reasoning: z.enum(["low", "medium", "high"]).optional(),
@@ -56,6 +58,7 @@ export const selectionSchema = z.object({
 export function installationOptions(command) {
     return command
         .option("--name <name>", "Installation name")
+        .option("--agent-name <name>", "Initial default agent 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)")
@@ -79,6 +82,8 @@ export function installationOptions(command) {
         .option("--connections-cloud-url <url>", "Use a separate Connections service")
         .option("--browser", "Enable experimental browser capability")
         .option("--no-browser", "Disable browser capability")
+        .option("--public-web", "Allow public HTTP(S) from agents and tools")
+        .option("--no-public-web", "Restrict runtime egress to configured services")
         .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([
@@ -116,6 +121,7 @@ export async function selectedDraft(context, recipe, selections, inputs, retaine
             "modelGatewayKeyFile",
             "modelGatewayCaFile",
             "connections",
+            "publicWeb",
             "connectionsCloudUrl",
             "pack",
             "packs",
@@ -123,11 +129,13 @@ export async function selectedDraft(context, recipe, selections, inputs, retaine
             "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.");
+            invalid("Existing installations support changes to models, keys, Connections, public web and packs only.");
     }
     const config = structuredClone(retained ?? recipeConfiguration(context, recipe));
     if (o.name !== undefined)
         config.name = o.name;
+    if (o.agentName !== undefined)
+        config.agentName = o.agentName;
     if (o.administratorName !== undefined)
         config.access.administratorName = o.administratorName;
     if (o.cpu !== undefined)
@@ -136,6 +144,8 @@ export async function selectedDraft(context, recipe, selections, inputs, retaine
         config.resources.runtime.memory = o.memory;
     if (o.browser !== undefined)
         config.browser.enabled = o.browser;
+    if (o.publicWeb !== undefined)
+        config.publicWeb = o.publicWeb;
     if (o.connections !== undefined)
         config.connections.mode = o.connections ? "hosted" : "disabled";
     if (o.connectionsCloudUrl)

package/scripts/installation/plan.js

@@ -1,7 +1,6 @@
 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";
@@ -9,21 +8,6 @@ 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);
@@ -54,29 +38,16 @@ export async function planInstallation(configFile) {
         : 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.");
+        throw new InstallationError("change_unsupported", "Preparation cannot replace retained settings. Run configure to review supported changes.");
     await verifyRetainedInputs(directory, resolved.fingerprint);
-    return planSchema.parse({
-        schemaVersion: 1,
+    return {
         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));
+export async function applyInstallation(configFile, plan) {
     const resolved = await resolveInstallation(configFile, plan.internalPorts);
     if (resolved.fingerprint !== plan.fingerprint ||
         resolved.stateDirectory !== plan.stateDirectory)

package/scripts/installation/prerequisites.js

@@ -12,8 +12,9 @@ import { acquireRuntimeTools } from "./runtime.js";
 import { InstallationError } from "./errors.js";
 /** No configuration, credentials or cloud account is needed for these checks. */
 export async function checkHost(command = run) {
-    if (process.platform !== "darwin" || process.arch !== "arm64")
-        throw new InstallationError("unsupported_platform", "This release requires macOS on Apple Silicon with Docker Desktop.");
+    if (!["darwin", "linux"].includes(process.platform) ||
+        !["arm64", "x64"].includes(process.arch))
+        throw new InstallationError("unsupported_platform", "Use macOS or Linux (including WSL2), with an ARM64 or x86-64 processor and Linux Docker containers. Run the Windows CLI inside WSL2.");
     let os;
     try {
         os = await command("docker", ["info", "--format", "{{.OSType}}"]);
@@ -23,8 +24,8 @@ export async function checkHost(command = run) {
             error.commandFailure?.reason === "spawn" &&
             error.commandFailure.systemCode === "ENOENT";
         throw new InstallationError("unavailable", missing
-            ? "Docker is not installed or is not on PATH. Install Docker Desktop, start it, then run configure again."
-            : "Cannot reach Docker. Start Docker Desktop and wait until it is running, then try again.");
+            ? "Docker is not installed or is not on PATH. Install Docker Engine with Compose or Docker Desktop, then run configure again."
+            : "Cannot reach Docker. Start Docker and check that your user can access its socket, then try again.");
     }
     if (os.trim() !== "linux")
         throw new InstallationError("unsupported_platform", "Docker must run Linux containers.");
@@ -32,8 +33,12 @@ export async function checkHost(command = run) {
         await command("docker", ["compose", "version"]);
     }
     catch {
-        throw new InstallationError("unavailable", "Docker Compose is unavailable. Install or update Docker Desktop, then try again.");
+        throw new InstallationError("unavailable", "Docker Compose is unavailable. Install the Docker Compose plugin or update Docker Desktop, then try again.");
     }
+    const version = (await command("docker", ["version", "--format", "{{.Server.Version}}"])).trim();
+    const major = Number(/^([0-9]+)\./.exec(version)?.[1]);
+    if (!Number.isInteger(major) || major < 29)
+        throw new InstallationError("unsupported_platform", "Docker Engine 29 or newer is required for automatic subnet allocation with fixed service addresses. Update Docker Engine or Docker Desktop, then try again.");
 }
 /** Stream only Docker's layer progress, never registry error payloads or credentials. */
 export function pullImage(image, report, signal) {

package/scripts/installation/recipes/definition.js

@@ -9,8 +9,10 @@ export const recipeSchema = z.strictObject({
     description: z.string().min(1).max(500),
     maturity: z.enum(["example", "supported"]),
     defaults: z.strictObject({
+        agentName: installationSchema.shape.agentName,
         resources: installationSchema.shape.resources,
         browser: installationSchema.shape.browser,
+        publicWeb: z.boolean().default(false),
         connections: z.strictObject({ enabled: z.boolean() }).optional(),
     }),
     models: z.strictObject({

package/scripts/installation/reconfigure.js

@@ -1,3 +1,7 @@
+import { validatePublicWebServices } from "../deployment/service-network.js";
+import { serviceNetworkRule } from "../deployment/policy.js";
+import { publicWebPolicy, } from "../deployment/public-web.js";
+import { stageNetworkPolicyChange, planNetworkPolicyChange, } from "../deployment/network-policy.js";
 import { applyConnectionSettings } from "../deployment/connection-settings.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -11,9 +15,8 @@ import { loadGatewayConfiguration, prepareModelGateway, } from "../deployment/mo
 import { readInitialConnectionsEndpoint, loadInitialConnections, prepareInitialConnections, } from "../deployment/connections.js";
 import { configureStoppedRuntimeModels } from "../models/runtime.js";
 import { loadInitialModels } from "../deployment/models.js";
-import { readState, resourceNames, withInstallationLock, writePrivate, } from "../deployment/state.js";
-import { requireNoUpgrade } from "../deployment/upgrade-state.js";
-import { run } from "../deployment/process.js";
+import { readState, readPreparation, resourceNames, withInstallationLock, writePrivate, } from "../deployment/state.js";
+import { run, LocalSetupError } from "../deployment/process.js";
 import { selectionSchema } from "./packs.js";
 import { installationSchema } from "./configuration.js";
 import { resolveInstallation } from "./resolve.js";
@@ -41,8 +44,8 @@ export async function planSettingsChange(configFile, reapply) {
     const previousPacks = selectionSchema.parse(await readJson(join(directory, "packs.json")));
     if (!desired.packSelection.python && previousPacks.python)
         desired.packSelection.python = previousPacks.python;
-    const { models: _oldModels, modelGateway: oldGateway, connections: oldConnections, ...oldFixed } = old;
-    const { models: _nextModels, modelGateway: nextGateway, connections: nextConnections, ...nextFixed } = next;
+    const { models: _oldModels, modelGateway: oldGateway, connections: oldConnections, publicWeb: oldPublicWeb, ...oldFixed } = old;
+    const { models: _nextModels, modelGateway: nextGateway, connections: nextConnections, publicWeb: nextPublicWeb, ...nextFixed } = next;
     if (!isDeepStrictEqual(oldFixed, nextFixed) ||
         !isDeepStrictEqual(await readJson(join(directory, "release.json")), desired.release))
         unsupported("Settings changes cannot replace the release, identity, addresses, access, resources or execution protection.");
@@ -67,14 +70,7 @@ export async function planSettingsChange(configFile, reapply) {
     const modelConfiguration = nextGateway
         ? (await loadGatewayConfiguration(nextGateway.configurationFile, nextGateway.upstreamEnvironmentFile)).configuration
         : (await loadInitialModels(next.models))?.configuration;
-    const pending = z
-        .strictObject({
-        ownerId: z.literal(state.ownerId),
-        settingsPending: z.string().optional(),
-        settingsCandidate: z.string().optional(),
-        settingsReapply: z.enum(["models", "connections"]).optional(),
-    })
-        .parse(await readJson(join(directory, "prepared.json")));
+    const pending = await readPreparation(directory);
     if (pending.settingsPending &&
         pending.settingsPending !== desired.fingerprint)
         unsupported("Finish the pending settings change with its original candidate before selecting another configuration.");
@@ -84,6 +80,14 @@ export async function planSettingsChange(configFile, reapply) {
     const scopes = await configurationChanges(installationSchema.parse(await readJson(join(directory, "settings.json"))), resolveConfigurationInputs(config, dirname(resolve(configFile))));
     if (reapply)
         scopes[reapply] = true;
+    await validatePublicWebServices(next.publicWeb, {
+        models: next.publicWeb && !nextGateway && (scopes.models || scopes.publicWeb)
+            ? (await loadInitialModels(next.models))?.network
+            : undefined,
+        connections: scopes.connections || scopes.publicWeb
+            ? connections?.endpoint.network
+            : undefined,
+    });
     return {
         directory,
         state,
@@ -92,6 +96,7 @@ export async function planSettingsChange(configFile, reapply) {
         scopes,
         reapply,
         changes: {
+            publicWeb: { from: oldPublicWeb, to: nextPublicWeb },
             models: modelConfiguration
                 ? {
                     enabled: modelConfiguration.models
@@ -126,15 +131,16 @@ export async function planSettingsChange(configFile, reapply) {
 }
 /** Explicit retained capability changes; native users and individual model overrides remain native-owned. */
 export async function reconfigureInstallation(configFile, expectedFingerprint, reapply) {
-    const planned = await planSettingsChange(configFile, reapply);
-    return withInstallationLock(planned.directory, async () => {
+    const config = installationSchema.parse(await readJson(configFile));
+    const location = resolve(dirname(resolve(configFile)), config.stateDirectory);
+    return withInstallationLock(location, async () => {
         const checked = await planSettingsChange(configFile, reapply);
-        if (checked.fingerprint !== expectedFingerprint)
+        if (checked.directory !== location ||
+            checked.fingerprint !== expectedFingerprint)
             throw new InstallationError("stale_plan", "Settings changed after preview. Review them again.");
         const { directory, state, desired, scopes } = checked;
         if (!checked.resuming && !Object.values(scopes).some(Boolean))
             return { state: "unchanged", restartRequired: false, directory };
-        await requireNoUpgrade(directory);
         const names = resourceNames(state);
         for (const filter of [
             `label=com.docker.compose.project=${names.project}`,
@@ -187,6 +193,18 @@ export async function reconfigureInstallation(configFile, expectedFingerprint, r
                 credential: models.credential,
                 apply: false,
             });
+        // Reconcile native policy before any native/service settings are written.
+        const network = {};
+        if (scopes.connections)
+            network.connections_broker = serviceNetworkRule("Connections broker", (await loadInitialConnections(desired.input.connections))?.endpoint
+                .network);
+        if (scopes.publicWeb)
+            network.public_web = publicWebPolicy(desired.input.publicWeb);
+        let networkChange;
+        if (Object.keys(network).length) {
+            await compose(directory, ["up", "-d", "--wait", "controller"]);
+            networkChange = await planNetworkPolicyChange(directory, state, network);
+        }
         // Startup already requires this exact prepared record. An interrupted mutation must not announce readiness.
         await writePrivate(prepared, JSON.stringify({
             ownerId: state.ownerId,
@@ -194,8 +212,11 @@ export async function reconfigureInstallation(configFile, expectedFingerprint, r
             settingsCandidate: resolve(configFile),
             ...(checked.reapply ? { settingsReapply: checked.reapply } : {}),
         }));
-        let stage = "model gateway configuration";
+        let stage = "network policy staging";
         try {
+            if (networkChange)
+                await stageNetworkPolicyChange(directory, networkChange);
+            stage = "model gateway configuration";
             if (scopes.models) {
                 await prepareModelGateway(directory, { ...state, input: desired.input }, { replaceConfiguration: true });
                 if (gateway && loaded)
@@ -249,7 +270,37 @@ export async function reconfigureInstallation(configFile, expectedFingerprint, r
             return { state: "configured", restartRequired: true, directory };
         }
         catch (error) {
+            if (error instanceof LocalSetupError)
+                throw new LocalSetupError(error.code, `Settings were not confirmed during ${stage}; the installation remains stopped. ${error.message} Run clawscarf configure to review and resume the change.`, error.commandFailure);
             throw new InstallationError("unavailable", `Settings were not confirmed during ${stage}; the installation remains stopped. Run configure --directory again to review and explicitly resume the same change. The gateway key is observed first and matching native settings are not repeated.${error instanceof ModelConfigurationError ? ` Native result: ${error.code}.` : ""}`);
         }
     });
 }
+/** Retain an authorization draft without blocking startup; no service mutation has begun. */
+export async function retainSettingsAuthorization(directory, candidate, acceptedSettings, reapply) {
+    await withInstallationLock(directory, async () => {
+        if ((await readFile(join(directory, "settings.json"), "utf8")) !==
+            acceptedSettings)
+            throw new InstallationError("stale_plan", "Settings changed during authorization. Reopen configure before applying.");
+        const prepared = await readPreparation(directory);
+        if (prepared.settingsCandidate || prepared.settingsPending)
+            throw new InstallationError("stale_plan", "Another configuration is pending. Resume it before applying these settings.");
+        await writePrivate(join(directory, "prepared.json"), JSON.stringify({
+            ...prepared,
+            settingsCandidate: candidate,
+            ...(reapply ? { settingsReapply: reapply } : {}),
+        }));
+    });
+}
+/** A draft can be discarded only before service mutation begins. */
+export async function discardSettingsCandidate(directory, candidate) {
+    return withInstallationLock(directory, async () => {
+        const prepared = await readPreparation(directory);
+        if (prepared.settingsCandidate !== candidate)
+            throw new InstallationError("stale_plan", "The pending change has changed. Reopen configure.");
+        if (prepared.settingsPending)
+            return false;
+        await writePrivate(join(directory, "prepared.json"), JSON.stringify({ ownerId: prepared.ownerId }));
+        return true;
+    });
+}

package/scripts/installation/resolve.js

@@ -3,7 +3,7 @@ import { hostedOidc, hostedConnections } from "../cloud/registration.js";
 import { dirname, resolve, join } from "node:path";
 import { loadGatewayConfiguration } from "../deployment/model-gateway.js";
 import { createServer } from "node:net";
-import { releaseSchema } from "../release/definition.js";
+import { releaseSchema, releaseTools } from "../release/definition.js";
 import { parseLocalInput, } from "../deployment/configuration.js";
 import { loadInitialModels } from "../deployment/models.js";
 import { loadInitialConnections, readInitialConnectionToken, } from "../deployment/connections.js";
@@ -49,10 +49,11 @@ export async function resolveInstallation(configFile, internalPorts) {
     if (!release.platforms.some((platform) => platform === `${process.platform}-${process.arch}`))
         throw new InstallationError("unsupported_platform", "This release does not support this host platform.");
     const toolBase = dirname(releasePath);
-    const cli = resolve(toolBase, release.tools.openshell.cli.file);
-    const gateway = resolve(toolBase, release.tools.openshell.gateway.file);
-    await verifyReleaseTool(cli, release.tools.openshell.cli.sha256);
-    await verifyReleaseTool(gateway, release.tools.openshell.gateway.sha256);
+    const tools = releaseTools(release);
+    const cli = resolve(toolBase, tools.cli.file);
+    const gateway = resolve(toolBase, tools.gateway.file);
+    await verifyReleaseTool(cli, tools.cli.sha256);
+    await verifyReleaseTool(gateway, tools.gateway.sha256);
     const [controller, management, native, nativeWidgets, database, browser, models,] = internalPorts;
     const inputs = {};
     async function inputFile(value, secret) {
@@ -70,8 +71,10 @@ export async function resolveInstallation(configFile, internalPorts) {
     const cloudConnections = await hostedConnections(config, configFile);
     const input = parseLocalInput({
         name: config.name,
+        agentName: config.agentName,
         administratorName: access.administratorName,
         runtimeImage: release.images.gateway,
+        publicWeb: config.publicWeb,
         companionImage: release.images.companion,
         ...(config.browser.enabled ? { relayImage: release.images.relay } : {}),
         openshellCli: cli,

package/scripts/installation/runtime.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { chmod, copyFile, mkdir, open, rename, rm, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { releaseSchema } from "../release/definition.js";
+import { releaseSchema, releaseTools } from "../release/definition.js";
 import { readJson, verifyReleaseTool } from "./files.js";
 import { InstallationError } from "./errors.js";
 /** Installation-owned paths survive npm cache cleanup and later CLI updates. */
@@ -10,7 +10,7 @@ export async function retainRuntime(source, directory) {
     const target = join(directory, "runtime");
     await mkdir(join(target, "tools"), { recursive: true, mode: 0o700 });
     for (const name of ["cli", "gateway"]) {
-        const tool = release.tools.openshell[name];
+        const tool = releaseTools(release)[name];
         const original = resolve(dirname(source), tool.file);
         tool.file = `tools/openshell${name === "gateway" ? "-gateway" : ""}`;
         try {
@@ -34,7 +34,7 @@ export async function acquireRuntimeTools(releaseFile, options) {
     const release = releaseSchema.parse(await readJson(releaseFile));
     for (const name of ["cli", "gateway"]) {
         options.signal?.throwIfAborted();
-        const tool = release.tools.openshell[name];
+        const tool = releaseTools(release)[name];
         const file = resolve(dirname(releaseFile), tool.file);
         try {
             await verifyReleaseTool(file, tool.sha256);