@abot-ai/runtime 1.6.0 → 1.8.0

package/dist/src/web-ui/local-runtime/plugin-removal-routes.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PluginRemovalRuntime } from "../plugin-removal-service.js";
+export declare class PluginRemovalRoutes {
+    private readonly options;
+    constructor(options: {
+        rootDir: string;
+        requireMutationIdle?: () => void;
+        getConfigPath?: () => string | undefined;
+        removalRuntime?: PluginRemovalRuntime;
+    });
+    handle(params: {
+        method: string;
+        route: string;
+        body: Record<string, unknown> | null;
+        request?: IncomingMessage;
+        response: ServerResponse;
+    }): Promise<boolean>;
+}

package/dist/src/web-ui/local-runtime/plugin-removal-routes.js

@@ -0,0 +1,60 @@
+import { ConfigFileConflictError } from "../../runtime/adapters/config-file-transaction.js";
+import { PluginRemovalActivationError } from "../plugin-removal-error.js";
+import { PluginManagementError } from "../plugin-management-service.js";
+import { removeRuntimePlugin, } from "../plugin-removal-service.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { sendJson } from "./http.js";
+export class PluginRemovalRoutes {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async handle(params) {
+        if (params.route !== "runtime/plugins/remove")
+            return false;
+        if (params.method !== "POST") {
+            sendJson(params.response, 405, {
+                ok: false,
+                error: "method_not_allowed",
+            });
+            return true;
+        }
+        if (!params.request) {
+            sendJson(params.response, 403, {
+                ok: false,
+                error: "request_origin_required",
+            });
+            return true;
+        }
+        if (!acceptConfigMutationRequest(params.request, params.response))
+            return true;
+        try {
+            if (!this.options.removalRuntime)
+                throw new PluginManagementError("plugin_removal_unavailable", "This Runtime cannot apply plugin removal.", 409);
+            this.options.requireMutationIdle?.();
+            const result = await removeRuntimePlugin({
+                rootDir: this.options.rootDir,
+                requireMutationIdle: this.options.requireMutationIdle,
+                configPath: this.options.getConfigPath?.(),
+                ...this.options.removalRuntime,
+            }, params.body);
+            sendJson(params.response, 200, { ok: true, ...result });
+        }
+        catch (error) {
+            const known = error instanceof PluginManagementError ||
+                error instanceof ConfigFileConflictError;
+            const status = error instanceof PluginManagementError ? error.statusCode : 500;
+            sendJson(params.response, error instanceof ConfigFileConflictError ? 409 : status, {
+                ok: false,
+                ...(error instanceof PluginRemovalActivationError
+                    ? { activation: error.activation }
+                    : {}),
+                error: known ? error.code : "plugin_removal_failed",
+                message: known
+                    ? error.message
+                    : "Plugin removal could not complete. Refresh plugins before trying again.",
+            });
+        }
+        return true;
+    }
+}

package/dist/src/web-ui/local-runtime/realtime-controller.js

@@ -1,5 +1,7 @@
 import { getNumber, getString, requestEnvironmentId } from "./http.js";
 import { ManagedWebToolApprovals } from "./managed-tool-approvals.js";
+import { diagnosticErrorType } from "../../runtime/observability/request-control-diagnostics.js";
+import { traceWebRequestControl } from "./request-control-observation.js";
 export class LocalRealtimeController {
     options;
     environments;
@@ -47,18 +49,42 @@ export class LocalRealtimeController {
             return;
         }
         if (message.type === "steer_request") {
-            this.clients.send(client, await this.requests.handleSteer(message, (id) => this.environments.get(id)));
+            const acknowledgement = await this.requests.handleSteer(message, (id) => this.environments.get(id));
+            traceWebRequestControl("steer.ack_dispatch_attempted", {
+                requestId: getString(acknowledgement.requestId),
+                steerId: getString(acknowledgement.steerId),
+                accepted: acknowledgement.accepted === true,
+                reason: getString(acknowledgement.reason) || undefined,
+                socketReadyState: client.readyState,
+            });
+            this.clients.send(client, acknowledgement);
             return;
         }
         if (message.type !== "resume_request")
             return;
-        await this.resume(client, message);
+        try {
+            await this.resume(client, message);
+        }
+        catch (error) {
+            traceWebRequestControl("resume.failed", {
+                requestId: getString(message.requestId),
+                requestedEnvironment: getString(message.environment),
+                errorType: diagnosticErrorType(error),
+            });
+            throw error;
+        }
     }
     async resume(client, message) {
         const requestId = getString(message.requestId);
         if (!requestId)
             return;
         const environmentId = requestEnvironmentId(new URL("/", "http://localhost"), message, this.options.defaultEnvironmentId);
+        const startedAt = Date.now();
+        traceWebRequestControl("resume.received", {
+            requestId,
+            environmentId,
+            afterSeq: getNumber(message.afterSeq),
+        });
         const environment = this.environments.get(environmentId);
         let replay = await environment.services.sessions.getRequestReplayById(requestId, getNumber(message.afterSeq));
         if (!replay?.finalState) {
@@ -86,5 +112,18 @@ export class LocalRealtimeController {
                 error: replay.finalState.error,
             });
         }
+        // A returned send call is not a browser delivery acknowledgement.
+        traceWebRequestControl("resume.dispatch_returned", {
+            requestId,
+            environmentId,
+            afterSeq: getNumber(message.afterSeq),
+            replayFound: replay !== null && replay !== undefined,
+            sessionId: replay?.sessionId,
+            eventCount: replay?.events.length ?? 0,
+            lifecycleStatus: replay?.lifecycle?.status,
+            finalStateStatus: replay?.finalState?.status,
+            socketReadyState: client.readyState,
+            elapsedMs: Date.now() - startedAt,
+        });
     }
 }

package/dist/src/web-ui/local-runtime/request-body-error.d.ts

@@ -0,0 +1,11 @@
+declare const REQUEST_BODY_ERROR_MESSAGES: {
+    readonly invalid_json: "Request body must contain valid JSON.";
+    readonly json_object_required: "Request body must be a JSON object.";
+};
+/** A client syntax/shape failure, distinct from unexpected backend exceptions. */
+export declare class RequestBodyInputError extends Error {
+    readonly code: keyof typeof REQUEST_BODY_ERROR_MESSAGES;
+    readonly statusCode = 400;
+    constructor(code: keyof typeof REQUEST_BODY_ERROR_MESSAGES);
+}
+export {};

package/dist/src/web-ui/local-runtime/request-body-error.js

@@ -0,0 +1,14 @@
+const REQUEST_BODY_ERROR_MESSAGES = {
+    invalid_json: "Request body must contain valid JSON.",
+    json_object_required: "Request body must be a JSON object.",
+};
+/** A client syntax/shape failure, distinct from unexpected backend exceptions. */
+export class RequestBodyInputError extends Error {
+    code;
+    statusCode = 400;
+    constructor(code) {
+        super(REQUEST_BODY_ERROR_MESSAGES[code]);
+        this.code = code;
+        this.name = "RequestBodyInputError";
+    }
+}

package/dist/src/web-ui/local-runtime/request-cancellation-route.js

@@ -1,5 +1,7 @@
 import { acceptConfigMutationRequest } from "./config-mutation-request.js";
 import { getString, sendJson } from "./http.js";
+import { diagnosticErrorType } from "../../runtime/observability/request-control-diagnostics.js";
+import { traceWebRequestControl } from "./request-control-observation.js";
 export async function cancelWebRequest(input) {
     if (!acceptConfigMutationRequest(input.request, input.response))
         return;
@@ -29,6 +31,31 @@ export async function cancelWebRequest(input) {
             commandId: getString(body.commandId),
         }
         : undefined;
-    const result = await cancel(requestId, sessionId, wait);
+    const fields = {
+        requestId,
+        sessionId,
+        environmentId: input.environment.services?.config?.runtimeId,
+        hasWaitIdentity: wait !== undefined,
+    };
+    const startedAt = Date.now();
+    traceWebRequestControl("cancel.received", fields);
+    let result;
+    try {
+        result = await cancel(requestId, sessionId, wait);
+    }
+    catch (error) {
+        traceWebRequestControl("cancel.failed", {
+            ...fields,
+            errorType: diagnosticErrorType(error),
+            elapsedMs: Date.now() - startedAt,
+        });
+        throw error;
+    }
+    traceWebRequestControl("cancel.result", {
+        ...fields,
+        accepted: result.accepted,
+        reason: result.accepted ? undefined : result.reason,
+        elapsedMs: Date.now() - startedAt,
+    });
     sendJson(input.response, 200, { ok: true, ...result });
 }

package/dist/src/web-ui/local-runtime/request-control-observation.d.ts

@@ -0,0 +1,19 @@
+import { type RequestControlDiagnosticFields } from "../../runtime/observability/request-control-diagnostics.js";
+import type { ActiveRequest, JsonObject } from "./contracts.js";
+export declare function traceWebRequestControl(event: string, fields: RequestControlDiagnosticFields): void;
+export declare function traceWebProjection(event: "projection.opened" | "projection.removed", requestId: string, active: ActiveRequest | undefined, reason: string, removed?: boolean): void;
+export declare function webSteerRoute(active: ActiveRequest | undefined, steer: unknown): string;
+/** Observes the existing routing decision; it never queries or changes an owner. */
+export declare class WebSteerObservation {
+    private readonly requestId;
+    private readonly steerId;
+    private readonly active;
+    private readonly currentProjection;
+    private readonly startedAt;
+    private route;
+    constructor(requestId: string, steerId: string, requestedEnvironment: string, textLength: number, active: ActiveRequest | undefined, currentProjection: () => ActiveRequest | undefined);
+    selectRoute(route: string): void;
+    result(acknowledgement: JsonObject): void;
+    failed(error: unknown): void;
+    private trace;
+}

package/dist/src/web-ui/local-runtime/request-control-observation.js

@@ -0,0 +1,80 @@
+import { diagnosticErrorType, traceRequestControl, } from "../../runtime/observability/request-control-diagnostics.js";
+import { getString } from "./http.js";
+export function traceWebRequestControl(event, fields) {
+    traceRequestControl("web.request_control", event, fields);
+}
+function projectionFields(active) {
+    return {
+        projectionPresent: active !== undefined,
+        environmentId: active?.environmentId,
+        sessionId: active?.sessionId,
+        projectionStartedAt: active?.startedAt,
+        lastEventAt: active?.lastEventAt,
+        finalStateStatus: getString(active?.finalState?.status) || undefined,
+    };
+}
+export function traceWebProjection(event, requestId, active, reason, removed) {
+    traceWebRequestControl(event, {
+        requestId,
+        ...projectionFields(active),
+        reason,
+        removed,
+    });
+}
+export function webSteerRoute(active, steer) {
+    if (steer)
+        return "runtime_owner";
+    if (!active)
+        return "web_projection_missing";
+    return "local_inbox";
+}
+/** Observes the existing routing decision; it never queries or changes an owner. */
+export class WebSteerObservation {
+    requestId;
+    steerId;
+    active;
+    currentProjection;
+    startedAt = Date.now();
+    route = "not_routed";
+    constructor(requestId, steerId, requestedEnvironment, textLength, active, currentProjection) {
+        this.requestId = requestId;
+        this.steerId = steerId;
+        this.active = active;
+        this.currentProjection = currentProjection;
+        traceWebRequestControl("steer.received", {
+            requestId,
+            steerId,
+            requestedEnvironment,
+            textLength,
+            ...projectionFields(active),
+        });
+    }
+    selectRoute(route) {
+        this.route = route;
+    }
+    result(acknowledgement) {
+        this.trace("steer.result", {
+            accepted: acknowledgement.accepted === true,
+            reason: getString(acknowledgement.reason) || undefined,
+            acceptedSequence: typeof acknowledgement.acceptedSequence === "number"
+                ? acknowledgement.acceptedSequence
+                : undefined,
+        });
+    }
+    failed(error) {
+        this.trace("steer.failed", { errorType: diagnosticErrorType(error) });
+    }
+    trace(event, fields) {
+        const current = this.currentProjection();
+        traceWebRequestControl(event, {
+            requestId: this.requestId,
+            steerId: this.steerId,
+            route: this.route,
+            ...projectionFields(this.active),
+            currentProjectionPresent: current !== undefined,
+            projectionStillCurrent: this.active !== undefined && current === this.active,
+            elapsedMs: Date.now() - this.startedAt,
+            ...fields,
+        });
+    }
+}

package/dist/src/web-ui/local-runtime/request-execution.js

@@ -4,7 +4,8 @@ import { getNumber, getString, sendJson } from "./http.js";
 import { PendingToolApprovals } from "./pending-tool-approvals.js";
 import { createWorkspaceChangeNotifier } from "./workspace-notifications.js";
 import { attachApprovalRequest } from "./approval-request-attachment.js";
-import { publicSparkChatAdmissionFailure, resolveSparkChatRequest } from "./spark-chat-admission.js";
+import { publicSparkChatAdmissionFailure, resolveSparkChatRequest, } from "./spark-chat-admission.js";
+import { traceWebProjection, webSteerRoute, WebSteerObservation, } from "./request-control-observation.js";
 function createRequestId() {
     const random = Math.random().toString(36).slice(2, 8);
     return `web-${Date.now()}-${random}`;
@@ -26,6 +27,7 @@ export class LocalRequestExecution {
     scheduledRequestOptions(run) {
         const requestSteering = createRequestSteeringInbox({
             requestId: run.requestId,
+            diagnostics: { origin: "web_projection" },
         });
         this.activeRequests.set(run.requestId, {
             requestId: run.requestId,
@@ -38,6 +40,7 @@ export class LocalRequestExecution {
             finalState: null,
             requestSteering,
         });
+        traceWebProjection("projection.opened", run.requestId, this.activeRequests.get(run.requestId), "schedule");
         return {
             toolApprovalController: this.toolApprovals,
             requestSteering,
@@ -51,7 +54,10 @@ export class LocalRequestExecution {
         if (payload.sessionDeleted !== true)
             this.publish(outbound);
         if (isTerminal) {
-            this.activeRequests.delete(getString(payload.requestId));
+            const requestId = getString(payload.requestId);
+            const active = this.activeRequests.get(requestId);
+            const removed = this.activeRequests.delete(requestId);
+            traceWebProjection("projection.removed", requestId, active, "published_terminal", removed);
         }
     }
     async start(res, body, environmentId, environment) {
@@ -78,10 +84,16 @@ export class LocalRequestExecution {
             body = await resolveSparkChatRequest(environment, sessionId, body);
         }
         catch (error) {
-            sendJson(res, 409, { ok: false, ...publicSparkChatAdmissionFailure(error) });
+            sendJson(res, 409, {
+                ok: false,
+                ...publicSparkChatAdmissionFailure(error),
+            });
             return;
         }
-        const requestSteering = createRequestSteeringInbox({ requestId });
+        const requestSteering = createRequestSteeringInbox({
+            requestId,
+            diagnostics: { origin: "web_projection" },
+        });
         const request = {
             type: "run_request",
             requestId,
@@ -103,6 +115,7 @@ export class LocalRequestExecution {
             finalState: null,
             requestSteering,
         });
+        traceWebProjection("projection.opened", requestId, this.activeRequests.get(requestId), "ordinary");
         void this.run(environment, request, environmentId, sessionId, requestSteering)
             .catch((error) => {
             this.publish({
@@ -113,7 +126,11 @@ export class LocalRequestExecution {
                 error: error instanceof Error ? error.message : String(error),
             });
         })
-            .finally(() => this.activeRequests.delete(requestId));
+            .finally(() => {
+            const active = this.activeRequests.get(requestId);
+            const removed = this.activeRequests.delete(requestId);
+            traceWebProjection("projection.removed", requestId, active, "run_handle_settled", removed);
+        });
         sendJson(res, 200, { ok: true, requestId, sessionId });
     }
     activeReplay(requestId, afterSeq) {
@@ -151,45 +168,60 @@ export class LocalRequestExecution {
         const steerId = getString(message.steerId).trim();
         const text = getString(message.text).trim();
         const active = requestId ? this.activeRequests.get(requestId) : undefined;
-        if (active) {
-            const sessions = resolveEnvironment(active.environmentId).services.sessions;
-            try {
+        const observation = new WebSteerObservation(requestId, steerId, getString(message.environment), text.length, active, () => this.activeRequests.get(requestId));
+        try {
+            if (active) {
+                observation.selectRoute("interactive_session_check");
+                const sessions = resolveEnvironment(active.environmentId).services
+                    .sessions;
                 await sessions.assertInteractiveSession?.(active.sessionId);
             }
-            catch (error) {
-                if (!isAutomationSessionLockedError(error))
-                    throw error;
-                return {
+            observation.selectRoute("environment_resolution");
+            // Saved approval waits retire the Web view; their resumed owner remains
+            // authoritative. Never infer inactivity from a missing local projection.
+            const steeringEnvironmentId = active?.environmentId ?? getString(message.environment).trim();
+            const hasSteeringEnvironment = steeringEnvironmentId.length > 0;
+            const steer = hasSteeringEnvironment
+                ? resolveEnvironment(steeringEnvironmentId).requests.steer
+                : undefined;
+            observation.selectRoute(webSteerRoute(active, steer));
+            const result = (steer
+                ? await steer(requestId, { steerId, text })
+                : active?.requestSteering.append({ steerId, text })) ??
+                { ok: false, reason: "request_not_active" };
+            const acknowledgement = result.ok
+                ? {
+                    type: "steer_ack",
+                    requestId,
+                    steerId,
+                    accepted: true,
+                    acceptedSequence: result.update.sequence,
+                }
+                : {
+                    type: "steer_ack",
+                    requestId,
+                    steerId,
+                    accepted: false,
+                    reason: result.reason,
+                };
+            observation.result(acknowledgement);
+            return acknowledgement;
+        }
+        catch (error) {
+            if (isAutomationSessionLockedError(error)) {
+                const acknowledgement = {
                     type: "steer_ack",
                     requestId,
                     steerId,
                     accepted: false,
                     reason: "automation_session_locked",
                 };
+                observation.result(acknowledgement);
+                return acknowledgement;
             }
+            observation.failed(error);
+            throw error;
         }
-        const steer = active
-            ? resolveEnvironment(active.environmentId).requests.steer
-            : undefined;
-        const result = (steer
-            ? await steer(requestId, { steerId, text })
-            : active?.requestSteering.append({ steerId, text })) ??
-            { ok: false, reason: "request_not_active" };
-        return result.ok
-            ? {
-                type: "steer_ack",
-                requestId,
-                steerId,
-                accepted: true,
-                acceptedSequence: result.update.sequence,
-            }
-            : {
-                type: "steer_ack",
-                requestId,
-                steerId,
-                accepted: false,
-                reason: result.reason,
-            };
     }
     resolveToolApproval(message) {
         this.toolApprovals.resolveRealtime(message);

package/dist/src/web-ui/local-runtime/runtime-setup-connection-edit.d.ts

@@ -1,3 +1,4 @@
+import { type RuntimeSetupCredentialWrite } from "./runtime-setup-credentials.js";
 import { type RuntimeSetupInput } from "./runtime-setup-input.js";
 import { type RuntimeSetupDraft } from "./runtime-setup-draft.js";
 /** Applies only fields owned by the unfinished wizard, retaining optional-step edits. */
@@ -7,6 +8,7 @@ export declare function editRuntimeSetupConnection(params: {
     draft: RuntimeSetupDraft;
     input: RuntimeSetupInput;
     credentialChanged: boolean;
+    credentialWrite: RuntimeSetupCredentialWrite;
 }): Promise<{
     draft: RuntimeSetupDraft;
     embeddingInvalidated: boolean;

package/dist/src/web-ui/local-runtime/runtime-setup-connection-edit.js

@@ -1,3 +1,5 @@
+import { commitRuntimeSetupEdit } from "./runtime-setup-edit-transaction.js";
+import { withPlannedRuntimeSetupCredentials, } from "./runtime-setup-credentials.js";
 import { randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -80,30 +82,41 @@ export async function editRuntimeSetupConnection(params) {
                 modelConfig,
                 ownedProviders: retained.ownedProviders,
             };
-            let modelWritten = false;
-            let configWritten = false;
-            try {
-                await modelTransaction.write(modelConfig, {
-                    expectedConfig: params.draft.modelConfig,
-                });
-                modelWritten = true;
-                await configTransaction.write(config, {
-                    expectedConfig: source.config,
-                });
-                configWritten = true;
-                await writeRuntimeSetupDraft(nextDraft);
-            }
-            catch (error) {
-                if (configWritten)
-                    await configTransaction.write(source.config, {
-                        expectedConfig: config,
+            await withPlannedRuntimeSetupCredentials(params.credentialWrite, async (credentials) => {
+                const json = (value) => JSON.stringify(value, null, 2) + "\n";
+                await commitRuntimeSetupEdit(params.rootDir, [
+                    {
+                        role: "model",
+                        path: modelTransaction.path,
+                        text: json(modelConfig),
+                    },
+                    {
+                        role: "config",
+                        path: configTransaction.path,
+                        text: json(config),
+                    },
+                    {
+                        role: "receipt",
+                        path: configTransaction.path + ".web-setup.json",
+                        text: json(nextDraft),
+                    },
+                    {
+                        role: "credentials",
+                        path: credentials.path,
+                        text: credentials.text,
+                        mode: 0o600,
+                    },
+                ], async () => {
+                    await modelTransaction.write(modelConfig, {
+                        expectedConfig: params.draft.modelConfig,
                     });
-                if (modelWritten)
-                    await modelTransaction.write(params.draft.modelConfig, {
-                        expectedConfig: modelConfig,
+                    await configTransaction.write(config, {
+                        expectedConfig: source.config,
                     });
-                throw error;
-            }
+                    await writeRuntimeSetupDraft(nextDraft);
+                    await credentials.write();
+                }, credentials.publish);
+            });
             return { draft: nextDraft, embeddingInvalidated };
         });
     });

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.d.ts

@@ -0,0 +1,13 @@
+import type { ModelContextCapacityIssue } from "../../runtime/config/model-context-capacity.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { type PublicContextWindowIssue } from "./model-context-capacity-error.js";
+export type RuntimeSetupContextWindowIssue = PublicContextWindowIssue;
+export declare class RuntimeSetupContextWindowError extends RuntimeSetupError {
+    readonly contextWindow: RuntimeSetupContextWindowIssue;
+    constructor(issue: ModelContextCapacityIssue, environmentId?: string);
+}
+/** Project only known capacity evidence; other exceptions keep their redaction. */
+export declare function throwRuntimeSetupValidationError(error: unknown, environmentId?: string): never;
+export declare function runtimeSetupContextWindowErrorDetails(error: unknown): {
+    contextWindow?: RuntimeSetupContextWindowIssue;
+};

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.js

@@ -0,0 +1,21 @@
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { modelContextCapacityMessage, publicContextWindowIssue, readModelContextCapacityIssue, } from "./model-context-capacity-error.js";
+export class RuntimeSetupContextWindowError extends RuntimeSetupError {
+    contextWindow;
+    constructor(issue, environmentId) {
+        super("context_window_too_small", modelContextCapacityMessage(issue));
+        this.contextWindow = publicContextWindowIssue(issue, environmentId);
+    }
+}
+/** Project only known capacity evidence; other exceptions keep their redaction. */
+export function throwRuntimeSetupValidationError(error, environmentId) {
+    const issue = readModelContextCapacityIssue(error, "default");
+    if (!issue)
+        throw error;
+    throw new RuntimeSetupContextWindowError(issue, environmentId);
+}
+export function runtimeSetupContextWindowErrorDetails(error) {
+    if (!(error instanceof RuntimeSetupContextWindowError))
+        return {};
+    return { contextWindow: error.contextWindow };
+}

package/dist/src/web-ui/local-runtime/runtime-setup-credentials.d.ts

@@ -1,4 +1,8 @@
-type RuntimeSetupCredentialWrite = {
+type CredentialFileSnapshot = {
+    raw?: string;
+    mode: number;
+};
+export type RuntimeSetupCredentialWrite = {
     rootDir: string;
     configPath: string;
     apiKey?: string;
@@ -9,6 +13,16 @@ export declare function readRuntimeSetupCredential(rootDir: string, apiKeyEnv?:
 export declare function assertRuntimeSetupCredentialFile(rootDir: string): Promise<void>;
 export declare function hasRuntimeSetupCredential(rootDir: string, apiKeyEnv?: string): Promise<boolean>;
 export declare function persistRuntimeSetupCredentials(params: RuntimeSetupCredentialWrite): Promise<void>;
+export type RuntimeSetupCredentialPlan = Readonly<{
+    rootDir: string;
+    path: string;
+    text: string;
+    previous: CredentialFileSnapshot;
+    write: () => Promise<void>;
+    publish: () => void;
+}>;
+/** Publish process credentials only after the caller's complete transaction commits. */
+export declare function withPlannedRuntimeSetupCredentials<T>(params: RuntimeSetupCredentialWrite, operation: (plan: RuntimeSetupCredentialPlan) => Promise<T>): Promise<T>;
 /** Keep the credential private and locked until the related setup commit settles. */
 export declare function commitRuntimeSetupCredentials<T>(params: RuntimeSetupCredentialWrite, commit: () => Promise<T>): Promise<T>;
 export {};