@elaraai/e3-rack 0.0.0-bootstrap.0 → 1.0.94

package/dist/src/client/connect.js

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { spawn } from 'node:child_process';
+import { open } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { IntegerType, compareFor, printFor } from '@elaraai/east';
+import { ensureRackHome, rackHome, HUB_LOG_FILE } from '../paths.js';
+import { HUB_PROTOCOL } from '../version.js';
+import { HubClient } from './hub-client.js';
+import { RackHubError } from './local-http.js';
+/** Reports a running hub whose protocol cannot serve this e3 release. */
+export class RackHubOutdatedError extends RackHubError {
+    /** @param message - The mismatch and how to replace the hub */
+    constructor(message) { super('protocol_mismatch', message); this.name = 'RackHubOutdatedError'; }
+}
+/** Reports unavailable rack service; a task runner may safely run locally. */
+export class RackHubUnavailableError extends RackHubError {
+    /** @param message - Transport failure and diagnostic log path */
+    constructor(message) { super('unavailable', message); this.name = 'RackHubUnavailableError'; }
+}
+/**
+ * Spawns a detached hub through this package's published entry point.
+ * Several callers may spawn concurrently; the hub lock elects one winner.
+ * @param home - Private state home and log destination
+ * @returns After the child was spawned and its inherited log descriptor closed
+ */
+export async function spawnHub(home = rackHome()) {
+    ensureRackHome(home);
+    const file = await open(join(home, HUB_LOG_FILE), 'a', 0o600);
+    try {
+        const main = createRequire(import.meta.url).resolve('@elaraai/e3-rack/hub-main');
+        const child = spawn(process.execPath, [main, '--background'], { detached: true, windowsHide: true,
+            stdio: ['ignore', file.fd, file.fd], env: { ...process.env, E3_RACK_HOME: home } });
+        await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+        child.unref();
+    }
+    finally {
+        await file.close();
+    }
+}
+/**
+ * Finds or starts the shared hub and negotiates its exact control protocol.
+ *
+ * @remarks
+ * This wire has no cross-protocol decoder. A newer protocol is refused too,
+ * without draining it. An older hub is asked to drain and the caller runs
+ * locally this time. A dead hub is never silently reattached mid-session.
+ * @param options - Startup policy, deadline and progress sink
+ * @returns A ready typed client
+ * @throws {RackHubOutdatedError} On an incompatible control protocol
+ * @throws {RackHubUnavailableError} On startup, connection or drain timeout
+ * @example
+ * const hub = await connectHub({ log: console.log });
+ */
+export async function connectHub(options = {}) {
+    const home = ensureRackHome(options.home ?? rackHome());
+    const timeout = options.timeoutMs ?? 10000;
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        throw new RangeError('Rack hub timeout must be positive');
+    const deadline = Date.now() + timeout;
+    const client = new HubClient(home);
+    let spawned = false;
+    let last = 'hub did not answer';
+    while (Date.now() < deadline) {
+        if (options.signal?.aborted === true)
+            throw new RackHubUnavailableError('Rack hub connection was abandoned: the run was aborted');
+        try {
+            const hello = await client.hello(Math.max(1, Math.min(1000, deadline - Date.now())));
+            const order = compareFor(IntegerType)(hello.protocol, BigInt(HUB_PROTOCOL));
+            if (order !== 0) {
+                if (order < 0)
+                    await client.drain();
+                throw new RackHubOutdatedError(`The running rack hub (e3 ${hello.version}, protocol ${printFor(IntegerType)(hello.protocol)}) is ${order < 0 ? 'older' : 'newer'} than this e3 (protocol ${HUB_PROTOCOL}). ` +
+                    (order < 0 ? 'It will exit once idle — run `e3 rack stop` to replace it now.' : 'Use a matching e3 release or stop the hub before replacing it.'));
+            }
+            if (!hello.draining)
+                return client;
+            if (options.spawn === false)
+                throw new RackHubUnavailableError('The running rack hub is draining');
+            last = 'the running rack hub is draining';
+            spawned = false;
+        }
+        catch (err) {
+            if (err instanceof RackHubOutdatedError || err instanceof RackHubUnavailableError)
+                throw err;
+            last = err instanceof Error ? err.message : String(err);
+            const absent = err instanceof RackHubError && ['ENOENT', 'ECONNREFUSED', 'EPIPE', 'ECONNRESET'].includes(err.code);
+            if (!absent)
+                break;
+            if (options.spawn === false)
+                break;
+            if (!spawned) {
+                options.log?.('starting rack hub…');
+                try {
+                    await spawnHub(home);
+                }
+                catch (error) {
+                    last = error instanceof Error ? error.message : String(error);
+                    break;
+                }
+                spawned = true;
+            }
+        }
+        await delay(Math.max(1, Math.min(100, deadline - Date.now())), undefined, { signal: options.signal }).catch(() => { });
+    }
+    throw new RackHubUnavailableError(`Rack hub unavailable: ${last}. See ${join(home, HUB_LOG_FILE)}`);
+}
+//# sourceMappingURL=connect.js.map

package/dist/src/client/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../../src/client/connect.ts"],"names":[],"mappings":"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"}

package/dist/src/client/hub-client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type ValueTypeOf } from '@elaraai/east';
+import { AttachLeaseResultType, CancelLeaseResultType, CreateLeaseResultType, HubEnrollResultType, HubEnrollType, HubHelloType, HubStatusType, OpenSessionResultType, RemoveRackResultType, SessionPollResultType, type CreateLease, type HubConfig, type OpenSession } from '../protocol/control.js';
+import { RackRegistrationType, type RackSecurityPolicy } from '../protocol/registration.js';
+/**
+ * Calls the typed control API of the single user-wide hub.
+ * Use connectHub to discover/start the process and negotiate its protocol.
+ * @example
+ * const client = new HubClient();
+ * console.log(await client.status());
+ */
+export declare class HubClient {
+    readonly home: string;
+    /** Private control socket or Windows pipe. */
+    readonly socketPath: string;
+    /** @param home - The shared state home whose hub to call */
+    constructor(home?: string);
+    /** Reads the fixed version handshake within the caller's startup deadline. */
+    hello(timeoutMs?: number): Promise<ValueTypeOf<typeof HubHelloType>>;
+    /** Reads listener readiness, attached sessions and fleet capacity. */
+    status(): Promise<ValueTypeOf<typeof HubStatusType>>;
+    /** Mints a one-time enrollment token for the configured private-network listener. */
+    enroll(request?: ValueTypeOf<typeof HubEnrollType>): Promise<ValueTypeOf<typeof HubEnrollResultType>>;
+    /** Revokes an enrolled rack and ends work it still holds. */
+    removeRack(id: string): Promise<ValueTypeOf<typeof RemoveRackResultType>>;
+    /** Approves exactly the boot the operator inspected; refuses a newer reboot. */
+    approveRack(id: string, bootId: string): Promise<ValueTypeOf<typeof RackRegistrationType>>;
+    /** Reads whether a rack's boots after its first need approval before it is leased work. */
+    getSecurityPolicy(): Promise<RackSecurityPolicy>;
+    /** Sets whether a rack's boots after its first need approval; a rack already admitted keeps its approved boot. */
+    setSecurityPolicy(policy: RackSecurityPolicy): Promise<RackSecurityPolicy>;
+    /** Reads the effective hub configuration. */
+    getConfig(): Promise<HubConfig>;
+    /** Persists configuration and rebinds a changed rack listener. */
+    setConfig(config: HubConfig): Promise<HubConfig>;
+    /** Refuses new sessions and exits after existing sessions finish. */
+    drain(): Promise<void>;
+    /** Cancels active work and gracefully exits the hub. */
+    stop(): Promise<void>;
+    /** Registers a live repository data endpoint; RackSession owns its lifecycle. */
+    openSession(request: OpenSession): Promise<ValueTypeOf<typeof OpenSessionResultType>>;
+    /** Ends a session, transferring shared leases before its data endpoint closes. */
+    closeSession(id: string): Promise<void>;
+    /** Submits or attaches to a task/unit lease of the session's repository. */
+    createLease(id: string, request: CreateLease): Promise<ValueTypeOf<typeof CreateLeaseResultType>>;
+    /** Attaches to identical work already queued or held, or answers none; it queues nothing. */
+    attachLease(id: string, request: CreateLease): Promise<ValueTypeOf<typeof AttachLeaseResultType>>;
+    /** Unsubscribes one session; only its final subscription cancels the lease. */
+    cancelLease(id: string, leaseId: string): Promise<ValueTypeOf<typeof CancelLeaseResultType>>;
+    /** Polls ordered updates and refreshes the session's liveness. */
+    events(id: string, after: bigint, waitMs?: number, signal?: AbortSignal): Promise<ValueTypeOf<typeof SessionPollResultType>>;
+    private path;
+}
+//# sourceMappingURL=hub-client.d.ts.map

package/dist/src/client/hub-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-client.d.ts","sourceRoot":"","sources":["../../../src/client/hub-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAmB,qBAAqB,EAAE,qBAAqB,EAAE,qBAAqB,EAC5E,mBAAmB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EACrG,oBAAoB,EAAE,qBAAqB,EAAmB,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACnJ,OAAO,EAAE,oBAAoB,EAA0B,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGpH;;;;;;GAMG;AACH,qBAAa,SAAS;IAIR,QAAQ,CAAC,IAAI;IAHzB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4DAA4D;gBACvC,IAAI,SAAa;IAEtC,8EAA8E;IAC9E,KAAK,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;IAGnE,sEAAsE;IACtE,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;IACpD,qFAAqF;IACrF,MAAM,CAAC,OAAO,GAAE,WAAW,CAAC,OAAO,aAAa,CAAqC,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAC;IAGxI,6DAA6D;IAC7D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;IAGzE,gFAAgF;IAChF,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;IAG1F,2FAA2F;IAC3F,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAGhD,kHAAkH;IAClH,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAG1E,6CAA6C;IAC7C,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;IAC/B,kEAAkE;IAClE,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAGhD,qEAAqE;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAC5B,wDAAwD;IAClD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAC3B,iFAAiF;IACjF,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAGrF,kFAAkF;IAC5E,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7C,4EAA4E;IAC5E,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAGjG,6FAA6F;IAC7F,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAGjG,+EAA+E;IAC/E,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAG5F,kEAAkE;IAClE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAI3H,OAAO,CAAC,IAAI;CACb"}

package/dist/src/client/hub-client.js

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { none } from '@elaraai/east';
+import { hubSocketPath, rackHome } from '../paths.js';
+import { ApproveRackType, AttachLeaseResultType, CancelLeaseResultType, CreateLeaseResultType, CreateLeaseType, EmptyType, HubConfigType, HubEnrollResultType, HubEnrollType, HubHelloType, HubStatusType, OpenSessionResultType, OpenSessionType, RemoveRackResultType, SessionPollResultType, SessionPollType } from '../protocol/control.js';
+import { RackRegistrationType, RackSecurityPolicyType } from '../protocol/registration.js';
+import { socketRequest } from './local-http.js';
+/**
+ * Calls the typed control API of the single user-wide hub.
+ * Use connectHub to discover/start the process and negotiate its protocol.
+ * @example
+ * const client = new HubClient();
+ * console.log(await client.status());
+ */
+export class HubClient {
+    home;
+    /** Private control socket or Windows pipe. */
+    socketPath;
+    /** @param home - The shared state home whose hub to call */
+    constructor(home = rackHome()) {
+        this.home = home;
+        this.socketPath = hubSocketPath(home);
+    }
+    /** Reads the fixed version handshake within the caller's startup deadline. */
+    hello(timeoutMs = 30000) {
+        return socketRequest(this.socketPath, 'POST', '/v1/hello', { responseType: HubHelloType, timeoutMs });
+    }
+    /** Reads listener readiness, attached sessions and fleet capacity. */
+    status() { return socketRequest(this.socketPath, 'GET', '/v1/status', { responseType: HubStatusType }); }
+    /** Mints a one-time enrollment token for the configured private-network listener. */
+    enroll(request = { label: none, ttlMinutes: none }) {
+        return socketRequest(this.socketPath, 'POST', '/v1/enroll', { requestType: HubEnrollType, body: request, responseType: HubEnrollResultType });
+    }
+    /** Revokes an enrolled rack and ends work it still holds. */
+    removeRack(id) {
+        return socketRequest(this.socketPath, 'DELETE', `/v1/racks/${encodeURIComponent(id)}`, { responseType: RemoveRackResultType });
+    }
+    /** Approves exactly the boot the operator inspected; refuses a newer reboot. */
+    approveRack(id, bootId) {
+        return socketRequest(this.socketPath, 'POST', `/v1/racks/${encodeURIComponent(id)}/approve`, { requestType: ApproveRackType, body: { bootId }, responseType: RackRegistrationType });
+    }
+    /** Reads whether a rack's boots after its first need approval before it is leased work. */
+    getSecurityPolicy() {
+        return socketRequest(this.socketPath, 'GET', '/v1/security', { responseType: RackSecurityPolicyType });
+    }
+    /** Sets whether a rack's boots after its first need approval; a rack already admitted keeps its approved boot. */
+    setSecurityPolicy(policy) {
+        return socketRequest(this.socketPath, 'POST', '/v1/security', { requestType: RackSecurityPolicyType, body: policy, responseType: RackSecurityPolicyType });
+    }
+    /** Reads the effective hub configuration. */
+    getConfig() { return socketRequest(this.socketPath, 'GET', '/v1/config', { responseType: HubConfigType }); }
+    /** Persists configuration and rebinds a changed rack listener. */
+    setConfig(config) {
+        return socketRequest(this.socketPath, 'POST', '/v1/config', { requestType: HubConfigType, body: config, responseType: HubConfigType });
+    }
+    /** Refuses new sessions and exits after existing sessions finish. */
+    async drain() { await socketRequest(this.socketPath, 'POST', '/v1/drain', { responseType: EmptyType }); }
+    /** Cancels active work and gracefully exits the hub. */
+    async stop() { await socketRequest(this.socketPath, 'POST', '/v1/stop', { responseType: EmptyType }); }
+    /** Registers a live repository data endpoint; RackSession owns its lifecycle. */
+    openSession(request) {
+        return socketRequest(this.socketPath, 'POST', '/v1/sessions', { requestType: OpenSessionType, body: request, responseType: OpenSessionResultType });
+    }
+    /** Ends a session, transferring shared leases before its data endpoint closes. */
+    async closeSession(id) { await socketRequest(this.socketPath, 'DELETE', this.path(id), { responseType: EmptyType }); }
+    /** Submits or attaches to a task/unit lease of the session's repository. */
+    createLease(id, request) {
+        return socketRequest(this.socketPath, 'POST', `${this.path(id)}/leases`, { requestType: CreateLeaseType, body: request, responseType: CreateLeaseResultType });
+    }
+    /** Attaches to identical work already queued or held, or answers none; it queues nothing. */
+    attachLease(id, request) {
+        return socketRequest(this.socketPath, 'POST', `${this.path(id)}/leases/attach`, { requestType: CreateLeaseType, body: request, responseType: AttachLeaseResultType });
+    }
+    /** Unsubscribes one session; only its final subscription cancels the lease. */
+    cancelLease(id, leaseId) {
+        return socketRequest(this.socketPath, 'POST', `${this.path(id)}/leases/${encodeURIComponent(leaseId)}/cancel`, { responseType: CancelLeaseResultType });
+    }
+    /** Polls ordered updates and refreshes the session's liveness. */
+    events(id, after, waitMs = 20000, signal) {
+        return socketRequest(this.socketPath, 'POST', `${this.path(id)}/events`, { requestType: SessionPollType,
+            body: { after, waitMs: BigInt(waitMs) }, responseType: SessionPollResultType, timeoutMs: 25000, signal });
+    }
+    path(id) { return `/v1/sessions/${encodeURIComponent(id)}`; }
+}
+//# sourceMappingURL=hub-client.js.map

package/dist/src/client/hub-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-client.js","sourceRoot":"","sources":["../../../src/client/hub-client.ts"],"names":[],"mappings":"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"}

package/dist/src/client/local-http.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { Server, type IncomingMessage } from 'node:http';
+import type { Server as HttpsServer } from 'node:https';
+import { Readable } from 'node:stream';
+import { type EastType, type ValueTypeOf } from '@elaraai/east';
+import type { Hono } from 'hono';
+/** Reports a control/data transport error without losing its machine-readable cause. */
+export declare class RackHubError extends Error {
+    readonly code: string;
+    /** @param code - HTTP, protocol or system error code @param message - Actionable explanation */
+    constructor(code: string, message: string);
+}
+/** Options shared by typed requests and streamed object transfers. */
+export interface SocketRequestOptions {
+    /** Private session credential. */
+    bearer?: string;
+    /** Whole-request deadline, including response streaming; defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Cancels connection, upload and response. */
+    signal?: AbortSignal;
+    /** Raw object bytes; never encoded in a BEAST2 envelope. */
+    rawBody?: Uint8Array | Readable;
+    /** Additional HTTP headers for streamed objects. */
+    headers?: Record<string, string>;
+}
+/**
+ * How long a listener lets a request's body take to arrive: a data URL's whole
+ * fifteen minutes, with a minute to spare. Node's default, five minutes, would
+ * cut a large upload over a slow link short of the time its URL grants.
+ */
+export declare const REQUEST_BODY_TIMEOUT_MS: number;
+/**
+ * Starts an HTTP listener on a private Unix socket or Windows named pipe.
+ * The caller must hold ownership before removing any stale socket.
+ * @param app - Local HTTP application
+ * @param path - Socket or pipe
+ * @returns The listening server
+ * @example
+ * const server = await serveOnSocket(app, socketPath);
+ */
+export declare function serveOnSocket(app: Hono, path: string): Promise<Server>;
+/**
+ * Closes a listener, allowing up to five seconds for active requests.
+ * @param server - Owned listener
+ * @param socket - Owned socket to remove after closing
+ * @returns Completion of shutdown
+ */
+export declare function closeSocketServer(server: Server | HttpsServer, socket?: string): Promise<void>;
+/**
+ * Streams a local HTTP response with an absolute, abortable deadline.
+ * @param socketPath - Unix socket or Windows pipe
+ * @param method - HTTP verb
+ * @param path - Request path
+ * @param options - Credentials, input stream and deadline
+ * @returns The raw response; callers consume or destroy it
+ * @throws {RackHubError} On timeout or connection failure
+ */
+export declare function socketStream(socketPath: string, method: string, path: string, options?: SocketRequestOptions): Promise<IncomingMessage>;
+/**
+ * Sends a BEAST2 control message and decodes its standard response envelope.
+ * @param socketPath - Unix socket or Windows pipe
+ * @param method - HTTP verb
+ * @param path - Control route
+ * @param options - Request/response schemas, value and transport settings
+ * @returns The decoded success value
+ * @throws {RackHubError} On an error envelope, HTTP error or deadline
+ * @example
+ * const hello = await socketRequest(socket, 'POST', '/v1/hello', { responseType: HubHelloType });
+ */
+export declare function socketRequest<Req extends EastType, Res extends EastType>(socketPath: string, method: string, path: string, options: SocketRequestOptions & {
+    requestType?: Req;
+    body?: ValueTypeOf<Req>;
+    responseType: Res;
+}): Promise<ValueTypeOf<Res>>;
+//# sourceMappingURL=local-http.d.ts.map

package/dist/src/client/local-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-http.d.ts","sourceRoot":"","sources":["../../../src/client/local-http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAW,MAAM,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAA8C,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5G,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC,wFAAwF;AACxF,qBAAa,YAAa,SAAQ,KAAK;IAEzB,QAAQ,CAAC,IAAI,EAAE,MAAM;IADjC,gGAAgG;gBAC3E,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CACnD;AAED,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IAChC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAc,CAAC;AAEnD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc5E;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsB3I;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,GAAG,SAAS,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAC5E,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAChD,OAAO,EAAE,oBAAoB,GAAG;IAAE,WAAW,CAAC,EAAE,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;IAAC,YAAY,EAAE,GAAG,CAAA;CAAE,GAChG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAoB3B"}

package/dist/src/client/local-http.js

@@ -0,0 +1,149 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { chmod, unlink } from 'node:fs/promises';
+import { request, Server } from 'node:http';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createAdaptorServer } from '@hono/node-server';
+import { decodeBeast2For, encodeBeast2For, printFor } from '@elaraai/east';
+import { BEAST2_CONTENT_TYPE, ErrorType, ResponseType } from '@elaraai/e3-types';
+/** Reports a control/data transport error without losing its machine-readable cause. */
+export class RackHubError extends Error {
+    code;
+    /** @param code - HTTP, protocol or system error code @param message - Actionable explanation */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RackHubError';
+    }
+}
+/**
+ * How long a listener lets a request's body take to arrive: a data URL's whole
+ * fifteen minutes, with a minute to spare. Node's default, five minutes, would
+ * cut a large upload over a slow link short of the time its URL grants.
+ */
+export const REQUEST_BODY_TIMEOUT_MS = 16 * 60_000;
+/**
+ * Starts an HTTP listener on a private Unix socket or Windows named pipe.
+ * The caller must hold ownership before removing any stale socket.
+ * @param app - Local HTTP application
+ * @param path - Socket or pipe
+ * @returns The listening server
+ * @example
+ * const server = await serveOnSocket(app, socketPath);
+ */
+export async function serveOnSocket(app, path) {
+    const server = createAdaptorServer({ fetch: app.fetch, serverOptions: { requestTimeout: REQUEST_BODY_TIMEOUT_MS } });
+    if (!(server instanceof Server))
+        throw new Error('Local rack transport requires HTTP/1');
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(path, () => { server.off('error', reject); resolve(); });
+        });
+        if (process.platform !== 'win32')
+            await chmod(path, 0o600);
+        return server;
+    }
+    catch (err) {
+        server.close();
+        throw err;
+    }
+}
+/**
+ * Closes a listener, allowing up to five seconds for active requests.
+ * @param server - Owned listener
+ * @param socket - Owned socket to remove after closing
+ * @returns Completion of shutdown
+ */
+export async function closeSocketServer(server, socket) {
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => server.closeAllConnections(), 5000);
+        timer.unref();
+        server.close((error) => { clearTimeout(timer); if (error)
+            reject(error);
+        else
+            resolve(); });
+    });
+    if (socket !== undefined && process.platform !== 'win32') {
+        await unlink(socket).catch((err) => { if (err.code !== 'ENOENT')
+            throw err; });
+    }
+}
+/**
+ * Streams a local HTTP response with an absolute, abortable deadline.
+ * @param socketPath - Unix socket or Windows pipe
+ * @param method - HTTP verb
+ * @param path - Request path
+ * @param options - Credentials, input stream and deadline
+ * @returns The raw response; callers consume or destroy it
+ * @throws {RackHubError} On timeout or connection failure
+ */
+export function socketStream(socketPath, method, path, options = {}) {
+    return new Promise((resolve, reject) => {
+        const headers = { ...options.headers, ...(options.bearer === undefined ? {} : { authorization: `Bearer ${options.bearer}` }) };
+        const req = request({ socketPath, method, path, headers });
+        const fail = (err) => { req.destroy(err); if (options.rawBody instanceof Readable)
+            options.rawBody.destroy(err); };
+        const timer = setTimeout(() => fail(new RackHubError('timeout', `Rack request ${method} ${path} timed out`)), options.timeoutMs ?? 30_000);
+        timer.unref();
+        const abort = () => fail(new RackHubError('aborted', `Rack request ${method} ${path} was aborted`));
+        const cleanup = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', abort); };
+        req.once('error', (err) => { cleanup(); reject(err instanceof RackHubError ? err : new RackHubError(err.code ?? 'transport', err.message)); });
+        req.once('response', (response) => {
+            response.once('close', cleanup);
+            response.once('error', () => { }); // a destroyed response remains observable by its consumer
+            resolve(response);
+        });
+        // Observe source errors before an already-aborted signal can destroy it.
+        // Without the pipeline, destroy(error) emits an unhandled stream error.
+        if (options.rawBody instanceof Readable)
+            void pipeline(options.rawBody, req).catch(fail);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted) {
+            abort();
+            return;
+        }
+        if (!(options.rawBody instanceof Readable))
+            req.end(options.rawBody);
+    });
+}
+/**
+ * Sends a BEAST2 control message and decodes its standard response envelope.
+ * @param socketPath - Unix socket or Windows pipe
+ * @param method - HTTP verb
+ * @param path - Control route
+ * @param options - Request/response schemas, value and transport settings
+ * @returns The decoded success value
+ * @throws {RackHubError} On an error envelope, HTTP error or deadline
+ * @example
+ * const hello = await socketRequest(socket, 'POST', '/v1/hello', { responseType: HubHelloType });
+ */
+export async function socketRequest(socketPath, method, path, options) {
+    const rawBody = options.requestType === undefined ? options.rawBody : encodeBeast2For(options.requestType)(options.body);
+    const response = await socketStream(socketPath, method, path, { ...options, rawBody,
+        headers: { ...options.headers, 'content-type': BEAST2_CONTENT_TYPE } });
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 16 * 1024 * 1024) {
+            response.destroy();
+            throw new RackHubError('too_large', 'Rack control response exceeds 16 MiB');
+        }
+        chunks.push(bytes);
+    }
+    if ((response.statusCode ?? 500) >= 300) {
+        // The hub answers a refusal in plain text: the reason is the message.
+        const text = String(response.headers['content-type']).startsWith('text/plain') ? Buffer.concat(chunks).toString('utf8').trim() : '';
+        throw new RackHubError(`http_${response.statusCode}`, text !== '' && text.length <= 2000 ? text : `Rack request ${path}: HTTP ${response.statusCode}`);
+    }
+    const envelope = decodeBeast2For(ResponseType(options.responseType))(Buffer.concat(chunks));
+    if (envelope.type === 'error')
+        throw new RackHubError(envelope.value.type, printFor(ErrorType)(envelope.value));
+    return envelope.value;
+}
+//# sourceMappingURL=local-http.js.map

package/dist/src/client/local-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-http.js","sourceRoot":"","sources":["../../../src/client/local-http.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAwB,MAAM,WAAW,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,QAAQ,EAAmC,MAAM,eAAe,CAAC;AAC5G,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjF,wFAAwF;AACxF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAEhB;IADrB,gGAAgG;IAChG,YAAqB,IAAY,EAAE,OAAe;QAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAAhD,SAAI,GAAJ,IAAI,CAAQ;QAAqC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAAC,CAAC;CACpG;AAgBD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,MAAM,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAS,EAAE,IAAY;IACzD,MAAM,MAAM,GAAG,mBAAmB,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,cAAc,EAAE,uBAAuB,EAAE,EAAE,CAAC,CAAC;IACrH,IAAI,CAAC,CAAC,MAAM,YAAY,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACzF,IAAI,CAAC;QACH,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3D,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAA4B,EAAE,MAAe;IACnF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,EAAE,EAAE,IAAI,CAAC,CAAC;QACnE,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK;YAAE,MAAM,CAAC,KAAK,CAAC,CAAC;;YAAM,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,CAAC,CAAC,CAAC;IACH,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzD,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAA0B,EAAE,EAAE,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxG,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,MAAc,EAAE,IAAY,EAAE,UAAgC,EAAE;IAC/G,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;QAC/H,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,CAAC,GAAU,EAAE,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,YAAY,QAAQ;YAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1H,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,gBAAgB,MAAM,IAAI,IAAI,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC,CAAC;QAC3I,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,gBAAgB,MAAM,IAAI,IAAI,cAAc,CAAC,CAAC,CAAC;QACpG,MAAM,OAAO,GAAG,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpG,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,YAAY,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,IAAI,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtK,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,EAAE;YAChC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,0DAA0D;YAC5F,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,OAAO,CAAC,OAAO,YAAY,QAAQ;YAAE,KAAK,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzF,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAAC,KAAK,EAAE,CAAC;YAAC,OAAO;QAAC,CAAC;QACjD,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,YAAY,QAAQ,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAkB,EAAE,MAAc,EAAE,IAAY,EAChD,OAAiG;IAEjG,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,IAAK,CAAC,CAAC;IAC1H,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO;QACjF,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAmB,CAAC,CAAC;QAChF,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;QACrB,IAAI,IAAI,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;YAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAAC,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,sCAAsC,CAAC,CAAC;QAAC,CAAC;QACjI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,UAAU,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QACxC,sEAAsE;QACtE,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpI,MAAM,IAAI,YAAY,CAAC,QAAQ,QAAQ,CAAC,UAAU,EAAE,EAAE,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,IAAI,UAAU,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACzJ,CAAC;IACD,MAAM,QAAQ,GAAG,eAAe,CAAC,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5F,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO;QAAE,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChH,OAAO,QAAQ,CAAC,KAAK,CAAC;AACxB,CAAC"}

package/dist/src/client/session-attempts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type StorageBackend } from '@elaraai/e3-core';
+import type { ExecutionOwner } from '@elaraai/e3-types';
+import type { RackAttemptStore } from '../server/rack-routes.js';
+/**
+ * Writes rack attempt records with the session's own repository formats.
+ * The hub serializes the calls and names itself as the process owner, so
+ * another session can take over without an owner-death probe ending the work.
+ * @param storage - Session storage backend
+ * @param repo - Repository path known only to the session
+ * @param owner - Resolves the hub's process identity
+ * @returns The current repository's attempt adapter
+ * @example
+ * const attempts = sessionAttempts(storage, repo, () => hubOwner);
+ */
+export declare function sessionAttempts(storage: StorageBackend, repo: string, owner: () => ExecutionOwner): RackAttemptStore;
+//# sourceMappingURL=session-attempts.d.ts.map

package/dist/src/client/session-attempts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-attempts.d.ts","sourceRoot":"","sources":["../../../src/client/session-attempts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,cAAc,GAAG,gBAAgB,CAqDpH"}