@cuna_labs/cli 0.1.0

package/dist/api/client.js

@@ -0,0 +1,937 @@
+import { providerSessionBody, decodeProviderPresets, decodeProviderObservation, decodeProviderSession } from "./provider-v2.js";
+import { EXIT_CODES, CunaError, usageError } from "../core/errors.js";
+import { MACHINE_CREATE_REQUEST_BUDGET_MS, MACHINE_LIFECYCLE_REQUEST_BUDGET_MS, SUPERVISOR_LIVE_UPDATE_REQUEST_BUDGET_MS, } from "../core/observation-budget.js";
+import { OFF_CONTRACT_RESPONSE_HINT } from "../core/product-web.js";
+import { ContractViolation, assertCanonicalUuid, assertIdempotencyKey, assertSafeDisplayText, contractViolation, encodeCanonicalUuid, encodeMachineId, } from "../core/validation.js";
+import { decodeAuditRecords, decodeAgentSessionAuth, decodeAgentSessionAuthLogout, decodeAgentSessionItem, decodeAgentSessionPage, decodeAgentSessionTerminalSeat, decodeApiKeyList, decodeApiKeyCreation, decodeCapabilitySnapshot, decodeMachineAuthorizations, decodeMachineItem, decodeMachineCreateRequest, decodeMachinePage, decodeOk, decodeCunaIdentity, decodeTerminalConnectionGrant, decodeTerminalConnectionCancellation, decodeTerminalWriterState, decodeWorkspaceBindingAuthority, TERMINAL_PROTOCOL, } from "./contracts.js";
+import { decodeSupervisorLiveUpdate, decodeSupervisorLiveUpdateOperation, } from "./supervisor-live-update.js";
+import { decodeExecutionWorkspacePage } from "./execution-workspaces.js";
+import { decodeManagedExecution, decodeManagedExecutionPage } from "./managed-executions.js";
+import { decodeManagedCommandResult } from "./managed-executions.js";
+import { decodeMachineDefaultWorkspace, decodeAgentSessionWorkspaceContext, decodeAgentSessionWorkspaceEnvelope } from "./remote-workspace.js";
+import { classifyCapabilitySnapshot, isPermanentSnapshotFault } from "./capability-evidence.js";
+/**
+ * `${method} ${path}` for the request that produced a body.
+ *
+ * Derived from the request object that was actually dispatched, never written
+ * beside it, so the operation the error names and the operation the transport
+ * sent cannot disagree. The path may carry identifiers, but only ones the caller
+ * supplied in this same invocation — no response value ever reaches here.
+ */
+function operationLabel(request) {
+    return `${request.method} ${request.path}`;
+}
+/**
+ * Build the malformed-response error, preserving what the decoder knew.
+ *
+ * WHAT `details` MAY CARRY. `operation`, `field` and `predicate` — a request
+ * label the CLI built, a key path the CLI asked for, and a token from this
+ * source tree. No response value, no fragment of one, and not its length: a
+ * `/v1/me` body holds an email address and an `/v1/api-keys` body holds key
+ * metadata, so echoing "what we got" would turn a diagnostic into a disclosure.
+ * That is why the decoders report a PREDICATE and not a comparison.
+ */
+function malformed(cause, operation) {
+    const violation = cause instanceof ContractViolation ? cause : undefined;
+    return new CunaError({
+        code: "cuna.remote.malformed_response",
+        message: "Cuna returned a response that does not match the public contract.",
+        exitCode: EXIT_CODES.remote,
+        hint: OFF_CONTRACT_RESPONSE_HINT,
+        details: {
+            operation,
+            ...(violation?.field === undefined ? {} : { field: violation.field }),
+            // A non-`ContractViolation` cause is a decoder that has not been converted
+            // or a genuine bug; it is reported as such rather than guessed at.
+            predicate: violation?.predicate ?? "contract_decode_failed",
+        },
+        cause,
+    });
+}
+function decode(decoder, value, operation) {
+    try {
+        return decoder(value);
+    }
+    catch (error) {
+        if (error instanceof CunaError)
+            throw error;
+        throw malformed(error, operation);
+    }
+}
+function assertAgentSessionBinding(session, expected, operation) {
+    const mismatch = expected.id !== undefined && session.id !== expected.id
+        ? "id"
+        : expected.machineId !== undefined && session.machineId !== expected.machineId
+            ? "machine_id"
+            : expected.workspaceBindingId !== undefined &&
+                session.workspaceBindingId !== expected.workspaceBindingId
+                ? "workspace_binding_id"
+                : expected.workspaceGeneration !== undefined &&
+                    session.workspaceGeneration !== expected.workspaceGeneration
+                    ? "workspace_generation"
+                    : undefined;
+    if (mismatch !== undefined) {
+        throw malformed(contractViolation("matches_requested_resource", mismatch), operation);
+    }
+    return session;
+}
+function containsAsciiControl(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function validatePageOptions(options, resource = "AgentSession") {
+    if (options.limit !== undefined &&
+        (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100)) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: `${resource} page limit must be an integer from 1 through 100.`,
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (options.cursor !== undefined &&
+        (options.cursor.length < 1 || options.cursor.length > 512 || containsAsciiControl(options.cursor))) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: `${resource} cursor is malformed.`,
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    return Object.freeze({
+        ...(options.limit === undefined ? {} : { limit: String(options.limit) }),
+        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+    });
+}
+function validateAgentSessionCreate(input) {
+    if (!Number.isSafeInteger(input.workspaceGeneration) || input.workspaceGeneration < 1) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "AgentSession workspace generation must be a positive safe integer.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.name !== undefined && (input.name.length < 1 || input.name.length > 80)) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "AgentSession name must contain 1 through 80 characters.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (!input.cwd.startsWith("/workspace") ||
+        (input.cwd !== "/workspace" && !input.cwd.startsWith("/workspace/")) ||
+        input.cwd.length > 1024 ||
+        input.cwd.split("/").includes("..")) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "AgentSession cwd must be a safe absolute path inside /workspace.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.agent === "opencode" &&
+        (input.authMode !== "interactive_login" || input.credentialBindingId !== undefined)) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "OpenCode AgentSessions require interactive_login and do not accept a credential binding.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.authMode === "credential_binding" && input.credentialBindingId === undefined) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "credential_binding auth mode requires a credential binding ID.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.authMode !== "credential_binding" && input.credentialBindingId !== undefined) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "A credential binding ID requires credential_binding auth mode.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.credentialBindingId !== undefined) {
+        assertCanonicalUuid(input.credentialBindingId, "credential binding ID");
+    }
+}
+function validateMachineCreate(input, idempotencyKey) {
+    assertIdempotencyKey(idempotencyKey);
+    assertSafeDisplayText(input.name, "machine name");
+    if (input.name.length < 1 || input.name.length > 80) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "Machine name must contain 1 through 80 characters.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.vcpus !== undefined && (!Number.isInteger(input.vcpus) || input.vcpus < 1 || input.vcpus > 8)) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "Machine vcpus must be an integer from 1 through 8.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+    if (input.memoryMiB !== undefined &&
+        (!Number.isInteger(input.memoryMiB) || input.memoryMiB < 512 || input.memoryMiB > 16_384)) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "Machine memoryMiB must be an integer from 512 through 16384.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+}
+function validateWorkspaceBindingIdentity(input) {
+    if (input.executionWorkspaceId !== undefined)
+        assertCanonicalUuid(input.executionWorkspaceId, "execution workspace ID");
+    assertCanonicalUuid(input.workspaceId, "workspace ID");
+    assertCanonicalUuid(input.projectId, "project ID");
+    assertCanonicalUuid(input.localInstanceId, "local instance ID");
+    assertCanonicalUuid(input.machineId, "machine ID");
+    if (!/^[0-9a-f]{64}$/u.test(input.exclusionPolicyDigest)) {
+        throw new CunaError({
+            code: "cuna.usage.invalid",
+            message: "Workspace exclusion policy digest must be a lowercase SHA-256 digest.",
+            exitCode: EXIT_CODES.usage,
+        });
+    }
+}
+function workspaceBindingIdentityMatches(actual, expected) {
+    return actual.workspaceId === expected.workspaceId &&
+        (expected.executionWorkspaceId === undefined || actual.executionWorkspaceId === expected.executionWorkspaceId) &&
+        actual.projectId === expected.projectId &&
+        actual.localInstanceId === expected.localInstanceId &&
+        actual.machineId === expected.machineId &&
+        actual.exclusionPolicyDigest === expected.exclusionPolicyDigest;
+}
+export function createCunaApiClient(transport) {
+    /**
+     * Dispatch one request and decode its body under that request's identity.
+     *
+     * Every decode in this client goes through here, so an off-contract body can
+     * no longer produce an error that fails to say which operation produced it.
+     * Passing the operation as a second literal beside each call was the obvious
+     * alternative and was rejected: it is a second authority for a fact the
+     * request object already holds, and it would drift on the first path edit.
+     */
+    async function fetchDecoded(request, decoder) {
+        return decode(decoder, await transport.request(request), operationLabel(request));
+    }
+    const client = {
+        async getIdentity(signal) {
+            return fetchDecoded({ method: "GET", path: "/v1/me", ...(signal === undefined ? {} : { signal }) }, decodeCunaIdentity);
+        },
+        async discoverCapabilities(scope, resourceId, signal) {
+            return fetchDecoded({
+                method: "GET",
+                path: "/v1/capabilities",
+                query: { scope, resource_id: resourceId },
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeCapabilitySnapshot);
+        },
+        async listMachines(signal) {
+            return fetchDecoded({
+                method: "GET",
+                path: "/v1/sessions",
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeMachinePage);
+        },
+        async getMachine(id, signal) {
+            const safeId = encodeMachineId(id);
+            const request = {
+                method: "GET",
+                path: `/v1/sessions/${safeId}`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const machine = await fetchDecoded(request, decodeMachineItem);
+            if (machine.id !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "id"), operationLabel(request));
+            }
+            return machine;
+        },
+        async listRecords() {
+            return fetchDecoded({ method: "GET", path: "/v1/records" }, decodeAuditRecords);
+        },
+        async listAuthorizations(machineId) {
+            const safeId = encodeMachineId(machineId);
+            return fetchDecoded({ method: "GET", path: `/v1/sessions/${safeId}/authorizations` }, decodeMachineAuthorizations);
+        },
+        async listApiKeys() {
+            return fetchDecoded({ method: "GET", path: "/v1/api-keys" }, decodeApiKeyList);
+        },
+        async createApiKey(input, idempotencyKey, signal) {
+            assertIdempotencyKey(idempotencyKey);
+            return fetchDecoded({
+                method: "POST",
+                path: "/v1/api-keys",
+                idempotencyKey,
+                settleWith: "cuna api-keys list",
+                body: {
+                    name: input.name,
+                    ...(input.expiresAt === undefined ? {} : { expires_at: input.expiresAt }),
+                },
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeApiKeyCreation);
+        },
+        async revokeApiKey(id) {
+            const safeId = encodeCanonicalUuid(id, "API key ID");
+            return fetchDecoded({ method: "DELETE", path: `/v1/api-keys/${safeId}`, settleWith: "cuna api-keys list" }, decodeOk);
+        },
+        async createMachine(input, idempotencyKey, requestId, signal) {
+            validateMachineCreate(input, idempotencyKey);
+            if (requestId !== undefined)
+                assertCanonicalUuid(requestId, "machine create request ID");
+            const body = {
+                name: input.name,
+                ...(input.agent === undefined ? {} : { agent: input.agent }),
+                ...(input.vcpus === undefined ? {} : { vcpus: input.vcpus }),
+                ...(input.memoryMiB === undefined ? {} : { memory_mib: input.memoryMiB }),
+                ...(input.background === undefined ? {} : { background: input.background }),
+            };
+            return fetchDecoded({
+                method: "POST",
+                path: "/v1/sessions",
+                body,
+                idempotencyKey,
+                // The producer provisions a real machine inside this request, so the
+                // budget that suits a list is not the budget that suits this. D1: the
+                // value is a named constant, not a literal repeated here.
+                budgetMs: MACHINE_CREATE_REQUEST_BUDGET_MS,
+                settleWith: "cuna machines list",
+                ...(requestId === undefined ? {} : { machineCreateRequestId: requestId }),
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeMachineItem);
+        },
+        async getMachineCreateRequest(id, signal) {
+            const safeId = encodeCanonicalUuid(id, "machine create request ID");
+            const httpRequest = {
+                method: "GET",
+                path: `/v1/machine-creates/${safeId}`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const request = await fetchDecoded(httpRequest, decodeMachineCreateRequest);
+            if (request.id !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "id"), operationLabel(httpRequest));
+            }
+            return request;
+        },
+        async reconcileMachineCreateRequest(id, signal) {
+            const safeId = encodeCanonicalUuid(id, "machine create request ID");
+            const httpRequest = {
+                method: "POST",
+                path: `/v1/machine-creates/${safeId}/reconcile`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const request = await fetchDecoded(httpRequest, decodeMachineCreateRequest);
+            if (request.id !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "id"), operationLabel(httpRequest));
+            }
+            return request;
+        },
+        async transitionMachine(id, action, signal) {
+            const safeId = encodeMachineId(id);
+            const request = {
+                method: "POST",
+                path: `/v1/sessions/${safeId}/${action}`,
+                settleWith: "cuna machines list",
+                // A start boots a VM and waits for its supervisor; the list budget
+                // aborted the journey's own step at 15 s and told the caller the
+                // operation "may have completed".
+                budgetMs: MACHINE_LIFECYCLE_REQUEST_BUDGET_MS,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const machine = await fetchDecoded(request, decodeMachineItem);
+            if (machine.id !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "id"), operationLabel(request));
+            }
+            return machine;
+        },
+        async replaceMachineSupervisor(id, signal) {
+            const safeId = encodeMachineId(id);
+            const request = {
+                method: "POST",
+                path: `/v1/sessions/${safeId}/supervisor/replace`,
+                settleWith: "cuna machines list",
+                budgetMs: MACHINE_LIFECYCLE_REQUEST_BUDGET_MS,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const machine = await fetchDecoded(request, decodeMachineItem);
+            if (machine.id !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "id"), operationLabel(request));
+            }
+            return machine;
+        },
+        async updateMachineSupervisorInPlace(id, operationId, signal) {
+            const safeId = encodeMachineId(id);
+            assertCanonicalUuid(operationId, "supervisor update operation ID");
+            const request = {
+                method: "POST",
+                path: `/v1/sessions/${safeId}/supervisor/live-update`,
+                // Chosen by the caller before this line, recorded durably before this
+                // line, and the reason a lost answer is recoverable at all. The producer
+                // journals it before it issues any enrollment, so the same value never
+                // rotates control twice.
+                body: { operation_id: operationId },
+                // The read that settles this operation's outcome without spending
+                // anything, and the only one that answers what this update did.
+                settleWith: `cuna machines live-update-status ${id} --operation ${operationId}`,
+                budgetMs: SUPERVISOR_LIVE_UPDATE_REQUEST_BUDGET_MS,
+                // Still off, and now for a sharper reason than before. The identity
+                // above makes a repeat SAFE on the producer's side, but it must remain
+                // a DECISION: `machines live-update-supervisor --resume` is that
+                // decision, taken by a person who has read the operation. A transport
+                // re-dispatch happens below the command, below the local record and
+                // below the person, so it would be the one repetition nobody chose.
+                automaticRedispatch: false,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const result = await fetchDecoded(request, decodeSupervisorLiveUpdate);
+            // The path id is the Machine, so the Machine in the body must be the one
+            // that was asked about. Without this, a producer answering about a sibling
+            // would have its control generation and artifact digest reported as this
+            // Machine's. The operation identity is checked for the same reason: an
+            // answer about another operation is not an answer about this one, and the
+            // caller is about to settle a durable record against it.
+            if (result.machine.id !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "machine.id"), operationLabel(request));
+            }
+            if (result.operationId !== operationId) {
+                throw malformed(contractViolation("matches_requested_operation", "operation_id"), operationLabel(request));
+            }
+            return result;
+        },
+        async readMachineSupervisorInPlaceUpdate(id, operationId, signal) {
+            const safeId = encodeMachineId(id);
+            const safeOperationId = encodeCanonicalUuid(operationId, "supervisor update operation ID");
+            const request = {
+                method: "GET",
+                path: `/v1/sessions/${safeId}/supervisor/live-update/${safeOperationId}`,
+                // A database read scoped to the owner and this Machine. It dispatches no
+                // installer and writes nothing, so the ordinary read budget applies and
+                // an automatic re-dispatch of it costs nothing.
+                settleWith: `cuna machines live-update-status ${id} --operation ${operationId}`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const operation = await fetchDecoded(request, decodeSupervisorLiveUpdateOperation);
+            if (operation.machineId !== id || operation.operationId !== operationId) {
+                throw malformed(contractViolation("matches_requested_operation", "operation_id"), operationLabel(request));
+            }
+            return operation;
+        },
+        async deleteMachine(id) {
+            const safeId = encodeMachineId(id);
+            return transport.request({
+                method: "DELETE",
+                path: `/v1/sessions/${safeId}`,
+                settleWith: "cuna machines list",
+            });
+        },
+        async executeManagedCommand(machineId, operationId, input, signal) {
+            const safeId = encodeMachineId(machineId);
+            assertCanonicalUuid(operationId, "execution ID");
+            if (typeof input.command !== "string" || input.command.length === 0 || input.command.includes("\0") ||
+                (input.args !== undefined && (!Array.isArray(input.args) || input.args.some(arg => typeof arg !== "string" || arg.includes("\0")))) ||
+                typeof input.cwd !== "string" ||
+                !/^\/workspace\/workspaces\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?:\/|$)/u.test(input.cwd) ||
+                input.cwd.includes("\\") || input.cwd.split("/").some(part => part === "." || part === "..") || /[\p{Cc}\p{Cf}]/u.test(input.cwd) ||
+                (input.timeoutSecs !== undefined && (!Number.isSafeInteger(input.timeoutSecs) || input.timeoutSecs < 1 || input.timeoutSecs > 600))) {
+                throw usageError("Invalid managed command request.", "Choose an exact remote Workspace path and a timeout from 1 to 600 seconds.");
+            }
+            const body = { operation_id: operationId, command: input.command,
+                ...(input.args === undefined ? {} : { args: [...input.args] }), cwd: input.cwd,
+                ...(input.timeoutSecs === undefined ? {} : { timeout_secs: input.timeoutSecs }) };
+            if (Buffer.byteLength(JSON.stringify(body)) > 8 * 1024 * 1024)
+                throw usageError("Managed command request exceeds 8 MiB.");
+            const request = { method: "POST", path: `/v1/sessions/${safeId}/exec`, body,
+                budgetMs: (input.timeoutSecs ?? 120) * 1000 + 5000,
+                settleWith: `cuna executions get ${operationId} --machine ${machineId}`,
+                ...(signal === undefined ? {} : { signal }) };
+            return fetchDecoded(request, decodeManagedCommandResult);
+        },
+        async listManagedExecutions(machineId, input = {}, signal) {
+            const safeId = encodeMachineId(machineId);
+            const query = new URLSearchParams();
+            if (input.executionWorkspaceId !== undefined)
+                query.set("execution_workspace_id", assertCanonicalUuid(input.executionWorkspaceId, "execution Workspace ID"));
+            if (input.after !== undefined)
+                query.set("after", assertCanonicalUuid(input.after, "execution cursor"));
+            const request = { method: "GET", path: `/v1/sessions/${safeId}/executions${query.size ? `?${query}` : ""}`,
+                ...(signal === undefined ? {} : { signal }) };
+            const page = await fetchDecoded(request, decodeManagedExecutionPage);
+            if (page.machineId !== machineId || page.items.some(item => (input.executionWorkspaceId !== undefined && item.executionWorkspaceId !== input.executionWorkspaceId) ||
+                (input.after !== undefined && item.operationId <= input.after))) {
+                throw malformed(contractViolation("managed_execution_scope"), operationLabel(request));
+            }
+            return page;
+        },
+        async getManagedExecution(machineId, operationId, signal) {
+            const path = `/v1/sessions/${encodeMachineId(machineId)}/executions/${encodeCanonicalUuid(operationId, "execution ID")}`;
+            const request = { method: "GET", path, ...(signal === undefined ? {} : { signal }) };
+            const result = await fetchDecoded(request, decodeManagedExecution);
+            if (result.machineId !== machineId || result.operationId !== operationId)
+                throw malformed(contractViolation("managed_execution_scope"), operationLabel(request));
+            return result;
+        },
+        async cancelManagedExecution(machineId, operationId, signal) {
+            const path = `/v1/sessions/${encodeMachineId(machineId)}/executions/${encodeCanonicalUuid(operationId, "execution ID")}/cancel`;
+            const request = { method: "POST", path, body: {},
+                settleWith: `cuna executions get ${operationId} --machine ${machineId}`, ...(signal === undefined ? {} : { signal }) };
+            const result = await fetchDecoded(request, decodeManagedExecution);
+            if (result.machineId !== machineId || result.operationId !== operationId || !result.cancelRequested) {
+                throw malformed(contractViolation("managed_execution_cancellation"), operationLabel(request));
+            }
+            return result;
+        },
+        async listExecutionWorkspaces(input, signal) {
+            assertCanonicalUuid(input.workspaceId, "workspace ID");
+            assertCanonicalUuid(input.projectId, "project ID");
+            assertCanonicalUuid(input.machineId, "machine ID");
+            if (input.after !== undefined)
+                assertCanonicalUuid(input.after, "execution workspace cursor");
+            const query = new URLSearchParams({ workspace_id: input.workspaceId, project_id: input.projectId, machine_id: input.machineId });
+            if (input.after !== undefined)
+                query.set("after", input.after);
+            const request = { method: "GET", path: `/v1/execution-workspaces?${query}`, ...(signal === undefined ? {} : { signal }) };
+            const page = await fetchDecoded(request, decodeExecutionWorkspacePage);
+            if (page.items.some(row => row.workspaceId !== input.workspaceId || row.projectId !== input.projectId || row.machineId !== input.machineId ||
+                (input.after !== undefined && row.executionWorkspaceId <= input.after))) {
+                throw malformed(contractViolation("execution_workspace_scope"), operationLabel(request));
+            }
+            return page;
+        },
+        async createWorkspaceBinding(input, idempotencyKey, signal) {
+            validateWorkspaceBindingIdentity(input);
+            assertIdempotencyKey(idempotencyKey);
+            if (!Array.isArray(input.excludedPrefixes) || input.excludedPrefixes.length > 10_000) {
+                throw new CunaError({ code: "cuna.usage.invalid", message: "Workspace excluded prefixes are invalid.", exitCode: EXIT_CODES.usage });
+            }
+            const prefixes = input.excludedPrefixes.map((prefix) => {
+                if (typeof prefix !== "string" || prefix.length < 1 || prefix.length > 4_096 ||
+                    prefix.startsWith("/") || prefix.startsWith("\\") || prefix.includes("\\") ||
+                    containsAsciiControl(prefix) || /^[A-Za-z]:/u.test(prefix) ||
+                    prefix.split("/").some((part) => part === "" || part === "." || part === "..")) {
+                    throw new CunaError({ code: "cuna.usage.invalid", message: "Workspace excluded prefixes are invalid.", exitCode: EXIT_CODES.usage });
+                }
+                return prefix;
+            });
+            if (new Set(prefixes).size !== prefixes.length) {
+                throw new CunaError({ code: "cuna.usage.invalid", message: "Workspace excluded prefixes must be unique.", exitCode: EXIT_CODES.usage });
+            }
+            const request = {
+                method: "POST",
+                path: "/v1/workspace-bindings",
+                idempotencyKey,
+                body: {
+                    workspace_id: input.workspaceId,
+                    project_id: input.projectId,
+                    local_instance_id: input.localInstanceId,
+                    machine_id: input.machineId,
+                    ...(input.executionWorkspaceId === undefined ? {} : { execution_workspace_id: input.executionWorkspaceId }),
+                    exclusion_policy_digest: input.exclusionPolicyDigest,
+                    excluded_prefixes: prefixes,
+                },
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const authority = await fetchDecoded(request, decodeWorkspaceBindingAuthority);
+            if (!workspaceBindingIdentityMatches(authority, input)) {
+                throw malformed(contractViolation("matches_requested_resource", "workspace_id"), operationLabel(request));
+            }
+            return authority;
+        },
+        async getWorkspaceBinding(bindingId, identity, signal) {
+            const safeId = encodeCanonicalUuid(bindingId, "workspace binding ID");
+            validateWorkspaceBindingIdentity(identity);
+            const request = {
+                method: "GET",
+                path: `/v1/workspace-bindings/${safeId}`,
+                query: {
+                    workspace_id: identity.workspaceId,
+                    project_id: identity.projectId,
+                    local_instance_id: identity.localInstanceId,
+                    machine_id: identity.machineId,
+                    exclusion_policy_digest: identity.exclusionPolicyDigest,
+                },
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const authority = await fetchDecoded(request, decodeWorkspaceBindingAuthority);
+            if (authority.bindingId !== bindingId) {
+                throw malformed(contractViolation("matches_requested_resource", "binding_id"), operationLabel(request));
+            }
+            if (!workspaceBindingIdentityMatches(authority, identity)) {
+                throw malformed(contractViolation("matches_requested_resource", "workspace_id"), operationLabel(request));
+            }
+            return authority;
+        },
+        async listAgentSessions(machineId, options = {}, signal) {
+            const safeId = encodeMachineId(machineId);
+            const query = validatePageOptions(options);
+            const request = {
+                method: "GET",
+                path: `/v1/sessions/${safeId}/agent-sessions`,
+                query,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const page = await fetchDecoded(request, decodeAgentSessionPage);
+            for (const session of page.items) {
+                assertAgentSessionBinding(session, { machineId }, operationLabel(request));
+            }
+            return page;
+        },
+        async createAgentSession(machineId, input, idempotencyKey, signal) {
+            const safeId = encodeMachineId(machineId);
+            assertCanonicalUuid(input.workspaceBindingId, "workspace binding ID");
+            validateAgentSessionCreate(input);
+            const request = {
+                method: "POST",
+                path: `/v1/sessions/${safeId}/agent-sessions`,
+                settleWith: `cuna agent-sessions list --machine ${machineId}`,
+                body: {
+                    ...(input.name === undefined ? {} : { name: input.name }),
+                    agent: input.agent,
+                    cwd: input.cwd,
+                    workspace_binding_id: input.workspaceBindingId,
+                    workspace_generation: input.workspaceGeneration,
+                    ...(input.authMode === undefined ? {} : { auth_mode: input.authMode }),
+                    ...(input.credentialBindingId === undefined
+                        ? {}
+                        : { credential_binding_id: input.credentialBindingId }),
+                },
+                idempotencyKey,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            return assertAgentSessionBinding(await fetchDecoded(request, decodeAgentSessionItem), {
+                machineId,
+                workspaceBindingId: input.workspaceBindingId,
+                workspaceGeneration: input.workspaceGeneration,
+            }, operationLabel(request));
+        },
+        async getProviderPresetsV2(signal) {
+            return fetchDecoded({ method: "POST", path: "/v1/collaboration/2/provider-profiles/catalog", body: { version: "2" }, ...(signal === undefined ? {} : { signal }) }, decodeProviderPresets);
+        },
+        async createProviderSessionV2(machineId, input, signal) {
+            assertCanonicalUuid(input.operation_id, "operation ID");
+            assertCanonicalUuid(input.profile_id, "profile ID");
+            return fetchDecoded({ method: "POST", path: `/v1/collaboration/2/sessions/${encodeMachineId(machineId)}/workspace-agent-sessions`, body: providerSessionBody(input), ...(signal === undefined ? {} : { signal }) }, value => decodeProviderSession(value, machineId, input));
+        },
+        async checkProviderV2(sessionId, epoch, signal) {
+            return fetchDecoded({ method: "POST", path: `/v1/collaboration/2/agent-sessions/${encodeCanonicalUuid(sessionId, "AgentSession ID")}/provider-observations`, body: { version: "2" }, ...(signal === undefined ? {} : { signal }) }, value => decodeProviderObservation(value, sessionId, epoch));
+        },
+        async getMachineDefaultWorkspace(machineId, signal) {
+            const request = { method: "GET", path: `/v1/sessions/${encodeMachineId(machineId)}/default-workspace`, ...(signal === undefined ? {} : { signal }) };
+            const workspace = await fetchDecoded(request, decodeMachineDefaultWorkspace);
+            if (workspace.machineId !== machineId)
+                throw malformed(contractViolation("matches_requested_resource", "machine_id"), operationLabel(request));
+            return workspace;
+        },
+        async getAgentSessionWorkspaceContext(id, signal) {
+            const request = { method: "GET", path: `/v1/agent-sessions/${encodeCanonicalUuid(id, "AgentSession ID")}/workspace-context`, ...(signal === undefined ? {} : { signal }) };
+            const context = await fetchDecoded(request, decodeAgentSessionWorkspaceContext);
+            if (context.agentSessionId !== id)
+                throw malformed(contractViolation("matches_requested_resource", "agent_session_id"), operationLabel(request));
+            return context;
+        },
+        async createAgentSessionInWorkspace(machineId, input, idempotencyKey, signal) {
+            const safeId = encodeMachineId(machineId);
+            assertCanonicalUuid(input.executionWorkspaceId, "execution Workspace ID");
+            assertIdempotencyKey(idempotencyKey);
+            validateAgentSessionCreate(input);
+            const root = `/workspace/workspaces/${input.executionWorkspaceId}`;
+            if ((input.cwd !== root && !input.cwd.startsWith(`${root}/`)) || input.cwd.includes("\\") || input.cwd.split("/").includes(".") ||
+                input.agent === "openclaw" || input.authMode !== "interactive_login" || input.credentialBindingId !== undefined) {
+                throw new CunaError({ code: "cuna.usage.invalid", message: "Remote Workspace sessions require their exact remote path and interactive agent login.", exitCode: EXIT_CODES.usage });
+            }
+            const request = { method: "POST", path: `/v1/sessions/${safeId}/workspace-agent-sessions`, idempotencyKey,
+                settleWith: `cuna agent-sessions list --machine ${machineId}`, body: { ...(input.name === undefined ? {} : { name: input.name }), agent: input.agent, cwd: input.cwd,
+                    execution_workspace_id: input.executionWorkspaceId, workspace_generation: input.workspaceGeneration, auth_mode: input.authMode }, ...(signal === undefined ? {} : { signal }) };
+            const result = await fetchDecoded(request, decodeAgentSessionWorkspaceEnvelope);
+            if (result.agentSession.machineId !== machineId || result.executionWorkspaceId !== input.executionWorkspaceId || result.workspaceGeneration !== input.workspaceGeneration ||
+                result.agentSession.cwd !== input.cwd || result.agentSession.agent !== input.agent || result.agentSession.authMode !== input.authMode) {
+                throw malformed(contractViolation("matches_requested_resource", "execution_workspace_id"), operationLabel(request));
+            }
+            return result;
+        },
+        async inspectAgentSessionCreate(idempotencyKey, signal) {
+            assertIdempotencyKey(idempotencyKey);
+            return fetchDecoded({
+                method: "GET",
+                path: "/v1/agent-session-creates",
+                idempotencyKey,
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeAgentSessionItem);
+        },
+        async getAgentSession(id, signal) {
+            const safeId = encodeCanonicalUuid(id, "AgentSession ID");
+            const request = {
+                method: "GET",
+                path: `/v1/agent-sessions/${safeId}`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            return assertAgentSessionBinding(await fetchDecoded(request, decodeAgentSessionItem), { id }, operationLabel(request));
+        },
+        async getAgentSessionAuth(id, signal) {
+            const safeId = encodeCanonicalUuid(id, "AgentSession ID");
+            const request = {
+                method: "GET",
+                path: `/v1/agent-sessions/${safeId}/agent-auth`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const status = await fetchDecoded(request, decodeAgentSessionAuth);
+            if (status.agentSessionId !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "agent_session_id"), operationLabel(request));
+            }
+            return status;
+        },
+        async getAgentSessionTerminalSeat(id, signal) {
+            const safeId = encodeCanonicalUuid(id, "AgentSession ID");
+            const request = {
+                method: "GET",
+                path: `/v1/agent-sessions/${safeId}/terminal`,
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const seat = await fetchDecoded(request, decodeAgentSessionTerminalSeat);
+            if (seat.agentSessionId !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "agent_session_id"), operationLabel(request));
+            }
+            return seat;
+        },
+        async logoutAgentSessionAuth(id, expectedProcessEpoch, signal) {
+            const safeId = encodeCanonicalUuid(id, "AgentSession ID");
+            const safeEpoch = assertCanonicalUuid(expectedProcessEpoch, "AgentSession process epoch");
+            const request = {
+                method: "POST",
+                path: `/v1/agent-sessions/${safeId}/agent-auth/logout`,
+                body: { process_epoch: safeEpoch },
+                ...(signal === undefined ? {} : { signal }),
+            };
+            const result = await fetchDecoded(request, decodeAgentSessionAuthLogout);
+            if (result.agentSessionId !== id) {
+                throw malformed(contractViolation("matches_requested_resource", "agent_session_id"), operationLabel(request));
+            }
+            if (result.processEpoch !== expectedProcessEpoch) {
+                throw malformed(contractViolation("matches_requested_resource", "process_epoch"), operationLabel(request));
+            }
+            return result;
+        },
+        async renameAgentSession(id, name) {
+            const safeId = encodeCanonicalUuid(id, "AgentSession ID");
+            if (name.length < 1 || name.length > 80) {
+                throw new CunaError({
+                    code: "cuna.usage.invalid",
+                    message: "AgentSession name must contain 1 through 80 characters.",
+                    exitCode: EXIT_CODES.usage,
+                });
+            }
+            const request = {
+                method: "PATCH",
+                path: `/v1/agent-sessions/${safeId}`,
+                settleWith: `cuna agent-sessions get ${id}`,
+                body: { name },
+            };
+            return assertAgentSessionBinding(await fetchDecoded(request, decodeAgentSessionItem), { id }, operationLabel(request));
+        },
+        async terminateAgentSession(id) {
+            const safeId = encodeCanonicalUuid(id, "AgentSession ID");
+            const request = {
+                method: "POST",
+                path: `/v1/agent-sessions/${safeId}/terminate`,
+                settleWith: `cuna agent-sessions get ${id}`,
+            };
+            return assertAgentSessionBinding(await fetchDecoded(request, decodeAgentSessionItem), { id }, operationLabel(request));
+        },
+        async createTerminalConnection(agentSessionId, input, idempotencyKey, signal) {
+            const safeId = encodeCanonicalUuid(agentSessionId, "AgentSession ID");
+            assertIdempotencyKey(idempotencyKey);
+            if (!/^[A-Za-z0-9._:-]{1,256}$/u.test(input.clientInstanceId)) {
+                throw new CunaError({
+                    code: "cuna.usage.invalid",
+                    message: "Terminal client instance ID is malformed.",
+                    exitCode: EXIT_CODES.usage,
+                });
+            }
+            if (input.resumeHandle !== undefined &&
+                !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(input.resumeHandle)) {
+                throw new CunaError({
+                    code: "cuna.usage.invalid",
+                    message: "Terminal resume handle must be a canonical Cuna UUID.",
+                    exitCode: EXIT_CODES.usage,
+                });
+            }
+            return fetchDecoded({
+                method: "POST",
+                path: `/v1/agent-sessions/${safeId}/terminal-connections`,
+                body: {
+                    protocol: input.protocol,
+                    client_instance_id: input.clientInstanceId,
+                    ...(input.resumeHandle === undefined ? {} : { resume_handle: input.resumeHandle }),
+                    ...(input.accessMode === undefined ? {} : { access_mode: input.accessMode }),
+                    ...(input.expectedWriterEpoch === undefined ? {} : { expected_writer_epoch: input.expectedWriterEpoch }),
+                },
+                idempotencyKey,
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeTerminalConnectionGrant);
+        },
+        async cancelTerminalConnection(agentSessionId, input, idempotencyKey, signal) {
+            const safeId = encodeCanonicalUuid(agentSessionId, "AgentSession ID");
+            assertIdempotencyKey(idempotencyKey);
+            if (input.protocol !== TERMINAL_PROTOCOL || !/^[A-Za-z0-9._:-]{1,256}$/u.test(input.clientInstanceId) ||
+                (input.accessMode !== undefined && !["writer", "observer"].includes(input.accessMode)) ||
+                (input.expectedWriterEpoch !== undefined && (!Number.isSafeInteger(input.expectedWriterEpoch) || input.expectedWriterEpoch < 0))) {
+                throw contractViolation("terminal_connection_cancellation_request");
+            }
+            if (input.resumeHandle !== undefined)
+                assertCanonicalUuid(input.resumeHandle, "Terminal resume handle");
+            return fetchDecoded({ method: "POST", path: `/v1/agent-sessions/${safeId}/terminal-connections/cancel`,
+                body: { protocol: input.protocol, client_instance_id: input.clientInstanceId,
+                    ...(input.resumeHandle === undefined ? {} : { resume_handle: input.resumeHandle }),
+                    ...(input.accessMode === undefined ? {} : { access_mode: input.accessMode }),
+                    ...(input.expectedWriterEpoch === undefined ? {} : { expected_writer_epoch: input.expectedWriterEpoch }) },
+                idempotencyKey, ...(signal === undefined ? {} : { signal }) }, decodeTerminalConnectionCancellation);
+        },
+        async transferTerminalWriter(agentSessionId, input, signal) {
+            const safeId = encodeCanonicalUuid(agentSessionId, "AgentSession ID");
+            if (!/^[A-Za-z0-9._:-]{1,256}$/u.test(input.clientInstanceId)) {
+                throw new CunaError({
+                    code: "cuna.usage.invalid",
+                    message: "Terminal client instance ID is malformed.",
+                    exitCode: EXIT_CODES.usage,
+                });
+            }
+            if (input.expectedWriterEpoch !== undefined &&
+                (!Number.isSafeInteger(input.expectedWriterEpoch) || input.expectedWriterEpoch < 0)) {
+                throw new CunaError({
+                    code: "cuna.usage.invalid",
+                    message: "The expected terminal writer epoch must be a non-negative integer.",
+                    exitCode: EXIT_CODES.usage,
+                });
+            }
+            if (input.operationId !== undefined)
+                assertCanonicalUuid(input.operationId, "writer operation ID");
+            const state = await fetchDecoded({
+                method: "POST",
+                path: `/v1/agent-sessions/${safeId}/terminal-writer`,
+                body: {
+                    client_instance_id: input.clientInstanceId,
+                    ...(input.operationId === undefined ? {} : { operation_id: input.operationId }),
+                    ...(input.expectedWriterEpoch === undefined ? {} : { expected_writer_epoch: input.expectedWriterEpoch }),
+                },
+                ...(signal === undefined ? {} : { signal }),
+            }, decodeTerminalWriterState);
+            if (state.agentSessionId !== agentSessionId || state.writerClientInstanceId !== input.clientInstanceId ||
+                (input.operationId !== undefined && state.operationId !== input.operationId)) {
+                throw malformed(contractViolation("matches_requested_resource", "operation_id"), `POST /v1/agent-sessions/${safeId}/terminal-writer`);
+            }
+            return state;
+        },
+    };
+    return Object.freeze(client);
+}
+export function decideCapability(snapshot, capabilityId, now = Date.now(), allowedInteractions = ["native"]) {
+    // The classifier's own verdict, verbatim. Collapsing all five outcomes into
+    // "snapshot_expired" told a user whose server sent an unsupported schema or an
+    // over-long TTL to retry a request that can only ever produce the same answer.
+    const validity = classifyCapabilitySnapshot(snapshot, now);
+    if (validity !== "valid") {
+        return Object.freeze({ status: "unknown", capabilityId, reason: validity });
+    }
+    const matches = snapshot.capabilities.filter((capability) => capability.id === capabilityId);
+    if (matches.length !== 1) {
+        return Object.freeze({
+            status: "unknown",
+            capabilityId,
+            reason: matches.length === 0 ? "capability_absent" : "capability_ambiguous",
+        });
+    }
+    const capability = matches[0];
+    if (capability === undefined || capability.availability !== "supported") {
+        return Object.freeze({
+            status: capability?.availability ?? "unknown",
+            capabilityId,
+            ...(capability?.reasonCode === undefined ? {} : { reason: capability.reasonCode }),
+        });
+    }
+    if (!capability.surfaces.includes("cli") || !allowedInteractions.includes(capability.interaction)) {
+        return Object.freeze({ status: "unsupported", capabilityId, reason: "cli_interaction_mismatch" });
+    }
+    return Object.freeze({ status: "supported", capabilityId });
+}
+export async function requireCapability(input) {
+    let snapshot;
+    try {
+        snapshot = await input.client.discoverCapabilities(input.scope, input.resourceId, input.signal);
+    }
+    catch (error) {
+        // `cuna.remote.operation_not_served` is the code a deployment without the
+        // route now produces. Before the transport read the status before the body,
+        // that case arrived as `cuna.remote.malformed_response` and this branch was
+        // unreachable against the one deployment that exists.
+        // A 404 means two different things here. On a resource scope it is the
+        // resource saying it is unavailable to this account; on account scope it is the route
+        // saying discovery is not served, because the account always exists.
+        if (error instanceof CunaError &&
+            error.code === "cuna.remote.not_found" &&
+            input.scope !== "account" &&
+            input.resourceId !== undefined) {
+            const subject = input.scope === "machine" ? "Machine" : "AgentSession";
+            throw new CunaError({
+                code: "cuna.remote.not_found",
+                message: `${subject} ${input.resourceId} is not available to this account.`,
+                exitCode: EXIT_CODES.remote,
+                hint: input.scope === "machine"
+                    ? "Nothing was attempted. Run `cuna machines list` to see the Machines on this account."
+                    : "Nothing was attempted. Run `cuna agent-sessions list --machine <id>` to see the AgentSessions on a Machine.",
+                details: { capability_id: input.capabilityId, scope: input.scope, resource_id: input.resourceId },
+                cause: error,
+            });
+        }
+        if (error instanceof CunaError &&
+            (error.code === "cuna.remote.not_found" || error.code === "cuna.remote.operation_not_served")) {
+            throw new CunaError({
+                code: "cuna.capability.discovery_unavailable",
+                message: "This Cuna deployment does not expose capability discovery.",
+                exitCode: EXIT_CODES.unsupported,
+                hint: "No mutation was attempted. Update the Cuna server contract before retrying.",
+                details: { capability_id: input.capabilityId },
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    if (snapshot.subjectScope !== input.scope ||
+        (input.scope !== "account" && snapshot.subjectId !== input.resourceId)) {
+        throw new CunaError({
+            code: "cuna.capability.unknown",
+            message: `Cuna cannot currently authorize the ${input.capabilityId} capability.`,
+            exitCode: EXIT_CODES.unsupported,
+            hint: "The capability snapshot describes a different subject than the one requested. Nothing was attempted; run `cuna capabilities` to see what this deployment advertises.",
+            details: {
+                capability_id: input.capabilityId,
+                availability: "unknown",
+                reason: "subject_scope_mismatch",
+            },
+        });
+    }
+    const receivedAt = typeof input.now === "function" ? input.now() : input.now;
+    const decision = decideCapability(snapshot, input.capabilityId, receivedAt, input.allowedInteractions);
+    if (decision.status === "supported")
+        return;
+    throw new CunaError({
+        code: decision.status === "temporarily_unavailable"
+            ? "cuna.capability.temporarily_unavailable"
+            : decision.status === "unsupported"
+                ? "cuna.capability.unsupported"
+                : "cuna.capability.unknown",
+        message: `Cuna cannot currently authorize the ${input.capabilityId} capability.`,
+        exitCode: decision.status === "temporarily_unavailable" ? EXIT_CODES.network : EXIT_CODES.unsupported,
+        retryable: decision.status === "temporarily_unavailable" && !isPermanentSnapshotFault(decision.reason),
+        hint: isPermanentSnapshotFault(decision.reason)
+            ? "The server sent capability evidence this CLI cannot accept. Retrying cannot help; update the Cuna server contract or this CLI."
+            : "Run `cuna capabilities` to inspect current server support.",
+        details: {
+            capability_id: input.capabilityId,
+            availability: decision.status,
+            ...(decision.reason === undefined ? {} : { reason: decision.reason }),
+        },
+    });
+}
+//# sourceMappingURL=client.js.map