@maiaos/client-core 0.0.0-stage → 0.1.0-nightly.20261024.5

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @maiaos/client-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Platform-neutral client use cases for Maia OS: Effect services that sit between
+a client's renderer and
+[`@maiaos/sdk`](https://github.com/vllnt/maia/blob/main/packages/sdk/README.md),
+so every client reads Maia Node state and sends requests the same way.
+
+> **Pre-release.** npm carries only `nightly` and `canary` builds, which are
+> not release-qualified. No stable release exists
+> ([D-132](https://github.com/vllnt/maia/blob/main/docs/decisions.md#d-132)).
+> Nothing in this package is a stability promise: entry points, names and
+> shapes can change in any build.
+
+Two Maia clients share it. The Expo client,
+[`@maiaos/client`](https://github.com/vllnt/maia/blob/main/apps/client/README.md)
+(Desktop and mobile), uses it today. The `maia` CLI will use it for its
+terminal dashboard
+([D-161](https://github.com/vllnt/maia/blob/main/docs/decisions.md#d-161),
+planned; the CLI does not use it yet).
+
+## Requirements
+
+Node.js 24.22.1, and a Maia Node to talk to through `@maiaos/sdk`, which
+installs with this package.
+
+## Install
+
+```sh
+pnpm add @maiaos/client-core@nightly   # or @canary, or an exact version
+```
+
+## Usage
+
+```ts
+import { makeNodeStatusClientService } from "@maiaos/client-core/node-status";
+import { validateVoiceProposal } from "@maiaos/client-core/single-session";
+import { makeTerminalClientService } from "@maiaos/client-core/terminal";
+import { makeWorkspaceScopeService } from "@maiaos/client-core/workspace-scope";
+```
+
+Each factory returns an Effect service that the renderer composes with a
+platform transport; React components only render its state.
+
+The package owns client-side validation, deadlines, cancellation, recovery of
+uncertain requests and projections of Node state. It owns no transport,
+credentials, native API, Node lifecycle or durable state: the SDK is the
+protocol client and Maia Node is the authority.
+
+| Entry point                        | Responsibility                                                                                                                                                                                |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `boot`                             | The Desktop boot sequence: lifecycle status, one start, then status reads until the host reports a ready Node                                                                                 |
+| `navigation`                       | Route names, the `?q=&state=&page=` list query, parent routes and the one pagination model                                                                                                    |
+| `node-status`                      | One truthful, point-in-time Node status projection                                                                                                                                            |
+| `workspace-scope`                  | The one active Workspace scope, loaded from and replaced only by Node                                                                                                                         |
+| `single-session`                   | Voice setup, Node-provided orchestrator context and local proposals                                                                                                                           |
+| `terminal`, `terminal-unavailable` | Live terminal client and its explicit unavailable state                                                                                                                                       |
+| `interaction`, `interaction-view`  | Record-only questions and answers, with recovery of unknown outcomes                                                                                                                          |
+| `presentation`                     | Bounded Workspace, Project and Session list reads                                                                                                                                             |
+| `cockpit`                          | Work cockpit per Node and a combined view: one bounded index, one change feed, attention, lists, launcher search, single or bulk Session creation over the SDK batch and first-run onboarding |
+| `session-view`                     | Focused Session detail: live items over `session.attach`, recent turns, summary, diff and a send, interrupt and wait composer                                                                 |
+| `commands`                         | The keyboard command registry: stable IDs, rebindable keymap, conflicts                                                                                                                       |
+| `node-registry`                    | The local and registered remote Nodes a client addresses: connecting, ready, stale or unreachable (with ssh's reason, or `auth` when the Node rejects the credential)                         |
+| `session-attach`                   | The SDK's Session attach reducer, re-exported unchanged                                                                                                                                       |
+| `dictation`                        | Composer dictation state: listening, partial text at the caret, cancel, language                                                                                                              |
+
+- **Deadlines and uncertainty.** Every request gets a unique message ID from
+  the package `IdGenerator` (Effect `Random` by default) and a 5.5-second
+  client deadline. A timed-out query is retryable; a timed-out
+  mutation is `outcome_unknown` and is reconciled with its original command
+  ID, never retried as a new one. Each request carries `deadlineAt`, that
+  deadline as an instant on `Clock.monotonicTimeNanos` (never wall-clock time),
+  for a requester that retries to stop before it. A client that must bound its
+  reads in flight provides `ReadAdmission`; a read waits for its permit before
+  its deadline starts, and a mutation never waits.
+- **Freshness.** Each Node's cockpit keeps the time of its last successful
+  read and one whole-Node load in flight. A failed load retries, after 2 s and
+  doubling to 30 s, until the Node answers; a reload a person asks for runs
+  once; the change feed resubscribes on the same backoff. A copy is `stale`
+  when its latest whole-Node read failed and `partial` until the Node first
+  answers or while it caps a read. The combined view stays ready once any Node
+  answers.
+- **Routing.** The combined view labels each Project and Session with its
+  Node, and `nodeIdOf` is the one lookup an action asks. It returns that Node,
+  or a `NodeRouteError` when the combined view holds no such target
+  (`unknown`) or two Nodes' indexes hold the same ID (`ambiguous`). A repeated
+  Workspace, Project or Session ID keeps the first Node's record and marks the
+  view truncated, and no action targets a repeated Project or Session. One
+  Node's own view routes every target to that Node, since its bounded index
+  can lack a Session the Node holds.
+- **Fail closed.** Token, Workspace, orchestrator and relay services are
+  unavailable by default. A proposal or preview is never evidence of delivery;
+  only an exact Node preview enables explicit confirmation.
+- **No hidden authority.** Browsing owns no execution focus or mutation
+  authority, and errors carry only bounded reason codes, never credentials or
+  request envelopes.
+
+## Status
+
+**Source candidate.** Its terminal, voice, interaction and cockpit services are
+not release-qualified. The cockpit follows today's `observe.events` feed; the
+planned R1 aggregate subscription, view store and reconnect policy will replace
+its index load here; see the
+[client architecture](https://github.com/vllnt/maia/blob/main/docs/clients/architecture.md).
+
+- **Bulk creation.** A preview fixes every target, task and command ID and
+  carries a digest; one confirmation runs it once, within its expiry. Each
+  item reports its receipts or the Node's refusal (for example `saturated`
+  when an account has no free slot). A retry replays the same commands and
+  request bodies, so the Node answers the original results. The Run ledger
+  (S19) joins as a second `CreationDispatch`.
+- **Onboarding.** `makeOnboarding` reads vendor accounts from Connection
+  records, scans native sessions as metadata (titles only when a person turns
+  them on), registers repositories, and runs adoption as a preview, then one
+  confirmation request per item, each opening the Desktop native sheet. A declined or uncertain confirmation stops the batch;
+  confirming again resends the same preview IDs. One-click use of signed-in
+  CLIs waits for `connection.detect` (`CliDetection` placeholder).
+- **Timeline seam.** `session-view` reads final turn text through a
+  `TimelineSource`; the S12b `reduceSessionAttach` source plugs in there.
+
+## Links
+
+- [Desktop and mobile client architecture](https://github.com/vllnt/maia/blob/main/docs/clients/architecture.md)
+- [`@maiaos/sdk`](https://github.com/vllnt/maia/blob/main/packages/sdk/README.md)
+- [Security policy](https://github.com/vllnt/maia/blob/main/SECURITY.md)
+- [Repository](https://github.com/vllnt/maia)

package/dist/boot/boot.d.ts

@@ -0,0 +1,63 @@
+import { Duration, Effect, type Scope, type Stream } from "effect";
+/**
+ * What the Desktop host reports about its local Node (`node_lifecycle_*`).
+ * The renderer never infers it: `ready` comes from the host alone, which
+ * checked the Node's descriptor and an authenticated `node.status`.
+ */
+export type NodeLifecycleState = {
+    readonly instanceId: string;
+    readonly state: "ready";
+} | {
+    readonly reason: string;
+    readonly state: "failed" | "unavailable";
+} | {
+    readonly state: "detecting" | "starting";
+};
+declare const NodeLifecycleError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NodeLifecycleError";
+} & Readonly<A>;
+export declare class NodeLifecycleError extends NodeLifecycleError_base<{
+    readonly message: string;
+}> {
+}
+/** The host's two lifecycle commands, lifted into Effect at the platform edge. */
+export type NodeLifecycle = {
+    readonly start: Effect.Effect<NodeLifecycleState, NodeLifecycleError>;
+    readonly status: Effect.Effect<NodeLifecycleState, NodeLifecycleError>;
+};
+/**
+ * Where the boot sequence is. `waiting` while the host starts or detects a
+ * Node; `stopped` when it gave up and a person may start it again; `ready`
+ * once the host reports a ready Node; routes read it from then on.
+ */
+export type BootState = {
+    readonly instanceId: string;
+    readonly phase: "ready";
+} | {
+    readonly phase: "checking";
+} | {
+    readonly phase: "stopped";
+    readonly reason: string;
+} | {
+    readonly phase: "waiting";
+};
+export type BootOptions = {
+    /** First pause between status reads; doubles up to `maxDelay`. */
+    readonly initialDelay?: Duration.Input;
+    readonly maxDelay?: Duration.Input;
+    /** How long to wait for a starting Node before stopping. */
+    readonly timeout?: Duration.Input;
+};
+export type Boot = {
+    readonly changes: Stream.Stream<BootState>;
+    readonly current: Effect.Effect<BootState>;
+    /** Runs the sequence again (the "Start Maia" action); ignored while one runs. */
+    readonly restart: Effect.Effect<void>;
+};
+/**
+ * Starts the boot sequence in the caller's scope. Routes mount once it
+ * publishes `ready`; closing the scope interrupts a sequence in flight.
+ */
+export declare const makeBoot: (lifecycle: NodeLifecycle, options?: BootOptions) => Effect.Effect<Boot, never, Scope.Scope>;
+export {};
+//# sourceMappingURL=boot.d.ts.map

package/dist/boot/boot.js

@@ -0,0 +1,86 @@
+import { Data, Duration, Effect, Semaphore, SubscriptionRef, } from "effect";
+export class NodeLifecycleError extends Data.TaggedError("NodeLifecycleError") {
+}
+/** The host starts its Node in up to 60 seconds; leave headroom. */
+const DEFAULTS = {
+    initialDelay: Duration.millis(250),
+    maxDelay: Duration.seconds(2),
+    timeout: Duration.seconds(75),
+};
+const settled = (lifecycle) => {
+    if (lifecycle.state === "ready")
+        return { instanceId: lifecycle.instanceId, phase: "ready" };
+    if (lifecycle.state === "failed" || lifecycle.state === "unavailable")
+        return { phase: "stopped", reason: lifecycle.reason };
+    return undefined;
+};
+/** A bridge call that fails reads as an unreachable host. */
+const unreachable = {
+    reason: "host_unreachable",
+    state: "unavailable",
+};
+const read = (effect) => effect.pipe(Effect.catch(() => Effect.succeed(unreachable)));
+/**
+ * A status read while the Node starts: a failed call is one missed answer,
+ * not a verdict, so the sequence keeps waiting until its deadline.
+ */
+const poll = (effect) => effect.pipe(Effect.catch(() => Effect.succeed({ state: "starting" })));
+/**
+ * Status reads with a growing pause until the host reports the Node ready
+ * or stopped. The caller bounds the whole wait.
+ */
+const waitForReady = (run, current, delay) => Effect.gen(function* () {
+    const outcome = settled(current);
+    if (outcome !== undefined)
+        return outcome;
+    yield* Effect.sleep(delay);
+    return yield* waitForReady(run, yield* poll(run.lifecycle.status), Duration.min(Duration.times(delay, 2), run.options.maxDelay));
+});
+/**
+ * Status; unless the Node is ready, one start (the host's start is
+ * idempotent: it adopts a running Node, keeps a start in flight, or spawns
+ * one); then status reads until the host reports ready or stopped. The
+ * whole sequence, every host call included, ends at the timeout. The state
+ * follows every step, so the screen tells the truth.
+ */
+const sequence = (run) => Effect.gen(function* () {
+    yield* SubscriptionRef.set(run.ref, { phase: "checking" });
+    const first = yield* read(run.lifecycle.status);
+    if (first.state === "ready")
+        return yield* SubscriptionRef.set(run.ref, {
+            instanceId: first.instanceId,
+            phase: "ready",
+        });
+    yield* SubscriptionRef.set(run.ref, { phase: "waiting" });
+    const outcome = yield* waitForReady(run, yield* read(run.lifecycle.start), run.options.initialDelay);
+    yield* SubscriptionRef.set(run.ref, outcome);
+}).pipe(Effect.timeoutOrElse({
+    duration: run.options.timeout,
+    orElse: () => SubscriptionRef.set(run.ref, {
+        phase: "stopped",
+        reason: "readiness_timeout",
+    }),
+}));
+const durations = (options) => ({
+    initialDelay: Duration.fromInputUnsafe(options.initialDelay ?? DEFAULTS.initialDelay),
+    maxDelay: Duration.fromInputUnsafe(options.maxDelay ?? DEFAULTS.maxDelay),
+    timeout: Duration.fromInputUnsafe(options.timeout ?? DEFAULTS.timeout),
+});
+/**
+ * Starts the boot sequence in the caller's scope. Routes mount once it
+ * publishes `ready`; closing the scope interrupts a sequence in flight.
+ */
+export const makeBoot = (lifecycle, options = {}) => Effect.gen(function* () {
+    const ref = yield* SubscriptionRef.make({ phase: "checking" });
+    const lock = yield* Semaphore.make(1);
+    const scope = yield* Effect.scope;
+    const run = { lifecycle, options: durations(options), ref };
+    const once = Effect.forkIn(lock.withPermitsIfAvailable(1)(sequence(run)), scope).pipe(Effect.asVoid);
+    yield* once;
+    return {
+        changes: SubscriptionRef.changes(ref),
+        current: SubscriptionRef.get(ref),
+        restart: once,
+    };
+});
+//# sourceMappingURL=boot.js.map

package/dist/boot/index.d.ts

@@ -0,0 +1,3 @@
+export type { Boot, BootOptions, BootState, NodeLifecycle, NodeLifecycleState, } from "./boot.js";
+export { makeBoot, NodeLifecycleError } from "./boot.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/boot/index.js

@@ -0,0 +1,2 @@
+export { makeBoot, NodeLifecycleError } from "./boot.js";
+//# sourceMappingURL=index.js.map

package/dist/cockpit/attention.d.ts

@@ -0,0 +1,23 @@
+import type { Session, SessionObservation } from "@maiaos/sdk";
+export type SessionRuntime = NonNullable<SessionObservation["runtime"]>;
+/**
+ * Why a Session needs a person, as the Node reports it (`session.list` and
+ * `session.observe` carry it). The client derives none of these values.
+ */
+export type AttentionReason = NonNullable<SessionObservation["attention"]>;
+export type AttentionItem = {
+    readonly projectId: string;
+    readonly reason: AttentionReason;
+    readonly sessionId: string;
+    readonly updatedAt: string;
+};
+/** Bounds the list a person triages; the portfolio list shows the rest. */
+export declare const MAX_ATTENTION_ITEMS = 500;
+/**
+ * The ordered, bounded list of Sessions the Node says need a person now.
+ * A Session the Node reports nothing for is absent.
+ */
+export declare const deriveAttention: (sessions: Iterable<Session>, reasons: ReadonlyMap<string, AttentionReason>) => readonly AttentionItem[];
+/** Short labels for people; the Node's value stays the source. */
+export declare const attentionLabel: (reason: AttentionReason) => string;
+//# sourceMappingURL=attention.d.ts.map

package/dist/cockpit/attention.js

@@ -0,0 +1,52 @@
+/** Most urgent first: a person blocks the work, then failures, then review. */
+const SEVERITY = [
+    "approval_pending",
+    "question",
+    "failed",
+    "turn_failed",
+    "stalled",
+    "settled_unreviewed",
+];
+/** Bounds the list a person triages; the portfolio list shows the rest. */
+export const MAX_ATTENTION_ITEMS = 500;
+const byUrgency = (left, right) => SEVERITY.indexOf(left.reason) - SEVERITY.indexOf(right.reason) ||
+    right.updatedAt.localeCompare(left.updatedAt) ||
+    left.sessionId.localeCompare(right.sessionId);
+/**
+ * The ordered, bounded list of Sessions the Node says need a person now.
+ * A Session the Node reports nothing for is absent.
+ */
+export const deriveAttention = (sessions, reasons) => [...sessions]
+    .flatMap((session) => {
+    const reason = reasons.get(session.id);
+    return reason === undefined
+        ? []
+        : [
+            {
+                projectId: session.projectId,
+                reason,
+                sessionId: session.id,
+                updatedAt: session.updatedAt,
+            },
+        ];
+})
+    .toSorted(byUrgency)
+    .slice(0, MAX_ATTENTION_ITEMS);
+/** Short labels for people; the Node's value stays the source. */
+export const attentionLabel = (reason) => {
+    switch (reason) {
+        case "approval_pending":
+            return "Needs approval";
+        case "failed":
+            return "Failed";
+        case "question":
+            return "Question";
+        case "settled_unreviewed":
+            return "Review";
+        case "stalled":
+            return "Stalled";
+        case "turn_failed":
+            return "Turn failed";
+    }
+};
+//# sourceMappingURL=attention.js.map

package/dist/cockpit/client.d.ts

@@ -0,0 +1,88 @@
+import { type LocalNodeClient } from "@maiaos/sdk";
+import { Context, Effect } from "effect";
+/** The SDK operations the cockpit, creation, Session detail and onboarding use. */
+export type CockpitClient = Pick<LocalNodeClient, "archiveSession" | "confirmSessionAdopt" | "createSession" | "detectConnections" | "diffSession" | "getReceipt" | "interruptTurn" | "listConnections" | "listContainerIndex" | "listDiscoveredSessions" | "listRemoteNodes" | "listSessionEvents" | "listSessions" | "listWorkspaces" | "observeSessions" | "previewSessionAdopt" | "registerProject" | "respondToApproval" | "resumeSession" | "sendTurn" | "showApproval" | "showSession" | "showTurn" | "startSession" | "stopSession" | "waitTurns">;
+/**
+ * Every Node operation the cockpit, creation, Session detail and onboarding
+ * send. Each request names one of them, so a test can hold the Desktop
+ * allowlist against this list.
+ */
+export declare const COCKPIT_OPERATIONS: readonly ["approval.respond", "approval.show", "connection.detect", "connection.list", "container.index.list", "discovery.sessions.list", "node.remote.list", "project.register", "session.adopt.confirm", "session.adopt.preview", "session.archive", "session.create", "session.diff", "session.events.list", "session.list", "session.observe", "session.resume", "session.show", "session.start", "session.stop", "turn.interrupt", "turn.send", "turn.show", "turn.wait", "workspace.list"];
+export type CockpitOperation = (typeof COCKPIT_OPERATIONS)[number];
+/**
+ * Why a request did not succeed. `refused` carries the Node's protocol code
+ * (for example `saturated` when an account has no free Session slot);
+ * `declined` means a person declined the native confirmation and nothing was
+ * sent; `sheet_busy` means another native confirmation was open or none was
+ * available, so the Node got nothing and the same request may run again;
+ * `outcome_unknown` means a mutation may have committed and must be
+ * reconciled with its original command ID.
+ */
+export type CockpitErrorReason = "declined" | "denied" | "invalid" | "offline" | "outcome_unknown" | "refused" | "sheet_busy" | "unavailable";
+declare const CockpitError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CockpitError";
+} & Readonly<A>;
+export declare class CockpitError extends CockpitError_base<{
+    /** The Node's protocol error code when it refused the request. */
+    readonly code?: string;
+    /**
+     * The Node's own explanation of a refusal, which often names the fix, or
+     * why a remote Node is unreachable, such as the last line ssh printed.
+     */
+    readonly detail?: string;
+    readonly message: string;
+    readonly operation: string;
+    readonly reason: CockpitErrorReason;
+}> {
+}
+/** How long the client waits for an ordinary request. */
+export declare const REQUEST_DEADLINE_MILLISECONDS = 5500;
+/**
+ * How long the client waits for a request behind the native confirmation:
+ * the sheet declines itself after two minutes (the Desktop's
+ * `CONFIRMATION_WINDOW_SECONDS`), then the Node deadline starts. A test
+ * holds this above the two together.
+ */
+export declare const CONFIRMATION_DEADLINE_MILLISECONDS = 150000;
+/**
+ * The Desktop bridge's code for a request it refused to send, such as an
+ * approval answer whose request it no longer remembers, or one to a remote
+ * Node whose registration changed.
+ */
+export declare const PLATFORM_DENIED = "request_denied";
+/**
+ * Classifies a failure with the SDK. A mutation the Node never answered is
+ * `outcome_unknown`, because it may have committed.
+ */
+export declare const toCockpitError: (operation: string, error: unknown, mutation?: boolean) => CockpitError;
+type RequestOptions = {
+    /** When the client stops waiting, on `Clock.monotonicTimeNanos`. */
+    readonly deadlineAt: bigint;
+    readonly messageId: string;
+    readonly signal: AbortSignal;
+};
+/**
+ * Admits a read before its deadline starts, so a wait for a permit never
+ * counts against the deadline. It never admits a mutation. The default admits
+ * every read at once, as the Desktop does; a client that must bound reads in
+ * flight provides one, such as a `Semaphore`'s `withPermits(1)`.
+ */
+export type ReadAdmissionService = <TValue, TError>(effect: Effect.Effect<TValue, TError>) => Effect.Effect<TValue, TError>;
+declare const ReadAdmission_base: Context.Reference<ReadAdmissionService>;
+export declare class ReadAdmission extends ReadAdmission_base {
+}
+/** A read: a fresh message ID, the client deadline and bounded errors. */
+export declare const read: <T>(operation: CockpitOperation, request: (options: RequestOptions) => Promise<T>) => Effect.Effect<T, CockpitError>;
+/**
+ * A mutation: a timeout is `outcome_unknown`, never a failure, because the
+ * Node may have committed it; callers reconcile with the same command ID.
+ */
+export declare const mutate: <T>(operation: CockpitOperation, request: (options: RequestOptions) => Promise<T>) => Effect.Effect<T, CockpitError>;
+/**
+ * A mutation behind the native confirmation sheet: the client waits as long
+ * as the sheet may stay open, and a timeout is `outcome_unknown` as above.
+ */
+export declare const confirmMutation: <T>(operation: CockpitOperation, request: (options: RequestOptions) => Promise<T>) => Effect.Effect<T, CockpitError>;
+export declare const unavailable: (operation: string) => CockpitError;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/cockpit/client.js

@@ -0,0 +1,190 @@
+import { classifyClientError, MaiaClientError, } from "@maiaos/sdk";
+import { Clock, Context, Data, Duration, Effect } from "effect";
+import { nextCompactId } from "../id-generator/index.js";
+/**
+ * Every Node operation the cockpit, creation, Session detail and onboarding
+ * send. Each request names one of them, so a test can hold the Desktop
+ * allowlist against this list.
+ */
+export const COCKPIT_OPERATIONS = [
+    "approval.respond",
+    "approval.show",
+    "connection.detect",
+    "connection.list",
+    "container.index.list",
+    "discovery.sessions.list",
+    "node.remote.list",
+    "project.register",
+    "session.adopt.confirm",
+    "session.adopt.preview",
+    "session.archive",
+    "session.create",
+    "session.diff",
+    "session.events.list",
+    "session.list",
+    "session.observe",
+    "session.resume",
+    "session.show",
+    "session.start",
+    "session.stop",
+    "turn.interrupt",
+    "turn.send",
+    "turn.show",
+    "turn.wait",
+    "workspace.list",
+];
+export class CockpitError extends Data.TaggedError("CockpitError") {
+}
+/** How long the client waits for an ordinary request. */
+export const REQUEST_DEADLINE_MILLISECONDS = 5500;
+/**
+ * How long the client waits for a request behind the native confirmation:
+ * the sheet declines itself after two minutes (the Desktop's
+ * `CONFIRMATION_WINDOW_SECONDS`), then the Node deadline starts. A test
+ * holds this above the two together.
+ */
+export const CONFIRMATION_DEADLINE_MILLISECONDS = 150_000;
+/**
+ * The Desktop bridge's code for a request it refused to send, such as an
+ * approval answer whose request it no longer remembers, or one to a remote
+ * Node whose registration changed.
+ */
+export const PLATFORM_DENIED = "request_denied";
+const nativeField = (error, field) => {
+    const cause = error.cause;
+    return cause !== null && typeof cause === "object"
+        ? Reflect.get(cause, field)
+        : undefined;
+};
+const nativeReason = (error) => nativeField(error, "reason");
+const MAX_DETAIL_LENGTH = 240;
+/** The native bridge's bounded reason text, never an envelope or credential. */
+const nativeDetail = (error) => {
+    const detail = nativeField(error, "detail");
+    return typeof detail === "string" && detail !== ""
+        ? detail.slice(0, MAX_DETAIL_LENGTH)
+        : undefined;
+};
+const message = (reason) => {
+    switch (reason) {
+        case "declined":
+            return "Declined in the confirmation dialog; nothing was sent.";
+        case "denied":
+            return "The Node denied this request.";
+        case "invalid":
+            return "The Node answer did not match the protocol.";
+        case "offline":
+            return "The Node did not answer.";
+        case "outcome_unknown":
+            return "The Node may have applied this change; reconcile it with the same command.";
+        case "refused":
+            return "The Node refused this request.";
+        case "sheet_busy":
+            return "Another confirmation is open or none is available; nothing was sent. Try again.";
+        case "unavailable":
+            return "This operation is not available on this client or Node.";
+    }
+};
+const failure = (operation, reason, code) => new CockpitError({
+    ...(code === undefined ? {} : { code }),
+    message: code === PLATFORM_DENIED
+        ? "The Desktop bridge refused this request; nothing was applied."
+        : message(reason),
+    operation,
+    reason,
+});
+/** A Node refusal keeps the Node's own explanation. */
+const refusedBy = (operation, error) => new CockpitError({
+    ...(error.remoteError === undefined
+        ? {}
+        : { code: error.remoteError.code, detail: error.remoteError.message }),
+    message: message("refused"),
+    operation,
+    reason: "refused",
+});
+/** A remote Node whose bridge is opening or failed, with ssh's reason. */
+const remoteFailure = (operation, code, error) => {
+    const detail = nativeDetail(error);
+    return new CockpitError({
+        code,
+        ...(detail === undefined ? {} : { detail }),
+        message: message("offline"),
+        operation,
+        reason: "offline",
+    });
+};
+/** The SDK's classification in the cockpit's words. */
+const reasonFor = (kind) => {
+    if (kind === "cancelled")
+        return "offline";
+    return kind === "conflict" || kind === "not_found" ? "refused" : kind;
+};
+/**
+ * Classifies a failure with the SDK. A mutation the Node never answered is
+ * `outcome_unknown`, because it may have committed.
+ */
+export const toCockpitError = (operation, error, mutation = false) => {
+    if (error instanceof CockpitError)
+        return error;
+    // A remote Node's bridge reports an opening or failed bridge before the
+    // request left, with ssh's reason; the SDK has no word for that.
+    if (error instanceof MaiaClientError) {
+        const native = nativeReason(error);
+        if (native === "node_connecting" || native === "node_unreachable")
+            return remoteFailure(operation, native, error);
+    }
+    const { code, kind } = classifyClientError(error, { mutation });
+    if (code === "confirmation_unavailable")
+        return failure(operation, "sheet_busy", code);
+    const reason = reasonFor(kind);
+    return reason === "refused" &&
+        error instanceof MaiaClientError &&
+        error.remoteError !== undefined
+        ? refusedBy(operation, error)
+        : failure(operation, reason, code);
+};
+const admitAtOnce = (effect) => effect;
+export class ReadAdmission extends Context.Reference("@maiaos/client-core/ReadAdmission", { defaultValue: () => admitAtOnce }) {
+}
+const send = (operation, request, { deadline, mutation }) => {
+    // One monotonic read sets the cutoff, then the timeout starts: the cutoff is
+    // never later than the timeout, and a wall clock that steps back moves neither.
+    const attempt = Effect.flatMap(Clock.monotonicTimeNanos, (now) => Effect.flatMap(nextCompactId("cockpit"), (messageId) => Effect.tryPromise({
+        catch: (error) => toCockpitError(operation, error, mutation),
+        try: (signal) => request({
+            deadlineAt: now + Duration.toNanosUnsafe(deadline),
+            messageId,
+            signal,
+        }),
+    })).pipe(Effect.timeoutOrElse({
+        duration: deadline,
+        orElse: () => Effect.fail(failure(operation, "offline", "timed_out")),
+    })));
+    return mutation
+        ? attempt
+        : Effect.flatMap(Effect.service(ReadAdmission), (admit) => admit(attempt));
+};
+/** A read: a fresh message ID, the client deadline and bounded errors. */
+export const read = (operation, request) => send(operation, request, {
+    deadline: REQUEST_DEADLINE_MILLISECONDS,
+    mutation: false,
+});
+const unknownOnTimeout = (operation, effect) => effect.pipe(Effect.catchIf((error) => error.code === "timed_out" || error.code === "deadline_exceeded", () => Effect.fail(failure(operation, "outcome_unknown"))));
+/**
+ * A mutation: a timeout is `outcome_unknown`, never a failure, because the
+ * Node may have committed it; callers reconcile with the same command ID.
+ */
+export const mutate = (operation, request) => unknownOnTimeout(operation, send(operation, request, {
+    deadline: REQUEST_DEADLINE_MILLISECONDS,
+    mutation: true,
+}));
+/**
+ * A mutation behind the native confirmation sheet: the client waits as long
+ * as the sheet may stay open, and a timeout is `outcome_unknown` as above.
+ */
+export const confirmMutation = (operation, request) => unknownOnTimeout(operation, send(operation, request, {
+    deadline: CONFIRMATION_DEADLINE_MILLISECONDS,
+    mutation: true,
+}));
+export const unavailable = (operation) => failure(operation, "unavailable");
+//# sourceMappingURL=client.js.map