@cuna_labs/cli 0.1.0

package/dist/api/contracts.js

@@ -0,0 +1,976 @@
+import { isTerminalReason } from "./terminal-reason.js";
+import { containsCredentialValue, isApiKeyDisplayPrefix, isSecretApiKey, isTerminalConnectToken, isTerminalStreamUrl, } from "../core/namespace.js";
+import { DEPLOYED_WIRE_COMPATIBILITY } from "../core/deployed-wire-compatibility.js";
+import { contractViolation, isObject, optionalDisplayString, optionalNumber, optionalString, requiredDisplayString, requiredString, underField, } from "../core/validation.js";
+const AVAILABILITY = new Set(["supported", "unsupported", "temporarily_unavailable", "unknown"]);
+const INTERACTION = new Set(["native", "read_only", "browser_handoff"]);
+const MUTATION = new Set(["none", "reversible", "destructive", "secret_revealing", "financial"]);
+const SCOPE = new Set(["account", "machine", "agent_session"]);
+function stringArray(value, key) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw contractViolation("array_of_strings", key);
+    }
+    return Object.freeze([...value]);
+}
+function decodeCapability(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const id = requiredString(value, "id");
+    const rawAvailability = requiredString(value, "availability");
+    const rawInteraction = requiredString(value, "interaction");
+    const rawMutation = requiredString(value, "mutation_class");
+    const known = AVAILABILITY.has(rawAvailability) && INTERACTION.has(rawInteraction) && MUTATION.has(rawMutation);
+    const reasonCode = optionalString(value, "reason_code");
+    return Object.freeze({
+        id,
+        availability: (known ? rawAvailability : "unknown"),
+        interaction: (INTERACTION.has(rawInteraction) ? rawInteraction : "unknown"),
+        mutationClass: (MUTATION.has(rawMutation) ? rawMutation : "unknown"),
+        surfaces: stringArray(value.surfaces, "surfaces"),
+        requiredPermissions: stringArray(value.required_permissions, "required_permissions"),
+        ...(reasonCode === undefined ? {} : { reasonCode }),
+    });
+}
+export function decodeCapabilitySnapshot(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const rawScope = requiredString(value, "subject_scope");
+    if (!SCOPE.has(rawScope))
+        throw contractViolation("known_subject_scope", "subject_scope");
+    if (!Array.isArray(value.capabilities))
+        throw contractViolation("array", "capabilities");
+    const subjectId = optionalString(value, "subject_id");
+    const schemaVersion = requiredString(value, "schema_version");
+    if (schemaVersion !== "1.0")
+        throw contractViolation("supported_schema_version", "schema_version");
+    const snapshot = Object.freeze({
+        schemaVersion,
+        subjectScope: rawScope,
+        ...(subjectId === undefined ? {} : { subjectId }),
+        observedAt: requiredString(value, "observed_at"),
+        expiresAt: requiredString(value, "expires_at"),
+        etag: requiredString(value, "etag"),
+        capabilities: Object.freeze(value.capabilities.map((item, index) => underField(`capabilities[${index}]`, () => decodeCapability(item)))),
+    });
+    // Split from one compound check into two, because they name different fields.
+    // Reported together, a stale `expires_at` sent the reader to `observed_at`.
+    if (!Number.isFinite(Date.parse(snapshot.observedAt))) {
+        throw contractViolation("parsable_timestamp", "observed_at");
+    }
+    if (!Number.isFinite(Date.parse(snapshot.expiresAt))) {
+        throw contractViolation("parsable_timestamp", "expires_at");
+    }
+    return snapshot;
+}
+function decodeMachine(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const id = canonicalUuid(value, "id");
+    const createOperation = value.create_operation === undefined ? undefined
+        : underField("create_operation", () => decodeMachineCreateRequest(value.create_operation));
+    if (createOperation !== undefined && createOperation.machineId !== id) {
+        throw contractViolation("matches_machine_id", "create_operation.machine_id");
+    }
+    const state = optionalDisplayString(value, "state") ?? optionalDisplayString(value, "status") ?? "unknown";
+    const memoryMiB = optionalNumber(value, "memory_mib");
+    const vcpus = optionalNumber(value, "vcpus");
+    const agent = optionalDisplayString(value, "agent");
+    const createdAt = optionalString(value, "created_at");
+    const updatedAt = optionalString(value, "updated_at");
+    return Object.freeze({
+        id,
+        ...(createOperation === undefined ? {} : { createOperation }),
+        name: optionalDisplayString(value, "name") ?? optionalDisplayString(value, "slug") ?? requiredString(value, "id"),
+        state,
+        ...(agent === undefined ? {} : { agent }),
+        ...(vcpus === undefined ? {} : { vcpus }),
+        ...(memoryMiB === undefined ? {} : { memoryMiB }),
+        ...(createdAt === undefined ? {} : { createdAt }),
+        ...(updatedAt === undefined ? {} : { updatedAt }),
+    });
+}
+export function decodeMachinePage(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze({
+            items: Object.freeze(value.map((item, index) => underField(`[${index}]`, () => decodeMachine(item)))),
+        });
+    }
+    if (!isObject(value) || !Array.isArray(value.items))
+        throw contractViolation("object_with_items_array");
+    const nextCursor = optionalString(value, "next_cursor");
+    return Object.freeze({
+        items: Object.freeze(value.items.map((item, index) => underField(`items[${index}]`, () => decodeMachine(item)))),
+        ...(nextCursor === undefined ? {} : { nextCursor }),
+    });
+}
+export function decodeMachineItem(value) {
+    return decodeMachine(value);
+}
+export function decodeMachineCreateRequest(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, ["id", "machine_id", "state", "retryable", "action", "updated_at"]);
+    const state = requiredString(value, "state");
+    const action = requiredString(value, "action");
+    const updatedAt = requiredString(value, "updated_at");
+    if (!new Set([
+        "prepared", "in_progress", "unknown", "provider_succeeded", "settled", "terminal_failed",
+    ]).has(state)) {
+        throw contractViolation("known_enum_value", "state");
+    }
+    if (!new Set(["retry_create", "reconcile", "wait", "none"]).has(action)) {
+        throw contractViolation("known_enum_value", "action");
+    }
+    if (typeof value.retryable !== "boolean")
+        throw contractViolation("boolean", "retryable");
+    if (!Number.isFinite(Date.parse(updatedAt)))
+        throw contractViolation("parsable_timestamp", "updated_at");
+    return Object.freeze({
+        id: canonicalUuid(value, "id"),
+        machineId: canonicalUuid(value, "machine_id"),
+        state,
+        retryable: value.retryable,
+        action,
+        updatedAt,
+    });
+}
+export function decodeWorkspaceBindingAuthority(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, [
+        "binding_id", "workspace_id", "project_id", "local_instance_id", "machine_id", "execution_workspace_id",
+        "remote_root", "exclusion_policy_digest", "active_generation", "active_manifest_root",
+        "binding_epoch", "minimum_reader", "minimum_writer", "created_at", "updated_at",
+    ]);
+    const bindingId = canonicalUuid(value, "binding_id");
+    const projectId = canonicalUuid(value, "project_id");
+    const executionWorkspaceId = value.execution_workspace_id === null ? null : canonicalUuid(value, "execution_workspace_id");
+    const exclusionPolicyDigest = requiredString(value, "exclusion_policy_digest");
+    const activeManifestRoot = requiredString(value, "active_manifest_root");
+    const remoteRoot = requiredString(value, "remote_root");
+    const createdAt = requiredString(value, "created_at");
+    const updatedAt = requiredString(value, "updated_at");
+    const activeGeneration = optionalNumber(value, "active_generation");
+    const bindingEpoch = optionalNumber(value, "binding_epoch");
+    const minimumReader = optionalNumber(value, "minimum_reader");
+    const minimumWriter = optionalNumber(value, "minimum_writer");
+    if (remoteRoot !== (executionWorkspaceId === null ? `/workspace/projects/${projectId}` : `/workspace/workspaces/${executionWorkspaceId}`)) {
+        throw contractViolation("remote_root_matches_execution_workspace", "remote_root");
+    }
+    if (!/^[0-9a-f]{64}$/u.test(exclusionPolicyDigest)) {
+        throw contractViolation("sha256_digest", "exclusion_policy_digest");
+    }
+    if (!/^[0-9a-f]{64}$/u.test(activeManifestRoot)) {
+        throw contractViolation("sha256_digest", "active_manifest_root");
+    }
+    if (!Number.isSafeInteger(activeGeneration) || Number(activeGeneration) < 0) {
+        throw contractViolation("safe_non_negative_integer", "active_generation");
+    }
+    if (!Number.isSafeInteger(bindingEpoch) || Number(bindingEpoch) < 1) {
+        throw contractViolation("safe_positive_integer", "binding_epoch");
+    }
+    if (!Number.isSafeInteger(minimumReader) || Number(minimumReader) < 1) {
+        throw contractViolation("safe_positive_integer", "minimum_reader");
+    }
+    if (!Number.isSafeInteger(minimumWriter) || Number(minimumWriter) < 1) {
+        throw contractViolation("safe_positive_integer", "minimum_writer");
+    }
+    if (!Number.isFinite(Date.parse(createdAt)))
+        throw contractViolation("parsable_timestamp", "created_at");
+    if (!Number.isFinite(Date.parse(updatedAt)))
+        throw contractViolation("parsable_timestamp", "updated_at");
+    return Object.freeze({
+        bindingId,
+        executionWorkspaceId,
+        workspaceId: canonicalUuid(value, "workspace_id"),
+        projectId,
+        localInstanceId: canonicalUuid(value, "local_instance_id"),
+        machineId: canonicalUuid(value, "machine_id"),
+        remoteRoot,
+        exclusionPolicyDigest,
+        activeGeneration: Number(activeGeneration),
+        activeManifestRoot,
+        bindingEpoch: Number(bindingEpoch),
+        minimumReader: Number(minimumReader),
+        minimumWriter: Number(minimumWriter),
+        createdAt,
+        updatedAt,
+    });
+}
+/**
+ * Validate `workspace.usage` and decode it.
+ *
+ * `balance_unavailable_reason` is the one optional key, present exactly when
+ * `balance_status` is `unavailable`. Everything else is required, and this is
+ * closed: a server that adds a field is refused rather than silently displayed.
+ *
+ * Separate from the identity decode on purpose. Usage is read by one command;
+ * identity is read by every command that needs to know who you are. A usage
+ * field this does not recognise must not decide whether a terminal can open.
+ */
+function decodeWorkspaceUsage(usage) {
+    if (Object.keys(usage).some((key) => ![
+        "est_spend_usd",
+        "est_spend_is_lower_bound",
+        "balance_status",
+        "balance_usd",
+        "balance_unavailable_reason",
+        "note",
+    ].includes(key))) {
+        throw contractViolation("no_unknown_fields", "workspace.usage");
+    }
+    if (typeof usage.est_spend_usd !== "number" || !Number.isFinite(usage.est_spend_usd)) {
+        throw contractViolation("finite_number", "workspace.usage.est_spend_usd");
+    }
+    // A constant, not a flag: `false` would be a different contract.
+    if (usage.est_spend_is_lower_bound !== true) {
+        throw contractViolation("const_true", "workspace.usage.est_spend_is_lower_bound");
+    }
+    if (usage.balance_status !== "available" && usage.balance_status !== "unavailable") {
+        throw contractViolation("balance_status_vocabulary", "workspace.usage.balance_status");
+    }
+    if (usage.balance_status === "available") {
+        if (typeof usage.balance_usd !== "number" || !Number.isFinite(usage.balance_usd)) {
+            throw contractViolation("finite_number", "workspace.usage.balance_usd");
+        }
+        if (usage.balance_unavailable_reason !== undefined) {
+            throw contractViolation("absent_when_available", "workspace.usage.balance_unavailable_reason");
+        }
+    }
+    else {
+        // `null`, not absent and not zero: a zero balance is a real reading.
+        if (usage.balance_usd !== null) {
+            throw contractViolation("null_when_unavailable", "workspace.usage.balance_usd");
+        }
+        if (typeof usage.balance_unavailable_reason !== "string" || usage.balance_unavailable_reason === "") {
+            throw contractViolation("required_when_balance_unavailable", "workspace.usage.balance_unavailable_reason");
+        }
+    }
+    if (typeof usage.note !== "string") {
+        throw contractViolation("string", "workspace.usage.note");
+    }
+    return Object.freeze({
+        estimatedSpendUsd: Number(usage.est_spend_usd),
+        estimatedSpendIsLowerBound: true,
+        balanceStatus: usage.balance_status,
+        balanceUsd: usage.balance_usd,
+        ...(usage.balance_unavailable_reason === undefined
+            ? {}
+            : { balanceUnavailableReason: String(usage.balance_unavailable_reason) }),
+        note: String(usage.note),
+    });
+}
+/**
+ * Decode `/v1/me`.
+ *
+ * THE COMPOUND CHECKS BELOW WERE SPLIT DELIBERATELY, and the accept/reject
+ * boundary is unchanged: exactly the same bodies are accepted and rejected as
+ * before. What changed is that a rejection now names ONE field.
+ *
+ * This is the decoder that motivated the whole change. Production omits
+ * `workspace.id` while its own published OpenAPI marks it required when
+ * `assigned` is true, so this function is the single most likely source of
+ * `cuna.remote.malformed_response` in the field — and it used to answer with
+ * "Malformed Cuna workspace identity" for any of TEN different faults. The one
+ * fact the user needed was already computed here and thrown away.
+ */
+export function decodeCunaIdentity(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    if (!isObject(value.workspace))
+        throw contractViolation("object", "workspace");
+    if (Object.keys(value).some((key) => key !== "id" && key !== "email" && key !== "workspace")) {
+        throw contractViolation("no_unknown_fields");
+    }
+    const assigned = value.workspace.assigned;
+    if (typeof assigned !== "boolean")
+        throw contractViolation("boolean", "workspace.assigned");
+    const workspaceKeys = Object.keys(value.workspace);
+    if (assigned) {
+        if (workspaceKeys.some((key) => key !== "assigned" && key !== "id" && key !== "usage")) {
+            throw contractViolation("no_unknown_fields", "workspace");
+        }
+        // The measured production defect lands exactly here.
+        if (typeof value.workspace.id !== "string") {
+            throw contractViolation("required_when_workspace_assigned", "workspace.id");
+        }
+        if (!isObject(value.workspace.usage)) {
+            throw contractViolation("required_when_workspace_assigned", "workspace.usage");
+        }
+    }
+    else {
+        if (workspaceKeys.some((key) => key !== "assigned" && key !== "waitlist_position")) {
+            throw contractViolation("no_unknown_fields", "workspace");
+        }
+        if (!Number.isSafeInteger(value.workspace.waitlist_position) ||
+            Number(value.workspace.waitlist_position) < 0) {
+            throw contractViolation("safe_non_negative_integer", "workspace.waitlist_position");
+        }
+    }
+    // A usage fault is recorded, not thrown: it stops `cuna usage show` and
+    // nothing else. Letting it throw here took down every command that reads an
+    // identity, including the one that opens a terminal.
+    let decodedUsage = {};
+    if (assigned) {
+        try {
+            decodedUsage = {
+                workspaceUsage: underField("workspace.usage", () => decodeWorkspaceUsage(value.workspace.usage)),
+            };
+        }
+        catch (error) {
+            decodedUsage = {
+                workspaceUsageProblem: error instanceof Error ? error.message : "workspace usage is off contract",
+            };
+        }
+    }
+    return Object.freeze({
+        id: canonicalUuid(value, "id"),
+        email: requiredString(value, "email"),
+        workspaceAssigned: assigned,
+        ...(assigned
+            ? {
+                workspaceId: underField("workspace", () => canonicalUuid(value.workspace, "id")),
+                ...decodedUsage,
+            }
+            : { waitlistPosition: Number(value.workspace.waitlist_position) }),
+    });
+}
+export const AGENT_SESSION_AUTH_ADAPTER_VERSION = DEPLOYED_WIRE_COMPATIBILITY.agentSessionAuthAdapterVersion;
+export const AGENT_SESSION_AUTH_MAX_TTL_MS = 30_000;
+export const AGENT_SESSION_AUTH_MAX_FUTURE_SKEW_MS = 5_000;
+const AGENTS = new Set(["claude-code", "codex", "openclaw", "opencode"]);
+const AUTH_MODES = new Set(["interactive_login", "credential_binding"]);
+const DESIRED_STATES = new Set(["running", "terminated"]);
+const REQUEST_STATES = new Set([
+    "launch_pending", "runtime_claimed", "launched", "termination_pending", "terminal", "failed",
+]);
+const PROCESS_STATES = new Set([
+    "unknown", "starting", "ready", "running", "exited", "failed", "terminating", "terminated",
+]);
+const PROCESS_OBSERVATIONS = new Set([
+    "observed", "unproven", "unknown",
+]);
+const AGENT_AUTH_STATES = new Set([
+    "login_required", "authenticated", "configured", "unavailable",
+]);
+const AGENT_AUTH_EVIDENCE_CLASSES = new Set([
+    "provider_cli_login_status", "provider_cli_credential_presence", "credential_binding_authority", "insufficient",
+]);
+const AGENT_AUTH_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/u;
+function enumField(value, key, allowed) {
+    const decoded = requiredString(value, key);
+    if (!allowed.has(decoded))
+        throw contractViolation("known_enum_value", key);
+    return decoded;
+}
+function decodeAgentSession(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const allowed = new Set([
+        "id",
+        "machine_id",
+        "workspace_binding_id",
+        "workspace_generation",
+        "project_id",
+        "workspace_failure_code",
+        "terminal_reason",
+        "name",
+        "agent",
+        "cwd",
+        "auth_mode",
+        "desired_state",
+        "request_state",
+        "process_state",
+        "process_observation",
+        "process_epoch",
+        "runtime_observed_at",
+        "runtime_expires_at",
+        "termination_requested_at",
+        "row_version",
+        "created_at",
+        "updated_at",
+    ]);
+    if (Object.keys(value).some((key) => !allowed.has(key))) {
+        throw contractViolation("no_unknown_fields");
+    }
+    const agent = enumField(value, "agent", AGENTS);
+    const authMode = enumField(value, "auth_mode", AUTH_MODES);
+    // Read paths intentionally remain tolerant of legacy OpenCode rows.  The
+    // producer and every mutation path reject credential bindings for OpenCode,
+    // while foreground admission rejects an unsafe legacy row before it can own
+    // a terminal.  Rejecting it here would make an entire paginated list
+    // unreadable during a consumer-first rollback.
+    const desiredState = enumField(value, "desired_state", DESIRED_STATES);
+    const requestState = enumField(value, "request_state", REQUEST_STATES);
+    const workspaceFailureCode = optionalString(value, "workspace_failure_code");
+    if (workspaceFailureCode !== undefined && (requestState !== "failed" || !/^[a-z][a-z0-9_.]{0,127}$/u.test(workspaceFailureCode))) {
+        throw contractViolation("failed_request_safe_workspace_reason", "workspace_failure_code");
+    }
+    const processState = enumField(value, "process_state", PROCESS_STATES);
+    const terminalReason = optionalString(value, "terminal_reason");
+    if (terminalReason !== undefined &&
+        (!isTerminalReason(terminalReason) || !["exited", "failed", "terminated"].includes(processState))) {
+        throw contractViolation("terminal_state_safe_reason", "terminal_reason");
+    }
+    // Strict where it is present, tolerant of its absence, and never defaulted.
+    // A value this build does not know is refused rather than demoted: an
+    // unrecognised provenance could be a NEW way to say "nobody looked", and
+    // reading it as `observed` is the one error this field exists to prevent.
+    const processObservation = optionalString(value, "process_observation");
+    if (processObservation !== undefined && !PROCESS_OBSERVATIONS.has(processObservation)) {
+        throw contractViolation("known_enum_value", "process_observation");
+    }
+    const processEpoch = optionalString(value, "process_epoch");
+    const runtimeObservedAt = optionalString(value, "runtime_observed_at");
+    const runtimeExpiresAt = optionalString(value, "runtime_expires_at");
+    const terminationRequestedAt = optionalString(value, "termination_requested_at");
+    const workspaceBindingId = optionalString(value, "workspace_binding_id");
+    const workspaceGeneration = optionalNumber(value, "workspace_generation");
+    if ((workspaceBindingId === undefined) !== (workspaceGeneration === undefined)) {
+        throw contractViolation("binding_id_and_generation_present_together");
+    }
+    if (workspaceBindingId !== undefined &&
+        (!UUID.test(workspaceBindingId) ||
+            !Number.isSafeInteger(workspaceGeneration) ||
+            workspaceGeneration === undefined ||
+            workspaceGeneration < 1)) {
+        throw contractViolation("workspace_binding_identity_shape");
+    }
+    // The Project is the server's answer about this exact session, so the CLI
+    // checks its shape and otherwise carries it through untouched. Absent stays
+    // absent: a session whose Workspace the server cannot resolve has an unknown
+    // Project, and inventing one here would let a caller scope work to a Project
+    // the session does not belong to.
+    const projectId = optionalString(value, "project_id");
+    if (projectId !== undefined && !UUID.test(projectId)) {
+        throw contractViolation("project_identity_shape", "project_id");
+    }
+    const rowVersion = optionalNumber(value, "row_version");
+    if (rowVersion === undefined || !Number.isSafeInteger(rowVersion) || rowVersion < 0) {
+        throw contractViolation("safe_non_negative_integer", "row_version");
+    }
+    return Object.freeze({
+        id: canonicalUuid(value, "id"),
+        machineId: canonicalUuid(value, "machine_id"),
+        ...(workspaceBindingId === undefined
+            ? {}
+            : { workspaceBindingId, workspaceGeneration: workspaceGeneration }),
+        ...(projectId === undefined ? {} : { projectId }),
+        ...(workspaceFailureCode === undefined ? {} : { workspaceFailureCode }),
+        ...(terminalReason === undefined ? {} : { terminalReason: terminalReason }),
+        name: requiredDisplayString(value, "name"),
+        agent,
+        cwd: requiredDisplayString(value, "cwd"),
+        authMode,
+        desiredState,
+        requestState,
+        processState,
+        ...(processObservation === undefined
+            ? {}
+            : { processObservation: processObservation }),
+        ...(processEpoch === undefined
+            ? {}
+            : UUID.test(processEpoch)
+                ? { processEpoch }
+                : (() => { throw contractViolation("canonical_uuid", "process_epoch"); })()),
+        ...(runtimeObservedAt === undefined ? {} : { runtimeObservedAt }),
+        ...(runtimeExpiresAt === undefined ? {} : { runtimeExpiresAt }),
+        ...(terminationRequestedAt === undefined ? {} : { terminationRequestedAt }),
+        rowVersion,
+        createdAt: requiredString(value, "created_at"),
+        updatedAt: requiredString(value, "updated_at"),
+    });
+}
+export function decodeAgentSessionPage(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze({
+            items: Object.freeze(value.map((item, index) => underField(`[${index}]`, () => decodeAgentSession(item)))),
+        });
+    }
+    if (!isObject(value) || !Array.isArray(value.items))
+        throw contractViolation("object_with_items_array");
+    const nextCursor = optionalString(value, "next_cursor");
+    return Object.freeze({
+        items: Object.freeze(value.items.map((item, index) => underField(`items[${index}]`, () => decodeAgentSession(item)))),
+        ...(nextCursor === undefined ? {} : { nextCursor }),
+    });
+}
+export function decodeAgentSessionItem(value) {
+    return decodeAgentSession(value);
+}
+export function decodeAgentSessionAuth(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const allowed = new Set([
+        "observation_id",
+        "agent_session_id",
+        "agent",
+        "process_epoch",
+        "auth_mode",
+        "agent_version",
+        "adapter_version",
+        "evidence_class",
+        "observed_at",
+        "valid_until",
+        "state",
+    ]);
+    if (Object.keys(value).some((key) => !allowed.has(key))) {
+        throw contractViolation("no_unknown_fields");
+    }
+    const processEpoch = value.process_epoch;
+    if (processEpoch !== null && (typeof processEpoch !== "string" || !UUID.test(processEpoch))) {
+        throw contractViolation("canonical_uuid_or_null", "process_epoch");
+    }
+    const observedAt = requiredString(value, "observed_at");
+    const validUntil = requiredString(value, "valid_until");
+    const observedTime = Date.parse(observedAt);
+    const validUntilTime = Date.parse(validUntil);
+    if (!Number.isFinite(observedTime) ||
+        !Number.isFinite(validUntilTime) ||
+        validUntilTime < observedTime ||
+        validUntilTime - observedTime > AGENT_SESSION_AUTH_MAX_TTL_MS) {
+        throw contractViolation("bounded_observation_freshness");
+    }
+    const authMode = enumField(value, "auth_mode", AUTH_MODES);
+    const agentVersion = requiredDisplayString(value, "agent_version");
+    const adapterVersion = requiredDisplayString(value, "adapter_version");
+    if (adapterVersion !== AGENT_SESSION_AUTH_ADAPTER_VERSION) {
+        throw contractViolation("supported_adapter_version", "adapter_version");
+    }
+    const evidenceClass = enumField(value, "evidence_class", AGENT_AUTH_EVIDENCE_CLASSES);
+    const state = enumField(value, "state", AGENT_AUTH_STATES);
+    const unavailable = state === "unavailable";
+    const providerCredentialPresence = value.agent === "opencode" &&
+        authMode === "interactive_login" &&
+        evidenceClass === "provider_cli_credential_presence" &&
+        (state === "login_required" || state === "configured");
+    const providerLoginStatus = value.agent === "claude-code" &&
+        authMode === "interactive_login" &&
+        evidenceClass === "provider_cli_login_status" &&
+        (state === "login_required" || state === "authenticated");
+    const credentialBindingAuthority = (value.agent === "claude-code" || value.agent === "codex" || value.agent === "openclaw") &&
+        authMode === "credential_binding" &&
+        evidenceClass === "credential_binding_authority" &&
+        state === "configured";
+    if ((!unavailable && processEpoch === null) ||
+        (!unavailable && validUntilTime === observedTime) ||
+        (!unavailable && !AGENT_AUTH_VERSION.test(agentVersion)) ||
+        (!unavailable && !(providerCredentialPresence || providerLoginStatus || credentialBindingAuthority)) ||
+        (unavailable !== (evidenceClass === "insufficient")) ||
+        (unavailable && validUntilTime !== observedTime) ||
+        (agentVersion === "unavailable" && !unavailable)) {
+        throw contractViolation("self_consistent_authentication_evidence");
+    }
+    return Object.freeze({
+        observationId: canonicalUuid(value, "observation_id"),
+        agentSessionId: canonicalUuid(value, "agent_session_id"),
+        agent: enumField(value, "agent", AGENTS),
+        processEpoch,
+        authMode,
+        agentVersion,
+        adapterVersion,
+        evidenceClass,
+        observedAt,
+        validUntil,
+        state,
+    });
+}
+export function decodeAgentSessionAuthLogout(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const allowed = new Set([
+        "observation_id", "agent_session_id", "process_epoch", "auth_mode", "agent",
+        "agent_version", "adapter_version", "observed_at", "outcome",
+    ]);
+    if (Object.keys(value).some((key) => !allowed.has(key)) ||
+        value.auth_mode !== "interactive_login" ||
+        (value.agent !== "claude-code" && value.agent !== "codex") ||
+        typeof value.agent_version !== "string" ||
+        !AGENT_AUTH_VERSION.test(value.agent_version) ||
+        value.adapter_version !== AGENT_SESSION_AUTH_ADAPTER_VERSION ||
+        typeof value.observed_at !== "string" ||
+        !Number.isFinite(Date.parse(value.observed_at)) ||
+        value.outcome !== "logout_confirmed") {
+        throw contractViolation("sign_out_confirmation_shape");
+    }
+    return Object.freeze({
+        observationId: canonicalUuid(value, "observation_id"),
+        agentSessionId: canonicalUuid(value, "agent_session_id"),
+        processEpoch: canonicalUuid(value, "process_epoch"),
+        authMode: "interactive_login",
+        agent: value.agent,
+        agentVersion: value.agent_version,
+        adapterVersion: AGENT_SESSION_AUTH_ADAPTER_VERSION,
+        observedAt: value.observed_at,
+        outcome: "logout_confirmed",
+    });
+}
+export const TERMINAL_PROTOCOL = DEPLOYED_WIRE_COMPATIBILITY.terminalProtocol;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+const TERMINAL_CAPABILITY_NAMES = new Set([
+    "acknowledgement",
+    "heartbeat",
+    "live_resize",
+    "resume",
+    "signals",
+]);
+const TERMINAL_CAPABILITY_AVAILABILITY = new Set([
+    "supported",
+    "unsupported",
+    "unknown",
+]);
+function canonicalUuid(value, key) {
+    const decoded = requiredString(value, key);
+    if (!UUID.test(decoded))
+        throw contractViolation("canonical_uuid", key);
+    return decoded;
+}
+function decodeTerminalCapability(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const name = requiredString(value, "name");
+    const availability = requiredString(value, "availability");
+    if (!TERMINAL_CAPABILITY_NAMES.has(name) ||
+        !TERMINAL_CAPABILITY_AVAILABILITY.has(availability) ||
+        Object.keys(value).some((key) => key !== "name" && key !== "availability")) {
+        throw contractViolation("terminal_capability_shape");
+    }
+    return Object.freeze({ name, availability });
+}
+export function decodeTerminalConnectionCancellation(value) {
+    if (!isObject(value) || value.cancelled !== true || Object.keys(value).some(key => key !== "cancelled"))
+        throw contractViolation("terminal_connection_cancellation");
+    return Object.freeze({ cancelled: true });
+}
+export function decodeTerminalConnectionGrant(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    const allowed = new Set([
+        "terminal_session_id",
+        "resume_handle",
+        "connect_url",
+        "connect_token",
+        "protocol",
+        "capabilities",
+        "expires_at",
+    ]);
+    if (Object.keys(value).some((key) => !allowed.has(key)) || !Array.isArray(value.capabilities)) {
+        throw contractViolation("no_unknown_fields");
+    }
+    const terminalSessionId = canonicalUuid(value, "terminal_session_id");
+    const resumeHandle = canonicalUuid(value, "resume_handle");
+    const connectUrl = requiredString(value, "connect_url");
+    const connectToken = requiredString(value, "connect_token");
+    const protocol = requiredString(value, "protocol");
+    const expiresAt = requiredString(value, "expires_at");
+    if (protocol !== TERMINAL_PROTOCOL ||
+        !isTerminalConnectToken(connectToken) ||
+        !isTerminalStreamUrl(connectUrl, terminalSessionId) ||
+        !Number.isFinite(Date.parse(expiresAt)) ||
+        value.capabilities.length !== TERMINAL_CAPABILITY_NAMES.size) {
+        throw contractViolation("terminal_grant_shape");
+    }
+    const capabilities = Object.freeze(value.capabilities.map((item, index) => underField(`capabilities[${index}]`, () => decodeTerminalCapability(item))));
+    if (new Set(capabilities.map((capability) => capability.name)).size !== TERMINAL_CAPABILITY_NAMES.size ||
+        [...TERMINAL_CAPABILITY_NAMES].some((name) => capabilities.filter((capability) => capability.name === name).length !== 1)) {
+        throw contractViolation("exactly_one_of_each_terminal_capability", "capabilities");
+    }
+    return Object.freeze({
+        terminalSessionId,
+        resumeHandle,
+        connectUrl,
+        connectToken,
+        protocol: TERMINAL_PROTOCOL,
+        capabilities,
+        expiresAt,
+    });
+}
+/**
+ * Control and format characters may never reach the operator's terminal. The
+ * credential half of this guard is NOT written here: it comes from
+ * `containsCredentialValue`, the one authority, because the copy that used to
+ * live on this line knew only five of the eight minted families.
+ */
+const FORBIDDEN_PUBLIC_CHARACTER = /[\p{Cc}\p{Cf}]/u;
+function exactKeys(value, required) {
+    const actual = Object.keys(value).sort();
+    const expected = [...required].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw contractViolation("exact_key_set");
+    }
+}
+function safePublicString(value, label, maximum = 4096) {
+    if (typeof value !== "string" ||
+        value.length > maximum ||
+        FORBIDDEN_PUBLIC_CHARACTER.test(value) ||
+        containsCredentialValue(value)) {
+        throw contractViolation("safe_public_string", label);
+    }
+    return value;
+}
+function decodeJsonValue(value, depth = 0) {
+    if (depth > 12)
+        throw contractViolation("bounded_nesting_depth");
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw contractViolation("finite_number");
+        return value;
+    }
+    if (typeof value === "string")
+        return safePublicString(value, "detail", 16_384);
+    if (Array.isArray(value)) {
+        if (value.length > 1024)
+            throw contractViolation("bounded_array_length");
+        return Object.freeze(value.map((item) => decodeJsonValue(item, depth + 1)));
+    }
+    if (!isObject(value) || Object.keys(value).length > 1024) {
+        throw contractViolation("bounded_object_size");
+    }
+    const decoded = {};
+    for (const [key, item] of Object.entries(value)) {
+        const safeKey = safePublicString(key, "detail key", 256);
+        decoded[safeKey] = decodeJsonValue(item, depth + 1);
+    }
+    return Object.freeze(decoded);
+}
+function decodeAuditRecord(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, ["id", "session_id", "kind", "summary", "detail", "created_at"]);
+    const createdAt = safePublicString(value.created_at, "created_at", 64);
+    if (!Number.isFinite(Date.parse(createdAt)))
+        throw contractViolation("parsable_timestamp", "created_at");
+    return Object.freeze({
+        id: canonicalUuid(value, "id"),
+        machineId: canonicalUuid(value, "session_id"),
+        kind: safePublicString(value.kind, "kind", 128),
+        summary: safePublicString(value.summary, "summary", 2048),
+        detail: decodeJsonValue(value.detail),
+        createdAt,
+    });
+}
+export function decodeAuditRecords(value) {
+    if (!Array.isArray(value) || value.length > 200)
+        throw contractViolation("bounded_array_length");
+    return Object.freeze(value.map((item, index) => underField(`[${index}]`, () => decodeAuditRecord(item))));
+}
+function injectionName(value, label, maximum) {
+    const text = safePublicString(value, label, maximum);
+    if (text.length === 0)
+        throw contractViolation("nonempty_string", label);
+    return text;
+}
+function injectionTemplate(value) {
+    if (typeof value !== "string" || value.length > 4096)
+        throw contractViolation("bounded_string", "value_template");
+    // Templates are opaque metadata, including multiline file content. Preserve
+    // whitespace without interpreting interpolation; reject terminal controls and
+    // known credential values. Human rendering must quote this string.
+    safePublicString(value.replace(/[\r\n\t]/gu, ""), "value_template", 4096);
+    return value;
+}
+function injectionArray(value, label, decode) {
+    if (!Array.isArray(value) || value.length > 64)
+        throw contractViolation("bounded_array_length", label);
+    return Object.freeze(value.map((item, index) => underField(`${label}[${index}]`, () => decode(item))));
+}
+export function decodeMachineAuthorizations(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, ["revision", "secret_configuration"]);
+    if (typeof value.revision !== "number" || !Number.isSafeInteger(value.revision) || value.revision < 1)
+        throw contractViolation("positive_safe_integer", "revision");
+    return Object.freeze({ revision: value.revision, secret_configuration: injectionArray(value.secret_configuration, "secret_configuration", (entry) => {
+            if (!isObject(entry))
+                throw contractViolation("object");
+            exactKeys(entry, ["secret_id", "environment", "egress_rules", "files"]);
+            return Object.freeze({
+                secret_id: canonicalUuid(entry, "secret_id"),
+                environment: injectionArray(entry.environment, "environment", (item) => {
+                    if (!isObject(item))
+                        throw contractViolation("object");
+                    exactKeys(item, ["name", "value_template"]);
+                    return Object.freeze({ name: injectionName(item.name, "name", 256), value_template: injectionTemplate(item.value_template) });
+                }),
+                egress_rules: injectionArray(entry.egress_rules, "egress_rules", (item) => {
+                    if (!isObject(item))
+                        throw contractViolation("object");
+                    exactKeys(item, ["host_pattern", "action", "name", "value_template", ...(Object.hasOwn(item, "path_pattern") ? ["path_pattern"] : [])]);
+                    if (item.action !== "header" && item.action !== "query")
+                        throw contractViolation("known_injection_action", "action");
+                    return Object.freeze({ host_pattern: injectionName(item.host_pattern, "host_pattern", 253), action: item.action,
+                        name: injectionName(item.name, "name", 256), value_template: injectionTemplate(item.value_template),
+                        ...(Object.hasOwn(item, "path_pattern") ? { path_pattern: item.path_pattern === null ? null : safePublicString(item.path_pattern, "path_pattern", 4096) } : {}) });
+                }),
+                files: injectionArray(entry.files, "files", (item) => {
+                    if (!isObject(item))
+                        throw contractViolation("object");
+                    exactKeys(item, ["path", "value_template"]);
+                    return Object.freeze({ path: injectionName(item.path, "path", 4096), value_template: injectionTemplate(item.value_template) });
+                }),
+            });
+        }) });
+}
+function optionalTimestamp(value, label) {
+    if (value === null)
+        return null;
+    const decoded = safePublicString(value, label, 64);
+    if (!Number.isFinite(Date.parse(decoded)))
+        throw contractViolation("parsable_timestamp", label);
+    return decoded;
+}
+function decodeApiKeyMetadata(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, [
+        "id", "name", "prefix", "last_four", "created_at", "expires_at", "last_used_at", "revoked_at",
+    ]);
+    const prefix = safePublicString(value.prefix, "prefix", 32);
+    const lastFour = safePublicString(value.last_four, "last_four", 4);
+    if (!isApiKeyDisplayPrefix(prefix) || !/^[A-Za-z0-9_-]{4}$/u.test(lastFour)) {
+        throw contractViolation("api_key_display_metadata");
+    }
+    const createdAt = optionalTimestamp(value.created_at, "created_at");
+    if (createdAt === null)
+        throw contractViolation("parsable_timestamp", "created_at");
+    return Object.freeze({
+        id: canonicalUuid(value, "id"),
+        name: safePublicString(value.name, "name", 80),
+        prefix,
+        lastFour,
+        createdAt,
+        expiresAt: optionalTimestamp(value.expires_at, "expires_at"),
+        lastUsedAt: optionalTimestamp(value.last_used_at, "last_used_at"),
+        revokedAt: optionalTimestamp(value.revoked_at, "revoked_at"),
+    });
+}
+export function decodeApiKeyList(value) {
+    if (!Array.isArray(value) || value.length > 100)
+        throw contractViolation("bounded_array_length");
+    return Object.freeze(value.map((item, index) => underField(`[${index}]`, () => decodeApiKeyMetadata(item))));
+}
+export function decodeApiKeyCreation(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    if (typeof value.idempotency_replayed !== "boolean") {
+        throw contractViolation("boolean", "idempotency_replayed");
+    }
+    exactKeys(value, [
+        "id", "name", "prefix", "last_four", "created_at", "expires_at", "last_used_at", "revoked_at",
+        "idempotency_replayed", ...(value.idempotency_replayed ? [] : ["key"]),
+    ]);
+    if (!value.idempotency_replayed && (typeof value.key !== "string" || !isSecretApiKey(value.key))) {
+        throw contractViolation("one_time_api_key");
+    }
+    const { key, idempotency_replayed: idempotencyReplayed, ...metadataValue } = value;
+    const metadata = decodeApiKeyMetadata(metadataValue);
+    if (typeof key === "string" && (!key.startsWith(metadata.prefix) || !key.endsWith(metadata.lastFour))) {
+        throw contractViolation("api_key_secret_metadata_binding");
+    }
+    return idempotencyReplayed
+        ? Object.freeze({ ...metadata, idempotencyReplayed: true })
+        : Object.freeze({ ...metadata, idempotencyReplayed: false, key: key });
+}
+export function decodeTerminalWriterState(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, ["agent_session_id", "process_epoch", "writer_epoch", "writer_client_instance_id", "transfer_pending", "operation_id", "operation_state"]);
+    const agentSessionId = canonicalUuid(value, "agent_session_id");
+    const processEpoch = canonicalUuid(value, "process_epoch");
+    const operationId = canonicalUuid(value, "operation_id");
+    if (value.operation_state !== "committed")
+        throw contractViolation("terminal_writer_operation_state");
+    if (!Number.isSafeInteger(value.writer_epoch) || Number(value.writer_epoch) < 1 ||
+        typeof value.writer_client_instance_id !== "string" ||
+        !/^[A-Za-z0-9._:-]{1,256}$/u.test(value.writer_client_instance_id) ||
+        typeof value.transfer_pending !== "boolean")
+        throw contractViolation("terminal_writer_state_shape");
+    return Object.freeze({
+        operationId,
+        operationState: "committed",
+        agentSessionId,
+        processEpoch,
+        writerEpoch: Number(value.writer_epoch),
+        writerClientInstanceId: value.writer_client_instance_id,
+        transferPending: value.transfer_pending,
+    });
+}
+const TERMINAL_SEAT_STATES = new Set([
+    "available",
+    "owner_unrecoverable",
+    "none",
+]);
+const CLIENT_INSTANCE_ID = /^[A-Za-z0-9._:-]{1,256}$/u;
+export function decodeAgentSessionTerminalSeat(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, [
+        "agent_session_id",
+        "process_epoch",
+        "state",
+        "unavailable_reason",
+        "writer_epoch",
+        "writer_client_instance_id",
+        "writer_attached",
+        "writer_attached_at",
+        "writer_detached_at",
+        "observed_at",
+    ]);
+    const agentSessionId = canonicalUuid(value, "agent_session_id");
+    if (value.process_epoch !== null && (typeof value.process_epoch !== "string" || !UUID.test(value.process_epoch))) {
+        throw contractViolation("canonical_uuid_or_null", "process_epoch");
+    }
+    const state = enumField(value, "state", TERMINAL_SEAT_STATES);
+    if (value.unavailable_reason !== null &&
+        (typeof value.unavailable_reason !== "string" || value.unavailable_reason.length > 4096)) {
+        throw contractViolation("string_or_null", "unavailable_reason");
+    }
+    if (!Number.isSafeInteger(value.writer_epoch) || Number(value.writer_epoch) < 0) {
+        throw contractViolation("non_negative_integer", "writer_epoch");
+    }
+    if (value.writer_client_instance_id !== null &&
+        (typeof value.writer_client_instance_id !== "string" || !CLIENT_INSTANCE_ID.test(value.writer_client_instance_id))) {
+        throw contractViolation("client_instance_id_or_null", "writer_client_instance_id");
+    }
+    if (typeof value.writer_attached !== "boolean") {
+        throw contractViolation("boolean", "writer_attached");
+    }
+    // An unheld seat cannot have an attached writer, and a seat nobody holds
+    // must not carry attachment timestamps: the two facts come from different
+    // rows, so their disagreement is a producer defect, not a state.
+    if (value.writer_client_instance_id === null && value.writer_attached === true) {
+        throw contractViolation("writer_attached_without_writer", "writer_attached");
+    }
+    for (const key of ["writer_attached_at", "writer_detached_at"]) {
+        const at = value[key];
+        if (at !== null && (typeof at !== "string" || !Number.isFinite(Date.parse(at)))) {
+            throw contractViolation("timestamp_or_null", key);
+        }
+    }
+    const observedAt = requiredString(value, "observed_at");
+    if (!Number.isFinite(Date.parse(observedAt)))
+        throw contractViolation("timestamp", "observed_at");
+    return Object.freeze({
+        agentSessionId,
+        processEpoch: value.process_epoch,
+        state,
+        unavailableReason: value.unavailable_reason,
+        writerEpoch: Number(value.writer_epoch),
+        writerClientInstanceId: value.writer_client_instance_id,
+        writerAttached: value.writer_attached,
+        writerAttachedAt: value.writer_attached_at,
+        writerDetachedAt: value.writer_detached_at,
+        observedAt,
+    });
+}
+export function decodeOk(value) {
+    if (!isObject(value))
+        throw contractViolation("object");
+    exactKeys(value, ["ok"]);
+    if (value.ok !== true)
+        throw contractViolation("acknowledgement_is_true", "ok");
+    return true;
+}
+//# sourceMappingURL=contracts.js.map